Forms
 

 < Home   < Developers   < Development Support   < Documentation

11 Forms


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part I: User Interface

11 Forms

Form Data Structures

FormAttrType

FormBitmapType

FormFrameType

FormGadgetAttrType

FormGadgetType

FormLabelType

FormLineType

FormObjAttrType

FormObjectKind

FormObjectType

FormObjListType

FormPopupType

FormPtr

FormRectangleType

FormTitleType

FormType

FrmGraffitiStateType

Form Constants

Form Resources

Form Functions

FrmAlert

FrmCloseAllForms

FrmCopyLabel

FrmCopyTitle

FrmCustomAlert

FrmCustomResponseAlert

FrmDeleteForm

FrmDispatchEvent

FrmDoDialog

FrmDrawForm

FrmEraseForm

FrmGetActiveField

FrmGetActiveForm

FrmGetActiveFormID

FrmGetControlGroupSelection

FrmGetControlValue

FrmGetFirstForm

FrmGetFocus

FrmGetFormBounds

FrmGetFormId

FrmGetFormPtr

FrmGetGadgetData

FrmGetLabel

FrmGetNumberOfObjects

FrmGetObjectBounds

FrmGetObjectId

FrmGetObjectIndex

FrmGetObjectIndexFromPtr

FrmGetObjectPosition

FrmGetObjectPtr

FrmGetObjectType

FrmGetTitle

FrmGetWindowHandle

FrmGotoForm

FrmHandleEvent

FrmHelp

FrmHideObject

FrmInitForm

FrmNewBitmap

FrmNewForm

FrmNewGadget

FrmNewGsi

FrmNewLabel

FrmPointInTitle

FrmPopupForm

FrmRemoveObject

FrmRestoreActiveState

FrmReturnToForm

FrmSaveActiveState

FrmSaveAllForms

FrmSetActiveForm

FrmSetCategoryLabel

FrmSetControlGroupSelection

FrmSetControlValue

FrmSetEventHandler

FrmSetFocus

FrmSetGadgetData

FrmSetGadgetHandler

FrmSetMenu

FrmSetObjectBounds

FrmSetObjectPosition

FrmSetTitle

FrmShowObject

FrmUpdateForm

FrmUpdateScrollers

FrmValidatePtr

FrmVisible

Application-Defined Functions

FormCheckResponseFunc

FormEventHandler

FormGadgetHandler

       

This chapter provides the following information about form objects:

Form Data Structures

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 "Forms, Windows, and Dialogs" in the Palm OS Programmer's Companion, vol. I.

Form Data Structures

FormAttrType

The FormAttrType bit field defines the visible characteristics of the form.


WARNING! Palm, 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.
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.

Field Descriptions

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 graffiti 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

The FormBitmapType structure defines the visible characteristics of a bitmap on a form.


WARNING! Palm, 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.
typedef struct { 
  FormObjAttrType  attr; 
  PointType        pos; 
  UInt16           rscID; 
} FormBitmapType; 

Field Descriptions

attr
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

The FormFrameType structure defines a frame that appears on the form.

typedef struct { 
  UInt16           id; 
  FormObjAttrType  attr; 
  RectangleType    rect; 
  UInt16           frameType; 
} FormFrameType; 

Field Descriptions

id
ID of the frame.
attr
rect
Location and size of the frame.
frameType
The type of frame.

FormGadgetAttrType

The FormGadgetAttrType bit field defines a gadget's attributes.


WARNING! Palm, 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.
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.

Field Descriptions

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

The FormGadgetType structure defines a gadget object that appears on a form.


WARNING! Palm, 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.
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.

Field Descriptions

id
ID of the gadget resource.
attr
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 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

In Palm OS® releases prior to 3.5, the attr field was of type FormObjAttrType and the handler field did not exist.

FormLabelType

The FormLabelType structure defines a label that appears on a form.


WARNING! Palm, 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.

Field Descriptions

id
Resource ID of the label.
pos
Location of the label.
attr
fontID
Font ID of the font used for the label.
reserved
Reserved for future use.
text
Text of the label.

