This chapter describes the API for user interface controls. It discusses the following topics:
Control Structures and Types
Control Constants
Control Events
Control Functions and Macros
The header file Control.h
declares the API that this chapter describes. For more information on using controls see Chapter 3, "Working with Controls."
Control Structures and Types
ControlAttrType Struct
Purpose
Private structure that specifies the control's visible characteristics.
Declared In
Control.h
Prototype
typedef struct ControlAttrTag ControlAttrType
Fields
ControlType Struct
Purpose
Private structure that defines the type and characteristics of a control. The ControlPtr
is a pointer to a to a ControlType
structure.
Declared In
Control.h
Prototype
typedef struct ControlType ControlType;
typedef ControlType *ControlPtr
Fields
GraphicControlType Struct
Purpose
Private structure that defines a graphical control. A graphical control is like any other control except that it displays a bitmap in place of the text label.
Declared In
Control.h
Prototype
typedef struct GraphicControlType GraphicControlType
Fields
See Also
CtlGetGraphics()
, CtlIsGraphicControl()
, CtlNewGraphicControl()
, CtlSetGraphics()
SliderControlType Struct
Purpose
Private structure that defines a slider control or a feedback slider control.
Declared In
Control.h
Prototype
typedef struct SliderControlType SliderControlType
Fields
See Also
CtlGetSliderValues()
, CtlSetSliderValues()
, CtlNewSliderControl()
Control Constants
ButtonFrameType Typedef
Purpose
Specifies the border style for a button.
Declared In
Control.h
Prototype
typedef Enum8 ButtonFrameType
Constants
-
noButtonFrame
- The button has no border.
-
standardButtonFrame
- Standard command button rectangular border with rounded corners.
-
boldButtonFrame
- Bold rectangular border with rounded corners.
-
rectangleButtonFrame
- Rectangular border with square corners.
See Also
ControlStyleType Typedef
Purpose
Specifies the type of the control defined by a ControlType
structure.
Declared In
Control.h
Prototype
typedef Enum8 ControlStyleType
Constants
-
buttonCtl
- Command button. Command 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
- Pop-up trigger. Pop-up triggers display a graphic element followed by a text label. They are used to display pop-up 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.
See Also
Control Events
ctlEnterEvent
Purpose
Sent when CtlHandleEvent()
receives a penDownEvent
within the bounds of a control.
For this event, the EventType
data
field contains the structure shown in the Prototype section, below.
Declared In
Event.h
Prototype
struct ctlEnter { struct ControlType *pControl; uint16_t controlID; _BA32_PADDING_16(1) } ctlEnter;
Fields
Comments
In most cases, you should wait for a ctlSelectEvent
before taking the intended action of the control. When the application receives the ctlEnterEvent
, it is not guaranteed that the control will become selected.
ctlExitEvent
Purpose
Sent by CtlHandleEvent()
when the stylus had previously entered the bounds of the control, but is lifted outside of the bounds of the control.
For this event, the EventType
data
field contains the structure shown in the Prototype section, below.
Declared In
Event.h
Prototype
struct ctlExit { struct ControlType *pControl; uint16_t controlID; _BA32_PADDING_16(1) } ctlExit;
Fields
The following fields in the EventType
structure are set for this event:
-
penDown
- Always
false
. -
screenX
- Draw window-relative position of the pen in standard coordinates (number of coordinates from the left bound of the window).
-
screenY
- Draw window-relative position of the pen in coordinates (number of coordinates from the top of the window).
ctlRepeatEvent
Purpose
Sent by CtlHandleEvent()
periodically while the stylus is down in the bounds of a repeating control (such as a repeating button or a feedback slider).
For this event, the EventType
data
field contains the structure shown in the Prototype section, below.
Declared In
Event.h
Prototype
struct ctlRepeat { struct ControlType *pControl; uint16_t controlID; uint16_t value; uint32_t time; } ctlRepeat;
Fields
-
pControl
- Pointer to a control structure.
-
controlID
- Resource ID of the control.
-
value
- Current value if the control is a feedback slider.
-
time
- System-ticks count when the event is added to the queue.
Comments
When CtlHandleEvent()
receives a ctlEnterEvent
in a repeating button or a feedback slider control, it sends a ctlRepeatEvent. When CtlHandleEvent()
receives a ctlRepeatEvent in a repeating button, it sends another ctlRepeatEvent if the pen remains down within the bounds of the control for 1/2 second beyond the last ctlRepeatEvent.
When CtlHandleEvent()
receives a ctlRepeatEvent
in a feedback slider control, it sends a ctlRepeatEvent
each time the slider's thumb moves by at least one pixel. Feedback sliders do not send ctlRepeatEvents
at regular intervals like repeating buttons do.
If you return true
in response to a ctlRepeatEvent
, it stops the ctlRepeatEvent
loop. No further ctlRepeatEvents
are sent.
ctlSelectEvent
Purpose
Sent by CtlHandleEvent()
when the stylus had previously entered the bounds of the control and is now lifted within the bounds of the control.
For this event, the EventType
data
field contains the structure shown in the Prototype section, below.
Declared In
Event.h
Prototype
struct ctlSelect { struct ControlType *pControl; uint16_t controlID; uint16_t value; Boolean on; uint8_t reserved1; _BA32_PADDING_16(1) } ctlSelect;
Fields
-
pControl
- Pointer to a control structure.
-
controlID
- Resource ID of the control.
-
value
- Current value if the control is a slider.
-
on
- true when the control has a pressed appearance; otherwise,
false
. -
reserved1
- Unused.
Comments
Applications should respond to this event to perform whatever action is necessary for this control.
Palm OS® only responds to this event if the control is a pop-up trigger. In that case, it displays the list associated with the pop-up trigger. If you must respond to this event for a pop-up trigger, return false
to allow the system to perform this default behavior. If you simply want to capture the user selection from the pop-up list, do not respond to ctlSelectEvent
; respond to popSelectEvent
instead.
For all other types of controls, it doesn't matter whether you return true
or false
from your event handler since the operating system doesn't handle this event.
frmControlPrvRefreshEvent
Purpose
Used to update the display of a slider control.
Declared In
Event.h
Prototype
struct ctlRepeat { struct ControlType *pControl; uint16_t controlID; uint16_t value; uint32_t time; } ctlRepeat;
Fields
-
pControl
- Pointer to a control structure.
-
controlID
- Resource ID of the control.
-
value
- Current value.
-
time
- System-ticks count when the event is added to the queue.
Comments
Applications do not respond to this event. It is used by the system to refresh the display.
Control Functions and Macros
CtlDrawCheckboxControl Function
Purpose
Declared In
Control.h
Prototype
void CtlDrawCheckboxControl ( fcoord_tleft
, fcoord_ttop
, Booleanselected
)
Parameters
-
→ left
- The x coordinate where the left side of the check box should be drawn.
-
→ top
- The y coordinate where the top of the check box should be drawn.
-
→ selected
- If
true
, the check should appear in the checkbox. Iffalse
, just the box should be drawn.
Returns
Comments
Don't call this function directly. Instead, add a check box to your form using a resource editor and the system draws the check box for you. If you want to dynamically add a check box to your user interface, use CtlNewControl()
.
CtlDrawControl Function
Purpose
Draws a control (and the text or graphic in it) on screen.
Declared In
Control.h
Prototype
void CtlDrawControl (
ControlType *controlP
)
Parameters
Returns
Comments
The control is drawn only if it is usable. This function sets the control to be visible if necessary.
See Also
CtlSetUsable()
, CtlShowControl()
, FrmDrawForm()
CtlEnabled Function
Purpose
Returns true
if the control responds to the pen.
Declared In
Control.h
Prototype
Boolean CtlEnabled (
const ControlType *controlP
)
Parameters
Returns
true
if the control responds to the pen; false
if not.
Comments
This function provides no indication of whether the control is visible on the screen. A control that doesn't respond to the pen may be visible, and if so, its appearance is no different from controls that do respond to the pen. You might use such a control to display some state of your application that cannot be modified.
See Also
CtlEraseControl Function
Purpose
Erases a usable and visible control and its frame from the screen.
Declared In
Control.h
Prototype
void CtlEraseControl (
ControlType *controlP
)
Parameters
Returns
Comments
Don't call this function directly; instead, use FrmHideObject()
, which calls this function.
CtlGetControlStyle Function
Purpose
Returns the type of the control, such as button, slider, and so on.
Declared In
Control.h
Prototype
ControlStyleType CtlGetControlStyle (
const ControlType *ctlP
)
Parameters
Returns
One of the ControlStyleType
constants.
CtlGetFont Function
Purpose
Gets the font used when drawing a specified control's label.
Declared In
Control.h
Prototype
FontID CtlGetFont (
const ControlType *ctlP
)
Parameters
Returns
The FontID
of the bitmapped font used to draw the control's label.
See Also
CtlGetGraphics Function
Purpose
Gets the bitmaps displayed in place of a specified control's label.
Declared In
Control.h
Prototype
void CtlGetGraphics ( const ControlType*ctlP
, DmResourceID*bitmapID
, DmResourceID*selectedBitmapID
)
Parameters
-
→ ctlP
- Pointer to the control.
-
← bitmapID
- Resource ID of the bitmap to display when the graphical control is not selected.
-
← selectedBitmapID
- Resource ID of the bitmap to display when the graphical control is selected, if, when selected, the graphical control should show a different bitmap.
Returns
Comments
If the specified control is not a graphical control—one that displays a bitmap in place of the text label—*bitmapID
and *selectedBitmapID
are set to zero.
This function works with any graphical control, including sliders.
See Also
CtlGetFont()
, CtlSetGraphics()
CtlGetLabel Function
Purpose
Returns a control's text label.
Declared In
Control.h
Prototype
const char *CtlGetLabel (
const ControlType *controlP
)
Parameters
Returns
A pointer to a null-terminated string containing the control's label.
Comments
Make sure that controlP
is not a graphical control or a slider control. The graphical control and slider control structures do not contain a text label field.
See Also
CtlGetSliderValues Function
Purpose
Returns current values used by a slider control.
Declared In
Control.h
Prototype
void CtlGetSliderValues ( const ControlType*ctlP
, uint16_t*minValueP
, uint16_t*maxValueP
, uint16_t*pageSizeP
, uint16_t*valueP
)
Parameters
-
→ ctlP
- Pointer to a slider.
-
← minValueP
- The value of the slider when the thumb is all the way to the left. Pass
NULL
if you don't want to retrieve this value. -
← maxValueP
- The value of the slider when the thumb is all the way to the right. Pass
NULL
if you don't want to retrieve this value. -
← pageSizeP
- The amount by which to increase or decrease the slider value when the user taps to the right or left of the thumb. Pass
NULL
if you don't want to retrieve this value. -
← valueP
- The current value represented by the slider. Pass
NULL
if you don't want to retrieve this value.
Returns
Comments
If ctlP
is not a slider or a feedback slider, this function immediately returns.
See Also
CtlGetValue Function
Purpose
Returns the current value of the specified control.
Declared In
Control.h
Prototype
int16_t CtlGetValue (
const ControlType *controlP
)
Parameters
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 current value represented by the slider.
Don't use this function on selector triggers or pop-up triggers.
See Also
CtlSetValue()
, FrmGetControlGroupSelection()
, FrmSetControlGroupSelection()
, FrmGetControlValue()
, FrmSetControlValue()
CtlHandleEvent Function
Purpose
Handles events in the specified control.
Declared In
Control.h
Prototype
Boolean CtlHandleEvent ( ControlType*controlP
, EventType*pEvent
)
Parameters
-
→ controlP
- Pointer to a control.
-
→ pEvent
- Pointer to an
EventType
structure.
Returns
true
if an event is handled by this function or false
otherwise.
Comments
The control must be usable, visible, and respond to the pen for this function to handle the event.
Table 16.1 lists the events that this function responds to. For update-based windows, the controls do not redraw immediately. Instead, the region corresponding to the control is invalidated and redrawn on the next drawing update cycle.
Table 16.1 CtlHandleEvent() actions
Begins tracking the pen. Redraws the control as necessary as either selected or deselected, depending on its previous state. For repeating controls, adds a |
|
Tracks the pen and continues to send |
|
Checks if the pen position is within the bounds of the control. If it is, a |
|
Redraws the control as necessary as either selected or deselected, depending on its previous state and if the pen is still within the bounds of the control. For repeating controls, adds a |
|
If the pen is within the bounds of the control, adds a |
CtlHideControl Function
Purpose
Sets a control to not usable and erases the control from the screen.
Declared In
Control.h
Prototype
void CtlHideControl (
ControlType *controlP
)
Parameters
Returns
Comments
Don't call this function directly; instead, use FrmHideObject()
, which performs the same function and works for all user interface elements.
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 makes the control both unusable and not visible. CtlEraseControl()
only makes the control not visible.
TIP: In Palm OS Cobalt, hiding an element means filling its region with the color set for
UIFormFill
. This is true regardless of the type of window used for the form (legacy, transitional, or update-based).
See Also
CtlHitControl Function
Purpose
Simulates tapping a control. This function adds a ctlSelectEvent
to the event queue.
Declared In
Control.h
Prototype
void CtlHitControl (
const ControlType *controlP
)
Parameters
Returns
Comments
CtlIsGraphicControl Function
Purpose
Returns whether or not a control is a graphical control.
Declared In
Control.h
Prototype
Boolean CtlIsGraphicControl (
ControlType *ctlP
)
Parameters
Returns
true
if the control indicated by ctlP
is a graphical control, a slider, or a feedback slider. Otherwise, it returns false
.
CtlNewControl Function
Purpose
Creates a new control dynamically and installs it in the specified form.
Declared In
Control.h
Prototype
ControlType *CtlNewControl ( void**formPP
, uint16_tID
, ControlStyleTypestyle
, const char*textP
, Coordx
, Coordy
, Coordwidth
, Coordheight
, FontIDfont
, uint8_tgroup
, 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 structure moves in memory. In subsequent calls, always use the newformPP
value returned by this function. -
→ ID
- Symbolic ID of the control.
-
→ style
- A
ControlStyleType
value specifying the kind of control to create: button, push button, repeating button, check box, pop-up trigger, or selector trigger. To create a graphical control or slider control dynamically, useCtlNewGraphicControl()
orCtlNewSliderControl()
, respectively. -
→ textP
- Pointer to the control's label text. If
textP
isNULL
, the control has no label. Because the contents of this pointer are copied into their own buffer, you can free thetextP
pointer any time after theCtlNewControl()
function returns. The buffer into which this string is copied is freed automatically when you remove the control from the form or delete the form. -
→ x
- Horizontal coordinate of the upper-left corner of the control's boundaries, relative to the window in which it appears.
-
→ y
- Vertical coordinate of the upper-left corner of the control's boundaries, relative to the window in which it appears.
-
→ width
- Width of the control, expressed in standard coordinates. If the value of either of the
width
orheight
parameters is 0, the control is sized automatically as necessary to display the text passed as the value of thetextP
parameter. -
→ height
- Height of the control, expressed in standard coordinates. If the value of either of the
width
orheight
parameters is 0, the control is sized automatically as necessary to display the text passed as the value of thetextP
parameter. -
→ font
- Bitmapped font used to draw the control's label. See
FontID
. -
→ group
- Group ID of a push button or a check box that is part of an exclusive group.
-
→ 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. It does not affect how the control is resized when the form that contains it is resized.
Returns
See Also
CtlValidatePointer()
, FrmRemoveObject()
CtlNewGraphicControl Function
Purpose
Creates a new graphical control dynamically and installs it in the specified form.
Declared In
Control.h
Prototype
GraphicControlType *CtlNewGraphicControl ( void**formPP
, uint16_tID
, ControlStyleTypestyle
, DmOpenRefdatabase
, DmResourceIDbitmapID
, DmResourceIDselectedBitmapID
, Coordx
, Coordy
, Coordwidth
, Coordheight
, uint8_tgroup
, 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 structure moves in memory. In subsequent calls, always use the newformPP
value returned by this function. -
→ ID
- Symbolic ID of the control.
-
→ style
- A
ControlStyleType
value specifying the kind of control to create: button, push button, pop-up trigger, repeating button, or selector trigger. Graphical controls cannot be check boxes. -
→ database
- Open database containing the
bitmapID
andselectedBitmapID
resources. -
→ 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 standard coordinates.
-
→ height
- Height of the control, expressed in standard coordinates.
-
→ group
- Group ID of a push button that is part of an exclusive group.
-
→ leftAnchor
-
true
specifies that the left bound of this control is fixed.
Returns
A pointer to the new graphical control.
See Also
CtlNewSliderControl()
, CtlNewControl()
, CtlValidatePointer()
, FrmRemoveObject()
CtlNewSliderControl Function
Purpose
Creates a new slider or feedback slider dynamically and installs it in the specified form.
Declared In
Control.h
Prototype
SliderControlType *CtlNewSliderControl ( void**formPP
, uint16_tID
, ControlStyleTypestyle
, DmOpenRefdatabase
, DmResourceIDthumbID
, DmResourceIDbackgroundID
, Coordx
, Coordy
, Coordwidth
, Coordheight
, uint16_tminValue
, uint16_tmaxValue
, uint16_tpageSize
, uint16_tvalue
)
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 structure moves in memory. In subsequent calls, always use the newformPP
value returned by this function. -
→ ID
- Symbolic ID of the slider.
-
→ style
- Either
sliderCtl
orfeedbackSliderCtl
. SeeControlStyleType
. -
→ database
- Open database containing the
thumbID
andbackgroundID
resources. PassNULL
for this parameter ifthumbID
andbackgroundID
are bothNULL
. -
→ 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 standard coordinates.
-
→ height
- Height of the slider, expressed in standard coordinates.
-
→ 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
A pointer to the new slider control.
See Also
CtlNewGraphicControl()
, CtlNewControl()
, CtlValidatePointer()
, FrmRemoveObject()
CtlSetEnabled Function
Purpose
Sets 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
Returns
Comments
If you disable a visible control, the control is still displayed, and its appearance is no different from controls that do respond to the pen. You might use such a control to inform your users of some state of your application that cannot be modified.
See Also
CtlSetFont Function
Purpose
Sets the font to use when drawing the control's label.
Declared In
Control.h
Prototype
void CtlSetFont ( ControlType*ctlP
, FontIDfontID
)
Parameters
-
→ ctlP
- Pointer to the control.
-
→ fontID
- The
FontID
of the bitmapped font to use when drawing the control's label.
Returns
See Also
CtlSetFrameStyle Function
Purpose
Sets the frame style for a button control.
Declared In
Control.h
Prototype
void CtlSetFrameStyle ( ControlType*ctlP
, ButtonFrameTypeframeStyle
)
Parameters
-
→ controlP
- Pointer to a button control.
-
→ frameStyle
- Frame style to be applied to the button. Supply one of the values from the
ButtonFrameType
enum.
Returns
CtlSetGraphics Function
Purpose
Sets the bitmaps for a graphical control and redraws the control if it is visible.
Declared In
Control.h
Prototype
void CtlSetGraphics ( ControlType*ctlP
, DmOpenRefdatabase
, DmResourceIDnewBitmapID
, DmResourceIDnewSelectedBitmapID
)
Parameters
-
→ ctlP
- Pointer to a graphical control.
-
→ database
- Open resource database containing the
newBitmapID
andnewSelectedBitmapID
resources. -
→ newBitmapID
- Resource ID of a new bitmap to display on the control, or
NULL
to use the current bitmap. -
→ newSelectedBitmapID
- Resource ID of a new bitmap to display when the control is selected, or
NULL
to use the current selected bitmap.
Returns
Comments
If ctlP
is not a graphical control, this function immediately returns.
See Also
CtlSetLabel Function
Purpose
Sets the current label for the specified control and redraws the control if it is visible.
Declared In
Control.h
Prototype
void CtlSetLabel ( ControlType*controlP
, const char*newLabel
)
Parameters
-
→ controlP
- Pointer to a control.
-
→ newLabel
- Pointer to the new text label. Must be a null-terminated string.
Returns
Comments
This function resizes the width of the control to the size of the new label.
This function stores the newLabel
pointer in the control's data structure. It doesn't make a copy of the string that is passed in. Therefore, if you use CtlSetLabel()
, you must manage the string yourself. You must ensure that it persists for as long as it is being displayed (that is, for as long as the control is displayed or until you call CtlSetLabel()
with a new string), and you must free the string after it is no longer in use (typically after the form containing the control is freed).
If you never use CtlSetLabel()
, you do not need to worry about freeing a control's label.
Make sure that controlP
is not a graphical control or a slider control. The graphical controls and slider control structures do not contain a text label field, so attempting to set one will crash your application.
See Also
CtlSetLeftAnchor Function
Purpose
Causes a control's left bound to be fixed or to float.
Declared In
Control.h
Prototype
void CtlSetLeftAnchor ( ControlType*ctlP
, BooleanleftAnchor
)
Parameters
-
→ ctlP
- Pointer to the control.
-
→ leftAnchor
- A value of
true
causes the left bound of the control to be fixed.
Returns
Comments
Used by controls that expand and shrink their width when the label is changed.
CtlSetSliderValues Function
Purpose
Changes a slider control's values and redraws the slider if it is visible.
Declared In
Control.h
Prototype
void CtlSetSliderValues ( ControlType*ctlP
, const uint16_t*minValueP
, const uint16_t*maxValueP
, const uint16_t*pageSizeP
, const uint16_t*valueP
)
Parameters
-
→ ctlP
- Pointer to an inactive slider or feedback slider control.
-
→ minValueP
- Pointer to a new value to use for the slider's minimum or
NULL
if you don't want to change this value. The minimum is the value of the slider when the thumb is all the way to the left. -
→ maxValueP
- Pointer to a new value to use for the slider's maximum, or
NULL
if you don't want to change this value. The maximum is the value of the slider when the thumb is all the way to the right. -
→ 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. The page size is the amount by which to increase or decrease the slider value when the user taps to the right or left of the thumb. -
→ valueP
- Pointer to a new value to use for the current value, or
NULL
if you don't want to change this value.
Returns
Comments
The control's style must be sliderCtl
or feedbackSliderCtl
, and it must not be currently tracking the pen. If the slider is currently tracking the pen, use CtlSetValue()
to set the value
field.
See Also
CtlSetUsable Function
Purpose
Sets a control to usable or not usable.
Declared In
Control.h
Prototype
void CtlSetUsable ( ControlType*controlP
, Booleanusable
)
Parameters
-
→ controlP
- Pointer to a control.
-
→ usable
-
true
to have the control be usable;false
to have the control be not usable.
Returns
Comments
A control that is not usable doesn't draw and doesn't respond to the pen.
This function doesn't usually update the control.
See Also
CtlEraseControl()
, CtlHideControl()
, CtlShowControl()
CtlSetValue Function
Purpose
Sets the current value of the specified control. If the control is visible, it's redrawn.
Declared In
Control.h
Prototype
void CtlSetValue ( ControlType*controlP
, int16_tnewValue
)
Parameters
-
→ controlP
- Pointer to a control.
-
→ newValue
- New value to set for the control. For sliders, specify a value between the slider's minimum and maximum. For graphical controls, push buttons, or check boxes, specify 0 for off, nonzero for on.
Returns
Comments
Don't use this function on pop-up triggers or selector triggers.
See Also
CtlGetValue()
, FrmGetControlGroupSelection()
, FrmSetControlGroupSelection()
, FrmGetControlValue()
, FrmSetControlValue()
CtlShowControl Function
Purpose
Sets a control's usable
attribute to true
and draws the control on the screen.
Declared In
Control.h
Prototype
void CtlShowControl (
ControlType *controlP
)
Parameters
Returns
Comments
Don't use this function directly; instead use FrmShowObject()
, which does the same thing.
See Also
CtlValidatePointer Function
Purpose
Returns true
if the specified pointer references a valid control.
Declared In
Control.h
Prototype
Boolean CtlValidatePointer (
const ControlType *controlP
)
Parameters
Returns
true
when passed a valid pointer to a control; otherwise, 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.
See Also
FrmValidatePtr()
, WinValidateHandle()