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

16    Control Reference

User Interface

Exploring Palm OS®

This chapter describes the API for user interface controls. It discusses the following topics:

Control Structures and Types
Control Constants
Control Events
Control Functions and Macros

The header file Control.h declares the API that this chapter describes. For more information on using controls see Chapter 3, "Working with Controls."

Control Structures and Types ^TOP^

ControlAttrType Struct ^TOP^

Purpose

Private structure that specifies the control's visible characteristics.

Declared In

Control.h

Prototype

typedef struct ControlAttrTag ControlAttrType

Fields

None.

ControlType Struct ^TOP^

Purpose

Private structure that defines the type and characteristics of a control. The ControlPtr is a pointer to a to a ControlType structure.

Declared In

Control.h

Prototype

typedef struct ControlType ControlType;
typedef ControlType *ControlPtr

Fields

None.

GraphicControlType Struct ^TOP^

Purpose

Private structure that defines a graphical control. A graphical control is like any other control except that it displays a bitmap in place of the text label.

Declared In

Control.h

Prototype

typedef struct GraphicControlType 
GraphicControlType

Fields

None.

See Also

CtlGetGraphics(), CtlIsGraphicControl(), CtlNewGraphicControl(), CtlSetGraphics()

SliderControlType Struct ^TOP^

Purpose

Private structure that defines a slider control or a feedback slider control.

Declared In

Control.h

Prototype

typedef struct SliderControlType SliderControlType

Fields

None.

See Also

CtlGetSliderValues(), CtlSetSliderValues(), CtlNewSliderControl()

Control Constants ^TOP^

ButtonFrameType Typedef ^TOP^

Purpose

Specifies the border style for a button.

Declared In

Control.h

Prototype

typedef Enum8 ButtonFrameType

Constants

noButtonFrame
The button has no border.
standardButtonFrame
Standard command button rectangular border with rounded corners.
boldButtonFrame
Bold rectangular border with rounded corners.
rectangleButtonFrame
Rectangular border with square corners.

See Also

CtlSetFrameStyle()

ControlStyleType Typedef ^TOP^

Purpose

Specifies the type of the control defined by a ControlType structure.

Declared In

Control.h

Prototype

typedef Enum8 ControlStyleType

Constants

buttonCtl
Command button. Command buttons display a text label in a box. The ButtonFrameType specifies the type of box.
pushButtonCtl
Push button. Selecting a push button inverts its display so that it appears highlighted.
checkboxCtl
Check box. Check boxes display a setting of either on (checked) or off (unchecked)
popupTriggerCtl
Pop-up trigger. Pop-up triggers display a graphic element followed by a text label. They are used to display pop-up lists.
selectorTriggerCtl
Selector trigger. Selector triggers display a text label surrounded by a gray rectangular frame. The control expands or contracts to the width of the new label.
repeatingButtonCtl
Repeating button. Repeating buttons look like buttons; however, a repeating button is repeatedly selected if the user holds the pen on it.
sliderCtl
Slider. Sliders display two bitmaps: one representing the current value (the thumb), and another representing the scale of available values. The user can slide the thumb to the left or the right to change the value.
feedbackSliderCtl
Feedback slider. A feedback slider looks like a slider; however, a feedback slider sends events each time the thumb moves while the pen is still down. A regular slider sends an event only when the user releases the pen.

See Also

CtlGetControlStyle()

Control Events ^TOP^

ctlEnterEvent ^TOP^

Purpose

Sent when CtlHandleEvent() receives a penDownEvent within the bounds of a control.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct ctlEnter {
   struct ControlType *pControl;
   uint16_t controlID;
   _BA32_PADDING_16(1)
} ctlEnter;

Fields

pControl
Pointer to a control structure.
controlID
Resource ID of the control.

Comments

In most cases, you should wait for a ctlSelectEvent before taking the intended action of the control. When the application receives the ctlEnterEvent, it is not guaranteed that the control will become selected.

ctlExitEvent ^TOP^

Purpose

Sent by CtlHandleEvent() when the stylus had previously entered the bounds of the control, but is lifted outside of the bounds of the control.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct ctlExit {
   struct ControlType *pControl;
   uint16_t controlID;
   _BA32_PADDING_16(1)
} ctlExit;

