Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

22    UI Controls

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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

UI Control Functions ^TOP^

UIBrightnessAdjust Function ^TOP^

Purpose

Displays the brightness adjust dialog.

Declared In

UIControls.h

Prototype

void UIBrightnessAdjust()

Parameters

None

Returns

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 Function ^TOP^

Purpose

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

Declared In

UIControls.h

Prototype

void UIContrastAdjust()

Parameters

None.

Returns

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 Function ^TOP^

Purpose

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

Declared In

UIControls.h

Prototype

Boolean UIPickColor (
   IndexedColorType*indexP,
   RGBColorType*rgbP,
   UIPickColorStartTypestart,
   constChar*titleP,
   constChar*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.

Returns

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()