FormLineType

The FormLineType structure defines a line appearing on a form.

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.

Field Descriptions

attr
point1
Starting point of the line.
point2
Ending point of the line.

FormObjAttrType

The FormObjAttrType bit field defines a form object's attributes.


WARNING! Palm, 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.
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.

Field Descriptions

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.

FormObjectKind

The FormObjectKind enum specifies values for the objectType field of the FormObjListType. It specifies how to interpret the object field.

enum formObjects { 
  frmFieldObj, 
  frmControlObj, 
  frmListObj, 
  frmTableObj, 
  frmBitmapObj, 
  frmLineObj, 
  frmFrameObj, 
  frmRectangleObj, 
  frmLabelObj, 
  frmTitleObj, 
  frmPopupObj,  
  frmGraffitiStateObj, 
  frmGadgetObj, 
  frmScrollbarObj, 
}; 
typedef enum formObjects FormObjectKind; 

Value Descriptions

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® state indicator
frmGadgetObj
Gadget (custom object)
frmScrollbarObj
Scrollbar

FormObjectType

The FormObjectType union points to the C structure for a user interface object that appears on the form.

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.

Field Descriptions

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
Graffiti 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

The FormObjectListType structure specifies a user interface object that appears on the form.


WARNING! Palm, 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.
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.

Field Descriptions

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

The FormPopupType structure defines a popup list that appears on a form.


WARNING! Palm, 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.
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.

Field Descriptions

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

The FormPtr type defines a pointer to a FormType structure.

typedef FormType *FormPtr; 

FormRectangleType

The FormRectangleType structure defines a rectangle that appears on the form.

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.

Field Descriptions

attr
rect
Location and size of the rectangle.

FormTitleType

The FormTitleType structure defines the title of the form.


WARNING! Palm, 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.
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.

Field Descriptions

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

FormType

The FormType structure and supporting structures are defined below.


WARNING! Palm, 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.
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.

Field Descriptions

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

The FrmGraffitiStateType structure defines the graffiti shift indicator.


WARNING! Palm, 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.
typedef struct{ 
  PointerType    pos; 
}FrmGraffitiStateType; 

Your code should treat the FrmGraffitiStateType structure as opaque. Do not attempt to change structure member values directly.

Field Descriptions

pos
Location of the graffiti shift indicator.

Form Constants

The following form constants are defined:

Constant
Value
Description
noFocus
0xffff
No form object has the focus
frmRedrawUpdateCode
0x8000
Indicates that the form should be redrawn; flag in a frmUpdateEvent.
frmNoSelectedControl
0xff
Returned by FrmGetControlGroupSelection if no control is selected.
frmResponseCreate
1974
Passed to FormCheckResponseFunc to indicate that the function should perform initialization.
frmResponseQuit
0xBEEF
Passed to FormCheckResponseFunc to indicate that the function should perform cleanup.

Form Resources

The following resources are associated with forms and with the objects on a form whose data structures are defined above:

Form-Form Resource (tFRM)

Alert dialog- Alert Resource (Talt)

Bitmap-Form Bitmap Resource (tFBM)

Button-Button Resource (tBTN)

Check box-Check Box Resource (tCBX)

Field-Field Resource (tFLD)

Gadget (custom object)- Gadget Resource (tGDT)

Graffiti shift indicator -Graffiti 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)

Form Functions

FrmAlert

Purpose

Create a modal dialog from an alert resource and display it until the user selects a button in the dialog.

Prototype

UInt16 FrmAlert (UInt16 alertId)

Parameters

-> alertIdID of the alert resource.

Result

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

Purpose

Send a frmCloseEvent to all open forms.

Prototype

void FrmCloseAllForms (void)

Parameters

None.

Result

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

Purpose

Copy the passed string into the data structure of the specified label object in the active form.

Prototype

void FrmCopyLabel (FormType *formP, UInt16 labelID, const Char *newLabel)

Parameters

-> formPPointer to the form object (FormType structure).
-> labelIDID of form label object.
-> newLabelPointer to a NULL-terminated string.