Fields

pControl
Pointer to a control structure.
controlID
Resource ID of the control.

The following fields in the EventType structure are set for this event:

penDown
Always false.
screenX
Draw window-relative position of the pen in standard coordinates (number of coordinates from the left bound of the window).
screenY
Draw window-relative position of the pen in coordinates (number of coordinates from the top of the window).

ctlRepeatEvent ^TOP^

Purpose

Sent by CtlHandleEvent() periodically while the stylus is down in the bounds of a repeating control (such as a repeating button or a feedback slider).

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct ctlRepeat {
   struct ControlType *pControl;
   uint16_t controlID;
   uint16_t value;
   uint32_t time;
} ctlRepeat;

Fields

pControl
Pointer to a control structure.
controlID
Resource ID of the control.
value
Current value if the control is a feedback slider.
time
System-ticks count when the event is added to the queue.

Comments

When CtlHandleEvent() receives a ctlEnterEvent in a repeating button or a feedback slider control, it sends a ctlRepeatEvent. When CtlHandleEvent() receives a ctlRepeatEvent in a repeating button, it sends another ctlRepeatEvent if the pen remains down within the bounds of the control for 1/2 second beyond the last ctlRepeatEvent.

When CtlHandleEvent() receives a ctlRepeatEvent in a feedback slider control, it sends a ctlRepeatEvent each time the slider's thumb moves by at least one pixel. Feedback sliders do not send ctlRepeatEvents at regular intervals like repeating buttons do.

If you return true in response to a ctlRepeatEvent, it stops the ctlRepeatEvent loop. No further ctlRepeatEvents are sent.

ctlSelectEvent ^TOP^

Purpose

Sent by CtlHandleEvent() when the stylus had previously entered the bounds of the control and is now lifted within the bounds of the control.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct ctlSelect {
   struct ControlType *pControl;
   uint16_t controlID;
   uint16_t value;
   Boolean on;
   uint8_t reserved1;
   _BA32_PADDING_16(1)
} ctlSelect;

Fields

pControl
Pointer to a control structure.
controlID
Resource ID of the control.
value
Current value if the control is a slider.
on
true when the control has a pressed appearance; otherwise, false.
reserved1
Unused.

Comments

Applications should respond to this event to perform whatever action is necessary for this control.

Palm OS® only responds to this event if the control is a pop-up trigger. In that case, it displays the list associated with the pop-up trigger. If you must respond to this event for a pop-up trigger, return false to allow the system to perform this default behavior. If you simply want to capture the user selection from the pop-up list, do not respond to ctlSelectEvent; respond to popSelectEvent instead.

For all other types of controls, it doesn't matter whether you return true or false from your event handler since the operating system doesn't handle this event.

frmControlPrvRefreshEvent ^TOP^

Purpose

Used to update the display of a slider control.

Declared In

Event.h

Prototype

struct ctlRepeat {
   struct ControlType *pControl;
   uint16_t controlID;
   uint16_t value;
   uint32_t time;
} ctlRepeat;

Fields

pControl
Pointer to a control structure.
controlID
Resource ID of the control.
value
Current value.
time
System-ticks count when the event is added to the queue.

Comments

Applications do not respond to this event. It is used by the system to refresh the display.

Control Functions and Macros ^TOP^

CtlDrawCheckboxControl Function ^TOP^

Purpose

Draws a check box.

Declared In

Control.h

Prototype

void CtlDrawCheckboxControl (
   fcoord_t left,
   fcoord_t top,
   Boolean selected
)

Parameters

left
The x coordinate where the left side of the check box should be drawn.
top
The y coordinate where the top of the check box should be drawn.
selected
If true, the check should appear in the checkbox. If false, just the box should be drawn.

Returns

Nothing.

Comments

Don't call this function directly. Instead, add a check box to your form using a resource editor and the system draws the check box for you. If you want to dynamically add a check box to your user interface, use CtlNewControl().

CtlDrawControl Function ^TOP^

Purpose

Draws a control (and the text or graphic in it) on screen.

Declared In

Control.h

Prototype

void CtlDrawControl (
   ControlType *controlP
)

Parameters

controlP
Pointer to the control to draw.

