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

11    Forms

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

Part I: User Interface

11 Forms

Form Structures and Types

AlertTemplateType

FormActiveStateType

FormAttrType

FormBitmapType

FormFrameType

FormGadgetAttrType

FormGadgetType

FormGadgetTypeInCallback

FormLabelType

FormLineType

FormObjAttrType

FormObjectType

FormObjListType

FormPopupType

FormPtr

FormRectangleType

FormTitleType

FormType

FrmGraffitiStateType

FrmNavHeaderType

FrmNavOrderEntryType

Form Constants

AlertType

FormObjectKind

FrmNavFocusRingStyleEnum

FrmNavHeaderFlagsType

FrmNavObjectFlagsType

FrmNavStateFlagsType

Form Navigation Focus Error Codes

Form Dynamic Input Area Policies

Miscellaneous Form Constants

One-Handed Navigation Trap Selectors

Form Resources

Form Functions

ECFrmValidatePtr

FrmAlert

FrmCloseAllForms

FrmCopyLabel

FrmCopyTitle

FrmCountObjectsInNavOrder

FrmCustomAlert

FrmCustomResponseAlert

FrmDeleteForm

FrmDispatchEvent

FrmDoDialog

FrmDrawForm

FrmEraseForm

FrmGetActiveField

FrmGetActiveForm

FrmGetActiveFormID

FrmGetControlGroupSelection

FrmGetControlValue

FrmGetDIAPolicyAttr

FrmGetFirstForm

FrmGetFocus

FrmGetFormBounds

FrmGetFormId

FrmGetFormPtr

FrmGetGadgetData

FrmGetLabel

FrmGetNavEntry

FrmGetNavOrder

FrmGetNavState

FrmGetNumberOfObjects

FrmGetObjectBounds

FrmGetObjectId

FrmGetObjectIndex

FrmGetObjectIndexFromPtr

FrmGetObjectPosition

FrmGetObjectPtr

FrmGetObjectType

FrmGetTitle

FrmGetWindowHandle

FrmGotoForm

FrmHandleEvent

FrmHelp

FrmHideObject

FrmInitForm

FrmNavDrawFocusRing

FrmNavGetFocusRingInfo

FrmNavObjectTakeFocus

FrmNavRemoveFocusRing

FrmNewBitmap

FrmNewForm

FrmNewGadget

FrmNewGsi

FrmNewLabel

FrmPointInTitle

FrmPopupForm

FrmRemoveObject

FrmRestoreActiveState

FrmReturnToForm

FrmSaveActiveState

FrmSaveAllForms

FrmSetActiveForm

FrmSetCategoryLabel

FrmSetControlGroupSelection

FrmSetControlValue

FrmSetDIAPolicyAttr

FrmSetEventHandler

FrmSetFocus

FrmSetGadgetData

FrmSetGadgetHandler

FrmSetMenu

FrmSetNavEntry

FrmSetNavOrder

FrmSetNavState

FrmSetObjectBounds

FrmSetObjectPosition

FrmSetTitle

FrmShowObject

FrmUpdateForm

FrmUpdateScrollers

FrmValidatePtr

FrmVisible

Application-Defined Functions

FormCheckResponseFuncType

FormEventHandlerType

FormGadgetHandlerType

     

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

AlertTemplateType Struct ^TOP^

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

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

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

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 a BitmapType structure.

FormFrameType Struct ^TOP^

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

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 by FrmHideObject().
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 its FormGadgetType. 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 ^TOP^

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

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

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

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

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

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

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

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

Purpose

The FormPtr type defines a pointer to a FormType structure.

Prototype

typedef FormType *FormPtr;

FormRectangleType Struct ^TOP^

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

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

rect
The location and size of the title area.
text
Text of the title.

FormType Struct ^TOP^

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 with FrmGetWindowHandle().
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 with FrmGetFormId().
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 to noFocus if no object has the focus. Set this field with FrmSetFocus().
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 ^TOP^

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

