Previous Page Table of Contents Index Next Page

Palm OS SDK Reference

Palm Logo 10 Forms

This chapter provides the following information about form objects:

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.

Form Data Structures

FormAttrType

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

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.

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.

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.

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.

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.

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

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.

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.

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.

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 as follows:

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.
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.
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. Use this attribute for modal forms.
handler Routine called when the form needs to handle an event. You typically set this in your application's event handling function.
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.
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.
objects Pointer to the array of objects contained within the form. See FormObjListType.

FrmGraffitiStateType

The FrmGraffitiStateType structure defines the graffiti shift indicator.

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

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.

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.

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.

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.

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.



FrmGetActiveForm

Purpose

Return the currently active form.

Prototype

FormType *FrmGetActiveForm (void)

Parameters

 

Result

Returns a pointer to the form object of the active form.

See Also

FrmGetActiveFormID, FrmSetActiveForm



FrmGetActiveFormID

Purpose

Return the ID of the currently active form.

Prototype

UInt16 FrmGetActiveFormID (void)

Parameters

 

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

Parameters

  -> formP
 Pointer to the form object (FormType structure).
  -> controlID
 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

 

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 (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 (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 object (the index of the first object is 0).

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



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.

Table 10.1 provides an overview of how FrmHandleEvent handles different events.

Table 10.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 has a vertical scrollbar, 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.

Comments

This function does not affect lists or tables.

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.

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.

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

 

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 (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. Don't pass a pointer to a stack-based object in newTitle.

This function redraws the title but does not erase the old one first. If the new title is shorter than the old one, the end of the old title will still be visible. To avoid this, you can hide the title using FrmHideObject, then show it using FrmShowObject, after using FrmSetTitle.

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

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


Palm OS SDK Reference

  Previous Page Table of Contents Index Next Page  

This is page 12 of 85 in this book

Palm Computing Platform Development Zone
Copyright © 2000, Palm, Inc. All rights reserved.