Returns

Nothing.

Comments

The control is drawn only if it is usable. This function sets the control to be visible if necessary.

See Also

CtlSetUsable(), CtlShowControl(), FrmDrawForm()

CtlEnabled Function ^TOP^

Purpose

Returns true if the control responds to the pen.

Declared In

Control.h

Prototype

Boolean CtlEnabled (
   const ControlType *controlP
)

Parameters

controlP
Pointer to a control.

Returns

true if the control responds to the pen; false if not.

Comments

This function provides no indication of whether the control is visible on the screen. A control that doesn't respond to the pen may be visible, and if so, its appearance is no different from controls that do respond to the pen. You might use such a control to display some state of your application that cannot be modified.

See Also

CtlSetEnabled()

CtlEraseControl Function ^TOP^

Purpose

Erases a usable and visible control and its frame from the screen.

Declared In

Control.h

Prototype

void CtlEraseControl (
   ControlType *controlP
)

Parameters

controlP
Pointer to the control to erase.

Returns

Nothing.

Comments

Don't call this function directly; instead, use FrmHideObject(), which calls this function.

CtlGetControlStyle Function ^TOP^

Purpose

Returns the type of the control, such as button, slider, and so on.

Declared In

Control.h

Prototype

ControlStyleType CtlGetControlStyle (
   const ControlType *ctlP
)

Parameters

ctlP
Pointer to the control.

Returns

One of the ControlStyleType constants.

CtlGetFont Function ^TOP^

Purpose

Gets the font used when drawing a specified control's label.

Declared In

Control.h

Prototype

FontID CtlGetFont (
   const ControlType *ctlP
)

Parameters

ctlP
Pointer to the control.

Returns

The FontID of the bitmapped font used to draw the control's label.

See Also

CtlSetFont()

CtlGetGraphics Function ^TOP^

Purpose

Gets the bitmaps displayed in place of a specified control's label.

Declared In

Control.h

Prototype

void CtlGetGraphics (
   const ControlType *ctlP,
   DmResourceID *bitmapID,
   DmResourceID *selectedBitmapID
)

Parameters

ctlP
Pointer to the control.
bitmapID
Resource ID of the bitmap to display when the graphical control is not selected.
selectedBitmapID
Resource ID of the bitmap to display when the graphical control is selected, if, when selected, the graphical control should show a different bitmap.

Returns

Nothing.

Comments

If the specified control is not a graphical control—one that displays a bitmap in place of the text label—*bitmapID and *selectedBitmapID are set to zero.

This function works with any graphical control, including sliders.

See Also

CtlGetFont(), CtlSetGraphics()

CtlGetLabel Function ^TOP^

Purpose

Returns a control's text label.

Declared In

Control.h

Prototype

const char *CtlGetLabel (
   const ControlType *controlP
)

Parameters

controlP
Pointer to the control.

Returns

A pointer to a null-terminated string containing the control's label.

Comments

Make sure that controlP is not a graphical control or a slider control. The graphical control and slider control structures do not contain a text label field.


TIP: Label resources are not controls. To retrieve the text of a label resource, use FrmGetLabel().

See Also

CtlSetLabel()

CtlGetSliderValues Function ^TOP^

Purpose

Returns current values used by a slider control.

Declared In

Control.h

Prototype

void CtlGetSliderValues (
   const ControlType *ctlP,
   uint16_t *minValueP,
   uint16_t *maxValueP,
   uint16_t *pageSizeP,
   uint16_t *valueP
)

Parameters

ctlP
Pointer to a slider.
minValueP
The value of the slider when the thumb is all the way to the left. Pass NULL if you don't want to retrieve this value.
maxValueP
The value of the slider when the thumb is all the way to the right. Pass NULL if you don't want to retrieve this value.
pageSizeP
The amount by which to increase or decrease the slider value when the user taps to the right or left of the thumb. Pass NULL if you don't want to retrieve this value.
valueP
The current value represented by the slider. Pass NULL if you don't want to retrieve this value.

Returns

Nothing.

Comments

If ctlP is not a slider or a feedback slider, this function immediately returns.

See Also

CtlSetSliderValues()

CtlGetValue Function ^TOP^

Purpose