Result

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

Purpose

Copy a new title over the form's current title. If the form is visible, the new title is drawn.

Prototype

void FrmCopyTitle (FormType *formP, const Char *newTitle)

Parameters

-> formPPointer to the form object (FormType structure).
-> newTitlePointer to the new title string.

Result

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

FrmCustomAlert

Purpose

Create a modal dialog from an alert resource and display the dialog until the user taps a button in the alert dialog.

Prototype

UInt16 FrmCustomAlert (UInt16 alertId, const Char *s1, const Char *s2, const Char *s3)

Parameters

-> alertIdResource ID of the alert.
-> s1, s2, s3Strings to replace ^1, ^2, and ^3 (see Comments).

Result

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

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.

Prototype

UInt16 FrmCustomResponseAlert (UInt16 alertId, const Char *s1, const Char *s2, const Char *s3, Char *entryStringBuf, Int16 entryStringBufLength, FormCheckResponseFuncPtr callback)

Parameters

-> alertIdResource ID of the alert.
-> s1, s2, s3Strings to replace ^1, ^2, and ^3. See the Comments in FrmCustomAlert for more information.
<- entryStringBufThe string the user entered in the text field.
-> entryStringBufLengthThe maximum length for the string in entryStringBuf.
-> callbackA callback function that processes the string. See FormCheckResponseFunc. Pass NULL if there is no callback.

Result

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

Purpose

Release the memory occupied by a form. Any memory allocated to objects in the form is also released.

Prototype

void FrmDeleteForm (FormType *formP)

Parameters

-> formPPointer to the form object (FormType structure).

Result

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

See Also

FrmInitForm, FrmReturnToForm

FrmDispatchEvent

Purpose

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

Prototype

Boolean FrmDispatchEvent (EventType *eventP)

Parameters

-> eventPPointer to an event.

Result

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 (FormEventHandler) is registered by FrmSetEventHandler.

Note that if the form does not have a registered event handler, this function causes a fatal error.

FrmDoDialog

Purpose

Display a modal dialog until the user taps a button in the dialog.

Prototype

UInt16 FrmDoDialog (FormType *formP)

Parameters

-> formPPointer to the form object (FormType structure).

Result

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.

See Also

FrmInitForm, FrmCustomAlert, FrmCustomResponseAlert

FrmDrawForm

Purpose

Draw all objects in a form and the frame around the form.

Prototype

void FrmDrawForm (FormType *formP)

Parameters

-> formPPointer to the form object (FormType structure).

Result

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

See Also

FrmEraseForm, FrmInitForm

FrmEraseForm

Purpose

Erase a form from the display.

Prototype

void FrmEraseForm (FormType *formP)

Parameters

-> formPPointer to the form object (FormType structure).

Result

Returns nothing.

Comments

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

New FrmGetActiveField

Purpose

Return the active field for a specified form.

Prototype

FieldType *FrmGetActiveField (const FormType *formP)

Parameters

-> formPPointer to the form for which the active field should be returned, or NULL if the active field on the active form is desired.

Result

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

Purpose

Return the currently active form.

Prototype

FormType *FrmGetActiveForm (void)

Parameters

None.

Result

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

Purpose

Return the ID of the currently active form.

Prototype

UInt16 FrmGetActiveFormID (void)

Parameters

None.

Result

Returns the active form's ID number.

See Also

FrmGetActiveForm

FrmGetControlGroupSelection

Purpose

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

Prototype

UInt16 FrmGetControlGroupSelection (const FormType *formP, UInt8 groupNum)

Parameters

-> formPPointer to the form object (FormType structure).
-> groupNumControl group number.

Result

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

Purpose

Return the current value of a control.

Prototype

Int16 FrmGetControlValue (const FormType *formP, UInt16 objIndex)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of the control object in the form object's data structure. You can obtain this by using FrmGetObjectIndex.

Result

Returns the current value of the control. For most controls the return value is either 0 (off) or 1 (on). For sliders, this function returns the value of the value field.

Comments

