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

7    Controls

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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

ButtonFrameType Enum ^TOP^

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

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(), 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 Typedef ^TOP^

Purpose

The ControlPtr is a pointer to a ControlType structure.

Prototype

typedef ControlType *ControlPtr;

ControlStyleType Enum ^TOP^

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

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() 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 Struct ^TOP^

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() 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 Struct ^TOP^

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

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

CtlDrawControl Function ^TOP^

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

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

Purpose

Return true if the control responds to the pen.

Declared In

Control.h

Prototype

Boolean CtlEnabled (
   constControlType*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

CtlSetEnabled()

CtlEraseControl Function ^TOP^

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

Purpose

Return a character pointer to a control's text label.

Declared In

Control.h

Prototype

const Char *CtlGetLabel(
   constControlType*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

CtlSetLabel()

CtlGetSliderValues Function ^TOP^

Purpose

Return current values used by a slider control.

Declared In

Control.h

Prototype

void CtlGetSliderValues (
   constControlType*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 ^TOP^

Purpose

Return the current value of the specified control.

Declared In

Control.h

Prototype

Int16 CtlGetValue (
   constControlType*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 ^TOP^

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:

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

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

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

Purpose

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

Declared In

Control.h

Prototype

void CtlHitControl (
   constControlType*controlP
)

Parameters

controlP
Pointer to a control object. (See ControlType.)

Returns

Returns nothing.

Comments

Useful for testing.

CtlNewControl Function ^TOP^

Purpose

Create a new control object dynamically and install it in the specified form.

Declared In

Control.h

Prototype

ControlType *CtlNewControl (
   void**formPP,
   UInt16ID,
   ControlStyleTypestyle,
   constChar*textP,
   Coordx,
   Coordy,
   Coordwidth,
   Coordheight,
   FontIDfont,
   UInt8group,
   BooleanleftAnchor
)

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.

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

Purpose

Create a new graphical control dynamically and install it in the specified form.

Declared In

Control.h

Prototype

GraphicControlType *CtlNewGraphicControl(
   void**formPP,
   UInt16ID,
   ControlStyleTypestyle,
   DmResIDbitmapID,
   DmResIDselectedBitmapID,
   Coordx,
   Coordy,
   Coordwidth,
   Coordheight,
   UInt8group,
   BooleanleftAnchor
)

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.

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

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,
   UInt16ID,
   ControlStyleTypestyle,
   DmResIDthumbID,
   DmResIDbackgroundID,
   Coordx,
   Coordy,
   Coordwidth,
   Coordheight,
   UInt16minValue,
   UInt16maxValue,
   UInt16pageSize,
   UInt16value
)

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.
style
Either sliderCtl or feedbackSliderCtl. See ControlStyleType.
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 ^TOP^

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

Parameters

controlP
Pointer to a control object. (See ControlType.)
usable
true to enable the control; false to disable the control.

Returns

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

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,
   DmResIDnewBitmapID,
   DmResIDnewSelectedBitmapID
)

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

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

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,
   constChar*newLabel
)

Parameters

controlP
Pointer to a control object. (See ControlType.)
newLabel
Pointer to the new text label. Must be a null-terminated string.

Returns

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

Purpose

Change a slider control's values and redraw the slider if it is visible.

Declared In

Control.h

Prototype

void CtlSetSliderValues (
   ControlType*ctlP,
   constUInt16*minValueP,
   constUInt16*maxValueP,
   constUInt16*pageSizeP,
   constUInt16*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

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

Purpose

Set a control to usable or not usable.

Declared In

Control.h

Prototype

void CtlSetUsable (
   ControlType*controlP,
   Booleanusable
)

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

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

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

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

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

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

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

Purpose

Returns true if the specified pointer references a valid control object.

Declared In

Control.h

Prototype

Boolean CtlValidatePointer(
   constControlType*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()