< 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 | 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 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 | See FormObjAttrType.
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 | 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 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 | See FormObjAttrType.
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 | See FormObjAttrType.
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 | See FormObjAttrType.
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 #####
-> alertId | ID 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> labelID | ID of form label object.
#####
-> newLabel | Pointer 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> newTitle | Pointer 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 #####
-> alertId | Resource ID of the alert.
#####
-> s1, s2, s3 | Strings 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 #####
-> 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 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 #####
-> formP | Pointer 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 #####
-> eventP | Pointer 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 #####
-> formP | Pointer 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 #####
-> formP | Pointer 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 #####
-> formP | Pointer 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 #####
-> 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.
#### 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> groupNum | Control 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 #####
-> 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.
#### 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 #####
-> formP | Pointer 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
<- rP | Pointer 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 #####
-> formP | Pointer 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 #####
-> formId | Form 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 #####
-> 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.
#### 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> labelID | ID 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 #####
-> formP | Pointer 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 #####
-> 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.
#### 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> objIndex | Index 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> objID | ID 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 #####
-> formP | Pointer to a FormType.
#####
-> objP | Pointer 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 #####
-> 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.
#### 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> objIndex | Index 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> objIndex | Index 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 #####
-> formP | Pointer 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 #####
-> formP | Pointer 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 #####
-> formId | ID 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> eventP | Pointer 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...
--- | ---
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 FormGadgetHandler.
frmGadgetMiscEvent | Passes the event to the gadget's callback function if the gadget has one. See FormGadgetHandler.
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. #### 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 #####
-> helpMsgId | Resource 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> objIndex | Index 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 #####
-> rscID | Resource 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 #####
<-> 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.
#### 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 #####
-> 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.
#### 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 #####
<-> 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.
#### 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 #####
<-> formPP | Pointer 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.
#####
-> x | Horizontal coordinate of the upper-left corner of the Graffiti shift indicator's boundaries, relative to the window in which it appears.
#####
-> y | Vertical 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 #####
<-> 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.
#### 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> x, y | Window-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 #####
-> formID | Resource 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 #####
<-> 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.
#### 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 #####
-> stateP | A 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 #####
-> formID | Resource 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 #####
<-> 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.
#### 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 #####
-> formP | Pointer 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 #####
-> 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.
#### 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> groupNum | Control group number.
#####
-> controlID | ID 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 #####
-> 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.
#### 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> handler | Address 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 #####
-> 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.
#### 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 #####
-> 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).
#### 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 #####
-> 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 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 #####
-> formP | Pointer 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 #####
-> 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 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 #####
-> 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.
#### 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> newTitle | Pointer 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 #####
-> formP | Pointer to the form object (FormType structure).
#####
-> objIndex | Index 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 #####
-> 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.
#### 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 #####
-> 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.
#### Result Returns nothing. ## FrmValidatePtr #### Purpose Return true if the specified pointer references a valid form. #### Prototype Boolean FrmValidatePtr (const FormType *formP) #### Parameters #####
-> formP | Pointer 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 #####
-> formP | Pointer 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 #####
-> button | The ID of the button that the user tapped.
#####
-> attempt | The 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 #####
-> eventP | Pointer 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 #####
-> 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.
#### 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 |