The caller must specify a valid index. This function is valid only for push button and check box control objects.

See Also

FrmSetControlValue

FrmGetFirstForm

Purpose

Return the first form in the window list.

Prototype

FormType *FrmGetFirstForm (void)

Parameters

None.

Result

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

Purpose

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

Prototype

UInt16 FrmGetFocus (const FormType *formP)

Parameters

-> formPPointer to the form object (FormType structure).

Result

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

Purpose

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

Prototype

void FrmGetFormBounds (const FormType *formP, RectangleType *rP)

Parameters

-> formPPointer to the form object (FormType structure).
<- rPPointer to a RectangleType structure where the bounds is returned.

Result

Returns nothing. The bounds of the form are returned in r.

FrmGetFormId

Purpose

Return the resource ID of a form.

Prototype

UInt16 FrmGetFormId (const FormType *formP)

Parameters

-> formPPointer to the form object (FormType structure).

Result

Returns form resource ID.

See Also

FrmGetFormPtr

FrmGetFormPtr

Purpose

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

Prototype

FormType *FrmGetFormPtr (UInt16 formId)

Parameters

-> formIdForm ID number.

Result

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

See Also

FrmGetFormId

FrmGetGadgetData

Purpose

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

Prototype

void *FrmGetGadgetData (const FormType *formP, UInt16 objIndex)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of the gadget object in the form object's data structure. You can obtain this by using FrmGetObjectIndex.

Result

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

Purpose

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

Prototype

const Char *FrmGetLabel (const FormType *formP, UInt16 labelID)

Parameters

-> formPPointer to the form object (FormType structure).
-> labelIDID of the label object.

Result

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

FrmGetNumberOfObjects

Purpose

Return the number of objects in a form.

Prototype

UInt16 FrmGetNumberOfObjects (const FormType *formP)

Parameters

-> formPPointer to the form object (FormType structure).

Result

Returns the number of objects in the specified form.

See Also

FrmGetObjectPtr, FrmGetObjectId

FrmGetObjectBounds

Purpose

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

Prototype

void FrmGetObjectBounds (const FormType *formP, UInt16 objIndex, RectangleType *rP)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of an object in the form. You can obtain this by using FrmGetObjectIndex.
<- rPPointer to a RectangleType structure where the object bounds are returned. The bounds are in window-relative coordinates.

Result

Returns nothing. The object's bounds are returned in r.

See Also

FrmGetObjectPosition, FrmSetObjectPosition

FrmGetObjectId

Purpose

Return the ID of the specified object.

Prototype

UInt16 FrmGetObjectId (const FormType *formP, UInt16 objIndex)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of an object in the form. You can obtain this by using FrmGetObjectIndex.

Result

Returns the ID number of an object or frmInvalidObjectId if the objIndex parameter is invalid.

See Also

FrmGetObjectPtr

FrmGetObjectIndex

Purpose

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

Prototype

UInt16 FrmGetObjectIndex (const FormType *formP, UInt16 objID)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIDID of an object in the form.

Result

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

New FrmGetObjectIndexFromPtr

Purpose

Return an object's index.

Prototype

UInt16 FrmGetObjectIndexFromPtr (const FormType *formP, void *objP)

Parameters

-> formPPointer to a FormType.
-> objPPointer to an object.

Result

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

FrmGetObjectPosition

Purpose

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

Prototype

void FrmGetObjectPosition (const FormType *formP, UInt16 objIndex, Coord *x, Coord *y)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of an object in the form. You can obtain this by using FrmGetObjectIndex.
<- x, yPointers where the window-relative x and y positions of the object are returned. These locate the top-left corner of the object.

Result

Returns nothing.

See Also

FrmGetObjectBounds, FrmSetObjectPosition

FrmGetObjectPtr

Purpose

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

Prototype

void *FrmGetObjectPtr (const FormType *formP, UInt16 objIndex)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of an object in the form. You can obtain this by using FrmGetObjectIndex.

Result

Returns a pointer to an object in the form.

See Also

FrmGetObjectId

FrmGetObjectType

Purpose

