< Home < Developers < Development Support < Documentation

## 7 Controls

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part I: User Interface 7 Controls Control Data Structures ButtonFrameType ControlAttrType ControlPtr ControlStyleType ControlType GraphicControlType SliderControlType Control Resources Control Functions CtlDrawControl CtlEnabled CtlEraseControl CtlGetLabel CtlGetSliderValues CtlGetValue CtlHandleEvent CtlHideControl CtlHitControl CtlNewControl CtlNewGraphicControl CtlNewSliderControl CtlSetEnabled CtlSetGraphics CtlSetLabel CtlSetSliderValues CtlSetUsable CtlSetValue CtlShowControl CtlValidatePointer |  |  |  | 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 #####
-> 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.
#### 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.
#####
-> 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.
#### 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 #####
-> 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.
#### 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 #####
-> controlP | Pointer to a control. (See ControlType.)
#### 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 |