This chapter describes the control object API as declared in the header file Control.h. It discusses the following topics:
Control Data Structures
Control Resources
Control Functions
For more information on controls, see the section "Controls" in the Palm OS Programmer's Companion, vol. I.
Control Data Structures

ButtonFrameType

The ButtonFrameType enum specifies the border style for the button. It defines values for the frame field of ControlAttrType.
enum buttonFrames {noButtonFrame,
standardButtonFrame, boldButtonFrame,
rectangleButtonFrame};
typedef enum buttonFrames ButtonFrameType;
Value Descriptions
noButtonFrame |
The button has no border. |
standardButtonFrame |
Standard button rectangular border with rounded corners. |
boldButtonFrame |
Bolded rectangular border with rounded corners. |
rectangleButtonFrame |
Rectangular border with square corners. |
ControlAttrType

The ControlAttrType bit field specifies the control's visible characteristics. It is defined as follows:
typedef struct {
UInt8 usable :1;
UInt8 enabled :1;
UInt8 visible :1;
UInt8 on :1;
UInt8 leftAnchor :1;
UInt8 frame :3;
UInt8 drawnAsSelected : 1;
UInt8 graphical :1;
UInt8 vertical :1;
} ControlAttrType;
WARNING! Palm, Inc. does not support or provide backward compatibility for the ControlAttrType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Your code should treat the ControlAttrType structure as opaque. Use the functions specified in the descriptions below to retrieve and set each value. Do not attempt to change structure member values directly.
Field Descriptions
usable |
If 0, the control is not considered to be part of the interface of the current application, and it doesn't appear on screen. You can use CtlSetUsable, CtlShowControl, or CtlHideControl to set or clear this value. |
enabled |
If 0, the control is visible but doesn't respond to the pen. This value is set by CtlSetEnabled and returned by CtlEnabled. |
visible |
Set and cleared internally when the control is drawn ( CtlDrawControl) and erased ( CtlEraseControl). |
on |
If set, the control has the value "on." For example, a check box that has the on value has a check mark displayed in it. Use CtlGetValue and CtlSetValue to retrieve and set this value. |
leftAnchor |
Used by controls that expand and shrink their width when the label is changed. If this attribute is set, the left bound of the control is fixed. |
frame |
The type of frame drawn around the button controls. See ButtonFrameType for possible values. Only button controls use this attribute; for all other controls, the ControlStyleType determines the frame. |
drawnAsSelected |
Used on Palm OS® release 3.5 for button controls that contain no text (indicating that the button is displayed on top of a bitmap). If set, the button is drawn as inverted. If clear, the button is drawn normally. |
graphical |
If set, the control is a graphical control, slider, or feedback slider. |
vertical |
Not currently used. |
Compatibility
The drawnAsSelected, graphical, and vertical attributes are only present if 3.5 New Feature Set is present.
ControlPtr

The ControlPtr is a pointer to a ControlType structure.
typedef ControlType* ControlPtr;
ControlStyleType

The ControlStyleType enum specifies values for the ControlType style field, which specifies the type of the control (button, push button, and so on).
enum controlStyles {buttonCtl, pushButtonCtl,
checkboxCtl, popupTriggerCtl,
selectorTriggerCtl, repeatingButtonCtl,
sliderCtl, feedbackSliderCtl};
typedef enum controlStyles ControlStyleType;
Value Descriptions
buttonCtl |
Button. 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 |
Popup trigger. Popup triggers display a graphic element followed by a text label. They are used to display popup 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. |
Compatibility
The sliderCtl and feedbackSliderCtl values are only defined if 3.5 New Feature Set is present.
ControlType