Return the type of an object.

Prototype

FormObjectKind FrmGetObjectType (const FormType *formP, UInt16 objIndex)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of an object in the form. You can obtain this by using FrmGetObjectIndex.

Result

Returns FormObjectKind of the item specified. See FormObjectKind.

FrmGetTitle

Purpose

Return a pointer to the title string of a form.

Prototype

const Char *FrmGetTitle (const FormType *formP)

Parameters

-> formPPointer to the form object (FormType structure).

Result

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

Purpose

Return the window handle of a form.

Prototype

WinHandle FrmGetWindowHandle (const FormType *formP)

Parameters

-> formPPointer to the form object (FormType structure).

Result

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

Purpose

Send a frmCloseEvent to the current form; send a frmLoadEvent and a frmOpenEvent to the specified form.

Prototype

void FrmGotoForm (UInt16 formId)

Parameters

-> formIdID of the form to display.

Result

Returns nothing.

Comments

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

See Also

FrmPopupForm

FrmHandleEvent

Purpose

Handle the event that has occurred in the form.

Prototype

Boolean FrmHandleEvent (FormType *formP, EventType *eventP)

Parameters

-> formPPointer to the form object (FormType structure).
-> eventPPointer to the event data structure (EventType).

Result

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...
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.
Passes the event and a pointer to the object the event occurred in to CtlHandleEvent. The object pointer is obtained from the event data.
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.
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.
Erases the form and releases any memory allocated for it.
Passes the event to the gadget's callback function if the gadget has one. See FormGadgetHandler.
Passes the event to the gadget's callback function if the gadget has one. See FormGadgetHandler.
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.
Adds a keyDownEvent with the vchrMenu character to the event queue.
Calls FrmDrawForm to redraw the form.
Passes the event to the handler for the object that has the focus. If no object has the focus, the event is ignored.
Passes the event and a pointer to the object the event occurred in to LstHandleEvent. The object pointer is obtained from the event data.
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.
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.
Sets the label of the popup trigger to the current selection of the popup list.
Passes the event and a pointer to the object the event occurred in to SclHandleEvent.
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.

See Also

FrmDispatchEvent

FrmHelp

Purpose

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

Prototype

void FrmHelp (UInt16 helpMsgId)

Parameters

-> helpMsgIdResource ID of help message string.

Result

Returns nothing.

Comments

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

FrmHideObject

Purpose

Erase the specified object and set its attribute data (usable bit) so that it does not redraw or respond to the pen.

Prototype

void FrmHideObject (FormType *formP, UInt16 objIndex)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of an object in the form. You can obtain this by using FrmGetObjectIndex.

Result

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

See Also

FrmShowObject

FrmInitForm

Purpose

Load and initialize a form resource.

Prototype

FormType *FrmInitForm (UInt16 rscID)

Parameters

-> rscIDResource ID of the form.

Result

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

FrmNewBitmap

Purpose

Create a new form bitmap dynamically.

Prototype

FormBitmapType *FrmNewBitmap (FormType **formPP, UInt16 ID, UInt16 rscID, Coord x, Coord y)

Parameters

<-> formPPPointer 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.
-> IDSymbolic ID of the bitmap, specified by the developer. By convention, this ID should match the resource ID (not mandatory).
-> rscIDNumeric value identifying the resource that provides the bitmap. This value must be unique within the application scope.
-> xHorizontal coordinate of the upper-left corner of the bitmap's boundaries, relative to the window in which it appears.
-> yVertical coordinate of the upper-left corner of the bitmap's boundaries, relative to the window in which it appears.

Result

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

Purpose

Create a new form object dynamically.

Prototype

FormType *FrmNewForm (UInt16 formID, const Char *titleStrP, Coord x, Coord y, Coord width, Coord height, Boolean modal, UInt16 defaultButton, UInt16 helpRscID, UInt16 menuRscID)

Parameters

