Previous Page Table of Contents Index Next Page

Palm OS SDK Reference

Palm Logo 6 Controls

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 "Controls" in the Palm OS Programmer's Companion.

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;

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;

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;

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.
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;

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.
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:

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:

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 enable)

Parameters

  -> controlP
 Pointer to a control object. (See ControlType.)
  -> enable
 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


Palm OS SDK Reference

  Previous Page Table of Contents Index Next Page  

This is page 8 of 85 in this book

Palm Computing Platform Development Zone
Copyright © 2000, Palm, Inc. All rights reserved.