Returns the current value of the specified control.

Declared In

Control.h

Prototype

int16_t CtlGetValue (
   const ControlType *controlP
)

Parameters

controlP
Pointer to a control.

Returns

The current value of the control. For most controls the return value is either 0 (off) or 1 (on). For sliders, this function returns the current value represented by the slider.

Don't use this function on selector triggers or pop-up triggers.

See Also

CtlSetValue(), FrmGetControlGroupSelection(), FrmSetControlGroupSelection(), FrmGetControlValue(), FrmSetControlValue()

CtlHandleEvent Function ^TOP^

Purpose

Handles events in the specified control.

Declared In

Control.h

Prototype

Boolean CtlHandleEvent (
   ControlType *controlP,
   EventType *pEvent
)

Parameters

controlP
Pointer to a control.
pEvent
Pointer to an EventType structure.

Returns

true if an event is handled by this function or false otherwise.

Comments

The control must be usable, visible, and respond to the pen for this function to handle the event.

Table 16.1 lists the events that this function responds to. For update-based windows, the controls do not redraw immediately. Instead, the region corresponding to the control is invalidated and redrawn on the next drawing update cycle.

Table 16.1  CtlHandleEvent() actions 

When CtlHandleEvent() receives...

CtlHandleEvent() performs these actions...

ctlEnterEvent

Begins tracking the pen. Redraws the control as necessary as either selected or deselected, depending on its previous state. For repeating controls, adds a ctlRepeatEvent to the queue.

ctlRepeatEvent

Tracks the pen and continues to send ctlRepeatEvents at intervals.

frmControlPrvRefreshEvent

Tracks the pen and updates the display.

penDownEvent

Checks if the pen position is within the bounds of the control. If it is, a ctlEnterEvent is added to the event queue and the function exits.

penMoveEvent

Redraws the control as necessary as either selected or deselected, depending on its previous state and if the pen is still within the bounds of the control. For repeating controls, adds a ctlRepeatEvent to the queue.

penUpEvent

If the pen is within the bounds of the control, adds a ctlSelectEvent to the event queue for all controls but repeating buttons. If not, adds ctlExitEvent. Redraws the control as selected or deselected as necessary.

CtlHideControl Function ^TOP^

Purpose

Sets a control to not usable and erases the control from the screen.

Declared In

Control.h

Prototype

void CtlHideControl (
   ControlType *controlP
)

Parameters

controlP
Pointer to the control to hide.

Returns

Nothing.

Comments

Don't call this function directly; instead, use FrmHideObject(), which performs the same function and works for all user interface elements.

A control that is not usable doesn't draw and doesn't respond to the pen.

This function is the same as CtlEraseControl() except that it also makes the control both unusable and not visible. CtlEraseControl() only makes the control not visible.


TIP: In Palm OS Cobalt, hiding an element means filling its region with the color set for UIFormFill. This is true regardless of the type of window used for the form (legacy, transitional, or update-based).

See Also

CtlShowControl()

CtlHitControl Function ^TOP^

Purpose

Simulates tapping a control. This function adds a ctlSelectEvent to the event queue.

Declared In

Control.h

Prototype

void CtlHitControl (
   const ControlType *controlP
)

Parameters

controlP
Pointer to a control.

Returns

Nothing.

Comments

Useful for testing.

CtlIsGraphicControl Function ^TOP^

Purpose

Returns whether or not a control is a graphical control.

Declared In

Control.h

Prototype

Boolean CtlIsGraphicControl (
   ControlType *ctlP
)

Parameters

ctlP
Pointer to the control.

Returns

true if the control indicated by ctlP is a graphical control, a slider, or a feedback slider. Otherwise, it returns false.

CtlNewControl Function ^TOP^

Purpose

Creates a new control dynamically and installs it in the specified form.

Declared In

Control.h

Prototype

ControlType *CtlNewControl (
   void **formPP,
   uint16_t ID,
   ControlStyleType style,
   const char *textP,
   Coord x,
   Coord y,
   Coord width,
   Coord height,
   FontID font,
   uint8_t group,
   Boolean leftAnchor
)

Parameters