-> formIDSymbolic ID of the form, specified by the developer. By convention, this ID should match the resource ID (not mandatory).
-> titleStrPPointer to a string that is the title of the form.
-> xHorizontal coordinate of the upper-left corner of the form's boundaries, relative to the window in which it appears.
-> yVertical coordinate of the upper-left corner of the form's boundaries, relative to the window in which it appears.
-> widthWidth of the form, expressed in pixels. Valid values are 1 -160.
-> heightHeight of the form, expressed in pixels.Valid values are 1 -160.
-> modaltrue specifies that the form ignores pen events outside its boundaries.
-> defaultButtonSymbolic ID of the button that provides the form's default action, specified by the developer.
-> helpRscIDSymbolic ID of the resource that provides the form's online help, specified by the developer. Only modal dialogs can have help resources.
-> menuRscIDSymbolic ID of the resource that provides the form's menus, specified by the developer.

Result

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

Purpose

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

Prototype

FormGadgetType *FrmNewGadget (FormType **formPP, UInt16 id, Coord x, Coord y, Coord width, Coord height)

Parameters

<-> formPPPointer 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.
-> idSymbolic ID of the gadget, specified by the developer. By convention, this ID should match the resource ID (not mandatory).
-> xHorizontal coordinate of the upper-left corner of the gadget's boundaries, relative to the window in which it appears.
-> yVertical coordinate of the upper-left corner of the gadget's boundaries, relative to the window in which it appears.
-> widthWidth of the gadget, expressed in pixels. Valid values are 1 - 160.
-> heightHeight of the gadget, expressed in pixels.Valid values are 1 - 160.

Result

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 "Gadget Resource".

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

FrmRemoveObject

FrmNewGsi

Purpose

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

Prototype

FrmGraffitiStateType *FrmNewGsi (FormType **formPP, Coord x, Coord y)

Parameters

<-> formPPPointer to a pointer to the form in which the new Graffiti 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.
-> xHorizontal coordinate of the upper-left corner of the Graffiti shift indicator's boundaries, relative to the window in which it appears.
-> yVertical coordinate of the upper-left corner of the Graffiti shift indicator's boundaries, relative to the window in which it appears.

Result

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 Graffiti 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 Graffiti 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

Purpose

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

Prototype

FormLabelType *FrmNewLabel (FormType **formPP, UInt16 ID, const Char *textP, Coord x, Coord y, FontID font)

Parameters

<-> formPPPointer 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.
-> IDSymbolic ID of the label, specified by the developer. By convention, this ID should match the resource ID (not mandatory).
-> textPPointer to a string that provides the label text. This string is copied into the label structure.
-> xHorizontal coordinate of the upper-left corner of the label's boundaries, relative to the window in which it appears.
-> yVertical coordinate of the upper-left corner of the label's boundaries, relative to the window in which it appears.
-> fontFont with which to draw the label text.

Result

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

Purpose

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

Prototype

Boolean FrmPointInTitle (const FormType *formP, Coord x, Coord y)

Parameters

-> formPPointer to the form object (FormType structure).
-> x, yWindow-relative x and y coordinates.

Result

Returns true if the specified coordinate is in the form's title.

Compatibility

Implemented only if 2.0 New Feature Set is present.

FrmPopupForm

Purpose

Queues a frmLoadEvent and a frmOpenEvent for the specified form.

Prototype

void FrmPopupForm (UInt16 formId)

Parameters

-> formIDResource ID of form to open.

Result

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

Purpose

Remove the specified object from the specified form.

Prototype

Err FrmRemoveObject (FormType **formPP, UInt16 objIndex)

Parameters

<-> formPPPointer 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.
-> objIndexThe 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.

Result

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

Purpose

Macro that restores the active window and form state.

Prototype

FrmRestoreActiveState (stateP)

Parameters

-> statePA pointer to the FormActiveStateType structure that you passed to FrmSaveActiveState when you saved the state.

Result

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 called FrmSaveActiveState to save the state.

Compatibility

Implemented only if 3.0 New Feature Set is present.

FrmReturnToForm

Purpose

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

Prototype

void FrmReturnToForm (UInt16 formId)

Parameters

-> formIDResource ID of the form to return to.

Result

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