pos
Location of the shift indicator.

FrmNavHeaderType Struct ^TOP^

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 by kFrmNavInfoVersion.
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 [see FrmNavOrderEntryType] is 0). A bottomLeftObjectIDHint 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 ^TOP^

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's FrmNavHeaderType 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 ^TOP^

AlertType Enum ^TOP^

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

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

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

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

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

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

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

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

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 from FrmNavGetFocusRingInfo() 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 and FrmNavOrderEntryType structures declared in Form.h.
#define noFocus 0xffff
No form object has the focus.

One-Handed Navigation Trap Selectors ^TOP^

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

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

ECFrmValidatePtr Macro ^TOP^

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

#defineECFrmValidatePtr (
   formP
)

Parameters

formP
Pointer to be tested.

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

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 (
   UInt16alertId
)

Parameters

alertId
ID of the alert resource.

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

Purpose

Send a frmCloseEvent to all open forms.

Declared In

Form.h

Prototype

void FrmCloseAllForms (
   void
)

Parameters

None.

Returns

Returns nothing.

Comments

Applications can call this function to ensure that all forms are closed cleanly before exiting PilotMain(); that is, before termination.

See Also

FrmSaveAllForms()

FrmCopyLabel Function ^TOP^

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

Parameters

formP
Pointer to the form object (FormType structure).
labelID
ID of form label object.
newLabel
Pointer to a null-terminated string.

Returns

Returns nothing.

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

FrmGetLabel()

FrmCopyTitle Function ^TOP^

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

Parameters

formP
Pointer to the form object (FormType structure).
newTitle
Pointer to the new title string.

Returns

Returns nothing.

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

FrmGetTitle(), FrmSetTitle()

FrmCountObjectsInNavOrder Function ^TOP^

Purpose

Obtains the number of objects in a form's navigation tab order.

Declared In

Form.h

Prototype

UInt16FrmCountObjectsInNavOrder (
   constFormType*formP
)

Parameters

formP
Pointer to the form whose navigation information is to be obtained.

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

FrmGetNavOrder()

FrmCustomAlert Function ^TOP^

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 (
   UInt16alertId,
   constChar*s1,
   constChar*s2,
   constChar*s3
) 

Parameters

alertId
Resource ID of the alert.
s1, s2, s3
Strings to replace ^1, ^2, and ^3 (see Comments).

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

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 (
   UInt16alertId,
   constChar*s1,
   constChar*s2,
   constChar*s3,
   Char*entryStringBuf,
   Int16entryStringBufLength,
   FormCheckResponseFuncPtrcallback
)

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(). Pass NULL 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 and entryStringBuf. The dialog is only dismissed if the callback returns true. 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

FrmAlert(), FrmDoDialog()

FrmDeleteForm Function ^TOP^

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

Returns nothing.

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

Purpose

Dispatch an event to the application's handler for the form.

Declared In

Form.h

Prototype

Boolean FrmDispatchEvent (
   EventType*eventP
)

Parameters

eventP
Pointer to an event.

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

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

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

Returns nothing.

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(), FrmInitForm()

FrmEraseForm Function ^TOP^

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

Returns nothing.

Comments

If the region obscured by the form was saved by FrmDrawForm(), this function restores that region.

FrmGetActiveField Function ^TOP^

Purpose

Return the active field for a specified form.

Declared In

Form.h

Prototype