formPP
Pointer to the pointer to the form in which the new control is installed. This value is not a handle; that is, the formPP value may change if the structure moves in memory. In subsequent calls, always use the new formPP value returned by this function.
ID
Symbolic ID of the control.
style
A ControlStyleType value specifying the kind of control to create: button, push button, repeating button, check box, pop-up trigger, or selector trigger. To create a graphical control or slider control dynamically, use CtlNewGraphicControl() or CtlNewSliderControl(), respectively.
textP
Pointer to the control's label text. If textP is NULL, the control has no label. Because the contents of this pointer are copied into their own buffer, you can free the textP pointer any time after the CtlNewControl() function returns. The buffer into which this string is copied is freed automatically when you remove the control from the form or delete the form.
x
Horizontal coordinate of the upper-left corner of the control's boundaries, relative to the window in which it appears.
y
Vertical coordinate of the upper-left corner of the control's boundaries, relative to the window in which it appears.
width
Width of the control, expressed in standard coordinates. If the value of either of the width or height parameters is 0, the control is sized automatically as necessary to display the text passed as the value of the textP parameter.
height
Height of the control, expressed in standard coordinates. If the value of either of the width or height parameters is 0, the control is sized automatically as necessary to display the text passed as the value of the textP parameter.
font
Bitmapped font used to draw the control's label. See FontID.
group
Group ID of a push button or a check box that is part of an exclusive group.
leftAnchor
true specifies that the left bound of this control is fixed. This attribute is used by controls that resize dynamically in response to label text changes. It does not affect how the control is resized when the form that contains it is resized.

Returns

A pointer to the new control.

See Also

CtlValidatePointer(), FrmRemoveObject()

CtlNewGraphicControl Function ^TOP^

Purpose

Creates a new graphical control dynamically and installs it in the specified form.

Declared In

Control.h

Prototype

GraphicControlType *CtlNewGraphicControl (
   void **formPP,
   uint16_t ID,
   ControlStyleType style,
   DmOpenRef database,
   DmResourceID bitmapID,
   DmResourceID selectedBitmapID,
   Coord x,
   Coord y,
   Coord width,
   Coord height,
   uint8_t group,
   Boolean leftAnchor
)

Parameters

formPP
Pointer to the pointer to the form in which the new control is installed. This value is not a handle; that is, the formPP value may change if the structure moves in memory. In subsequent calls, always use the new formPP value returned by this function.
ID
Symbolic ID of the control.
style
A ControlStyleType value specifying the kind of control to create: button, push button, pop-up trigger, repeating button, or selector trigger. Graphical controls cannot be check boxes.
database
Open database containing the bitmapID and selectedBitmapID resources.
bitmapID
Resource ID of the bitmap to display on the control.
selectedBitmapID
Resource ID of the bitmap to display when the control is selected, if different from bitmapID.
x
Horizontal coordinate of the upper-left corner of the control's boundaries, relative to the window in which it appears.
y
Vertical coordinate of the upper-left corner of the control's boundaries, relative to the window in which it appears.
width
Width of the control, expressed in standard coordinates.
height
Height of the control, expressed in standard coordinates.
group
Group ID of a push button that is part of an exclusive group.
leftAnchor
true specifies that the left bound of this control is fixed.

Returns

A pointer to the new graphical control.

See Also

CtlNewSliderControl(), CtlNewControl(), CtlValidatePointer(), FrmRemoveObject()

CtlNewSliderControl Function ^TOP^

Purpose

Creates a new slider or feedback slider dynamically and installs it in the specified form.

Declared In

Control.h

Prototype

SliderControlType *CtlNewSliderControl (
   void **formPP,
   uint16_t ID,
   ControlStyleType style,
   DmOpenRef database,
   DmResourceID thumbID,
   DmResourceID backgroundID,
   Coord x,
   Coord y,
   Coord width,
   Coord height,
   uint16_t minValue,
   uint16_t maxValue,
   uint16_t pageSize,
   uint16_t value
)

Parameters