Purpose

Macro that saves the active window and form state.

Prototype

FrmSaveActiveState (stateP)

Parameters

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

Result

Returns zero on success.

Comments

Use this function to save the state of displayed forms before dynamically showing a new modal form. Call FrmRestoreActiveState to restore the state after you remove the modal form.

Compatibility

Implemented only if 3.0 New Feature Set is present.

FrmSaveAllForms

Purpose

Send a frmSaveEvent to all open forms.

Prototype

void FrmSaveAllForms (void)

Parameters

None.

Result

Returns nothing.

See Also

FrmCloseAllForms

FrmSetActiveForm

Purpose

Set the active form. All input (key and pen) is directed to the active form and all drawing occurs there.

Prototype

void FrmSetActiveForm (FormType *formP)

Parameters

-> formPPointer to the form object (FormType structure).

Result

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

Purpose

Set the category label displayed on the title line of a form. If the form's visible attribute is set, redraw the label.

Prototype

void FrmSetCategoryLabel (const FormType *formP, UInt16 objIndex, Char *newLabel)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of an object in the form. You can obtain this by using FrmGetObjectIndex.
-> newLabelPointer to the name of the new category.

Result

Returns nothing.

Comments

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

FrmSetControlGroupSelection

Purpose

Set the selected control in a group of controls.

Prototype

void FrmSetControlGroupSelection (const FormType *formP, UInt8 groupNum, UInt16 controlID)

Parameters

-> formPPointer to the form object (FormType structure).
-> groupNumControl group number.
-> controlIDID of control to set.

Result

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

Purpose

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

Prototype

void FrmSetControlValue (const FormType *formP, UInt16 objIndex, Int16 newValue)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of the control in the form. You can obtain this by using FrmGetObjectIndex.
-> newValueNew value to set for the control. For sliders, specify a value between the slider's minimum and maximum. For graphical controls, push buttons, or check boxes, specify 0 for off, nonzero for on.

Result

Returns nothing.

Comments

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

See Also

FrmGetControlValue

FrmSetEventHandler

Purpose

Registers the event handler callback routine for the specified form.

Prototype

void FrmSetEventHandler (FormType *formP, FormEventHandlerType *handler)

Parameters

-> formPPointer to the form object (FormType structure).
-> handlerAddress of the form event handler function, FormEventHandler.

Result

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

Purpose

Set the focus of a form to the specified object.

Prototype

void FrmSetFocus (FormType *formP, UInt16 fieldIndex)

Parameters

-> formPPointer to the form object (FormType structure).
-> fieldIndexIndex 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.

Result

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

Purpose

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

Prototype

void FrmSetGadgetData (FormType *formP, UInt16 objIndex, const void *data)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of an object in the form. You can obtain this by using FrmGetObjectIndex.
-> dataApplication-defined value. This value is stored into the data field of the gadget data structure (FormGadgetType).

Result

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

Purpose

Registers the gadget event handler callback routine for the specified gadget on the specified form.

Prototype

void FrmSetGadgetHandler (FormType *formP, UInt16 objIndex, FormGadgetHandlerType *attrP)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of a gadget object in the form. You can obtain this by using FrmGetObjectIndex.
-> attrPAddress of the callback function. See FormGadgetHandler.

Result

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

Purpose

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

Prototype

void FrmSetMenu (FormType *formP, UInt16 menuRscID)

Parameters

-> formPPointer to the form object (FormType structure).
-> menuRscID Resource ID of the menu.

Result

Returns nothing.

Compatibility

Implemented only if 2.0 New Feature Set is present.

FrmSetObjectBounds

Purpose

Set the bounds or position of an object.

Prototype

void FrmSetObjectBounds (FormType *formP, UInt16 objIndex, const RectangleType *bounds)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of an object in the form. You can obtain this by using FrmGetObjectIndex.
-> boundsWindow-relative bounds. For the following objects, this sets only the position of the top-left corner: label, bitmap, and Graffiti state indicator.

Result

Returns nothing.

Comments

Doesn't update the display.

Compatibility

