21 UI Controls

This chapter describes the UI controls API as declared in UIControls.h.

UI Control Functions

UIBrightnessAdjust

Purpose

Displays the brightness adjust dialog.

Prototype

void UIBrightnessAdjust()

Parameters

Result

Returns nothing.

Comments

On hardware that supports a brightness setting, this function displays a dialog that allows the user to change the brightness level. On hardware that has a backlight, this function toggles the backlight.

Compatibility

Implemented only if 3.5 New Feature Set is present.

UIContrastAdjust

Purpose

Displays the contrast adjust dialog (currently only available on the Palm V^™ Connected Organizer).

Prototype

void UIContrastAdjust()

Parameters

Result

Returns nothing.

Compatibility

This function was renamed from ContrastAdjust to UIContrastAdjust in Palm OS^® release 3.5. The ContrastAdjust function is available if 3.1 New Feature Set is present.

UIPickColor

Purpose

Displays a dialog that allows the user to choose a color.

Prototype

Boolean UIPickColor (IndexedColorType *indexP, RGBColorType *rgbP, UIPickColorStartType start, const Char *titleP, const Char *tipP)

Parameters

<-> indexP

Index value of the selected color. (See IndexedColorType.) Upon entry, this points to the index value of the color initially selected. Upon return, this points to the index value of the color the user selected. Pass NULL to not set or return this value.

<-> rgbP

RGB value of the selected color. (See RGBColorType.) Upon entry, this points to the RGB value of the color initially selected when the dialog is displayed. Upon return, this points to the RGB value that the user selected. Pass NULL to not set or return this value.

-> start

Either UIPickColorStartPalette to display the system palette as a series of color squares or UIPickColorStartRGB to display individual sliders for the red, green, and blue values. This parameter is only used if both indexP and rgbP are not NULL.

-> titleP

String to display as the title of the dialog. Specify NULL to use the default title, which is "Pick Color."

-> tipP

Not used.

Result

Returns true if a new color was selected, false otherwise.

Comments

Use this function to allow users to choose a color used in your user interface. (The system never calls UIPickColor.)

This function can display two versions of the dialog: palette or RGB. The palette version of the dialog displays a series of squares, each containing a different color defined on the system palette. The indexP value contains the index of the square that is initially selected.

The RGB version of the dialog displays three sliders that allow the user to select the level of red, green, and blue in the color. The rgbP parameter contains the red, green, and blue values initially shown in the dialog. The sliders only allow values that are defined in the current system color table.

If indexP is initially NULL, only the RGB dialog is displayed. Similarly, if rgbP is NULL, only the palette version is displayed. If both parameters are non-NULL, the system adds a pull-down list that allows the user to switch between the palette dialog and the RGB dialog, and the start parameter controls which version of the dialog is initially shown. In this case, both indexP and rgbP contain the value of the user-selected color upon return.

Palm OS 3.5 supports a maximum of 256 colors. The number of possible RGB colors greatly exceeds this amount. For this reason, the chosen RGB may not have an exact match. If this is the case, the indexP parameter (if not NULL) contains the closest match using a luminance best-fit if the color lookup table is entirely grayscale (red, green, and blue values for each entry are identical), or a shortest-distance fit in the RGB space is used if the palette contains colors.

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

WinSetBackColor, WinSetForeColor, WinSetTextColor, UIColorSetTableEntry