formPP
Pointer to the pointer to the form in which the new control is installed. This value is not a handle; that is, the formPP value may change if the structure moves in memory. In subsequent calls, always use the new formPP value returned by this function.
ID
Symbolic ID of the slider.
style
Either sliderCtl or feedbackSliderCtl. See ControlStyleType.
database
Open database containing the thumbID and backgroundID resources. Pass NULL for this parameter if thumbID and backgroundID are both NULL.
thumbID
Resource ID of the bitmap to display as the slider thumb. The slider thumb is the knob that the user can drag to change the slider's value. To use the default thumb bitmap, pass NULL for this parameter.
backgroundID
Resource ID of the bitmap to display as the slider background. To use the default background bitmap, pass NULL for this parameter.
x
Horizontal coordinate of the upper-left corner of the slider's boundaries, relative to the window in which it appears.
y
Vertical coordinate of the upper-left corner of the slider's boundaries, relative to the window in which it appears.
width
Width of the slider, expressed in standard coordinates.
height
Height of the slider, expressed in standard coordinates.
minValue
Value of the slider when its thumb is all the way to the left.
maxValue
Value of the slider when its thumb is all the way to the right.
pageSize
Amount by which to increase or decrease the slider's value when the user clicks to the right or left of the thumb.
value
The initial value to display in the slider.

Returns

A pointer to the new slider control.

See Also

CtlNewGraphicControl(), CtlNewControl(), CtlValidatePointer(), FrmRemoveObject()

CtlSetEnabled Function ^TOP^

Purpose

Sets a control as enabled or disabled. Disabled controls do not respond to the pen.

Declared In

Control.h

Prototype

void CtlSetEnabled (
   ControlType *controlP,
   Boolean usable
)

Parameters

controlP
Pointer to a control.
usable
true to enable the control; false to disable the control.

Returns

Nothing.

Comments

If you disable a visible control, the control is still displayed, and its appearance is no different from controls that do respond to the pen. You might use such a control to inform your users of some state of your application that cannot be modified.

See Also

CtlEnabled()

CtlSetFont Function ^TOP^

Purpose

Sets the font to use when drawing the control's label.

Declared In

Control.h

Prototype

void CtlSetFont (
   ControlType *ctlP,
   FontID fontID
)

Parameters

ctlP
Pointer to the control.
fontID
The FontID of the bitmapped font to use when drawing the control's label.

Returns

Nothing.

See Also

CtlGetFont()

CtlSetFrameStyle Function ^TOP^

Purpose

Sets the frame style for a button control.

Declared In

Control.h

Prototype

void CtlSetFrameStyle (
   ControlType *ctlP,
   ButtonFrameType frameStyle
)

Parameters

controlP
Pointer to a button control.
frameStyle
Frame style to be applied to the button. Supply one of the values from the ButtonFrameType enum.

Returns

Nothing.

CtlSetGraphics Function ^TOP^

Purpose

Sets the bitmaps for a graphical control and redraws the control if it is visible.

Declared In

Control.h

Prototype

void CtlSetGraphics (
   ControlType *ctlP,
   DmOpenRef database,
   DmResourceID newBitmapID,
   DmResourceID newSelectedBitmapID
)

Parameters

ctlP
Pointer to a graphical control.
database
Open resource database containing the newBitmapID and newSelectedBitmapID resources.
newBitmapID
Resource ID of a new bitmap to display on the control, or NULL to use the current bitmap.
newSelectedBitmapID
Resource ID of a new bitmap to display when the control is selected, or NULL to use the current selected bitmap.

Returns

Nothing.

Comments

If ctlP is not a graphical control, this function immediately returns.

See Also

CtlGetGraphics()

CtlSetLabel Function ^TOP^

Purpose

Sets the current label for the specified control and redraws the control if it is visible.

Declared In

Control.h

Prototype

void CtlSetLabel (
   ControlType *controlP,
   const char *newLabel
)

Parameters

controlP
Pointer to a control.
newLabel
Pointer to the new text label. Must be a null-terminated string.

Returns

Nothing.

Comments

This function resizes the width of the control to the size of the new label.

This function stores the newLabel pointer in the control's data structure. It doesn't make a copy of the string that is passed in. Therefore, if you use CtlSetLabel(), you must manage the string yourself. You must ensure that it persists for as long as it is being displayed (that is, for as long as the control is displayed or until you call CtlSetLabel() with a new string), and you must free the string after it is no longer in use (typically after the form containing the control is freed).