Implemented only if 2.0 New Feature Set is present.

FrmSetObjectPosition

Purpose

Set the position of an object.

Prototype

void FrmSetObjectPosition (FormType *formP, UInt16 objIndex, Coord x, Coord y)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of an object in the form. You can obtain this by using FrmGetObjectIndex.
-> xWindow-relative horizontal coordinate.
-> yWindow-relative vertical coordinate.

Result

Returns nothing.

See Also

FrmGetObjectPosition, FrmGetObjectBounds

FrmSetTitle

Purpose

Set the title of a form. If the form is visible, draw the new title.

Prototype

void FrmSetTitle (FormType *formP, Char *newTitle)

Parameters

-> formPPointer to the form object (FormType structure).
-> newTitlePointer to the new title string.

Result

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

Purpose

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

Prototype

void FrmShowObject (FormType *formP, UInt16 objIndex)

Parameters

-> formPPointer to the form object (FormType structure).
-> objIndexIndex of an object in the form. You can obtain this by using FrmGetObjectIndex.

Result

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

See Also

FrmHideObject

FrmUpdateForm

Purpose

Send a frmUpdateEvent to the specified form.

Prototype

void FrmUpdateForm (UInt16 formId, UInt16 updateCode)

Parameters

-> formIdResource ID of form to update.
-> updateCodeAn 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.

Result

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

Purpose

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

Prototype

void FrmUpdateScrollers (FormType *formP, UInt16 upIndex, UInt16 downIndex, Boolean scrollableUp, Boolean scrollableDown)

Parameters

-> formPPointer to the form object (FormType structure).
-> upIndexIndex of the up-scroller button. You can obtain this by using FrmGetObjectIndex.
-> downIndexIndex of the down-scroller button. You can obtain this by using FrmGetObjectIndex.
-> scrollableUpSet to true to make the up scroll arrow active (shown), or false to hide it.
-> scrollableDownSet to true to make the down scroll arrow active (shown), or false to hide it.

Result

Returns nothing.

FrmValidatePtr

Purpose

Return true if the specified pointer references a valid form.

Prototype

Boolean FrmValidatePtr (const FormType *formP)

Parameters

-> formPPointer to be tested.

Result

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.

FrmVisible

Purpose

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

Prototype

Boolean FrmVisible (const FormType *formP)

Parameters

-> formPPointer to the form object (FormType structure).

Result

Returns true if the form is visible; false if it is not visible.

See Also

FrmDrawForm, FrmEraseForm

Application-Defined Functions

FormCheckResponseFunc

Purpose

Callback function for FrmCustomResponseAlert.

Prototype

Boolean FormCheckResponseFuncType (Int16 button, Char *attempt)

Parameters

-> buttonThe ID of the button that the user tapped.
-> attemptThe string that the user entered in the alert dialog.

Result

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.

FormEventHandler

Purpose

The event handler callback routine for a form.

Prototype

Boolean FormEventHandlerType (EventType *eventP)

Parameters

-> eventPPointer to the form event (FormType structure).

Result

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.

FormGadgetHandler

Purpose

The event handler callback for an extended gadget.

Prototype

Boolean (FormGadgetHandlerType) (struct FormGadgetType *gadgetP, UInt16 cmd, void *paramP)

Parameters

-> gadgetPPointer to the gadget structure. See FormGadgetType.
-> cmdA constant that specifies what action the handler should take. This can be one of the following:
formGadgetDeleteCmdSent by FrmDeleteForm to indicate that the gadget is being deleted and must clean up any memory it has allocated or perform other cleanup tasks.
formGadgetDrawCmdSent by FrmDrawForm and FrmShowObject to indicate that the gadget must be drawn or redrawn.
formGadgetEraseCmdSent 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.
formGadgetHandleEventCmdSent by FrmHandleEvent to indicate that a gadget event has been received. The paramP parameter contains the pointer to the EventType structure.
-> paramPNULL except if cmd is formGadgetHandleEventCmd. In that case, this parameter holds the pointer to the EventType structure containing the event.

Result

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