The ControlType structure defines the type and characteristics of a control. It is defined as follows:
typedef struct {
UInt16 id;
RectangleType bounds;
Char * text;
ControlAttrType attr;
ControlStyleType style;
FontID font;
UInt8 group;
UInt8 reserved;
} ControlType;
WARNING! Palm, Inc. does not support or provide backward compatibility for the ControlType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Your code should treat the ControlType structure as opaque. The fields in the struct are set by values you specify when you create the control resource, and they typically do not change. Use the functions specified in the descriptions below to retrieve and set the values. Do not attempt to change structure member values directly.
Field Descriptions
id |
ID value you specified when you created the control resource. |
bounds |
Bounds of the control, in window-relative coordinates. The control's text label is clipped to the control's bounds. The control's frame is drawn around (outside) the bounds of the control. FrmGetObjectBounds and FrmSetObjectBounds retrieve and set this value. |
text |
Pointer to the control's label. If text is NULL, the control has no label. Use CtlGetLabel and CtlSetLabel to retrieve and set this value. |
attr |
Control attributes. See ControlAttrType. |
style |
Style of the control. See ControlStyleType. |
font |
Font to use to draw the control's label. |
group |
Group ID of a push button or a check box that is part of an exclusive group. The control routines don't automatically turn one control off when another is selected. It's up to the application or a higher-level object, like a dialog box, to manage this. |
reserved |
Reserved for future use. |
GraphicControlType

The GraphicControlType struct defines a graphical control. A graphical control is like any other control except that it displays a bitmap in place of the text label.
typedef struct GraphicControlType {
UInt16 id;
RectangleType bounds;
DmResID bitmapID;
DmResID selectedBitmapID;
ControlAttrType attr;
ControlStyleType style;
FontID unused;
UInt8 group;
UInt8 reserved;
} GraphicControlType;
WARNING! Palm, Inc. does not support or provide backward compatibility for the GraphicControlType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Your code should treat the GraphicControlType structure as opaque. The fields in the struct are set by values you specify when you create the control resource, and they typically do not change. Use the functions specified in the descriptions below to retrieve and set the values. Do not attempt to change structure member values directly.
Field Descriptions
id |
ID value you specified when you created the control resource. |
bounds |
Bounds of the control, in window-relative coordinates. The control's frame is drawn around (outside) the bounds of the control. FrmGetObjectBounds and FrmSetObjectBounds retrieve and set this value. |
bitmapID |
Resource ID of the bitmap to display in the button. You can use CtlSetGraphics to change this value. |
selectedBitmapID |
If the button should show a different bitmap when selected, this field contains the resource ID of that bitmap. You typically use this field for push buttons or repeating buttons. CtlSetGraphics can change this value. |
attr |
Control attributes. See ControlAttrType. For a graphical control, the graphical attribute must be set. The APIs described in the ControlAttrType section can be used to access the bitfields here. Because the ControlAttrType APIs take a ControlType* as an argument, the GraphicControlType* should be cast to a ControlType* when making the API calls. |
style |
Style of the control. See ControlStyleType. A graphical control can be any type of control other than checkboxCtl. |
unused |
Unused. |
group |
Group ID of a push button that is part of an exclusive group. The control routines don't automatically turn one control off when another is selected. It's up to the application or a higher-level object, like a dialog box, to manage this. |
reserved |
Reserved for future use. |
Compatibility
This struct is defined only if 3.5 New Feature Set is present.
SliderControlType

The SliderControlType struct defines a slider control or a feedback slider control.
typedef struct SliderControlType {
UInt16 id;
RectangleType bounds;
DmResID thumbID;
DmResID backgroundID;
ControlAttrType attr;
ControlStyleType style;
UInt8 reserved;
Int16 minValue;
Int16 maxValue;
Int16 pageSize;
Int16 value;
MemPtr activeSliderP;
} SliderControlType;
WARNING! Palm, Inc. does not support or provide backward compatibility for the SliderControlType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Your code should treat the SliderControlType structure as opaque. The fields in the struct are set by values you specify when you create the control resource, and they typically do not change. You can use CtlSetSliderValues to set new minimum, maximum, page size, and current values, and CtlGetSliderValues to retrieve these values. Do not attempt to change structure member values directly.
Field Descriptions
id |
ID value you specified when you created the control resource. |
bounds |
Bounds of the control, in window-relative coordinates. FrmGetObjectBounds and FrmSetObjectBounds retrieve and set this value. |
thumbID |
Resource ID of the bitmap to use for the slider knob (called the "thumb"). If NULL, the default bitmap is used. |
backgroundID |
Resource ID of the bitmap to use for the slider background. If NULL, the default bitmap is used. |
attr |
Control attributes. See ControlAttrType. For a slider, the graphical attribute is set. The APIs described in the ControlAttrType section can be used to access the bitfields here. Because the ControlAttrType APIs take a ControlType* as an argument, the SliderControlType* should be cast to a ControlType* when making the API calls. |
style |
Style of the control. See ControlStyleType. Must be sliderCtl or feedbackSliderCtl. |
reserved |
Reserved for future use. |
minValue |
Value of the slider when the thumb is all the way to the left. |
maxValue |
Value of the slider when the thumb is all the way to the right. |
pageSize |
Amount by which to increase or decrease the slider value when the user taps to the right or left of the thumb. |
value |
Current value represented by the slider. Use CtlGetValue and CtlSetValue to retrieve and set this value. |
activeSliderP |
Pointer to a memory location used when the slider is active. A slider is active if it is currently being drawn or if it is tracking the pen. If the slider is inactive, this pointer is NULL. |
Compatibility
This struct is defined only if 3.5 New Feature Set is present.
Control Resources