FieldType*FrmGetActiveField(
   constFormType*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()

FrmGetActiveForm Function ^TOP^

Purpose

Return the currently active form.

Declared In

Form.h

Prototype

FormType*FrmGetActiveForm (
   void
)

Parameters

None.

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

Purpose

Return the ID of the currently active form.

Declared In

Form.h

Prototype

UInt16 FrmGetActiveFormID (
   void
)

Parameters

None.

Returns

Returns the active form's ID number.

See Also

FrmGetActiveForm()

FrmGetControlGroupSelection Function ^TOP^

Purpose

Return the item number of the control selected in a group of controls.

Declared In

Form.h

Prototype

UInt16 FrmGetControlGroupSelection(
   constFormType*formP,
   UInt8groupNum
)

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

Purpose

Return the current value of a control.

Declared In

Form.h

Prototype

Int16 FrmGetControlValue (
   constFormType*formP,
   UInt16objIndex
)

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

FrmSetControlValue()

FrmGetDIAPolicyAttr Function ^TOP^

Purpose

Returns a form's dynamic input area policy.

Declared In

Form.h

Prototype

UInt16 FrmGetDIAPolicyAttr (
   FormPtrformP
)

Parameters

formP
A pointer to a FormType structure.

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

FrmSetDIAPolicyAttr

FrmGetFirstForm Function ^TOP^

Purpose

Return the first form in the window list.

Declared In

Form.h

Prototype

FormType*FrmGetFirstForm (
   void
)

Parameters

None.

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

Purpose

Return the item (index) number of the object that has the focus.

Declared In

Form.h

Prototype

UInt16 FrmGetFocus (
   constFormType*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 ^TOP^

Purpose

Return the visual bounds of the form; the region returned includes the form's frame.

Declared In

Form.h

Prototype

void FrmGetFormBounds (
   constFormType*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 ^TOP^

Purpose

Return the resource ID of a form.

Declared In

Form.h

Prototype

UInt16 FrmGetFormId (
   constFormType*formP
)

Parameters

formP
Pointer to the form object (FormType structure).

Returns

Returns form resource ID.

See Also

FrmGetFormPtr()

FrmGetFormPtr Function ^TOP^

Purpose

Return a pointer to the form that has the specified ID.

Declared In

Form.h

Prototype

FormType*FrmGetFormPtr (
   UInt16formId
)

Parameters

formId
Form ID number.

Returns

Returns a pointer to the form object, or NULL if the form is not in memory.

See Also

FrmGetFormId()

FrmGetGadgetData Function ^TOP^

Purpose

Return the value stored in the data field of the gadget object.

Declared In

Form.h

Prototype

void *FrmGetGadgetData (
   constFormType*formP,
   UInt16objIndex
)

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

Purpose

Return pointer to the text of the specified label object in the specified form.

Declared In

Form.h

Prototype

constChar*FrmGetLabel (
   constFormType*formP,
   UInt16labelID
)

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

FrmCopyLabel()

FrmGetNavEntry Function ^TOP^

Purpose

Gets the navigation information for a single object in the form.

Declared In

Form.h

Prototype

ErrFrmGetNavEntry (
   constFormType*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. Pass NULL 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. Pass NULL 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. Pass NULL if you do not need this information.
objectFlagsP
Pointer to a FrmNavObjectFlagsType into which will be written the object flags for the target object. Pass NULL 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 ^TOP^

Purpose

Obtains information about the navigation order of a form.

Declared In

Form.h

Prototype

ErrFrmGetNavOrder (
   constFormType*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-supplied FrmNavHeaderType structure is filled with the header information for the form's navigation order.
navOrderP
If this pointer is not NULL, the caller-supplied array of FrmNavOrderEntryType 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 ^TOP^

Purpose

Gets the current navigation state of a form.

Declared In

Form.h

Prototype

ErrFrmGetNavState (
   constFormType*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

FrmSetNavState()

FrmGetNumberOfObjects Function ^TOP^

Purpose

Return the number of objects in a form.

Declared In

Form.h

Prototype

UInt16 FrmGetNumberOfObjects(
   constFormType*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 ^TOP^

Purpose

Retrieve the bounds of an object given its form and index.

Declared In

Form.h

Prototype

void FrmGetObjectBounds (
   constFormType*formP,
   UInt16objIndex,
   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 ^TOP^

Purpose

Return the ID of the specified object.

Declared In

Form.h

Prototype

UInt16 FrmGetObjectId (
   constFormType*formP,
   UInt16objIndex
)

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

FrmGetObjectPtr()

FrmGetObjectIndex Function ^TOP^

Purpose

Return the index of an object in the form's objects list.

Declared In

Form.h

Prototype

UInt16 FrmGetObjectIndex (
   constFormType*formP,
   UInt16objID
)

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

Purpose

Return an object's index.

Declared In

Form.h

Prototype

UInt16 FrmGetObjectIndexFromPtr(
   constFormType*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 ^TOP^

Purpose

Return the coordinates of the specified object relative to the form.

Declared In

Form.h

Prototype

void FrmGetObjectPosition (
   constFormType*formP,
   UInt16objIndex,
   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

Returns nothing.

See Also

FrmGetObjectBounds(), FrmSetObjectPosition()

FrmGetObjectPtr Function ^TOP^

Purpose

Return a pointer to the data structure of an object in a form.

Declared In

Form.h

Prototype

void *FrmGetObjectPtr (
   constFormType*formP,
   UInt16objIndex
)

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

FrmGetObjectId()

FrmGetObjectType Function ^TOP^

Purpose

Return the type of an object.

Declared In

Form.h

Prototype

FormObjectKind FrmGetObjectType(
   constFormType*formP,
   UInt16objIndex
)

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

Purpose

Return a pointer to the title string of a form.

Declared In

Form.h

Prototype

constChar*FrmGetTitle (
   constFormType*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

FrmCopyTitle(), FrmSetTitle()

FrmGetWindowHandle Function ^TOP^

Purpose

Return the window handle of a form.

Declared In

Form.h

Prototype

WinHandle FrmGetWindowHandle(
   constFormType*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 ^TOP^

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 (
   UInt16formId
)

Parameters

formId
ID of the form to display.

Returns

Returns nothing.

Comments

The default form event handler (FrmHandleEvent()) erases and disposes of a form when it receives a frmCloseEvent.

See Also

FrmPopupForm()

FrmHandleEvent Function ^TOP^

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

When FrmHandleEvent receives...

FrmHandleEvent performs these actions...

ctlEnterEvent

Passes the event and a pointer to the object the event occurred in to CtlHandleEvent(). The object pointer is obtained from the event data. If the control is part of an exclusive control group, it deselects the currently selected control of the group first.

ctlRepeatEvent

Passes the event and a pointer to the object the event occurred in to CtlHandleEvent. The object pointer is obtained from the event data.

ctlSelectEvent

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 popSelectEvent is added to the event queue.

fldEnterEvent or
fldHeightChangedEvent

Checks if a field object or a table object has the focus and passes the event to the appropriate handler (FldHandleEvent() or TblHandleEvent()). The table object is also a container object, which may contain a field object. If TblHandleEvent receives a field event, it passes the event to the field object contained within it.

frmCloseEvent

Erases the form and releases any memory allocated for it.

frmGadgetEnterEvent

Passes the event to the gadget's callback function if the gadget has one. See FormGadgetHandlerType().

frmGadgetMiscEvent

Passes the event to the gadget's callback function if the gadget has one. See FormGadgetHandlerType().

frmTitleEnterEvent

Tracks the pen until it is lifted. If it is lifted within the bounds of the form title, adds a frmTitleSelectEvent event to the event queue.

frmTitleSelectEvent

Adds a keyDownEvent with the vchrMenu character to the event queue.

frmUpdateEvent

Calls FrmDrawForm() to redraw the form.

keyDownEvent

Passes the event to the handler for the object that has the focus. If no object has the focus, the event is ignored.

lstEnterEvent

Passes the event and a pointer to the object the event occurred in to LstHandleEvent(). The object pointer is obtained from the event data.

menuCmdBarOpenEvent

Checks if a field object or a table object has the focus and passes the event to the appropriate handler (FldHandleEvent or TblHandleEvent), broadcasts the notification sysNotifyMenuCmdBarOpenEvent, and then displays the command toolbar.

menuEvent

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. FrmHandleEvent responds to these commands.

penDownEvent; pen position in the bounds of the form object

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, CtlHandleEvent is called. If the pen isn't within the bounds of an object, the event is ignored by the form. If the pen is within the bounds of the help icon, it is tracked until it is lifted, and if it's still within the help icon bounds, the help dialog is displayed.

popSelectEvent

Sets the label of the popup trigger to the current selection of the popup list.

sclEnterEvent or
sclRepeatEvent

Passes the event and a pointer to the object the event occurred in to SclHandleEvent().

tblEnterEvent

Passes the event and a pointer to the object the event occurred in to TblHandleEvent. The object pointer is obtained from the event data.

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

FrmDispatchEvent()

FrmHelp Function ^TOP^

Purpose

Display the specified help message until the user taps the Done button in the help dialog.

Declared In

Form.h

Prototype

void FrmHelp (
   UInt16helpMsgId
)

Parameters

helpMsgId
Resource ID of help message string.

Returns

Returns nothing.

Comments

The help message is displayed in a modal dialog that supports scrolling the text if necessary.

FrmHideObject Function ^TOP^

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

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

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

FrmShowObject()

FrmInitForm Function ^TOP^

Purpose

Load and initialize a form resource.

Declared In

Form.h

Prototype

FormType*FrmInitForm (
   UInt16rscID
)

Parameters

rscID
Resource ID of the form.

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

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

ErrFrmNavDrawFocusRing (
   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. Pass frmNavFocusRingStyleObjectTypeDefault 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 or boundsInsideRingP is NULL.
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 ^TOP^

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

ErrFrmNavGetFocusRingInfo (
   constFormType*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. Pass NULL 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; pass NULL if you don't need this information. "Extra information" is any information that was associated with the ring when FrmNavDrawFocusRing() 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. Pass NULL 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. Pass NULL 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 ^TOP^

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

voidFrmNavObjectTakeFocus (
   constFormType*formP,
   UInt16objID
)

Parameters

formP
Pointer to the form that contains the object.
objID
ID of the object.

Returns

Nothing.

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

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

ErrFrmNavRemoveFocusRing (
   FormType*formP
)

Parameters

formP
Pointer to the form containing the object with the focus ring.

Returns

errNone if the focus ring was drawn successfully, or an error code such as one of the following otherwise:

uilibErrInvalidParam
formP is NULL.
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 ^TOP^

Purpose

Create a new form bitmap dynamically.

Declared In

Form.h

Prototype

FormBitmapType *FrmNewBitmap (
   FormType**formPP,
   UInt16ID,
   UInt16rscID,
   Coordx,
   Coordy
)

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 new formPP 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

FrmRemoveObject()

FrmNewForm Function ^TOP^

Purpose

Create a new form object dynamically.

Declared In

Form.h

Prototype

FormType*FrmNewForm (
   UInt16formID,
   constChar*titleStrP,
   Coordx,
   Coordy,
   Coordwidth,
   Coordheight,
   Booleanmodal,
   UInt16defaultButton,
   UInt16helpRscID,
   UInt16menuRscID
)

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

Purpose

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

Declared In

Form.h

Prototype

FormGadgetType *FrmNewGadget (
   FormType**formPP,
   UInt16id,
   Coordx,
   Coordy,
   Coordwidth,
   Coordheight
)

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 new formPP 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

FrmRemoveObject()

FrmNewGsi Function ^TOP^

Purpose

Create a new shift indicator dynamically and install it in the specified form.

Declared In

Form.h

Prototype

FrmGraffitiStateType*FrmNewGsi(
   FormType**formPP,
   Coordx,
   Coordy
)

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 new formPP 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

FrmRemoveObject()

FrmNewLabel Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

FormLabelType *FrmNewLabel (
   FormType**formPP,
   UInt16ID,
   constChar*textP,
   Coordx,
   Coordy,
   FontIDfont
)

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

Purpose

Check if a coordinate is within the bounds of the form's title.

Declared In

Form.h

Prototype

Boolean FrmPointInTitle (
   constFormType*formP,
   Coordx,
   Coordy
)

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

Purpose

Queues a frmLoadEvent and a frmOpenEvent for the specified form.

Declared In

Form.h

Prototype

void FrmPopupForm (
   UInt16formId
)

Parameters

formID
Resource ID of form to open.

Returns

Returns nothing.

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

Purpose

Remove the specified object from the specified form.

Declared In

Form.h

Prototype

Err FrmRemoveObject (
   FormType**formPP,
   UInt16objIndex
)

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 new formPP 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

Returns 0 if no error.

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

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 to FrmSaveActiveState when you saved the state.

Returns

Returns zero on success.

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

Purpose

Erase and delete the currently active form and make the specified form the active form.

Declared In

Form.h

Prototype

void FrmReturnToForm (
   UInt16formId
)

Parameters

formID
Resource ID of the form to return to.

Returns

Returns nothing.

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

FrmGotoForm(), FrmPopupForm()

FrmSaveActiveState Macro ^TOP^

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 to FrmRestoreActiveState() to restore the state. Treat the structure like a black box; that is, don't attempt to read it or write to it.

Returns

Returns zero on success.

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

Purpose

Send a frmSaveEvent to all open forms.

Declared In

Form.h

Prototype

void FrmSaveAllForms (
   void
)

Parameters

None.

Returns

Returns nothing.

See Also

FrmCloseAllForms()

FrmSetActiveForm Function ^TOP^

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

Returns nothing.

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

FrmGetActiveForm()

FrmSetCategoryLabel Function ^TOP^

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 (
   constFormType*formP,
   UInt16objIndex,
   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

Returns nothing.

Comments

The pointer to the new label (newLabel) is saved in the object.

FrmSetControlGroupSelection Function ^TOP^

Purpose

Set the selected control in a group of controls.

Declared In

Form.h

Prototype

void FrmSetControlGroupSelection(
   constFormType*formP,
   UInt8groupNum,
   UInt16controlID
)

Parameters

formP
Pointer to the form object (FormType structure).
groupNum
Control group number.
controlID
ID of control to set.

Returns

Returns nothing.

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

FrmGetControlGroupSelection()

FrmSetControlValue Function ^TOP^

Purpose

Sets the current value of a control. If the control is visible, it's redrawn.

Declared In

Form.h

Prototype

void FrmSetControlValue (
   constFormType*formP,
   UInt16objIndex,
   Int16newValue
)

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

Returns nothing.

Comments

This function works only with graphical controls, sliders, push buttons, and check boxes. If you set the value of any other type of control, the behavior is undefined.

See Also

FrmGetControlValue()

FrmSetDIAPolicyAttr Function ^TOP^

Purpose

Sets a form's dynamic input area policy.

Declared In

Form.h

Prototype

Err FrmSetDIAPolicyAttr (
   FormPtrformP,
   UInt16diaPolicy
)

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

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

Returns nothing.

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

Purpose

Set the focus of a form to the specified object.

Declared In

Form.h

Prototype

void FrmSetFocus (
   FormType*formP,
   UInt16fieldIndex
)

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 constant noFocus so that no object has the focus.

Returns

Returns nothing.

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

FrmGetFocus()

FrmSetGadgetData Function ^TOP^

Purpose

Store a data value in the data field of the gadget object.

Declared In

Form.h

Prototype

void FrmSetGadgetData (
   FormType*formP,
   UInt16objIndex,
   constvoid *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

Returns nothing.

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

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,
   UInt16objIndex,
   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

Returns nothing.

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

Purpose

Change a form's menu bar and make the new menu active.

Declared In

Form.h

Prototype

void FrmSetMenu (
   FormType*formP,
   UInt16menuRscID
)

Parameters

formP
Pointer to the form object (FormType structure).
menuRscID
Resource ID of the menu.

Returns

Returns nothing.

Compatibility

Implemented only if 2.0 New Feature Set is present.

FrmSetNavEntry Function ^TOP^

Purpose

Alters the navigation information for a single object in the form.

Declared In

Form.h

Prototype

ErrFrmSetNavEntry (
   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

FrmGetNavEntry()

FrmSetNavOrder Function ^TOP^

Purpose

Sets the navigation order and/or header information for a form.

Declared In

Form.h

Prototype

ErrFrmSetNavOrder (
   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 be NULL.
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's numberOfObjects field. Pass NULL 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

FrmGetNavOrder()

FrmSetNavState Function ^TOP^

Purpose

Sets the navigation state of a form.

Declared In

Form.h

Prototype

ErrFrmSetNavState (
   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

FrmGetNavState()

FrmSetObjectBounds Function ^TOP^

Purpose

Set the bounds or position of an object.

Declared In

Form.h

Prototype

void FrmSetObjectBounds (
   FormType*formP,
   UInt16objIndex,
   constRectangleType*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

Returns nothing.

Comments

Doesn't update the display.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

FrmGetObjectPosition(), FrmGetObjectBounds(), FrmSetObjectPosition()

FrmSetObjectPosition Function ^TOP^

Purpose

Set the position of an object.

Declared In

Form.h

Prototype

void FrmSetObjectPosition (
   FormType*formP,
   UInt16objIndex,
   Coordx,
   Coordy
)

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

Returns nothing.

See Also

FrmGetObjectPosition(), FrmGetObjectBounds()

FrmSetTitle Function ^TOP^

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

Returns nothing.

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

Purpose

Set a form object as usable. If the form is visible, draw the object.

Declared In

Form.h

Prototype

void FrmShowObject (
   FormType*formP,
   UInt16objIndex
)

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

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

FrmHideObject()

FrmUpdateForm Function ^TOP^

Purpose

Send a frmUpdateEvent to the specified form.

Declared In

Form.h

Prototype

void FrmUpdateForm (
   UInt16formId,
   UInt16updateCode
)

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

Returns nothing.

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

Purpose

Visually update (show or hide) the field scroll arrow buttons.

Declared In

Form.h

Prototype

void FrmUpdateScrollers (
   FormType*formP,
   UInt16upIndex,
   UInt16downIndex,
   BooleanscrollableUp,
   BooleanscrollableDown
)

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

Returns nothing.

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

Purpose

Return true if the specified pointer references a valid form.

Declared In

Form.h

Prototype

Boolean FrmValidatePtr (
   constFormType*formP
)

Parameters

formP
Pointer to be tested.

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

ECFrmValidatePtr()

FrmVisible Function ^TOP^

Purpose

Return true if the form is visible (is drawn).

Declared In

Form.h

Prototype

Boolean FrmVisible (
   constFormType*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

FrmDrawForm(), FrmEraseForm()

Application-Defined Functions ^TOP^

FormCheckResponseFuncType Function ^TOP^

Purpose

Callback function for FrmCustomResponseAlert().

Declared In

Form.h

Prototype

Boolean FormCheckResponseFuncType (
   Int16button,
   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 of frmResponseCreate. 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 call TsmSetFepMode(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 return true. If not, it should return false to give the user a chance to re-enter the string.
  • At the end of FrmCustomResponseAlert, this function is called with a button ID of frmResponseQuit. 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 ^TOP^

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

Purpose

The event handler callback for an extended gadget.

Declared In

Form.h

Prototype

Boolean (
   FormGadgetHandlerType
)(
   structFormGadgetTypeInCallback*gadgetP,
   UInt16cmd,
   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() and FrmShowObject() 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 the visible and usable flags for you. If you return false, it also calls WinEraseRectangle to erase the gadget's bounds.
formGadgetHandleEventCmd
Sent by FrmHandleEvent() to indicate that a gadget event has been received. The paramP parameter contains the pointer to the EventType structure.
paramP
NULL except if cmd is formGadgetHandleEventCmd. In that case, this parameter holds the pointer to the EventType 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.

See Also

FrmSetGadgetHandler()