This chapter describes the control object API as declared in the header file Control.h
. It discusses the following topics:
For more information on controls, see the section "Offscreen Windows" in the Palm OS Programmer's Companion, vol. I.
Control Data Structures
ButtonFrameType Enum
Purpose
The ButtonFrameType
enum specifies the border style for the button. It defines values for the frame
field of ControlAttrType
.
Prototype
enum buttonFrames {noButtonFrame, standardButtonFrame, boldButtonFrame, rectangleButtonFrame};
typedef enum buttonFrames ButtonFrameType;
Constants
-
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 Struct
Purpose
The ControlAttrType
bit field specifies the control's visible characteristics. It is defined as follows:
Prototype
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! PalmSource, 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.
Fields
-
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()
, orCtlHideControl()
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 byCtlEnabled()
. -
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()
andCtlSetValue()
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, theControlStyleType
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 Typedef
Purpose
The ControlPtr
is a pointer to a ControlType
structure.
Prototype
typedef ControlType *ControlPtr;
ControlStyleType Enum
Purpose
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;
Constants
-
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 Struct
Purpose
The ControlType
structure defines the type and characteristics of a control. It is defined as follows:
Prototype
typedef struct { UInt16 id; RectangleType bounds; Char *text; ControlAttrType attr; ControlStyleType style; FontID font; UInt8 group; UInt8 reserved; } ControlType;
WARNING! PalmSource, 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.
Fields
-
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()
andFrmSetObjectBounds()
retrieve and set this value. -
text
- Pointer to the control's label. If
text
isNULL
, the control has no label. UseCtlGetLabel()
andCtlSetLabel()
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 Struct
Purpose
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.
Prototype
typedef struct GraphicControlType { UInt16 id; RectangleType bounds; DmResID bitmapID; DmResID selectedBitmapID; ControlAttrType attr; ControlStyleType style; FontID unused; UInt8 group; UInt8 reserved; } GraphicControlType;
WARNING! PalmSource, 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.
Fields
-
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()
andFrmSetObjectBounds()
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, thegraphical
attribute must be set. The APIs described in theControlAttrType
section can be used to access the bitfields here. Because theControlAttrType
APIs take aControlType*
as an argument, theGraphicControlType*
should be cast to aControlType*
when making the API calls. -
style
- Style of the control. See
ControlStyleType
. A graphical control can be any type of control other thancheckboxCtl
. -
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 Struct
Purpose
The SliderControlType
struct defines a slider control or a feedback slider control.
Prototype
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! PalmSource, 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.
Fields
-
id
- ID value you specified when you created the control resource.
-
bounds
- Bounds of the control, in window-relative coordinates.
FrmGetObjectBounds()
andFrmSetObjectBounds()
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, thegraphical
attribute is set. The APIs described in theControlAttrType
section can be used to access the bitfields here. Because theControlAttrType
APIs take aControlType*
as an argument, theSliderControlType*
should be cast to aControlType*
when making the API calls. -
style
- Style of the control. See
ControlStyleType
. Must besliderCtl
orfeedbackSliderCtl
. -
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()
andCtlSetValue()
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)
See Palm OS User Interface Guidelines for more information.
Control Functions
CtlDrawControl Function
Purpose
Draw a control object (and the text or graphic in it) on screen.
Declared In
Control.h
Prototype
void CtlDrawControl ( ControlType *controlP )
Parameters
-
→
controlP
- Pointer to the control object to draw. (See
ControlType
.)
Returns
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 Function
Purpose
Return true
if the control responds to the pen.
Declared In
Control.h
Prototype
Boolean CtlEnabled ( const ControlType *controlP )
Parameters
-
→
controlP
- Pointer to control object. (See
ControlType
.)
Returns
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
CtlEraseControl Function
Purpose
Erase a usable and visible control object and its frame from the screen.
Declared In
Control.h
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 Function
Purpose
Return a character pointer to a control's text label.
Declared In
Control.h
Prototype
const Char *CtlGetLabel( const ControlType *controlP )
Parameters
-
→
controlP
- Pointer to control object. (See
ControlType
.)
Returns
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
CtlGetSliderValues Function
Purpose
Return current values used by a slider control.
Declared In
Control.h
Prototype
void CtlGetSliderValues ( const ControlType *ctlP, UInt16 *minValueP, UInt16 *maxValueP, UInt16 *pageSizeP, UInt16 *valueP )
Parameters
-
→
ctlP
- Pointer to a control object. (See
ControlType
.) -
←
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.
Returns
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 Function
Purpose
Return the current value of the specified control.
Declared In
Control.h
Prototype
Int16 CtlGetValue ( const ControlType *controlP )
Parameters
-
→
controlP
- Pointer to a control object. (See
ControlType
.)
Returns
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 Function
Purpose
Handle event in the specified control object.
Declared In
Control.h
Prototype
Boolean CtlHandleEvent ( ControlType *controlP, EventType *pEvent )
Parameters
-
→
controlP
- Pointer to control object. (See
ControlType
.) -
→
pEvent
- Pointer to an EventType structure.
Returns
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
, andctlExitEvent
— 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 Function
Purpose
Set a control's usable
attribute to false
and erase the control from the screen.
Declared In
Control.h
Prototype
void CtlHideControl ( ControlType *controlP )
Parameters
-
→
controlP
- Pointer to the control object to hide. (See
ControlType
.)
Returns
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
CtlHitControl Function
Purpose
Simulate 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 object. (See
ControlType
.)
Returns
Comments
CtlNewControl Function
Purpose
Create a new control object dynamically and install it in the specified form.
Declared In
Control.h
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 newformPP
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, useCtlNewGraphicControl()
orCtlNewSliderControl()
, respectively. -
textP
- Pointer to the control's label text. If
textP
isNULL
, 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 thetextP
pointer any time after theCtlNewControl
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
orheight
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
orheight
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.
Returns
Returns a pointer to the new control.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
CtlValidatePointer()
, FrmRemoveObject()
CtlNewGraphicControl Function
Purpose
Create a new graphical control dynamically and install it in the specified form.
Declared In
Control.h
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 newformPP
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.
Returns
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 Function
Purpose
Create a new slider or feedback slider dynamically and install it in the specified form.
Declared In
Control.h
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 newformPP
value returned by this function. -
→
ID
- Symbolic ID of the slider.
-
→
style
- Either
sliderCtl
orfeedbackSliderCtl
. SeeControlStyleType
. -
→
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.
Returns
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 Function
Purpose
Set 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 object. (See
ControlType
.) -
→
usable
-
true
to enable the control;false
to disable the control.
Returns
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
CtlSetGraphics Function
Purpose
Set the bitmaps for a graphical control and redraw the control if it is visible.
Declared In
Control.h
Prototype
void CtlSetGraphics ( ControlType *ctlP, DmResID newBitmapID, DmResID newSelectedBitmapID )
Parameters
-
→
ctlP
- Pointer to a graphical control object. (See
GraphicControlType
.) -
→
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
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
CtlSetLabel Function
Purpose
Set the current label for the specified control object and redraw the control if it is visible.
Declared In
Control.h
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.
Returns
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
CtlSetSliderValues Function
Purpose
Change a slider control's values and redraw the slider if it is visible.
Declared In
Control.h
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.
Returns
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 Function
Purpose
Set a control to usable or not usable.
Declared In
Control.h
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.
Returns
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
Purpose
Set 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 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.
Returns
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 Function
Purpose
Set a control's usable
attribute to true
and draw the control on the screen. This function calls CtlDrawControl()
.
Declared In
Control.h
Prototype
void CtlShowControl ( ControlType *controlP )
Parameters
-
→
controlP
- Pointer to a control object. (See
ControlType
.)
Returns
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
CtlValidatePointer Function
Purpose
Returns true
if the specified pointer references a valid control object.
Declared In
Control.h
Prototype
Boolean CtlValidatePointer( const ControlType *controlP )
Parameters
-
→ controlP
- Pointer to a control. (See
ControlType
.)
Returns
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()