This chapter provides the following information about form objects:
Form Structures and Types
Form Constants
Form Resources
Form Functions
Application-Defined Functions
The header file Form.h
declares the API that this chapter describes. For more information on forms, see the section "Text" in the Palm OS Programmer's Companion, vol. I.
Form Structures and Types
AlertTemplateType Struct
Purpose
Structure of an alert resource. Then operating system uses this structure when it needs to retrieve an alert resource from a resource database and manipulate the alert's contents prior to display.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
AlertTemplateType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Declared In
Form.h
Prototype
typedef struct AlertTemplateTag { UInt16 alertType; UInt16 helpRscID; UInt16 numButtons; UInt16 defaultButton; } AlertTemplateType
Fields
-
alertType
- The alert type. One of the values defined under
AlertType
. -
helpRscID
- Symbolic ID of the resource that provides the alert's online help.
-
numButtons
- The number of buttons on the alert.
-
defaultButton
- Symbolic ID of the button that provides the alert's default action.
Comments
This structure is immediately followed by the alert title, the alert message, and the button strings, each null-terminated and each immediately following the previous.
FormActiveStateType Struct
Purpose
Structure that is passed to FrmSaveActiveState()
and FrmRestoreActiveState()
when saving and restoring the active form and window state.
Declared In
Form.h
Prototype
typedef struct FormActiveStateType { UInt16 data[11]; } FormActiveStateType
Fields
-
data
- Abstract data containing the form and window state information. Note that this data is abstract since the structure's contents can differ significantly from one release of Palm OS to another. Applications should not attempt to read or write the contents of this field.
Compatibility
This structure was added in Palm OS 3.0.
FormAttrType Struct
Purpose
The FormAttrType
bit field defines the visible characteristics of the form.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
FormAttrType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct { UInt16 usable:1; UInt16 enabled:1; UInt16 visible:1; UInt16 dirty:1; UInt16 saveBehind:1; UInt16 graffitiShift:1; UInt16 globalsAvailable:1; UInt16 doingDialog:1; UInt16 exitDialog:1; UInt16 reserved:7; UInt16 reserved2; } FormAttrType;
Your code should treat the FormAttrType
bit field as opaque. Do not attempt to change bit field member values directly.
Fields
-
usable
- Not set if the form is not considered part of the current interface of the application, and it doesn't appear on screen.
-
enabled
- Not used.
-
visible
- Set or cleared internally when the field object is drawn or erased.
-
dirty
- Not used.
-
saveBehind
- Set if the bits behind the form are saved when the form is drawn.
-
graffitiShift
- Set if the shift indicator is supported.
-
globalsAvailable
- System use only.
-
doingDialog
- System use only.
-
exitDialog
- System use only.
-
reserved
- Reserved for system use.
-
reserved2
- Reserved for system use.
Compatibility
The globalsAvailable
, doingDialog
, and exitDialog
flags are present only if 3.5 New Feature Set is present.
FormBitmapType Struct
Purpose
The FormBitmapType
structure defines the visible characteristics of a bitmap on a form.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
FormBitmapType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct { FormObjAttrType attr; PointType pos; UInt16 rscID; } FormBitmapType;
Fields
-
attr
- See
FormObjAttrType()
. -
pos
- Location of the bitmap.
-
rscID
- Resource ID of the bitmap. If you use
DmGetResource()
with this value as the resource ID, it returns a pointer to aBitmapType
structure.
FormFrameType Struct
Purpose
The FormFrameType
structure defines a frame that appears on the form.
Prototype
typedef struct { UInt16 id; FormObjAttrType attr; RectangleType rect; UInt16 frameType; } FormFrameType;
Fields
-
id
- ID of the frame.
-
attr
- See
FormObjAttrType
. -
rect
- Location and size of the frame.
-
frameType
- The type of frame.
FormGadgetAttrType Struct
Purpose
The FormGadgetAttrType
bit field defines a gadget's attributes.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
FormGadgetAttrType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct { UInt16 usable:1; UInt16 extended:1; UInt16 visible:1; UInt16 reserved:13; } FormGadgetAttrType;
Your code should treat the FormGadgetAttrType
structure as opaque. Use the functions specified in the descriptions below to retrieve and set each value. Do not attempt to change structure member values directly.
Fields
-
usable
- Not set if the gadget is not considered part of the current interface of the application, and it doesn't appear on screen. This is set by
FrmShowObject()
and cleared byFrmHideObject()
. -
extended
- If set, the gadget is an extended gadget. Extended gadgets are supported if 3.5 New Feature Set is present. An extended gadget has the
handler
field defined in itsFormGadgetType
. If not set, the gadgets is a standard gadget compatible with all releases of Palm OS®. -
visible
- Set or cleared when the gadget is drawn or erased.
FrmHideObject()
clears this value. You should set it explicitly in the gadget's callback function (if it has one) in response to a draw request. -
reserved
- Reserved for future use.
Many form functions (FrmGetObjectType()
, FrmHideObject()
, and FrmGetObjectBounds()
, for example) take an object index as one of their arguments. The most common way to get an object's index is to call FrmGetObjectIndex()
. FrmGetObjectIndex
takes a form ID and returns the form object's index. This is the routine one should use in most cases, because the application usually knows the object ID. However, gadgets and specifically extended gadgets, have APIs with callbacks that pass back the gadget pointer and not the ID. In those cases, the only way to get the object index (so one can use the FrmGetObject
* APIs) is to use the function FrmGetObjectIndexFromPtr()
.
If you need the same functionality on pre-Palm OS 4.0 systems then you can accomplish the same thing with the following code snippet.
UInt16 index; UInt16 objIndex = frmInvalidObjectId; UInt16 numObjects = FrmGetNumberOfObjects(frmP) for (index = 0; index < numObjects; index++) { if (FrmGetObjectPtr(index) == myObjPtr) { // Found it objIndex = index; break; } }
Compatibility
This type is defined only if 3.5 New Feature Set is present.
FormGadgetType Struct
Purpose
The FormGadgetType
structure defines a gadget object that appears on a form.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
FormGadgetType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct { UInt16 id; FormGadgetAttrType attr; RectangleType rect; const void *data; FormGadgetHandlerType *handler; } FormGadgetType;
Your code should treat the FormGadgetType
structure as opaque. Use the functions specified in the descriptions below to retrieve and set each value. Do not attempt to change structure member values directly.
Fields
-
id
- ID of the gadget resource.
-
attr
- See
FormGadgetAttrType
. -
rect
- Location and size of the object.
-
data
- Pointer to any specific data that needs to be stored. You can set and retrieve the value of this field with
FrmGetGadgetData()
andFrmSetGadgetData()
. -
handler
- Pointer to a callback function that controls the gadget's behavior and responds to events. You can set this field with
FrmSetGadgetHandler()
.
Many form functions (FrmGetObjectType()
, FrmHideObject()
, and FrmGetObjectBounds()
, for example) take an object index as one of their arguments. The most common way to get an object's index is to call FrmGetObjectIndex()
. FrmGetObjectIndex
takes a form ID and returns the form object's index. This is the routine one should use in most cases, because the application usually knows the object ID. However, gadgets have APIs with callbacks that pass back the gadget pointer and not the ID. In those cases, the only way to get the object index (so one can use the FrmGetObject
* APIs) is to use the function FrmGetObjectIndexFromPtr()
.
If you need the same functionality on pre-Palm OS 4.0 systems then you can accomplish the same thing with the following code snippet.
UInt16 index; UInt16 objIndex = frmInvalidObjectId; UInt16 numObjects = FrmGetNumberOfObjects(frmP) for (index = 0; index < numObjects; index++) { if (FrmGetObjectPtr(index) == myObjPtr) { // Found it objIndex = index; break; } }
Compatibility
In Palm OS® releases prior to 3.5, the attr
field was of type FormObjAttrType()
and the handler
field did not exist.
FormGadgetTypeInCallback Struct
Purpose
The FormGadgetTypeInCallback
structure is passed to your extended gadget handler and is identical to FormGadgetType
except that its contents are not hidden when DO_NOT_ALLOW_ACCESS_TO_INTERNALS_OF_STRUCTS is defined. This allows you to freely access the contents of an extended gadget structure from within your extended gadget callback functions.
Prototype
typedef struct { UInt16 id; FormGadgetAttrType attr; RectangleType rect; const void *data; FormGadgetHandlerType *handler; } FormGadgetTypeInCallback;
Fields
-
id
- ID of the gadget resource.
-
attr
- See
FormGadgetAttrType
. -
rect
- Location and size of the object.
-
data
- Pointer to any specific data that needs to be stored.
-
handler
- Pointer to a callback function that controls the gadget's behavior and responds to events.
Many form functions (FrmGetObjectType()
, FrmHideObject()
, and FrmGetObjectBounds()
, for example) take an object index as one of their arguments. The most common way to get an object's index is to call FrmGetObjectIndex()
. FrmGetObjectIndex
takes a form ID and returns the form object's index. This is the routine one should use in most cases, because the application usually knows the object ID. However, extended gadgets have APIs with callbacks that pass back the gadget pointer and not the ID. In those cases, the only way to get the object index (so one can use the FrmGetObject
* APIs) is to use the function FrmGetObjectIndexFromPtr()
.
If you need the same functionality on pre-Palm OS 4.0 systems then you can accomplish the same thing with the following code snippet.
UInt16 index; UInt16 objIndex = frmInvalidObjectId; UInt16 numObjects = FrmGetNumberOfObjects(frmP) for (index = 0; index < numObjects; index++) { if (FrmGetObjectPtr(index) == myObjPtr) { // Found it objIndex = index; break; } }
Compatibility
Introduced in the Palm OS 4.0 SDK Update 1.
FormLabelType Struct
The FormLabelType
structure defines a label that appears on a form.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
FormLabelType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
typedef struct { UInt16 id; PointType pos; FormObjAttrType attr; FontID fontID; UInt8 reserved; Char *text; } FormLabelType;
Your code should treat the FormLabelType
structure as opaque. Do not attempt to change structure member values directly.
Fields
-
id
- Resource ID of the label.
-
pos
- Location of the label.
-
attr
- See
FormObjAttrType
. -
fontID
- Font ID of the font used for the label.
-
reserved
- Reserved for future use.
-
text
- Text of the label.
FormLineType Struct
Purpose
The FormLineType
structure defines a line appearing on a form.
Prototype
typedef struct { FormObjAttrType attr; PointType point1; PointType point2; } FormLineType;
Your code should treat the FormLineType
structure as opaque. Do not attempt to change structure member values directly.
Fields
-
attr
- See
FormObjAttrType
. -
point1
- Starting point of the line.
-
point2
- Ending point of the line.
FormObjAttrType Struct
Purpose
The FormObjAttrType
bit field defines a form object's attributes.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
FormObjAttrType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct { UInt16 usable : 1; UInt16 reserved : 15; } FormObjAttrType;
Your code should treat the FormObjAttrType
structure as opaque. Do not attempt to change structure member values directly.
Fields
-
usable
- Not set if the object is not considered part of the current interface of the application, and it doesn't appear on screen.
-
reserved
- Reserved for future use.
FormObjectType Struct
Purpose
The FormObjectType
union points to the C structure for a user interface object that appears on the form.
Prototype
typedef union { void *ptr; FieldType *field; ControlType *control; GraphicControlType *graphicControl; SliderControlType *sliderControl; ListType *list; TableType *table; FormBitmapType *bitmap; FormLabelType *label; FormTitleType *title; FormPopupType *popup; FormGraffitiStateType *grfState; FormGadgetType *gadget; ScrollBarType *scrollBar; } FormObjectType;
Your code should treat the FormObjectType
structure as opaque. Do not attempt to change structure member values directly.
Fields
-
ptr
- Used when the object's type is not one of those specified below.
-
field
- Text field's structure. See
FieldType
. -
control
- Control's structure. See
ControlType
. -
graphicControl
- Graphic button structure. See
GraphicControlType
. -
sliderControl
- Slider control structure. See
SliderControlType
. -
list
- List object's structure. See
ListType
. -
table
- Table structure. See
TableType
. -
bitmap
- Form bitmap's structure. See
FormBitmapType
. -
label
- Label's structure. See
FormLabelType
. -
title
- Form title's structure. See
FormTitleType
. -
popup
- Popup list's structure. See
FormPopupType
. -
grfState
- Shift indicator's structure. See
FrmGraffitiStateType
. -
gadget
- Gadget (custom UI resource) structure. See
FormGadgetType
. -
scrollbar
- Scroll bar's structure. See
ScrollBarType
.
Compatibility
The graphicControl
and sliderControl
fields are only defined if 3.5 New Feature Set is present.
FormObjListType Struct
Purpose
The FormObjectListType
structure specifies a user interface object that appears on the form.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
FormObjListType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct { FormObjectKind objectType; UInt8 reserved; FormObjectType object; } FormObjListType;
Your code should treat the FormObjListType
structure as opaque. Do not attempt to change structure member values directly.
Fields
-
objectType
- Specifies the type of the object (control, field, etc.). See
FormObjectKind
. -
reserved
- Reserved for future use.
-
object
- The C data structure that defines the object. See
FormObjectType
.
FormPopupType Struct
Purpose
The FormPopupType
structure defines a popup list that appears on a form.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
FormPopupType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct { UInt16 controlID; UInt16 listID; } FormPopupType;
Your code should treat the FormPopupType
structure as opaque. Do not attempt to change structure member values directly.
Fields
-
controlID
- Resource ID of the popup trigger control that triggers the list's display.
-
listID
- Resource ID of the list object that defines the popup list.
FormPtr Typedef
Purpose
The FormPtr
type defines a pointer to a FormType
structure.
Prototype
typedef FormType *FormPtr;
FormRectangleType Struct
Purpose
The FormRectangleType
structure defines a rectangle that appears on the form.
Prototype
typedef struct { FormObjAttrType attr; RectangleType rect; } FormRectangleType;
Your code should treat the FormRectangleType
structure as opaque. Do not attempt to change structure member values directly.
Fields
-
attr
- See
FormObjAttrType
. -
rect
- Location and size of the rectangle.
FormTitleType Struct
Purpose
The FormTitleType
structure defines the title of the form.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
FormTitleType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct { RectangleType rect; char *text; } FormTitleType;
Your code should treat the FormTitleType
structure as opaque. Do not attempt to change structure member values directly.
Fields
FormType Struct
Purpose
The FormType
structure and supporting structures are defined below.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
FormType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct { WindowType window; UInt16 formId; FormAttrType attr; WinHandle bitsBehindForm; FormEventHandlerType *handler; UInt16 focus; UInt16 defaultButton; UInt16 helpRscId; UInt16 menuRscId; UInt16 numObjects; FormObjListType *objects; } FormType;
Your code should treat the FormType
structure as opaque. Do not attempt to change structure member values directly.
Fields
-
window
- Structure of the window object that corresponds to the form. See
WindowType
. Access this field withFrmGetWindowHandle()
. -
formId
- ID number of the form, specified by the application developer. This ID value is part of the event data of
frmOpenEvent
. The ID should match the form's resource ID. Access this field withFrmGetFormId()
. -
attr
- Form object attributes. See
FormAttrType
. -
bitsBehindForm
- Used to save all the bits behind the form so the screen can be properly refreshed when the form is closed. This field is for internal use only by modal forms.
-
handler
- Routine called when the form needs to handle an event. You typically set this in your application's event handling function by calling
FrmSetEventHandler()
. -
focus
- Index of a field or table object within the form that contains the focus. Any
keyDownEvent
is passed to the object that has the focus. Set tonoFocus
if no object has the focus. Set this field withFrmSetFocus()
. -
defaultButton
- Resource ID of the object defined as the default button. This value is used by the routine
FrmDoDialog()
. -
helpRscId
- Resource ID number of the help resource. The help resource is a String resource (type tSTR).
-
menuRscId
- ID number of a menu bar to use if the form has a menu, or zero if the form doesn't have a menu.
-
numObjects
- Number of objects contained within the form. Access this field with
FrmGetNumberOfObjects()
. -
objects
- Pointer to the array of objects contained within the form. See
FormObjListType
.
FrmGraffitiStateType Struct
Purpose
The FrmGraffitiStateType
structure defines the shift indicator.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
FrmGraffitiStateType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct{ PointerType pos; }FrmGraffitiStateType;
Your code should treat the FrmGraffitiStateType
structure as opaque. Do not attempt to change structure member values directly.
Fields
FrmNavHeaderType Struct
Purpose
Contains header information for the form's navigation order. Obtain this structure for a given form by calling FrmGetNavOrder()
; set it by calling FrmSetNavOrder()
.
Declared In
Form.h
Prototype
typedef struct FrmNavHeaderTag { UInt16 version; UInt16 numberOfObjects; UInt16 headerSizeInBytes; UInt16 listElementSizeInBytes; FrmNavHeaderFlagsType navFlags; UInt16 initialObjectIDHint; UInt16 jumpToObjectIDHint; UInt16 bottomLeftObjectIDHint; UInt16 padding1; } FrmNavHeaderType
Fields
-
version
- The version of this structure used by the device. The version of the structure defined in
Form.h
is specified bykFrmNavInfoVersion
. -
numberOfObjects
- The number of objects in the navigation order for this form.
-
headerSizeInBytes
- The size of this header structure, in bytes. The version 1 structure is 20 bytes in length.
-
listElementSizeInBytes
- Size of the
FrmNavOrderEntryType
structures that are used to represent each object in the navigation order. -
navFlags
- A combination of the flags listed under
FrmNavHeaderFlagsType
. These flags specify the form's initial focus mode. -
initialObjectIDHint
- ID of the object where focus is positioned when the form is initialized. If
initialObjectIDHint
is 0, the operating system places the initial focus on the first action button, if there is one, or on the first object in the tab order if there is not. -
jumpToObjectIDHint
- ID of the object to which focus can "jump," if the device supports this feature. Devices can optionally have an action trigger the movement of the focus to a commonly used object.
-
bottomLeftObjectIDHint
- For platforms that cycle vertically, this field specifies which object receives the focus when navigating up from an object in the top row of the form (an object whose
aboveObjectID
[seeFrmNavOrderEntryType
] is 0). AbottomLeftObjectIDHint
value of zero means that focus does not cycle vertically in the form. -
padding1
- Structure padding bytes.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
FrmNavOrderEntryType Struct
Purpose
Defines how navigation up or down using keys for that purpose should proceed from a given UI object.
Declared In
Form.h
Prototype
typedef struct FrmNavOrderEntryTag { UInt16 objectID; FrmNavObjectFlagsType objectFlags; UInt16 aboveObjectID; UInt16 belowObjectID; } FrmNavOrderEntryType
Fields
-
objectID
- ID of the object in the navigation order.
-
objectFlags
- One or more of the flags defined under
FrmNavObjectFlagsType
. -
aboveObjectID
- ID of the object that is above the object being described. Should be 0 if the object being described is in the top row of the form. If the user navigates up from an object with 0 for its above object, some platforms will move the focus to the object specified by
bottomLeftObjectIDHint
in the form'sFrmNavHeaderType
structure. -
belowObjectID
- ID of the object that is below the object being described. Should be 0 if the object is in the bottom row of the form. If the user navigates down from an object with 0 for its below object, some platforms will move the focus to the first object in the tab order.
Comments
You can obtain an array of structures of this type for a given form by calling FrmGetNavOrder()
. When setting the navigation order for a form, you create an array of these structures—one for each UI object in the navigation order—and then pass the address of that array to FrmSetNavOrder()
.
NOTE:
FrmSetNavOrder()
is not intended to replace the use of navigation resources. A form that needs to have a custom navigation order should always provide a navigation resource. FrmSetNavOrder()
is mainly for dynamically created forms or forms that have a navigation resource but change the order sometime after form initialization.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
Form Constants
AlertType Enum
Purpose
Constants the define the types of alerts that can be presented to the user.
Declared In
Form.h
Prototype
typedef enum alertTypes AlertType;
Constants
-
informationAlert
- An alert that simply informs the user of a non-critical situation.
-
confirmationAlert
- An alert requiring that the user confirms the displayed information.
-
warningAlert
- An alert that is informing the user of a potentially serious condition.
-
errorAlert
- An alert that is informing the user that an error has occurred.
FormObjectKind Enum
Purpose
The FormObjectKind
enum specifies values for the objectType
field of the FormObjListType
. It specifies how to interpret the object
field.
Declared In
Form.h
Prototype
typedef enum formObjects FormObjectKind;
Constants
-
frmFieldObj
- Text field.
-
frmControlObj
- Control.
-
frmListObj
- List.
-
frmTableObj
- Table.
-
frmBitmapObj
- Form bitmap.
-
frmLineObj
- Line.
-
frmFrameObj
- Frame.
-
frmRectangleObj
- Rectangle.
-
frmLabelObj
- Label.
-
frmTitleObj
- Form title.
-
frmPopupObj
- Popup list.
-
frmGraffitiStateObj
- Graffiti® or Graffiti 2 shift indicator.
-
frmGadgetObj
- Gadget (custom object).
-
frmScrollBarObj
- Scrollbar.
FrmNavFocusRingStyleEnum Typedef
Purpose
Constants that indicate the focus ring style.
Declared In
Form.h
Prototype
typedef UInt16 FrmNavFocusRingStyleEnum
Constants
-
frmNavFocusRingStyleObjectTypeDefault = 0
- Use a focus ring that matches the underlying object.
-
frmNavFocusRingStyleSquare = 1
- A rectangular focus ring with square corners.
-
frmNavFocusRingStyleRound = 2
- A rectangular focus ring with rounded corners.
-
frmNavFocusRingStyleHorizontalBars = 3
- The focus ring simply consists only of horizontal lines.
-
frmNavFocusRingStyleInvalid = 0xFFFF
- A value returned by
FrmNavGetFocusRingInfo()
to indicate that the ring style is invalid.
Comments
Set a form object's ring style with FrmNavDrawFocusRing()
. You can determine an existing object's ring style by calling FrmNavGetFocusRingInfo()
.
If a chosen focus ring style is not supported by the device, FrmNavDrawFocusRing()
will instead use frmNavFocusRingStyleObjectTypeDefault
. Note that frmNavFocusRingStyleHorizontalBars is not supported on all devices.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
FrmNavHeaderFlagsType Typedef
Purpose
Form navigation flags that primarily specify the form's initial focus mode (application focus mode or object focus mode). These flags make up the navFlags
field of the FrmNavHeaderType
structure.
Declared In
Form.h
Prototype
typedef UInt32 FrmNavHeaderFlagsType
Constants
-
#define kFrmNavHeaderFlagsAppFocusStartState 0x00000002
- If this flag is set, the form will initially be in application focus mode.
-
#define kFrmNavHeaderFlagsAppFocusStartStateValue 0x00000002
- After masking the flag bits with
kFrmNavHeaderFlagsStartStateMask
, the result can be compared with this value to determine if the form will initially be in application focus mode. -
#define kFrmNavHeaderFlagsAutoGenerated 0x80000000
-
#define kFrmNavHeaderFlagsDefaultStartStateValue 0x00000000
- After masking the flag bits with
kFrmNavHeaderFlagsStartStateMask
, the result can be compared with this value to determine if the form's initial focus mode will be chosen by the system. -
#define kFrmNavHeaderFlagsInvalidStartStateValue 0x00000003
- After masking the flag bits with
kFrmNavHeaderFlagsStartStateMask
, the result can be compared with this value to determine if the focus mode flags are improperly set. -
#define kFrmNavHeaderFlagsObjectFocusStartState 0x00000001
- If this flag is set, the form will initially be in object focus mode.
-
#define kFrmNavHeaderFlagsObjectFocusStartStateValue 0x00000001
- After masking the flag bits with
kFrmNavHeaderFlagsStartStateMask
, the result can be compared with this value to determine if the form will initially be in object focus mode. -
#define kFrmNavHeaderFlagsStartStateMask 0x00000003
- A mask that allows you to isolate the "start state" bits and treat the result as a value. The result can be compared with any of the
kFrmNavHeaderFlags...StartStateValue
constants to determine the starting state.
Comments
If neither kFrmNavHeaderFlagsObjectFocusStartState
nor kFrmNavHeaderFlagsAppFocusStartState
is set, then the system decides whether to initially put the form in object focus mode or application focus mode. It is an error if both flags are set.
Example
The following code excerpt shows how you can check if a form's initial state will be decided by the system.
if ( (navFlags & kFrmNavHeaderFlagsStartStateMask) == kFrmNavHeaderFlagsDefaultStartStateValue)) { // Form's initial state is decided by system }
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
FrmNavObjectFlagsType Typedef
Purpose
Flags that specify different aspects of a navigation object.
Declared In
Form.h
Prototype
typedef UInt16 FrmNavObjectFlagsType
Constants
-
#define kFrmNavObjectFlagsForceInteractionMode 0x0002
- Used with multi-line text fields, if this flag is set the field is put in interaction mode when it receives the focus. Otherwise, the field is drawn in the focused, non-interaction mode state when it receives the focus.
-
#define kFrmNavObjectFlagsIsBigButton 0x8000
- The object is a "big button." Big buttons are a type of UI object created by palmOne. Basically, they are thumbable buttons with a bitmap and some text. They are implemented as gadgets.
-
#define kFrmNavObjectFlagsSkip 0x0001
- If this flag is set, the object is skipped when focus moves from object to object. The object is included in the order only when it explicitly gets focus (which primarily occurs when a field, table with a field, popup trigger, or selector trigger gets focus by being tapped with the pen).
Comments
The flags for a given control in the navigation order can be obtained by calling FrmGetNavEntry()
; you can set them for a control by calling FrmSetNavEntry()
. In both cases the flags are one of the fields of a FrmNavOrderEntryType
structure.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
FrmNavStateFlagsType Typedef
Purpose
Flags that define a form's navigation state. Use FrmGetNavState()
to retrieve a form's navigation state. Use FrmSetNavState()
to set it.
Declared In
Form.h
Prototype
typedef UInt32 FrmNavStateFlagsType
Constants
-
#define kFrmNavStateFlagsInteractionMode 0x00000001
- The form is in "interaction mode." If this bit is not set, the form is in "navigation mode." See the Comments section, below, for information on what these modes mean.
-
#define kFrmNavStateFlagsObjectFocusMode 0x00000002
- The form is in "object focus mode." If this bit is not set, the form is in "application focus mode." See the Comments section, below, for information on what these modes mean.
Comments
Interaction Mode vs. Navigation Mode
More complex objects need to "take over" the scroll keys in order to interact with them. For example, a text field needs to allocate all four scroll keys to move the cursor. Similarly, a pop-up list needs to use up and down to change the selection in the list. This conflicts with the requirement of using the scroll keys to navigate between objects. As a result, these complex objects need to have an interaction mode, where they can take over control of the keys. The opposite of interaction mode is navigation mode, where scroll keys navigate between objects. On a system with one-handed navigation, pressing "center" toggles between interaction mode and navigation mode. Finally, a subset of interaction mode is edit mode, which refers specifically to text fields.
Object Focus Mode vs. Application Focus Mode
Interaction mode and Navigation mode are palmOne concepts. PalmSource has defined application focus mode and object focus mode. Application focus mode refers to applications that do not have keyboard navigation enabled. In this state, up and down act as page up and page down in the traditional method that Palm OS implemented in its original form. Object focus mode refers to the state where individual objects on the screen can receive focus, essentially what "navigation mode" refers to above.
Applications may or may not be able to toggle between application focus and object focus modes.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
Form Navigation Focus Error Codes
Purpose
Error codes returned by the FrmNav...
and Frm...Nav...
functions.
Declared In
Form.h
Constants
-
#define uilibErrCurrentFocusInvalid (uilibErrorClass | 2)
- There is no current focus object.
-
#define uilibErrFormDoesNotHaveFocus (uilibErrorClass | 7)
- The specified form doesn't currently have the focus.
-
#define uilibErrInvalidFocusObject (uilibErrorClass | 6)
- The control to which focus is being transferred is not marked as usable.
-
#define uilibErrInvalidParam (uilibErrorClass | 1)
- At least one of the supplied parameters is invalid.
-
#define uilibErrNoNavInfoForForm (uilibErrorClass | 5)
- The specified form has no navigation information.
-
#define uilibErrObjectFocusModeOff (uilibErrorClass | 3)
- The specified form is not in object focus mode. For the
FrmGlueNav...
functions in the Palm OS Glue library, this error code is also used to indicate that the device doesn't support one-handed navigation. -
#define uilibErrObjectNotFound (uilibErrorClass | 4)
- There is no object with a system-drawn focus ring.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
Form Dynamic Input Area Policies
Purpose
A dynamic input area policy specifies how the dynamic input area should be handled while a form is active. These values are used for the diaPolicy
attribute in a form's attribute structure. You can set the value with FrmSetDIAPolicyAttr
and retrieve it with FrmGetDIAPolicyAttr
.
Declared In
Form.h
Constants
-
#define frmDIAPolicyCustom 1
- The user and the application control whether the input area is active.
-
#define frmDIAPolicyStayOpen 0
- Forces the dynamic input area to stay open while the form is active. The input trigger is disabled.
Compatibility
Implemented only if Pen Input Manager Feature Set is present.
Miscellaneous Form Constants
Purpose
These form constants are also defined.
Declared In
Form.h
Constants
-
#define formNavRscType 'fnav'
- (defined in
UIResources.h
) The resource type of a navigation resource. It is defined as a 68K format (big endian) resource. -
#define frmInvalidObjectId 0xffff
- A constant value that represents an invalid object ID or index.
-
#define frmNavFocusRingNoExtraInfo ((Int16)0xFFFF)
- Value that indicates that there is no extra information associated with current navigation object. Pass this value to
FrmNavDrawFocusRing()
if you have no such information to associate with the object getting the focus ring. This value is returned fromFrmNavGetFocusRingInfo()
if there was no extra information associated with the object around which the focus ring is currently drawn. -
#define frmNoSelectedControl 0xff
- Returned by
FrmGetControlGroupSelection()
if no control is selected. -
#define frmRedrawUpdateCode 0x8000
- Indicates that the form should be redrawn; flag in a
frmUpdateEvent
. -
#define frmResponseCreate 1974
- Passed to
FormCheckResponseFuncType()
to indicate that the function should perform initialization. -
#define frmResponseQuit ((Int16) 0xBEEF)
- Passed to
FormCheckResponseFuncType()
to indicate that the function should perform cleanup. -
#define kFrmNavInfoVersion 1
- The version of the
FrmNavHeaderType
andFrmNavOrderEntryType
structures declared inForm.h
. -
#define noFocus 0xffff
- No form object has the focus.
One-Handed Navigation Trap Selectors
Purpose
Trap selectors for the one-handed navigation functions.
Declared In
Form.h
Constants
-
#define NavSelectorFrmCountObjectsInNavOrder 0x0
-
#define NavSelectorFrmGetNavEntry 0x3
-
#define NavSelectorFrmGetNavOrder 0x1
-
#define NavSelectorFrmGetNavState 0x5
-
#define NavSelectorFrmNavDrawFocusRing 0x7
-
#define NavSelectorFrmNavGetFocusRingInfo 0x9
-
#define NavSelectorFrmNavObjectTakeFocus 0xA
-
#define NavSelectorFrmNavRemoveFocusRing 0x8
-
#define NavSelectorFrmSetNavEntry 0x4
-
#define NavSelectorFrmSetNavOrder 0x2
-
#define NavSelectorFrmSetNavState 0x6
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
Form Resources
The following resources are associated with forms and with the objects on a form whose data structures are defined above:
- Form—Form Resource (tFRM)
- Alert dialog— Alert Resource (Talt)
- Bitmap—Form Bitmap Resource (tFBM)
- Button—Button Resource (tBTN)
- Check box—Check Box Resource (tCBX)
- Field—Field Resource (tFLD)
- Gadget (custom object) — Gadget Resource (tGDT)
- Shift indicator — Shift Indicator Resource (tGSI)
- Label—Label Resource (tLBL)
- List—List Resource (tLST)
- Popup trigger—Popup Trigger Resource (tPUT)
- Push button—Push Button Resource (tPBN)
- Repeating button—Repeating Button Resource (tREP)
- Scrollbar—Scroll Bar Resource (tSCL)
- Selector trigger—Selector Trigger Resource (tSLT)
- Table—Table Resource (tTBL)
See Palm OS User Interface Guidelines for more information on these and other resources.
Form Functions
ECFrmValidatePtr Macro
Returns true
if ERROR_CHECK_LEVEL
is equal to ERROR_CHECK_FULL
and if the specified pointer references a valid form.
Declared In
Form.h
Prototype
#define ECFrmValidatePtr (
formP
)
Parameters
Returns
Returns true
if ERROR_CHECK_LEVEL
is equal to ERROR_CHECK_FULL
and if the specified pointer is a non-NULL
pointer to an object having a valid form structure. If ERROR_CHECK_LEVEL
is not equal to ERROR_CHECK_FULL
, this macro does nothing.
Comments
This macro simply calls FrmValidatePtr()
function if ERROR_CHECK_LEVEL
is equal to ERROR_CHECK_FULL
, and does nothing if it is not. Since FrmValidatePtr()
is intended for debugging purposes only and should not be included in released code, this macro can be used to conditionally compile calls to FrmValidatePtr()
.
Compatibility
FrmValidatePtr()
is implemented only if 3.0 New Feature Set is present.
FrmAlert Function
Purpose
Create a modal dialog from an alert resource and display it until the user selects a button in the dialog.
Declared In
Form.h
Prototype
UInt16 FrmAlert ( UInt16 alertId )
Parameters
Returns
Returns the item number of the button the user selected. A button's item number is determined by its order in the alert dialog; the first button has the item number 0 (zero).
NOTE: A default button press is simulated if the user switches to a different application while a modal dialog is active.
See Also
FrmDoDialog()
, FrmCustomAlert()
, FrmCustomResponseAlert()
FrmCloseAllForms Function
Purpose
Send a frmCloseEvent
to all open forms.
Declared In
Form.h
Prototype
void FrmCloseAllForms ( void )
Parameters
Returns
Comments
Applications can call this function to ensure that all forms are closed cleanly before exiting PilotMain()
; that is, before termination.
See Also
FrmCopyLabel Function
Purpose
Copy the passed string into the data structure of the specified label object in the active form.
Declared In
Form.h
Prototype
void FrmCopyLabel ( FormType *formP, UInt16 labelID, const Char *newLabel )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
labelID
- ID of form label object.
-
→
newLabel
- Pointer to a null-terminated string.
Returns
Comments
The size of the new label must not exceed the size of the label defined in the resource. When defining the label in the resource, specify an initial size at least as big as any of the strings that will be assigned dynamically. This function redraws the label if the form's usable
attribute and the label's visible
attribute are set.
This function redraws the label but does not erase the old one first. If the new label is shorter than the old one, the end of the old label will still be visible. To avoid this, you can hide the label using FrmHideObject()
, then show it using FrmShowObject()
, after using FrmCopyLabel
.
Note that FrmCopyLabel
copies the passed string into memory already allocated for the label. Thus, the string doesn't need to remain in existence once FrmCopyLabel
returns.
See Also
FrmCopyTitle Function
Purpose
Copy a new title over the form's current title. If the form is visible, the new title is drawn.
Declared In
Form.h
Prototype
void FrmCopyTitle ( FormType *formP, const Char *newTitle )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
newTitle
- Pointer to the new title string.
Returns
Comments
The size of the new title must not exceed the title size defined in the resource. When defining the title in the resource, specify an initial size at least as big as any of the strings to be assigned dynamically.
See Also
FrmCountObjectsInNavOrder Function
Purpose
Obtains the number of objects in a form's navigation tab order.
Declared In
Form.h
Prototype
UInt16 FrmCountObjectsInNavOrder (
const FormType *formP
)
Parameters
Returns
The number of objects in the navigation tab order.
Comments
If a form does not have a navigation resource, all objects in the form are included in the tab order. Note, however, that many will be marked as skipped.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
See Also
FrmCustomAlert Function
Purpose
Create a modal dialog from an alert resource and display the dialog until the user taps a button in the alert dialog.
Declared In
Form.h
Prototype
UInt16 FrmCustomAlert ( UInt16 alertId, const Char *s1, const Char *s2, const Char *s3 )
Parameters
Returns
Returns the number of the button the user tapped (the first button is zero).
Comments
A button's item number is determined by its order in the alert template; the first button has the item number zero.
Up to three strings can be passed to this routine. They are used to replace the variables ^1, ^2 and ^3 that are contained in the message string of the alert resource.
If the variables ^1, ^2, and ^3 occur in the message string, do not pass NULL
for the arguments s1
, s2
, and s3
. If you want an argument to be ignored, pass the empty string (""
). In Palm OS 2.0 or below, pass a string containing a space (" "
) instead of the empty string.
NOTE: A default button press is simulated if the user switches to a different application while a modal dialog is active.
See Also
FrmAlert()
, FrmDoDialog()
, FrmCustomResponseAlert()
FrmCustomResponseAlert Function
Purpose
Create a modal dialog with a text field from an alert resource and display it until the user taps a button in the alert dialog.
Declared In
Form.h
Prototype
UInt16 FrmCustomResponseAlert ( UInt16 alertId, const Char *s1, const Char *s2, const Char *s3, Char *entryStringBuf, Int16 entryStringBufLength, FormCheckResponseFuncPtr callback )
Parameters
-
→
alertId
- Resource ID of the alert.
-
→
s1, s2, s3
- Strings to replace ^1, ^2, and ^3. See the Comments in
FrmCustomAlert()
for more information. -
←
entryStringBuf
- The string the user entered in the text field.
-
→
entryStringBufLength
- The maximum length for the string in
entryStringBuf
. -
→
callback
- A callback function that processes the string. See
FormCheckResponseFuncType()
. PassNULL
if there is no callback.
Returns
Returns the number of the button the user tapped (the first button is zero).
Comments
This function differs from FrmCustomAlert()
in these ways:
- The dialog it displays contains a text field for user entry. The text that the user enters is returned in the
entryStringBuf
parameter. - When the user taps a button, the
callback
function is called and is passed the button number andentryStringBuf
. The dialog is only dismissed if the callback returnstrue
. This behavior allows you to perform error checking on the string that the user entered and give the user a chance to re-enter the string.The callback function is also called with special constants when the alert dialog is being initialized and when it is being deallocated. This allows the callback to perform any necessary initialization and cleanup.
NOTE: A default button press is simulated if the user switches to a different application while a modal dialog is active.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
FrmDeleteForm Function
Purpose
Release the memory occupied by a form. Any memory allocated to objects in the form is also released.
Declared In
Form.h
Prototype
void FrmDeleteForm ( FormType *formP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure).
Returns
Comments
This function doesn't modify the display.
Compatibility
If 3.5 New Feature Set is present and the form contains an extended gadget, this function calls the gadget's callback with formGadgetDeleteCmd
. See FormGadgetHandlerType()
.
See Also
FrmInitForm()
, FrmReturnToForm()
FrmDispatchEvent Function
Purpose
Dispatch an event to the application's handler for the form.
Declared In
Form.h
Prototype
Boolean FrmDispatchEvent ( EventType *eventP )
Parameters
Returns
Returns the Boolean value returned by the form's event handler or FrmHandleEvent()
. (If the form's event handler returns false
, the event is passed to FrmHandleEvent
.) This function also returns false if the form specified in the event is invalid.
Comments
The event is dispatched to the current form's handler unless the form ID is specified in the event data, as, for example, with frmOpenEvent
or frmGotoEvent
. A form's event handler (FormEventHandlerType()
) is registered by FrmSetEventHandler()
.
Note that if the form does not have a registered event handler, this function causes a fatal error.
FrmDoDialog Function
Purpose
Display a modal dialog until the user taps a button in the dialog.
Declared In
Form.h
Prototype
UInt16 FrmDoDialog ( FormType *formP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure).
Returns
Returns the resource ID of the button the user tapped.
NOTE: A default button press is simulated if the user switches to a different application while a modal dialog is active.
Comments
Before calling FrmDoDialog you must have called FrmInitForm()
to load and initialize the dialog and you must have then set the event handler, if one is needed. After the call, read any values needed from the dialog's objects and then call FrmDeleteForm()
to release the memory occupied by the dialog.
See Also
FrmInitForm()
, FrmCustomAlert()
, FrmCustomResponseAlert()
FrmDrawForm Function
Purpose
Draw all objects in a form and the frame around the form.
Declared In
Form.h
Prototype
void FrmDrawForm ( FormType *formP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure).
Returns
Comments
If the saveBehind
form attribute is set and the form is visible, this function saves the bits behind the form using the bitsBehindForm field in the FormType
structure.
You should call this function in response to a frmOpenEvent
.
If you do any custom drawing, you should do so after you call this function not before. If you do custom drawing, respond to frmUpdateEvent
as well as frmOpenEvent
, and be sure to return true to specify that the frmUpdateEvent
was handled. The default event handler for frmUpdateEvent
calls FrmDrawForm
, so if you allow the event to fall through by returning false
, your custom drawing is erased.
Compatibility
If 3.5 New Feature Set is present, FrmDrawForm
erases the form's window before performing any drawing. Thus, it is especially important to do any custom drawing after this function call on Palm OS 3.5 and higher.
If 3.5 New Feature Set is present and the form contains an extended gadget, this function calls the gadget's callback with formGadgetDrawCmd
. See FormGadgetHandlerType()
.
See Also
FrmEraseForm Function
Purpose
Erase a form from the display.
Declared In
Form.h
Prototype
void FrmEraseForm ( FormType *formP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure).
Returns
Comments
If the region obscured by the form was saved by FrmDrawForm()
, this function restores that region.
FrmGetActiveField Function
Purpose
Return the active field for a specified form.
Declared In
Form.h
Prototype
FieldType *FrmGetActiveField( const FormType *formP )
Parameters
-
→
formP
- Pointer to the form for which the active field should be returned, or
NULL
if the active field on the active form is desired.
Returns
Returns a pointer to the field object of the active field, or NULL
if the form doesn't have an active field or if there is no active form.
Comments
This function will most often be called with a NULL
parameter to obtain the active field on the active form.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
FrmGetActiveForm Function
Purpose
Return the currently active form.
Declared In
Form.h
Prototype
FormType *FrmGetActiveForm ( void )
Parameters
Returns
Returns a pointer to the form object of the active form.
Comments
You should not call the FrmGetActiveForm
function when a popup window is open. There is no active form while a popup is displayed, and the value returned from FrmGetActiveForm
in this situation has no meaning.
See Also
FrmGetActiveField()
, FrmGetActiveFormID()
, FrmSetActiveForm()
FrmGetActiveFormID Function
Purpose
Return the ID of the currently active form.
Declared In
Form.h
Prototype
UInt16 FrmGetActiveFormID ( void )
Parameters
Returns
Returns the active form's ID number.
See Also
FrmGetControlGroupSelection Function
Purpose
Return the item number of the control selected in a group of controls.
Declared In
Form.h
Prototype
UInt16 FrmGetControlGroupSelection( const FormType *formP, UInt8 groupNum )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
groupNum
- Control group number.
Returns
Returns the item number of the selected control; returns frmNoSelectedControl
if no item is selected.
Comments
The item number is the index into the form object's data structure.
NOTE:
FrmSetControlGroupSelection
sets the selection in a control group based on an object ID, not its index, which FrmGetControlGroupSelection
returns.
Compatibility
On versions prior to 3.5, this function returned a Byte
instead of UInt16
.
See Also
FrmGetObjectId()
, FrmGetObjectPtr()
, FrmSetControlGroupSelection()
FrmGetControlValue Function
Purpose
Return the current value of a control.
Declared In
Form.h
Prototype
Int16 FrmGetControlValue ( const FormType *formP, UInt16 objIndex )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of the control object in the form object's data structure. You can obtain this by using
FrmGetObjectIndex()
.
Returns
Returns the current value of the control. For most controls the return value is either 0 (off) or 1 (on). For sliders, this function returns the value of the value
field.
Comments
The caller must specify a valid index. This function is valid only for push button and check box control objects.
See Also
FrmGetDIAPolicyAttr Function
Purpose
Returns a form's dynamic input area policy.
Declared In
Form.h
Prototype
UInt16 FrmGetDIAPolicyAttr ( FormPtr formP )
Parameters
Returns
Returns one of the constants listed in "Form Dynamic Input Area Policies."
Compatibility
Implemented only if the Pen Input Manager Feature Set is present.
See Also
FrmGetFirstForm Function
Purpose
Return the first form in the window list.
Declared In
Form.h
Prototype
FormType *FrmGetFirstForm ( void )
Parameters
Returns
Returns a pointer to a form object, or NULL
if there are no forms.
Comments
The window list is a LIFO stack. The last window created is the first window in the window list.
FrmGetFocus Function
Purpose
Return the item (index) number of the object that has the focus.
Declared In
Form.h
Prototype
UInt16 FrmGetFocus ( const FormType *formP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure).
Returns
Returns the index of the object (UI element) that has the focus, or returns noFocus
if none does. To convert the object index to an ID, use FrmGetObjectId()
.
See Also
FrmGetObjectPtr()
, FrmSetFocus()
FrmGetFormBounds Function
Purpose
Return the visual bounds of the form; the region returned includes the form's frame.
Declared In
Form.h
Prototype
void FrmGetFormBounds ( const FormType *formP, RectangleType *rP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
←
rP
- Pointer to a RectangleType structure where the bounds is returned.
Returns
Returns nothing. The bounds of the form are returned in r
.
FrmGetFormId Function
Purpose
Return the resource ID of a form.
Declared In
Form.h
Prototype
UInt16 FrmGetFormId ( const FormType *formP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure).
Returns
See Also
FrmGetFormPtr Function
Purpose
Return a pointer to the form that has the specified ID.
Declared In
Form.h
Prototype
FormType *FrmGetFormPtr ( UInt16 formId )
Parameters
Returns
Returns a pointer to the form object, or NULL if the form is not in memory.
See Also
FrmGetGadgetData Function
Purpose
Return the value stored in the data
field of the gadget object.
Declared In
Form.h
Prototype
void *FrmGetGadgetData ( const FormType *formP, UInt16 objIndex )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of the gadget object in the form object's data structure. You can obtain this by using
FrmGetObjectIndex()
.
Returns
Returns a pointer to the custom gadget's data.
Comments
Gadget objects provide a way for an application to attach custom gadgetry to a form. In general, the data
field of a gadget object contains a pointer to the custom object's data structure.
See Also
FrmSetGadgetData()
, FrmSetGadgetHandler()
FrmGetLabel Function
Purpose
Return pointer to the text of the specified label object in the specified form.
Declared In
Form.h
Prototype
const Char *FrmGetLabel ( const FormType *formP, UInt16 labelID )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
labelID
- ID of the label object.
Returns
Returns a pointer to the label string.
Comments
Does not make a copy of the string; returns a pointer to the string. The object must be a label.
See Also
FrmGetNavEntry Function
Purpose
Gets the navigation information for a single object in the form.
Declared In
Form.h
Prototype
Err FrmGetNavEntry ( const FormType*formP
, UInt16targetObjectID
, UInt16*afterObjectIDP
, UInt16*aboveObjectIDP
, UInt16*belowObjectIDP
, FrmNavObjectFlagsType*objectFlagsP
)
Parameters
-
→ formP
- Pointer to the form whose navigation order is being obtained.
-
→ targetObjectID
- The ID of the "target object"—the object whose navigation information is being obtained.
-
← afterObjectIDP
- Pointer to a
UInt16
into which will be written the ID of the object which is to the left of the target object. If the target object is the first one in the tab order, a value of 0 will be written to*afterObjectIDP
. PassNULL
if you do not need this information. -
← aboveObjectIDP
- Pointer to a
UInt16
into which will be written the ID of the object that is above the target object. If the target object is in the top row of the form, a value of 0 will be written to*aboveObjectIDP
. PassNULL
if you do not need this information. -
← belowObjectIDP
- Pointer to a
UInt16
into which will be written the ID of the object that is below the target object. If the target object is in the bottom row of the form, a value of 0 will be written to*belowObjectIDP
. PassNULL
if you do not need this information. -
← objectFlagsP
- Pointer to a
FrmNavObjectFlagsType
into which will be written the object flags for the target object. PassNULL
if you do not need this information.
Returns
errNone
if the operation completed successfully, or an error code otherwise.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
See Also
FrmGetNavOrder()
, FrmSetNavEntry()
FrmGetNavOrder Function
Purpose
Obtains information about the navigation order of a form.
Declared In
Form.h
Prototype
Err FrmGetNavOrder ( const FormType*formP
, FrmNavHeaderType*navHeaderP
, FrmNavOrderEntryType*navOrderP
, UInt16*numObjectsP
)
Parameters
-
→ formP
- Pointer to the form whose focus order is to be obtained.
-
← navHeaderP
- If this pointer is not
NULL
, the caller-suppliedFrmNavHeaderType
structure is filled with the header information for the form's navigation order. -
← navOrderP
- If this pointer is not
NULL
, the caller-supplied array ofFrmNavOrderEntryType
structures is filled with information for each object in the navigation order. -
↔ numObjectsP
- On entry, the number of entries that you allocated in the navigation order array. On exit, this is set to the number of entries that were filled in in the navigation order array.
Returns
errNone
if the operation completed successfully, or an error code otherwise.
Comments
If a form does not have a navigation resource, all objects in the form are included in the tab order. Note, however, that many will be marked as skipped.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
See Also
FrmCountObjectsInNavOrder()
, FrmSetNavOrder()
FrmGetNavState Function
Purpose
Gets the current navigation state of a form.
Declared In
Form.h
Prototype
Err FrmGetNavState ( const FormType*formP
, FrmNavStateFlagsType*stateFlagsP
)
Parameters
-
→ formP
- Pointer to the form whose navigation state is to be obtained.
-
← stateFlagsP
- Pointer to a
FrmNavStateFlagsType
into which the current navigation state is written. This state identifies the form's current focus mode.
Returns
errNone
if the operation completed successfully, or an error code otherwise.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
See Also
FrmGetNumberOfObjects Function
Purpose
Return the number of objects in a form.
Declared In
Form.h
Prototype
UInt16 FrmGetNumberOfObjects( const FormType *formP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure).
Returns
Returns the number of objects in the specified form.
See Also
FrmGetObjectPtr()
, FrmGetObjectId()
FrmGetObjectBounds Function
Purpose
Retrieve the bounds of an object given its form and index.
Declared In
Form.h
Prototype
void FrmGetObjectBounds ( const FormType *formP, UInt16 objIndex, RectangleType *rP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of an object in the form. You can obtain this by using
FrmGetObjectIndex()
. -
←
rP
- Pointer to a RectangleType structure where the object bounds are returned. The bounds are in window-relative coordinates.
Returns
Returns nothing. The object's bounds are returned in r
.
See Also
FrmGetObjectPosition()
, FrmSetObjectBounds()
, FrmSetObjectPosition()
FrmGetObjectId Function
Purpose
Return the ID of the specified object.
Declared In
Form.h
Prototype
UInt16 FrmGetObjectId ( const FormType *formP, UInt16 objIndex )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of an object in the form. You can obtain this by using
FrmGetObjectIndex()
.
Returns
Returns the ID number of an object or frmInvalidObjectId
if the objIndex
parameter is invalid.
See Also
FrmGetObjectIndex Function
Purpose
Return the index of an object in the form's objects list.
Declared In
Form.h
Prototype
UInt16 FrmGetObjectIndex ( const FormType *formP, UInt16 objID )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objID
- ID of an object in the form.
Returns
Returns the index of the specified object (the index of the first object is 0), or frmInvalidObjectId
if the supplied object ID is invalid.
Comments
Bitmaps use a different mechanism for IDs than the rest of the form objects. When finding a bitmap with FrmGetObjectIndex
, you need to pass the bitmap's resource ID, not the ID of the form bitmap object. (Passing the ID of the form bitmap object may or may not give you the right object back, depending on how you created the objects.)
This means that if you've got the same bitmap in two different form bitmap objects on the same form, you won't be able to use FrmGetObjectIndex
to get at the second one; it'll always return the first.
See Also
FrmGetObjectPtr()
, FrmGetObjectId()
FrmGetObjectIndexFromPtr Function
Purpose
Declared In
Form.h
Prototype
UInt16 FrmGetObjectIndexFromPtr( const FormType *formP, void *objP )
Parameters
-
→
formP
- Pointer to a
FormType
. -
→
objP
- Pointer to an object.
Returns
Returns the object's index. frmInvalidObjectId
is returned if objP
is not associated with the form.
Comments
Many form functions (FrmGetObjectType()
, FrmHideObject()
, and FrmGetObjectBounds()
, for example) take an object index as one of their arguments. The most common way to get an object's index is to call FrmGetObjectIndex()
. FrmGetObjectIndex
takes a form ID and returns the form object's index. This is the routine one should use in most cases, because the application usually knows the object ID. However, gadgets and specifically extended gadgets, have APIs with callbacks that pass back the gadget pointer and not the ID. In those cases, the only way to get the object index (so one can use the FrmGetObject
* APIs) is to use FrmGetObjectIndexFromPtr
.
If you need the same functionality on pre-Palm OS 4.0 systems then you can accomplish the same thing with the following code snippet.
UInt16 index; UInt16 objIndex = frmInvalidObjectId; UInt16 numObjects = FrmGetNumberOfObjects(frmP) for (index = 0; index < numObjects; index++) { if (FrmGetObjectPtr(index) == myObjPtr) { // Found it objIndex = index; break; } }
Compatibility
Implemented only if 4.0 New Feature Set is present.
FrmGetObjectPosition Function
Purpose
Return the coordinates of the specified object relative to the form.
Declared In
Form.h
Prototype
void FrmGetObjectPosition ( const FormType *formP, UInt16 objIndex, Coord *x, Coord *y )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of an object in the form. You can obtain this by using
FrmGetObjectIndex()
. -
← x, y
- Pointers where the window-relative x and y positions of the object are returned. These locate the top-left corner of the object.
Returns
See Also
FrmGetObjectBounds()
, FrmSetObjectPosition()
FrmGetObjectPtr Function
Purpose
Return a pointer to the data structure of an object in a form.
Declared In
Form.h
Prototype
void *FrmGetObjectPtr ( const FormType *formP, UInt16 objIndex )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of an object in the form. You can obtain this by using
FrmGetObjectIndex()
.
Returns
Returns a pointer to an object in the form.
See Also
FrmGetObjectType Function
Purpose
Declared In
Form.h
Prototype
FormObjectKind FrmGetObjectType( const FormType *formP, UInt16 objIndex )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of an object in the form. You can obtain this by using
FrmGetObjectIndex()
.
Returns
Returns the type of the specified object. See FormObjectKind
for the set of values that can be returned by this function.
FrmGetTitle Function
Purpose
Return a pointer to the title string of a form.
Declared In
Form.h
Prototype
const Char *FrmGetTitle ( const FormType *formP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure).
Returns
Returns a pointer to title string, or NULL
if there is no title string or there is an error finding it.
Comments
This is a pointer to the internal structure itself, not to a copy.
See Also
FrmGetWindowHandle Function
Purpose
Return the window handle of a form.
Declared In
Form.h
Prototype
WinHandle FrmGetWindowHandle( const FormType *formP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure).
Returns
Returns the handle of the memory block that contains the form data structure. Since the form structure begins with the WindowType
, this is also a WinHandle.
FrmGotoForm Function
Purpose
Send a frmCloseEvent
to the current form; send a frmLoadEvent
and a frmOpenEvent
to the specified form.
Declared In
Form.h
Prototype
void FrmGotoForm ( UInt16 formId )
Parameters
Returns
Comments
The default form event handler (FrmHandleEvent()
) erases and disposes of a form when it receives a frmCloseEvent
.
See Also
FrmHandleEvent Function
Purpose
Handle the event that has occurred in the form.
Declared In
Form.h
Prototype
Boolean FrmHandleEvent ( FormType *formP, EventType *eventP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
eventP
- Pointer to the event data structure (
EventType
).
Returns
Returns true if the event was handled.
Comments
Never call this function directly. Call FrmDispatchEvent()
instead. FrmDispatchEvent
passes events to a form's custom event handler and then, if the event was not handled, to this function.
WARNING! You should never call this function directly. You should call the FrmDispatchEvent function instead.
Table 11.1 provides an overview of how FrmHandleEvent
handles different events.
Table 11.1 FrmHandleEvent Actions
Passes the event and a pointer to the object the event occurred in to |
|
Passes the event and a pointer to the object the event occurred in to |
|
Checks if the control is a Popup Trigger Control. If it is, the list associated with the popup trigger is displayed until the user makes a selection or touches the pen outside the bounds of the list. If a selection is made, a |
|
Checks if a field object or a table object has the focus and passes the event to the appropriate handler ( |
|
Passes the event to the gadget's callback function if the gadget has one. See |
|
Passes the event to the gadget's callback function if the gadget has one. See |
|
Tracks the pen until it is lifted. If it is lifted within the bounds of the form title, adds a |
|
Adds a |
|
Calls |
|
Passes the event to the handler for the object that has the focus. If no object has the focus, the event is ignored. |
|
Passes the event and a pointer to the object the event occurred in to |
|
Checks if a field object or a table object has the focus and passes the event to the appropriate handler ( |
|
Checks if the menu command is one of the system edit menu commands. The system provides a standard edit menu that contains the commands Undo, Cut, Copy, Paste, Select All, and Keyboard. |
|
|
Checks the list of objects contained by the form to determine if the pen is within the bounds of one. If it is, the appropriate handler is called to handle the event, for example, if the pen is in a control, |
Sets the label of the popup trigger to the current selection of the popup list. |
|
Passes the event and a pointer to the object the event occurred in to |
|
Passes the event and a pointer to the object the event occurred in to |
Compatibility
FrmHandleEvent
only handles frmTitleSelectEvent
, menuCmdBarOpenEvent
, frmGadgetEnterEvent
, and frmGadgetMiscEvent
if 3.5 New Feature Set is present. If 5.0 New Feature Set is present, this function should be considered "System Use Only"; applications should do what they can to avoid using it.
See Also
FrmHelp Function
Purpose
Display the specified help message until the user taps the Done button in the help dialog.
Declared In
Form.h
Prototype
void FrmHelp ( UInt16 helpMsgId )
Parameters
Returns
Comments
The help message is displayed in a modal dialog that supports scrolling the text if necessary.
FrmHideObject Function
Purpose
Erase the specified object and set its attribute data (usable
bit) so that it does not redraw or respond to the pen.
Declared In
Form.h
Prototype
void FrmHideObject ( FormType *formP, UInt16 objIndex )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of an object in the form. You can obtain this by using
FrmGetObjectIndex()
.
Returns
Compatibility
Prior to OS version 3.2, this function did not set the usable
bit of the object attribute data to false
. On an OS version prior to 3.2 you can work around this bug by directly setting this bit to false
yourself.
On versions of Palm OS prior to 3.5 this function doesn't affect lists or tables. On Palm OS 3.5 it operates correctly on lists but doesn't have any effect on tables. On Palm OS 4.0 it operates correctly on both lists and tables.
If 3.5 New Feature Set is present and the object is an extended gadget, this function calls the gadget's callback with formGadgetEraseCmd
. See FormGadgetHandlerType()
.
See Also
FrmInitForm Function
Purpose
Load and initialize a form resource.
Declared In
Form.h
Prototype
FormType *FrmInitForm ( UInt16 rscID )
Parameters
Returns
Returns a pointer to the form data structure.
When using debug ROMs, FrmInitForm
displays an error message if the form has already been initialized.
Comments
This function does not affect the display (use FrmDrawForm()
to draw the form) nor make the form active (use FrmSetActiveForm()
to make it active).
For each initialized form, you must call FrmDeleteForm
to release the form memory when you are done with the form. Alternatively, you can free the active form by calling FrmReturnToForm
.
See Also
FrmDoDialog()
, FrmDeleteForm()
, FrmReturnToForm()
FrmNavDrawFocusRing Function
Purpose
Tells the system to draw a focus ring for an object.
NOTE: This function is implemented differently on different Palm OS handhelds; developers should use
FrmGlueNavDrawFocusRing()
instead.
Declared In
Form.h
Prototype
Err FrmNavDrawFocusRing ( FormType*formP
, UInt16objectID
, Int16extraInfo
, RectangleType*boundsInsideRingP
, FrmNavFocusRingStyleEnumringStyle
, BooleanforceRestore
)
Parameters
-
→ formP
- Pointer to the form containing the object whose ring is to be drawn.
-
→ objectID
- ID of object getting the focus ring.
-
→ extraInfo
- Any information that you want associated with the focus ring. For example, the system uses this field to store the temporarily-selected item of a focused, embedded list. Pass frmNavFocusRingNoExtraInfo if you have no information to associate with the ring.
-
→ boundsInsideRingP
- Pointer to a
RectangleType
structure defining the bounds around which the ring should be drawn. -
→ ringStyle
- One of the
FrmNavFocusRingStyleEnum
values that represents the desired style for the ring. PassfrmNavFocusRingStyleObjectTypeDefault
if you want the default ring style for the object's type. -
→ forceRestore
- Specifies whether, if the ring is already on the object, what is behind the ring should be restored prior to redrawing the ring.
Returns
errNone
if the focus ring was drawn successfully, or an error code such as one of the following otherwise:
-
uilibErrInvalidParam
-
formP
orboundsInsideRingP
isNULL
. -
uilibErrInvalidFocusObject
-
objectID
specifies a control that is not marked as usable. -
uilibErrFormDoesNotHaveFocus
- The specified form doesn't currently have the focus.
-
uilibErrObjectFocusModeOff
- The specified form is not in object focus mode.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present. Developers should use the Palm OS Glue Library equivalent of this function—FrmGlueNavDrawFocusRing()
—for maximum compatibility.
See Also
FrmNavGetFocusRingInfo()
, FrmNavObjectTakeFocus()
, FrmNavRemoveFocusRing()
FrmNavGetFocusRingInfo Function
Purpose
If a form has a system-drawn focus ring, gets information about the ring.
NOTE: This function is implemented differently on different Palm OS handhelds; developers should use
FrmGlueNavGetFocusRingInfo()
instead.
Declared In
Form.h
Prototype
Err FrmNavGetFocusRingInfo ( const FormType*formP
, UInt16*objectIDP
, Int16*extraInfoP
, RectangleType*boundsInsideRingP
, FrmNavFocusRingStyleEnum*ringStyleP
)
Parameters
-
→ formP
- Pointer to the form whose ring information is to be obtained.
-
← objectIDP
- Supply a pointer to a
UInt16
that, upon exit will contain the ID of the object with the system-drawn focus ring. PassNULL
for this parameter if you don't need this information. -
← extraInfoP
- Supply a pointer to a
UInt16
that, upon exit will contain to any extra information associated with the focus ring; passNULL
if you don't need this information. "Extra information" is any information that was associated with the ring whenFrmNavDrawFocusRing()
was called. If there is no extra information associated with the focus ring,*extraInfoP
is set to frmNavFocusRingNoExtraInfo. -
← boundsInsideRingP
- Supply a pointer to a
RectangleType
structure into which the bounds of the system-drawn focus ring will be written. PassNULL
for this parameter if you don't need this information. -
← ringStyleP
- Supply a pointer to a
FrmNavFocusRingStyleEnum
variable into which the style of the focus ring will be written. PassNULL
for this parameter if you don't need this information.
Returns
errNone
if the focus ring was drawn successfully, or an error code such as one of the following otherwise:
-
uilibErrFormDoesNotHaveFocus
- The specified form doesn't currently have the focus.
-
uilibErrObjectFocusModeOff
- The specified form is not in object focus mode.
-
uilibErrObjectNotFound
- There is no object with a system-drawn focus ring.
Comments
For embedded lists in interaction mode, the system stores the temporarily selected item in the extra info field.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present. Developers should use the Palm OS Glue Library equivalent of this function—FrmGlueNavGetFocusRingInfo()
—for maximum compatibility.
See Also
FrmNavDrawFocusRing()
, FrmNavRemoveFocusRing()
FrmNavObjectTakeFocus Function
Purpose
Sends a frmObjectFocusTakeEvent
event for an object.
NOTE: This function is implemented differently on different Palm OS handhelds; developers should use
FrmGlueNavObjectTakeFocus()
instead.
Declared In
Form.h
Prototype
void FrmNavObjectTakeFocus ( const FormType*formP
, UInt16objID
)
Parameters
Returns
Compatibility
Implemented only if One-Handed Navigation Feature Set is present. Developers should use the Palm OS Glue Library equivalent of this function—FrmGlueNavObjectTakeFocus()
—for maximum compatibility.
FrmNavRemoveFocusRing Function
Purpose
Removes the system-drawn ring from around the currently-focused object.
NOTE: This function is implemented differently on different Palm OS handhelds; developers should use
FrmGlueNavRemoveFocusRing()
instead.
Declared In
Form.h
Prototype
Err FrmNavRemoveFocusRing (
FormType *formP
)
Parameters
Returns
errNone
if the focus ring was drawn successfully, or an error code such as one of the following otherwise:
-
uilibErrInvalidParam
-
formP
isNULL
. -
uilibErrFormDoesNotHaveFocus
- The specified form doesn't currently have the focus.
-
uilibErrObjectFocusModeOff
- The specified form is not in object focus mode.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present. Developers should use the Palm OS Glue Library equivalent of this function—FrmGlueNavRemoveFocusRing()
—for maximum compatibility.
See Also
FrmNavDrawFocusRing()
, FrmNavGetFocusRingInfo()
FrmNewBitmap Function
Purpose
Create a new form bitmap dynamically.
Declared In
Form.h
Prototype
FormBitmapType *FrmNewBitmap ( FormType **formPP, UInt16 ID, UInt16 rscID, Coord x, Coord y )
Parameters
-
↔
formPP
- Pointer to a pointer to the form in which the new bitmap is installed. This value is not a handle; that is, the old
formPP
value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the newformPP
value returned by this function. -
→
ID
- Symbolic ID of the bitmap, specified by the developer. By convention, this ID should match the resource ID (not mandatory).
-
→
rscID
- Numeric value identifying the resource that provides the bitmap. This value must be unique within the application scope.
-
→
x
- Horizontal coordinate of the upper-left corner of the bitmap's boundaries, relative to the window in which it appears.
-
→
y
- Vertical coordinate of the upper-left corner of the bitmap's boundaries, relative to the window in which it appears.
Returns
Returns a pointer to the new bitmap, or 0 if the call did not succeed. The most common cause of failure is lack of memory.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
FrmNewForm Function
Purpose
Create a new form object dynamically.
Declared In
Form.h
Prototype
FormType *FrmNewForm ( UInt16 formID, const Char *titleStrP, Coord x, Coord y, Coord width, Coord height, Boolean modal, UInt16 defaultButton, UInt16 helpRscID, UInt16 menuRscID )
Parameters
-
→
formID
- Symbolic ID of the form, specified by the developer. By convention, this ID should match the resource ID (not mandatory).
-
→
titleStrP
- Pointer to a string that is the title of the form.
-
→
x
- Horizontal coordinate of the upper-left corner of the form's boundaries, relative to the window in which it appears.
-
→
y
- Vertical coordinate of the upper-left corner of the form's boundaries, relative to the window in which it appears.
-
→
width
- Width of the form, expressed in pixels. Valid values are 1 -160.
-
→
height
- Height of the form, expressed in pixels.Valid values are 1 -160.
-
→
modal
-
true
specifies that the form ignores pen events outside its boundaries. -
→
defaultButton
- Symbolic ID of the button that provides the form's default action, specified by the developer.
-
→
helpRscID
- Symbolic ID of the resource that provides the form's online help, specified by the developer. Only modal dialogs can have help resources.
-
→
menuRscID
- Symbolic ID of the resource that provides the form's menus, specified by the developer.
Returns
Returns a pointer to the new form object, or 0 if the call did not succeed. The most common cause of failure is lack of memory.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
FrmValidatePtr()
, WinValidateHandle()
, FrmRemoveObject()
FrmNewGadget Function
Purpose
Create a new gadget dynamically and install it in the specified form.
Declared In
Form.h
Prototype
FormGadgetType *FrmNewGadget ( FormType **formPP, UInt16 id, Coord x, Coord y, Coord width, Coord height )
Parameters
-
↔
formPP
- Pointer to a pointer to the form in which the new gadget is installed. This value is not a handle; that is, the old
formPP
value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the newformPP
value returned by this function. -
→
id
- Symbolic ID of the gadget, specified by the developer. By convention, this ID should match the resource ID (not mandatory).
-
→
x
- Horizontal coordinate of the upper-left corner of the gadget's boundaries, relative to the window in which it appears.
-
→
y
- Vertical coordinate of the upper-left corner of the gadget's boundaries, relative to the window in which it appears.
-
→
width
- Width of the gadget, expressed in pixels. Valid values are 1 - 160.
-
→
height
- Height of the gadget, expressed in pixels.Valid values are 1 - 160.
Returns
Returns a pointer to the new gadget object or 0 if the call did not succeed. The most common cause of failure is lack of memory.
Comments
A gadget is a custom user interface object. For more information, see Palm OS User Interface Guidelines.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
FrmNewGsi Function
Purpose
Create a new shift indicator dynamically and install it in the specified form.
Declared In
Form.h
Prototype
FrmGraffitiStateType *FrmNewGsi( FormType **formPP, Coord x, Coord y )
Parameters
-
↔
formPP
- Pointer to a pointer to the form in which the new shift indicator is installed. This value is not a handle; that is, the old
formPP
value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the newformPP
value returned by this function. -
→
x
- Horizontal coordinate of the upper-left corner of the shift indicator's boundaries, relative to the window in which it appears.
-
→
y
- Vertical coordinate of the upper-left corner of the shift indicator's boundaries, relative to the window in which it appears.
Returns
Returns a pointer to the new gadget object or 0 if the call did not succeed. The most common cause of failure is lack of memory.
Comments
In normal operation, the shift indicator is drawn in the lower-right portion of the screen when the user enters the shift keystroke. You use this function if the shift indicator needs to be drawn in a nonstandard location. For example, the form manager uses it to draw the shift indicator in a custom alert dialog that contains a text field (FrmCustomResponseAlert()
).
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
FrmNewLabel Function
Purpose
Create a new label object dynamically and install it in the specified form.
Declared In
Form.h
Prototype
FormLabelType *FrmNewLabel ( FormType **formPP, UInt16 ID, const Char *textP, Coord x, Coord y, FontID font )
Parameters
-
↔
formPP
- Pointer to a pointer to the form in which the new label is installed. This value is not a handle; that is, the old
formPP
value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the newformPP
value returned by this function. -
→
ID
- Symbolic ID of the label, specified by the developer. By convention, this ID should match the resource ID (not mandatory).
-
→
textP
- Pointer to a string that provides the label text. This string is copied into the label structure.
-
→
x
- Horizontal coordinate of the upper-left corner of the label's boundaries, relative to the window in which it appears.
-
→
y
- Vertical coordinate of the upper-left corner of the label's boundaries, relative to the window in which it appears.
-
→
font
- Font with which to draw the label text.
Returns
Returns a pointer to the new label object or 0 if the call did not succeed. The most common cause of failure is lack of memory.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
CtlValidatePointer()
, FrmRemoveObject()
FrmPointInTitle Function
Purpose
Check if a coordinate is within the bounds of the form's title.
Declared In
Form.h
Prototype
Boolean FrmPointInTitle ( const FormType *formP, Coord x, Coord y )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
x, y
- Window-relative x and y coordinates.
Returns
Returns true
if the specified coordinate is in the form's title.
Compatibility
Implemented only if 2.0 New Feature Set is present.
FrmPopupForm Function
Purpose
Queues a frmLoadEvent
and a frmOpenEvent
for the specified form.
Declared In
Form.h
Prototype
void FrmPopupForm ( UInt16 formId )
Parameters
Returns
Comments
This routine differs from FrmGotoForm()
in that the current form is not closed. You can call FrmReturnToForm()
to close a form opened by FrmPopupForm
.
FrmRemoveObject Function
Purpose
Remove the specified object from the specified form.
Declared In
Form.h
Prototype
Err FrmRemoveObject ( FormType **formPP, UInt16 objIndex )
Parameters
-
↔
formPP
- Pointer to a pointer to the form from which this function removes an object. This value is not a handle; that is, the old
formPP
value is not necessarily valid after this function returns. In subsequent calls, always use the newformPP
value returned by this function. -
→
objIndex
- The object to remove, specified as an index into the list of objects installed in the form. You can use the
FrmGetObjectIndex()
function to discover this value.
Returns
Comments
You can use this function to remove any form object (a bitmap, control, list, and so on) and free the memory allocated to it within the form data structure. The data structures for most form objects are embedded within the form data structure memory chunk. This function frees that memory and moves the other objects, if necessary, to close up the memory "hole" and decrease the size of the form chunk.
Note that this function does not free memory outside the form data structure that may be allocated to an object, such as the memory allocated to the string in an editable field object.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
FrmNewBitmap()
, FrmNewForm()
, FrmNewGadget()
, FrmNewLabel()
, CtlNewControl()
, FldNewField()
, LstNewList()
FrmRestoreActiveState Macro
Purpose
Restores the active window and form state.
Declared In
Form.h
Prototype
#define FrmRestoreActiveState ( stateP )
Parameters
-
→
stateP
- A pointer to the
FormActiveStateType
structure that you passed toFrmSaveActiveState
when you saved the state.
Returns
Comments
Use this function to restore the state of displayed forms to the state that existed before you dynamically showed a new modal form. You must have previously invoked FrmSaveActiveState()
to save the state.
Compatibility
Implemented only if 3.0 New Feature Set is present.
FrmReturnToForm Function
Purpose
Erase and delete the currently active form and make the specified form the active form.
Declared In
Form.h
Prototype
void FrmReturnToForm ( UInt16 formId )
Parameters
Returns
Comments
It is assumed that the form being returned to is already loaded into memory and initialized. Passing a form ID of 0 returns to the first form in the window list, which is the last form to be loaded.
FrmReturnToForm
does not generate a frmCloseEvent
when called from a modal form's event handler. It assumes that you have already handled cleaning up your form's variables since you are explicitly calling FrmReturnToForm
.
See Also
FrmSaveActiveState Macro
Purpose
Saves the active window and form state.
Declared In
Form.h
Prototype
#define FrmSaveActiveState ( stateP )
Parameters
-
↔
stateP
- A pointer to a
FormActiveStateType
structure that is used to save the state. Pass the same pointer toFrmRestoreActiveState()
to restore the state. Treat the structure like a black box; that is, don't attempt to read it or write to it.
Returns
Comments
Use this function to save the state of displayed forms before dynamically showing a new modal form. Invoke FrmRestoreActiveState()
to restore the state after you remove the modal form.
Compatibility
Implemented only if 3.0 New Feature Set is present.
FrmSaveAllForms Function
Purpose
Send a frmSaveEvent
to all open forms.
Declared In
Form.h
Prototype
void FrmSaveAllForms ( void )
Parameters
Returns
See Also
FrmSetActiveForm Function
Purpose
Set the active form. All input (key and pen) is directed to the active form and all drawing occurs there.
Declared In
Form.h
Prototype
void FrmSetActiveForm ( FormType *formP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure).
Returns
Comments
A penDownEvent
outside the form but within the display area is ignored.
Compatibility
In Palm OS releases earlier than 3.5, this function generated a winEnterEvent
for the new form immediately following the winExitEvent
for the old form. Starting in Palm OS 3.5, FrmSetActiveForm
does not generate the winEnterEvent
. The winEnterEvent
does not occur until the newly active form is drawn.
See Also
FrmSetCategoryLabel Function
Purpose
Set the category label displayed on the title line of a form. If the form's visible
attribute is set, redraw the label.
Declared In
Form.h
Prototype
void FrmSetCategoryLabel ( const FormType *formP, UInt16 objIndex, Char *newLabel )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of an object in the form. You can obtain this by using
FrmGetObjectIndex()
. -
→
newLabel
- Pointer to the name of the new category.
Returns
Comments
The pointer to the new label (newLabel
) is saved in the object.
FrmSetControlGroupSelection Function
Purpose
Set the selected control in a group of controls.
Declared In
Form.h
Prototype
void FrmSetControlGroupSelection( const FormType *formP, UInt8 groupNum, UInt16 controlID )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
groupNum
- Control group number.
-
→
controlID
- ID of control to set.
Returns
Comments
This function unsets all the other controls in the group. The display is updated.
NOTE:
FrmGetControlGroupSelection
returns the selection in a control group as an object index, not as an object ID, which FrmSetControlGroupSelection
uses to set the selection.
See Also
FrmSetControlValue Function
Purpose
Sets the current value of a control. If the control is visible, it's redrawn.
Declared In
Form.h
Prototype
void FrmSetControlValue ( const FormType *formP, UInt16 objIndex, Int16 newValue )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→ objIndex
- Index of the control in the form. You can obtain this by using
FrmGetObjectIndex()
. -
→
newValue
- New value to set for the control. For sliders, specify a value between the slider's minimum and maximum. For graphical controls, push buttons, or check boxes, specify 0 for off, nonzero for on.
Returns
Comments
This function works only with graphical controls, sliders, push buttons, and check boxes. If you set the value of any other type of control, the behavior is undefined.
See Also
FrmSetDIAPolicyAttr Function
Purpose
Sets a form's dynamic input area policy.
Declared In
Form.h
Prototype
Err FrmSetDIAPolicyAttr ( FormPtr formP, UInt16 diaPolicy )
Parameters
-
→
formP
- A pointer to a
FormType
structure. -
→
diaPolicy
- One of the constants listed in "Form Dynamic Input Area Policies."
Returns
Returns errNone
if no error or pinErrInvalidParam
if the diaPolicy
parameter is out of range.
Comments
Applications call this function in response to the frmLoadEvent
or frmOpenEvent
, to set the policy that the form should use for opening and closing the dynamic input area. Note that if an application does not call this function, the default is frmDIAPolicyStayOpen
. This allows legacy application to always be sized appropriately because the input area is always open, with the trigger disabled, while the legacy application is running.
Compatibility
Implemented only if the Pen Input Manager Feature Set is present.
See Also
PINSetInputAreaState
, FrmGetDIAPolicyAttr
FrmSetEventHandler Function
Purpose
Registers the event handler callback routine for the specified form.
Declared In
Form.h
Prototype
void FrmSetEventHandler ( FormType *formP, FormEventHandlerType *handler )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
handler
- Address of the form event handler function,
FormEventHandlerType()
.
Returns
Comments
FrmDispatchEvent()
calls this handler whenever it receives an event for a specific form.
FrmSetEventHandler
must be called right after a form resource is loaded. The callback routine it registers is the mechanism for dispatching events to an application. The tutorial explains how to use callback routines.
FrmSetFocus Function
Purpose
Set the focus of a form to the specified object.
Declared In
Form.h
Prototype
void FrmSetFocus ( FormType *formP, UInt16 fieldIndex )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
fieldIndex
- Index of the object to get the focus in the form. You can obtain this by using
FrmGetObjectIndex()
. You can pass the constantnoFocus
so that no object has the focus.
Returns
Comments
You can set the focus to a field or table object. If the focus is set to a field object, this function turns on the insertion point in the field by calling FldGrabFocus()
internally.
See Also
FrmSetGadgetData Function
Purpose
Store a data value in the data
field of the gadget object.
Declared In
Form.h
Prototype
void FrmSetGadgetData ( FormType *formP, UInt16 objIndex, const void *data )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of an object in the form. You can obtain this by using
FrmGetObjectIndex()
. -
→
data
- Application-defined value. This value is stored into the
data
field of the gadget data structure (FormGadgetType
).
Returns
Comments
Gadget objects provide a way for an application to attach custom gadgetry to a form. Typically, the data
field of a gadget object contains a pointer to the custom object's data structure.
See Also
FrmGetGadgetData()
, FrmSetGadgetHandler()
FrmSetGadgetHandler Function
Purpose
Registers the gadget event handler callback routine for the specified gadget on the specified form.
Declared In
Form.h
Prototype
void FrmSetGadgetHandler ( FormType *formP, UInt16 objIndex, FormGadgetHandlerType *attrP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of a gadget object in the form. You can obtain this by using
FrmGetObjectIndex()
. -
→
attrP
- Address of the callback function. See
FormGadgetHandlerType()
.
Returns
Comments
This function sets the application-defined function that controls the specified gadget's behavior. This function is called when the gadget needs to be drawn, erased, deleted, or needs to handle an event.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
FrmGetGadgetData()
, FrmSetGadgetData()
FrmSetMenu Function
Purpose
Change a form's menu bar and make the new menu active.
Declared In
Form.h
Prototype
void FrmSetMenu ( FormType *formP, UInt16 menuRscID )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
menuRscID
- Resource ID of the menu.
Returns
Compatibility
Implemented only if 2.0 New Feature Set is present.
FrmSetNavEntry Function
Purpose
Alters the navigation information for a single object in the form.
Declared In
Form.h
Prototype
Err FrmSetNavEntry ( FormType*formP
, UInt16targetObjectID
, UInt16afterObjectID
, UInt16aboveObjectID
, UInt16belowObjectID
, FrmNavObjectFlagsTypeobjectFlags
)
Parameters
-
→ formP
- Pointer to the form whose navigation order is being changed.
-
→ targetObjectID
- The ID of the object which is being edited, added, or removed.
-
→ afterObjectID
- The ID of the object which will be to the left of the target object. The object that is currently to the right of the after object will then be to the right of the target object. To place the target object at the beginning of the order, making it the leftmost object in the row, supply an ID of 0. Supply an ID of
frmInvalidObjectId
to have the target object completely removed from the navigation order. -
→ aboveObjectID
- The ID of the object that will be above the target object. Supply an ID of 0 if the target object is in the top row of the form.
-
→ belowObjectID
- The ID of the object that will be below the target object. Supply an ID of 0 if the target object is in the bottom row of the form.
-
→ objectFlags
- The new object flags for the target object. See
FrmNavObjectFlagsType
.
Returns
errNone
if the operation completed successfully, or an error code otherwise.
Comments
NOTE: This function is not intended to replace the use of navigation resources. A form that needs to have a custom navigation order should always provide a navigation resource. This function is mainly for dynamically created forms or forms that have a navigation resource but change the order sometime after form initialization.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
See Also
FrmSetNavOrder Function
Purpose
Sets the navigation order and/or header information for a form.
Declared In
Form.h
Prototype
Err FrmSetNavOrder ( FormType*formP
, FrmNavHeaderType*navHeaderP
, FrmNavOrderEntryType*navOrderP
)
Parameters
-
→ formP
- Pointer to the form whose focus order is to be set.
-
→ navHeaderP
- Pointer to a
FrmNavHeaderType
structure that contains header information for the form's navigation order. This parameter cannot beNULL
. -
→ navOrderP
- Pointer to an array of
FrmNavOrderEntryType
structures that specifies the new navigation order for the form. The number of entries in the array must be equal to the header parameter'snumberOfObjects
field. PassNULL
if you do not want to change the form's navigation order but only want to change the form's header information.
Returns
errNone
if the operation completed successfully, or an error code otherwise.
Comments
This function makes a copy of all information passed-in.
If the object with the current focus is removed from the order, the object will be redrawn in its non-focused state and the form will have no current focus.
NOTE: This function is not intended to replace the use of navigation resources. A form that needs to have a custom navigation order should always provide a navigation resource. This function is mainly for dynamically created forms or forms that have a navigation resource but change the order sometime after form initialization.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
See Also
FrmSetNavState Function
Purpose
Sets the navigation state of a form.
Declared In
Form.h
Prototype
Err FrmSetNavState ( FormType*formP
, FrmNavStateFlagsTypestateFlags
)
Parameters
-
→ formP
- Pointer to the form whose navigation state is being set.
-
→ stateFlags
- Flags that indicate the new navigation state. This state identifies the form's current focus mode. See "FrmNavStateFlagsType" for the flags that make up this parameter.
Returns
errNone
if the operation completed successfully, or an error code otherwise.
Compatibility
Implemented only if One-Handed Navigation Feature Set is present.
See Also
FrmSetObjectBounds Function
Purpose
Set the bounds or position of an object.
Declared In
Form.h
Prototype
void FrmSetObjectBounds ( FormType *formP, UInt16 objIndex, const RectangleType *bounds )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of an object in the form. You can obtain this by using
FrmGetObjectIndex()
. -
→
bounds
- Window-relative bounds. For the following objects, this sets only the position of the top-left corner: label, bitmap, and shift indicator.
Returns
Comments
Compatibility
Implemented only if 2.0 New Feature Set is present.
See Also
FrmGetObjectPosition()
, FrmGetObjectBounds()
, FrmSetObjectPosition()
FrmSetObjectPosition Function
Purpose
Set the position of an object.
Declared In
Form.h
Prototype
void FrmSetObjectPosition ( FormType *formP, UInt16 objIndex, Coord x, Coord y )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of an object in the form. You can obtain this by using
FrmGetObjectIndex()
. -
→
x
- Window-relative horizontal coordinate.
-
→
y
- Window-relative vertical coordinate.
Returns
See Also
FrmGetObjectPosition()
, FrmGetObjectBounds()
FrmSetTitle Function
Purpose
Set the title of a form. If the form is visible, draw the new title.
Declared In
Form.h
Prototype
void FrmSetTitle ( FormType *formP, Char *newTitle )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
newTitle
- Pointer to the new title string.
Returns
Comments
This function draws the title if the form is visible.
This function saves the pointer passed in newTitle
; it does not make a copy. The value of newTitle
must not be a pointer to a stack-based object.
Compatibility
Earlier versions of this function redrew the title without first erasing the old one. This problem was corrected in version 3.0 of Palm OS.
See Also
FrmGetTitle()
, FrmCopyTitle()
, FrmCopyLabel()
FrmShowObject Function
Purpose
Set a form object as usable. If the form is visible, draw the object.
Declared In
Form.h
Prototype
void FrmShowObject ( FormType *formP, UInt16 objIndex )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
objIndex
- Index of an object in the form. You can obtain this by using
FrmGetObjectIndex()
.
Returns
Compatibility
On versions of Palm OS prior to 3.5 this function doesn't affect lists or tables. On Palm OS 3.5 it operates correctly on lists but doesn't have any effect on tables. On Palm OS 4.0 it operates correctly on both lists and tables.
If 3.5 New Feature Set is present and the object is an extended gadget, this function calls the gadget's callback with formGadgetDrawCmd
. See FormGadgetHandlerType()
.
See Also
FrmUpdateForm Function
Purpose
Send a frmUpdateEvent
to the specified form.
Declared In
Form.h
Prototype
void FrmUpdateForm ( UInt16 formId, UInt16 updateCode )
Parameters
-
→
formId
- Resource ID of form to update.
-
→
updateCode
- An application-defined code that can be used to indicate what needs to be updated. Specify the code frmRedrawUpdateCode to indicate that the whole form should be redrawn.
Returns
Comments
If the frmUpdateEvent
posted by this function is handled by the default form event handler, FrmHandleEvent()
, the updateCode
parameter is ignored. FrmHandleEvent
always redraws the form.
If you handle the frmUpdateEvent
in a custom event handler, you can use the updateCode
parameter any way you want. For example, you might use it to indicate that only a certain part of the form needs to be redrawn. If you do handle the frmUpdateEvent
, be sure to return true
from your event handler so that the default form handler does not also redraw the whole form.
If you do handle the frmUpdateEvent
in a custom event handler, be sure to handle the case where updateCode
is set to frmRedrawUpdateCode, and redraw the whole form. This event (and code) is sent by the system when the whole form needs to be redrawn because the display needs to be refreshed.
FrmUpdateScrollers Function
Purpose
Visually update (show or hide) the field scroll arrow buttons.
Declared In
Form.h
Prototype
void FrmUpdateScrollers ( FormType *formP, UInt16 upIndex, UInt16 downIndex, Boolean scrollableUp, Boolean scrollableDown )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure). -
→
upIndex
- Index of the up-scroller button. You can obtain this by using
FrmGetObjectIndex()
. -
→
downIndex
- Index of the down-scroller button. You can obtain this by using
FrmGetObjectIndex
. -
→
scrollableUp
- Set to true to make the up scroll arrow active (shown), or
false
to hide it. -
→
scrollableDown
- Set to true to make the down scroll arrow active (shown), or
false
to hide it.
Returns
Comments
This function was originally only supposed to be used with textual buttons, because it uses the Symbol font to update the arrow appearance (either black or gray, up or down). However, it is somewhat tolerant of various button types. On non-textual buttons you can get the enable/disable behavior, which, if you're using a gadget, you can use to change the appearance of your custom scroller button. If you don't pass this function a textual button, it won't try to update the button's appearance using the button's the "text" member.
FrmValidatePtr Function
Purpose
Return true
if the specified pointer references a valid form.
Declared In
Form.h
Prototype
Boolean FrmValidatePtr ( const FormType *formP )
Parameters
Returns
Returns true
if the specified pointer is a non-NULL
pointer to an object having a valid form structure.
Comments
This function is intended for debugging purposes only. Do not include it in released code.
To distinguish between a window and a form in released code, instead of using this function, look at the flag windowFlags.dialog
in the WindowType
structure. This flag is true
if the window is a form.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
FrmVisible Function
Purpose
Return true
if the form is visible (is drawn).
Declared In
Form.h
Prototype
Boolean FrmVisible ( const FormType *formP )
Parameters
-
→
formP
- Pointer to the form object (
FormType
structure).
Returns
Returns true if the form is visible; false if it is not visible.
See Also
Application-Defined Functions
FormCheckResponseFuncType Function
Purpose
Callback function for FrmCustomResponseAlert()
.
Declared In
Form.h
Prototype
Boolean FormCheckResponseFuncType ( Int16 button, Char *attempt )
typedef FormCheckResponseFuncType *FormCheckResponseFuncPtr
Parameters
-
→
button
- The ID of the button that the user tapped.
-
→
attempt
- The string that the user entered in the alert dialog.
Returns
Return true
if the dialog should be dismissed. Return false
if the dialog should not be dismissed.
Comments
This function is called at these times during the FrmCustomResponseAlert
routine:
- At the beginning of
FrmCustomResponseAlert
, this function is called with a button ID offrmResponseCreate
. This constant indicates that the dialog is about to be displayed, and your function should perform any necessary initialization. For example, on a Japanese system, a password dialog might need to disable the Japanese FEP. So it would callTsmSetFepMode(NULL, tsmFepModeOff)
in this function. - When the user has tapped a button on the dialog. The function should process the
attempt
string. If the string is valid input, the function should returntrue
. If not, it should returnfalse
to give the user a chance to re-enter the string. - At the end of
FrmCustomResponseAlert
, this function is called with a button ID offrmResponseQuit
. This gives the callback a change to perform any cleanup, such as re-enabling the Japanese FEP.
Compatibility
Implemented only if 3.5 New Feature Set is present.
FormEventHandlerType Function
Purpose
The event handler callback routine for a form.
Declared In
Form.h
Prototype
Boolean FormEventHandlerType ( EventType *eventP )
typedef FormEventHandlerType *FormEventHandlerPtr
Parameters
-
→ eventP
- Pointer to the form event (
FormType
structure).
Returns
Must return true
if this routine handled the event, otherwise false
.
Comments
FrmDispatchEvent()
calls this handler whenever it receives an event for the form.
This callback routine is the mechanism for dispatching events to particular forms in an application. The callback is registered by the routine FrmSetEventHandler()
.
FormGadgetHandlerType Function
Purpose
The event handler callback for an extended gadget.
Declared In
Form.h
Prototype
Boolean ( FormGadgetHandlerType )( struct FormGadgetTypeInCallback *gadgetP, UInt16 cmd, void *paramP )
Parameters
-
→
gadgetP
- Pointer to the gadget structure. See
FormGadgetType
. -
→
cmd
- A constant that specifies what action the handler should take. This can be one of the following:
-
formGadgetDeleteCmd
- Sent by
FrmDeleteForm()
to indicate that the gadget is being deleted and must clean up any memory it has allocated or perform other cleanup tasks. -
formGadgetDrawCmd
- Sent by
FrmDrawForm()
andFrmShowObject()
to indicate that the gadget must be drawn or redrawn. -
formGadgetEraseCmd
- Sent by
FrmHideObject()
to indicate that the gadget is going to be erased.FrmHideObject
clears thevisible
andusable
flags for you. If you returnfalse
, it also callsWinEraseRectangle
to erase the gadget's bounds. -
formGadgetHandleEventCmd
- Sent by
FrmHandleEvent()
to indicate that a gadget event has been received. TheparamP
parameter contains the pointer to theEventType
structure. -
→
paramP
-
NULL
except ifcmd
isformGadgetHandleEventCmd
. In that case, this parameter holds the pointer to theEventType
structure containing the event.
Returns
Return true
if the event was handed successfully; false
otherwise.
Comments
If this function performs any drawing in response to the formGadgetDrawCmd
, it should set the gadget's visible
attribute flag. (gadgetP->attr.visible = true
). This flag indicates that the gadget appears on the screen. If you don't set the visible
flag, the gadget won't be erased when FrmHideObject()
is called. (FrmHideObject
immediately returns if the object's visible
flag is false
.)
Note that if the function receives the formGadgetEraseCmd
, it may simply choose to perform any necessary cleanup and return false
. If the function returns false
, FrmHideObject
erases the gadget's bounding rectangle. If the function returns true
, it must erase the gadget area itself.
If this function receives a formGadgetHandleEventCmd
, paramP
points one of two events: frmGadgetEnterEvent
or frmGadgetMiscEvent
. The frmGadgetEnterEvent
is passed when there is a penDownEvent
within the gadget's bounds. This function should track the pen and perform any necessary highlighting. The frmGadgetMiscEvent
is never sent by the system. Your application may choose to use it if at any point it needs to send data to the extended gadget. In this case, the event has one or both of these fields defined: selector
, an unsigned integer, and dataP
, a pointer to data.
Compatibility
Implemented only if 3.5 New Feature Set is present.