If you never use CtlSetLabel(), you do not need to worry about freeing a control's label.

Make sure that controlP is not a graphical control or a slider control. The graphical controls and slider control structures do not contain a text label field, so attempting to set one will crash your application.


TIP: Label resources are not controls. To change the text of a label resource, use FrmCopyLabel().

See Also

CtlGetLabel()

CtlSetLeftAnchor Function ^TOP^

Purpose

Causes a control's left bound to be fixed or to float.

Declared In

Control.h

Prototype

void CtlSetLeftAnchor (
   ControlType *ctlP,
   Boolean leftAnchor
)

Parameters

ctlP
Pointer to the control.
leftAnchor
A value of true causes the left bound of the control to be fixed.

Returns

Nothing.

Comments

Used by controls that expand and shrink their width when the label is changed.

CtlSetSliderValues Function ^TOP^

Purpose

Changes a slider control's values and redraws the slider if it is visible.

Declared In

Control.h

Prototype

void CtlSetSliderValues (
   ControlType *ctlP,
   const uint16_t *minValueP,
   const uint16_t *maxValueP,
   const uint16_t *pageSizeP,
   const uint16_t *valueP
)

Parameters

ctlP
Pointer to an inactive slider or feedback slider control.
minValueP
Pointer to a new value to use for the slider's minimum or NULL if you don't want to change this value. The minimum is the value of the slider when the thumb is all the way to the left.
maxValueP
Pointer to a new value to use for the slider's maximum, or NULL if you don't want to change this value. The maximum is the value of the slider when the thumb is all the way to the right.
pageSizeP
Pointer to a new value to use for the slider's page size, or NULL if you don't want to change this value. The page size is the amount by which to increase or decrease the slider value when the user taps to the right or left of the thumb.
valueP
Pointer to a new value to use for the current value, or NULL if you don't want to change this value.

Returns

Nothing.

Comments

The control's style must be sliderCtl or feedbackSliderCtl, and it must not be currently tracking the pen. If the slider is currently tracking the pen, use CtlSetValue() to set the value field.

See Also

CtlGetSliderValues()

CtlSetUsable Function ^TOP^

Purpose

Sets a control to usable or not usable.

Declared In

Control.h

Prototype

void CtlSetUsable (
   ControlType *controlP,
   Boolean usable
)

Parameters

controlP
Pointer to a control.
usable
true to have the control be usable; false to have the control be not usable.

Returns

Nothing.

Comments

A control that is not usable doesn't draw and doesn't respond to the pen.

This function doesn't usually update the control.

See Also

CtlEraseControl(), CtlHideControl(), CtlShowControl()

CtlSetValue Function ^TOP^

Purpose

Sets the current value of the specified control. If the control is visible, it's redrawn.

Declared In

Control.h

Prototype

void CtlSetValue (
   ControlType *controlP,
   int16_t newValue
)

Parameters

controlP
Pointer to a control.
newValue
New value to set for the control. For sliders, specify a value between the slider's minimum and maximum. For graphical controls, push buttons, or check boxes, specify 0 for off, nonzero for on.

Returns

Nothing.

Comments

Don't use this function on pop-up triggers or selector triggers.

See Also

CtlGetValue(), FrmGetControlGroupSelection(), FrmSetControlGroupSelection(), FrmGetControlValue(), FrmSetControlValue()

CtlShowControl Function ^TOP^

Purpose

Sets a control's usable attribute to true and draws the control on the screen.

Declared In

Control.h

Prototype

void CtlShowControl (
   ControlType *controlP
)

Parameters

controlP
Pointer to a control.

Returns

Nothing.

Comments

Don't use this function directly; instead use FrmShowObject(), which does the same thing.

See Also

CtlHideControl()

CtlValidatePointer Function ^TOP^

Purpose

Returns true if the specified pointer references a valid control.

Declared In

Control.h

Prototype

Boolean CtlValidatePointer (
   const ControlType *controlP
)

Parameters

controlP
Pointer to a control.

Returns

true when passed a valid pointer to a control; otherwise, false.

Comments

For debugging purposes; do not include this function in commercial products. In debug builds, this function displays a dialog and waits for the debugger when an error occurs.

See Also

FrmValidatePtr(), WinValidateHandle()