Different resources are associated with different controls, as follows:
Button-Button Resource (tBTN)
Popup trigger- Popup Trigger Resource (tPUT)
Selector trigger-Selector Trigger Resource (tSLT)
Repeat control-Repeating Button Resource (tREP)
Push button-Push Button Resource (tPBN)
Check box-Check Box Resource (tCBX)
Slider- Slider Resource (tsld)
Feedback slider- Feedback Slider Resource (tslf)
Control Functions

CtlDrawControl

Purpose
Draw a control object (and the text or graphic in it) on screen.
Prototype
void CtlDrawControl (ControlType *controlP)
Parameters
-> controlP | Pointer to the control object to draw. (See ControlType.) |
Result
Returns nothing.
Comments
The control is drawn only if its usable attribute is true. This function sets the visible attribute to true.
Compatibility
In releases prior to Palm OS® 3.5, it is common to create graphical buttons by drawing a button with no text label on top of a bitmap. If 3.5 New Feature Set is present, you should use graphical controls instead. (See GraphicControlType.) CtlDrawControl attempts to provide backward compatibility for the old-style graphical buttons.
See Also
CtlSetUsable, CtlShowControl
CtlEnabled

Purpose
Return true if the control responds to the pen.
Prototype
Boolean CtlEnabled (const ControlType *controlP)
Parameters
-> controlP | Pointer to control object. (See ControlType.) |
Result
Returns true if the controls object 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

Purpose
Erase a usable and visible control object and its frame from the screen.
Prototype
void CtlEraseControl (ControlType *controlP)
Parameters
-> controlP | Pointer to control object to erase. (See ControlType.) |
Comments
This function sets the visible attribute to false. If 3.5 New Feature Set is present, it also sets the drawnAsSelected attribute to false.
Don't call this function directly; instead, use FrmHideObject, which calls this function.
CtlGetLabel

Purpose
Return a character pointer to a control's text label.
Prototype
const Char *CtlGetLabel (const ControlType *controlP)
Parameters
-> controlP | Pointer to control object. (See ControlType.) |
Result
Returns a pointer to a null-terminated string.
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.
See Also
CtlSetLabel
CtlGetSliderValues

Purpose
Return current values used by a slider control.
Prototype
void CtlGetSliderValues (const ControlType *ctlP, UInt16 *minValueP, UInt16 *maxValueP, UInt16 *pageSizeP, UInt16 *valueP)
Parameters
<- minValueP | The slider's minimum value. Pass NULL if you don't want to retrieve this value. |
<- maxValueP | The slider's maximum value. Pass NULL if you don't want to retrieve this value. |
<- pageSizeP | The slider's page size value. Pass NULL if you don't want to retrieve this value. |
<- valueP | The slider's current value. Pass NULL if you don't want to retrieve this value. |
Result
Returns nothing. The slider's values are returned in the parameters to this function.
Comments
If ctlP is not a slider or a feedback slider, this function immediately returns.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
CtlSetSliderValues, SliderControlType
CtlGetValue

Purpose
Return the current value of the specified control.
Prototype
Int16 CtlGetValue (const ControlType *controlP)
Parameters
-> controlP | Pointer to a control object. (See ControlType.) |
Result
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 value of the value field.
See Also
CtlSetValue, FrmGetControlGroupSelection, FrmSetControlGroupSelection, FrmGetControlValue, FrmSetControlValue
CtlHandleEvent

