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

UI Dialog Constants

UI Dialog Functions and Macros

UI Dialog Constants ^TOP^

UIPickColorStartType Typedef ^TOP^

Purpose

Controls how the dialog displayed by UIPickColor() presents the available colors to the user.

Declared In

UIControls.h

Prototype

typedef uint16_t UIPickColorStartType

Constants

#define UIPickColorStartPalette 0

Displays a series of color squares

#define UIPickColorStartRGB 1

Displays individual sliders for the red, green, and blue values.

UI Dialog Functions and Macros ^TOP^

UIBrightnessAdjust Function ^TOP^

Purpose

Displays the brightness adjust slip window.

Declared In

UIControls.h

Prototype

void UIBrightnessAdjust (
   void
)

Parameters

None.

Returns

Nothing.

Comments

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

UIContrastAdjust Function ^TOP^

Purpose

Displays the contrast adjust slip window.

Declared In

UIControls.h

Prototype

void UIContrastAdjust (
   void
)

Parameters

None.

Returns

Nothing.

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,
   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

One of the UIPickColorStartType constants. 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" in the US English locale.

→ tipP

Not used.

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. 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.

See Also

WinSetBackColor(), WinSetForeColor(), WinSetTextColor(), UIColorSetTableEntry()