Purpose
Handle event in the specified control object.
Prototype
Boolean CtlHandleEvent (ControlType *controlP, EventType *pEvent)
Parameters
-> controlP | Pointer to control object. (See ControlType.) |
-> pEvent | Pointer to an EventType structure. |
Result
Returns true if an event is handled by this function. Events that are handled are:
penDownEvent - If the pen is within the bounds of the control
ctlEnterEvent, ctlRepeatEvent, and ctlExitEvent- If the control ID in the event data matches the control's ID.
Comments
The control object must be usable, visible, and respond to the pen for this function to handle the event.
When this routine receives a penDownEvent, it checks if the pen position is within the bounds of the control object. If it is, a ctlEnterEvent is added to the event queue and the routine exits.
When this routine receives a ctlEnterEvent, the control object is redrawn as necessary as either selected or deselected, depending on its previous state.
When this routine receives a ctlEnterEvent or ctlRepeatEvent, it checks that the control ID in the passed event record matches the ID of the specified control. If they match, this routine tracks the pen until it comes up or until it leaves the object's bounds. When that happens, ctlSelectEvent is sent to the event queue if the pen came up in the bounds of the control. If the pen exits the bounds, a ctlExitEvent is sent to the event queue.
CtlHideControl

Purpose
Set a control's usable attribute to false and erase the control from the screen.
Prototype
void CtlHideControl (ControlType *controlP)
Parameters
-> controlP | Pointer to the control object to hide. (See ControlType.) |
Result
Returns nothing.
Comments
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 sets usable to false (in addition to setting visible to false).
Don't call this function directly; instead, use FrmHideObject, which performs the same function and works for all user interface objects.
See Also
CtlShowControl
CtlHitControl

Purpose
Simulate tapping a control. This function adds a ctlSelectEvent to the event queue.
Prototype
void CtlHitControl (const ControlType *controlP)
Parameters
-> controlP | Pointer to a control object. (See ControlType.) |
Result
Returns nothing.
Comments
Useful for testing.
CtlNewControl

Purpose
Create a new control object dynamically and install it in the specified form.
Prototype
ControlType *CtlNewControl (void **formPP, UInt16 ID, ControlStyleType style, const Char *textP, Coord x, Coord y, Coord width, Coord height, FontID font, UInt8 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 object 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, popup trigger, or popup selector. 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. Only buttons, push buttons, and text boxes have text labels. 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 pixels. Valid values are 1-160. 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 text parameter. |
-> height | Height of the control, expressed in pixels. Valid values are 1-160. 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 text parameter. |
-> font | Font used to draw the control's label. |
-> group | Group ID of a push button or a check box that is part of an exclusive group. The control routines don't turn one control off automatically when another is selected. It's up to the application or a higher-level object, such as a dialog box, to manage this. |
-> 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. |
Result
Returns a pointer to the new control.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
CtlValidatePointer, FrmRemoveObject
CtlNewGraphicControl

Purpose
Create a new graphical control dynamically and install it in the specified form.
Prototype
GraphicControlType *CtlNewGraphicControl (void **formPP, UInt16 ID, ControlStyleType style, DmResID bitmapID, DmResID selectedBitmapID, Coord x, Coord y, Coord width, Coord height, UInt8 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 object 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, popup trigger, repeating button, or popup selector. Graphic controls cannot be check boxes. |
-> 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 pixels. Valid values are 1-160. |
-> height | Height of the control, expressed in pixels. Valid values are 1-160. |
-> group | Group ID of a push button that is part of an exclusive group. The control routines don't turn one control off automatically when another is selected. It's up to the application or a higher-level object, such as a dialog box, to manage this. |
-> leftAnchor | true specifies that the left bound of this control is fixed. |
Result
Returns a pointer to the new graphical control. See GraphicControlType.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
CtlNewSliderControl, CtlNewControl, CtlValidatePointer, FrmRemoveObject
CtlNewSliderControl

Purpose
Create a new slider or feedback slider dynamically and install it in the specified form.
Prototype
SliderControlType *CtlNewSliderControl (void **formPP, UInt16 ID, ControlStyleType style, DmResID thumbID, DmResID backgroundID, Coord x, Coord y, Coord width, Coord height, UInt16 minValue, UInt16 maxValue, UInt16 pageSize, UInt16 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 object moves in memory. In subsequent calls, always use the new formPP value returned by this function. |
-> ID | Symbolic ID of the slider. |
-> 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 pixels. Valid values are 1-160. |
-> height | Height of the slider, expressed in pixels. Valid values are 1-160. |
-> 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. |
Result
Returns a pointer to the new slider control. See SliderControlType.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
CtlNewGraphicControl, CtlNewControl, CtlValidatePointer, FrmRemoveObject
CtlSetEnabled

Purpose
Set a control as enabled or disabled. Disabled controls do not respond to the pen.
Prototype
void CtlSetEnabled (ControlType *controlP, Boolean usable)
Parameters
-> controlP | Pointer to a control object. (See ControlType.) |
-> usable | true to enable the control; false to disable the control. |
Result
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
CtlSetGraphics

Purpose
Set the bitmaps for a graphical control and redraw the control if it is visible.
Prototype
void CtlSetGraphics (ControlType *ctlP, DmResID newBitmapID, DmResID newSelectedBitmapID)
Parameters
-> 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. |
Result
Returns nothing.
Comments
If ctlP is not a graphical control, this function immediately returns.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
GraphicControlType
CtlSetLabel

Purpose
Set the current label for the specified control object and redraw the control if it is visible.
Prototype
void CtlSetLabel (ControlType *controlP, const Char *newLabel)
Parameters
-> controlP | Pointer to a control object. (See ControlType.) |
-> newLabel | Pointer to the new text label. Must be a NULL-terminated string. |
Result
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.
See Also
CtlGetLabel
CtlSetSliderValues

Purpose
Change a slider control's values and redraw the slider if it is visible.
Prototype
void CtlSetSliderValues (ControlType *ctlP, const UInt16 *minValueP, const UInt16 *maxValueP, const UInt16 *pageSizeP, const UInt16 *valueP)
Parameters
-> ctlP | Pointer to an inactive slider or feedback slider control. (See SliderControlType.) |
-> minValueP | Pointer to a new value to use for the slider's minimum or NULL if you don't want to change this value. |
-> maxValueP | Pointer to a new value to use for the slider's maximum, or NULL if you don't want to change this value. |
-> 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. |
-> valueP | Pointer to a new value to use for the current value, or NULL if you don't want to change this value. |
Result
Returns nothing.
Comments
The control's style must be sliderCtl or feedbackSliderCtl, and it not be currently tracking the pen. If the slider is currently tracking the pen, use CtlSetValue to set the value field.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
CtlGetSliderValues, SliderControlType
CtlSetUsable

Purpose
Set a control to usable or not usable.
Prototype
void CtlSetUsable (ControlType *controlP, Boolean usable)
Parameters
-> controlP | Pointer to a control object. (See ControlType.) |
-> usable | true to have the control be usable; false to have the control be not usable. |
Result
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

Purpose
Set the current value of the specified control. If the control is visible, it's redrawn.
Prototype
void CtlSetValue (ControlType *controlP, Int16 newValue)
Parameters
-> controlP | Pointer to a control object. (See ControlType.) |
-> 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. |
Result
Returns nothing.
Comments
This function works only with graphical controls, sliders, push buttons, and check boxes. If you set the value of any other type of control, the behavior is undefined.
Compatibility
Sliders and graphical controls are only supported if 3.5 New Feature Set is present.
See Also
CtlGetValue, FrmGetControlGroupSelection, FrmSetControlGroupSelection, FrmGetControlValue, FrmSetControlValue
CtlShowControl

Purpose
Set a control's usable attribute to true and draw the control on the screen. This function calls CtlDrawControl.
Prototype
void CtlShowControl (ControlType *controlP)
Parameters
-> controlP | Pointer to a control object. (See ControlType.) |
Result
Returns nothing.
Comments
If the control is already usable, this function is the functional equivalent of CtlDrawControl.
Sets the visible and the usable attributes to true. (See ControlAttrType.)
Don't use this function directly; instead use FrmShowObject, which does the same thing.
See Also
CtlHideControl
CtlValidatePointer

Purpose
Returns true if the specified pointer references a valid control object.
Prototype
Boolean CtlValidatePointer (const ControlType *controlP)
Parameters
Result
Returns true when passed a valid pointer to a control; otherwise, returns 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.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
FrmValidatePtr, WinValidateHandle
|