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

20    Form Reference

User Interface

Exploring Palm OS®

This chapter provides the following information about forms:

Form Structures and Types
Form Constants
Form Events
Form Functions and Macros
Application-Defined Functions

The header files Form.h and FormLayout.h declare the API that this chapter describes. For more information on forms, see Chapter 2, "Working with Forms and Dialogs."

Form Structures and Types ^TOP^

AlertTemplateType Struct ^TOP^

Purpose

Internal structure used to construct alert dialogs.

Declared In

Form.h

Prototype

typedef struct AlertTemplateTag AlertTemplateType

Fields

None.

See Also

FrmAlert(), FrmAlertWithFlags(), FrmCustomAlert(), FrmCustomAlertWithFlags(), FrmCustomResponseAlert(), FrmCustomResponseAlertWithFlags(), FrmUIAlert()

FormActiveStateType Struct ^TOP^

Purpose

Saves the active state of the current form.

Declared In

Form.h

Prototype

typedef struct FormActiveStateType {
   uint32_t data[5];
   uint16_t dataLast;
   uint16_t paddingNeverUse;
} FormActiveStateType

Comments

Treat the contents of this structure like a black box. Do not attempt to read to or write from this structure.

See Also

FrmRestoreActiveState(), FrmSaveActiveState()

FormBitmapType Struct ^TOP^

Purpose

Defines the visible characteristics of a bitmap on a form.

Declared In

Form.h

Prototype

typedef struct FormBitmapType FormBitmapType

Fields

None.

FormGadgetAttrType Struct ^TOP^

Purpose

Defines a gadget's attributes. See FormGadgetTypeInCallback.

Declared In

Form.h

Prototype

typedef struct FormGadgetAttrTag {
   uint16_t usable :1;
   uint16_t extended :1;
   uint16_t visible :1;
   uint16_t reserved :13;
} FormGadgetAttrType

Fields

usable
Not set if the gadget is not considered part of the current interface of the application, and it doesn't appear on screen. This is set by FrmShowObject() and cleared by FrmHideObject().
extended
If set, the gadget is an extended gadget. An extended gadget has the handler field defined in its FormGadgetTypeInCallback structure. If not set, the gadget 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.

FormGadgetType Struct ^TOP^

Purpose

A gadget that appears on a form.

Declared In

Form.h

Prototype

typedef struct FormGadgetType FormGadgetType

Fields

None.

See Also

FrmSetGadgetData(), FrmGetGadgetData()

FormGadgetTypeInCallback Struct ^TOP^

Purpose

A gadget element as it is passed to the extended gadget handler (FormGadgetHandlerType()).

Declared In

Form.h

Prototype

typedef struct FormGadgetTypeInCallback {
   uint16_t id;
   FormGadgetAttrType attr;
   RectangleType rect;
   const void *data;
   FormGadgetHandlerType *handler;
} FormGadgetTypeInCallback

Fields

id
ID of the gadget resource.
attr
See FormGadgetAttrType.
rect
Bounds of the gadget. See RectangleType.
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().

FormLabelType Struct ^TOP^

Purpose

A label that appears on the form.

Declared In

Form.h

Prototype

typedef struct FormLabelType FormLabelType

Fields

None.

FormLayoutType Struct ^TOP^

Purpose

Layout information for a control in a form

Declared In

FormLayout.h

Prototype

typedef struct FormLayoutType {
   int32_t structSize;
   uint16_t id;
   uint16_t reserved1;
   uint32_t rule;
} FormLayoutType

Fields

structSize
Always set to sizeof(FormLayoutType).
id
The resource ID of the UI element whose layout rule is specified by this structure.
reserved1
Reserved for future use. Always set to 0.
rule
One of the Form Layout Constants or a layout rule constructed with frmLayoutRule().

See Also

FrmInitLayout()

FormType Struct ^TOP^

Purpose

An internal structure that describes a form. FormPtr defines a pointer to a FormType structure.

Declared In

Form.h

Prototype

typedef struct FormType FormType;
typedef FormType *FormPtr

Fields

None. All fields are private.

FrmGraffitiStateType Struct ^TOP^

Purpose

Defines the shift indicator.

Declared In

Form.h

Prototype

typedef struct FormGraffitiStateTag 
FrmGraffitiStateType

Fields

None.

Form Constants ^TOP^

AlertType Enum ^TOP^

Purpose

Specifies the type of an alert.

Declared In

Form.h

Constants

informationAlert
Informational alert. Use for actions that shouldn't or can't be completed but that don't generate an error or risk data loss.
confirmationAlert
Confirmation alert. Use to confirm an action or suggest options.
warningAlert
Warning alert. Use to confirm a serious or potentially dangerous action.
errorAlert
Error alert. Use for actions that generate an error and cannot be completed.

Custom Response Alert Actions ^TOP^

Purpose

Sent to the FormCheckResponseFuncType() to specify the action that the callback should perform.

Declared In

Form.h

Constants

#define frmResponseCreate 1974
The function should perform initialization.
#define frmResponseQuit ((int16_t) 0xBEEF)
The function should perform cleanup.

Form Basic Layout Constants ^TOP^

Purpose

Used to construct a layout rule with frmLayoutRule().

Declared In

FormLayout.h

Constants

frmAttachLeftTop = 0
Element's left and top sides should follow left and top edges of window.
frmAttachRightBottom = 1
Element's right and bottom sides should follow right and bottom edges of window.

Form Layout Constants ^TOP^

Purpose

Specify the resizing rule for a UI element. This constant is used as the value of the rule field in the FormLayoutType structure.

Declared In

FormLayout.h

Constants

frmFollowNone = 0
No resizing rule.
frmFollowAllSides
The element resizes vertically and horizontally.
frmFollowLeft
The element moves so that there is always a fixed amount of space between it and the left side of the form.
frmFollowRight
The element moves so that there is always a fixed amount of space between it and the right side of the form.
frmFollowLeftRight
The element resizes horizontally if the form is horizontally resized.
frmFollowTop
The element moves so that there is always a fixed amount of space between it and the top of the form.
frmFollowBottom
The element moves so that there is always a fixed amount of space between it and the bottom of the form.
frmFollowTopBottom
The element resizes vertically.

FormObjectKind Typedef ^TOP^

Purpose

Types of user interface elements that may appear on a form.

Declared In

Form.h

Constants

frmFieldObj
Text field
frmControlObj
Control
frmListObj
List
frmTableObj
Table
frmBitmapObj
Form bitmap
frmLineObj
Line
frmFrameObj
Frame
frmRectangleObj
Rectangle
frmLabelObj
Label
frmTitleObj
Form title
frmPopupObj
Pop-up list
frmGraffitiStateObj
Shift indicator
frmGadgetObj
Gadget (custom element)
frmScrollBarObj
Scroll bar

See Also

FrmGetObjectType()

Gadget Actions ^TOP^

Purpose

Sent to the FormGadgetHandlerType() callback to specify the action that the gadget handler should perform.

Declared In

Form.h

Constants

#define formGadgetDrawCmd 0
Sent in response to the frmUpdateEvent to indicate that the gadget must be drawn or redrawn.
#define formGadgetEraseCmd 1
Sent by FrmHideObject() to indicate that the gadget is going to be erased. FrmHideObject() clears the visible flag for you. If you return false, it also clears the usable flag and invalidates the window region that displays the gadget so that it is erased on the next update cycle.
#define formGadgetHandleEventCmd 2
Sent by FrmHandleEvent() to indicate that a gadget event has been received.
#define formGadgetDeleteCmd 3
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.

Miscellaneous Constants ^TOP^

Purpose

The Form.h file also declares these constants.

Declared In

Form.h

Constants

#define customAlertInsertionTag ((char*)"^ErrMsg")
Used by ErrAlert(), which is documented in Exploring Palm OS: System Management.
#define frmInvalidObjectId (0xffff)
Returned by some functions if the specified UI element cannot be found.
#define frmNoSelectedControl 0xff
Returned by FrmGetControlGroupSelection() if no control is selected.
#define frmRedrawUpdateCode 0x8000
Indicates that the form should be redrawn; flag in a frmUpdateEvent.
#define noFocus (frmInvalidObjectId)
No element in the form has the focus.
#define frmLayoutGraffitiShiftID (frmInvalidObjectId - 1)
Special constant to use as the resource ID for the shift indicator when setting up the FormLayoutType structure.

Form Events ^TOP^

frmCloseEvent ^TOP^

Purpose

Sent when a form is being closed.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct frmClose {
  uint16_t formID;
} frmClose

Fields

formID
Resource ID of the form.

Comments

The functions FrmGotoForm() and FrmCloseAllForms() send this event. FrmGotoForm() sends a frmCloseEvent to the currently active form; FrmCloseAllForms() sends a frmCloseEvent to all forms an application has loaded into memory.

FrmHandleEvent() calls FrmEraseForm() and FrmDeleteForm() in response to the frmCloseEvent to remove the form from the screen and deallocate its internal data structure.

Applications should respond to this event if they need to do one of the following before the form is deallocated:

  • Save data stored in the form
  • Clean up memory used by the form

Return false from your event handler to get the default behavior from FrmHandleEvent().

frmGadgetEnterEvent ^TOP^

Purpose

Sent when there is a penDownEvent within the bounds of an extended gadget.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct gadgetEnter {
   struct FormGadgetType *gadgetP;
   uint16_t gadgetID;
   BA32_PADDING_16(1)
} gadgetEnter;

Fields

gadgetID
Resource ID of the gadget.
gadgetP
Pointer to the FormGadgetType structure representing this gadget.

Comments

The gadget handler function (see FormGadgetHandlerType()) should handle this event. It should perform any necessary highlighting. If the gadget needs to track the pen, call FrmSetPenTracking() in response to this event. When you do so, the gadget receives all further pen events (penMoveEvent and penUpEvent).

frmGadgetMiscEvent ^TOP^

Purpose

An application may choose to send this event when it needs to pass information to an extended gadget. The FrmHandleEvent() function passes frmGadgetMiscEvents on to the extended gadget's handler function (see FormGadgetHandlerType()).

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct gadgetMisc {
   struct FormGadgetType *gadgetP;
   uint16_t gadgetID;
   uint16_t selector;
   void *dataP;
} gadgetMisc;

Fields

gadgetP
Pointer to the FormGadgetType structure representing this gadget.
gadgetID
Resource ID of the gadget.
selector
Any necessary integer value to pass to the gadget handler function.
dataP
A pointer to any necessary data to pass to the gadget handler function.

frmGotoEvent ^TOP^

Purpose

An application may choose to send itself this event when it receives a sysAppLaunchCmdGoTo launch code. sysAppLaunchCmdGoto is generated when the user selects a record in the global find facility.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct frmGoto {
   uint16_t formID;
   _BA32_PADDING_16(1)
   uint32_t recordNum;
   uint32_t recordID;
   size_t matchPos;
   size_t  matchLen;
   uint32_t matchFieldNum;
   uint32_t matchCustom;
} frmGoto;

Fields

formID
Resource ID of the form.
recordNum
Index of record containing the match string.
matchPos
Position of the match.
matchLen
Length of the matched string.
matchFieldNum
Number of the field the matched string was found in.
matchCustom
Application-specific information. You might use this if you need to provide extra information to locate the matching string within the record.

Comments

The application is responsible for handling this event.

Like frmOpenEvent, frmGotoEvent is a request that the application initialize a form, but this event provides extra information so that the application may display and highlight the matching string in the form.

frmLoadEvent ^TOP^

Purpose

Sent when a form should be loaded from the resource file.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct frmLoad {
  uint16_t formID;
  uint16_t reserved;
  DmOpenRef formDatabase;
} frmLoad

Fields

formID
Resource ID of the form.
reserved
Reserved for future use.
formDatabase
Open database containing the form.

Comments

The functions FrmGotoForm() and FrmPopupForm() send this event. It's a request that the application load a form into memory.

The application is responsible for handling this event. In response to this event, applications typically initialize the form, make it active, set the event handler, and return true.

If you want your form automatically resized, also call FrmInitLayout() in response to this event.

Example

The following example shows the functions that are typically called in response to this event:


FormType *frm; 
case frmLoadEvent: 
{ 
  frm = FrmInitForm (event->data.frmLoad.formDatabase,  
        event->data.frmLoad.formID); 
  FrmSetActiveForm (frm); 
  FrmInitLayout(frm, MainFormLayout); 
  FrmSetEventHandler(frm, MainFormHandleEvent); 
  handled = true; 
  break; 
} 

frmOpenEvent ^TOP^

Purpose

Sent when a form should be initialized.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct frmOpen {
  uint16_t formID;
} frmOpen

Fields

formID
Resource ID of the form.

Comments

The functions FrmGotoForm() and FrmPopupForm() send this event. It is a request that the application initialize a form.

The application is responsible for handling this event. Perform any initializations that should take place before the form is drawn and return true to indicate that you've handled the event.

Compatibility

Applications should no longer call FrmDrawForm() in response to this event. Do so only in response to frmUpdateEvent.

frmSaveEvent ^TOP^

Purpose

Sent when FrmSaveAllForms() is called.

Declared In

EventCodes.h

Prototype

No data is passed with this event.

Comments

Applications should respond to this event by saving any data stored in an open form.

frmStopDialogEvent ^TOP^

Purpose

Causes FrmDoDialog() to exit with a simulated default button tap.

Declared In

EventCodes.h

Prototype

No data is passed with this event.

frmTitleEnterEvent ^TOP^

Purpose

Sent when a pen down occurs within the form's title. Note that only the written title, not the whole title bar, is active.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct frmTitleEnter {
   uint16_t formID;
} frmTitleEnter;

Fields

formID
Resource ID of the form.

Comments

Applications do not normally respond to this event. When FrmHandleEvent() receives this event, it tracks the pen until it is lifted. If the pen is lifted within the bounds of the same title bar region, a frmTitleSelectEvent is added to the event queue.

frmTitleSelectEvent ^TOP^

Purpose

Sent when the user taps the form's title.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct frmTitleSelect {
   uint16_t formID;
} frmTitleSelect;

Fields

formID
Resource ID of the form.

Comments

Applications do not normally respond to this event. FrmHandleEvent() responds by displaying the form's menu.

frmUpdateEvent ^TOP^

Purpose

Sent when all or a portion of a form needs to be redrawn. This includes when the form is first opened, when it is resized, and as a result of the functions WinInvalidateWindow() or WinInvalidateRect().

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct frmUpdate {
  uint16_t formID;
  uint16_t updateCode;
  RectangleType dirtyRect;
} frmUpdate;

Fields

formID
Resource ID of the form.
updateCode
The reason for the update request. Most often, this is frmRedrawUpdateCode, which indicates that the form needs to be redrawn.
dirtyRect
The portion of the form that needs to be redrawn. (See RectangleType.)

Comments

Applications that do not perform any special drawing need not respond to this event. The default handler in FrmHandleEvent() calls FrmDrawForm(). If your application performs custom drawing, respond to this event. Call FrmDrawForm() first and then draw.

All drawing to forms with update-based windows must be done only in response to this event.

When a window obscures a portion of your form, your form still receives frmUpdateEvents. All drawing into the obscured region is clipped. When the obscuring window is closed, your form receives an update event again with the previously obscured region as the region that needs to be redrawn.


IMPORTANT: Never post a frmUpdateEvent or winUpdateEvent explicitly. Instead, use one of the functions WinInvalidateRect(), WinInvalidateRectFunc(), or WinInvalidateWindow().

Compatibility

Forms that use legacy windows, as a rule, do not receive frmUpdateEvent. For this style of form, the region that another form obscures is saved and restored by the UI Library without application intervention. However, in cases where the system is running low on memory, the UI library does not save obscured regions itself. In that case, the legacy form receives a frmUpdateEvent and redraws the region using the updateCode value.

Form Functions and Macros ^TOP^

ECFrmValidatePtr Macro ^TOP^

Purpose

Evaluates to true if the specified pointer references a valid form.

Declared In

Form.h

Prototype

#define ECFrmValidatePtr (
   formP
)

Parameters

formP
Pointer to be tested.

Returns

true if the specified pointer is a non-NULL pointer to a valid form structure.

Comments

This macro is intended for debugging purposes only. Do not include it in released code.

See Also

FrmValidatePtr()

FrmAlert Function ^TOP^

Purpose

Creates a modal dialog from an alert resource and displays it until the user taps a button.

Declared In

Form.h

Prototype

uint16_t FrmAlert (
   DmOpenRef database,
   uint16_t alertId
)

Parameters

database
Open database containing the alert resource.
alertId
ID of the alert resource.

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

Comments

Alert resources cannot be associated with window constraints resources, and usually one is not necessary. The UI Library makes sure that the alert is always the same size and snaps to the bottom of the application area. If you need to set window creation attributes that you would normally set in a constraints resource, use FrmAlertWithFlags().

See Also

FrmDoDialog(), FrmCustomAlert(), FrmCustomResponseAlert(), FrmAlertWithFlags(), FrmUIAlert()

FrmAlertWithFlags Function ^TOP^

Purpose

Creates a modal dialog using the specified window attributes and alert resource. Displays the dialog until the user taps a button.

Declared In

Form.h

Prototype

uint16_t FrmAlertWithFlags (
   DmOpenRef database,
   uint16_t alertId,
   WinFlagsType windowFlags
)

Parameters

database
Open database containing the alert resource.
alertId
ID of the alert resource.
windowFlags
Window attributes to use when creating the dialog. See WinFlagsType. The attribute winFlagModal is set for you.

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

Comments

Use this function in one of two circumstances:

  • You need the window created for the alert to be a transitional window so that you can draw to it outside of frmUpdateEvents. In this case set the winFlagBackBuffer bit in windowFlags.
  • You are displaying an alert outside of the application process and the alert should appear in the same window layer as all of the other windows in that process.

See Also

FrmAlert(), FrmCustomResponseAlertWithFlags(), FrmCustomAlertWithFlags()

FrmAmIPenTracking Function ^TOP^

Purpose

Returns true if the specified element is tracking the pen.

Declared In

Form.h

Prototype

Boolean FrmAmIPenTracking (
   FormType *formP,
   uint16_t objectID
)

Parameters

formP
Pointer to the form.
objectID
The ID of the element that might be tracking the pen.

Returns

true if the element is tracking the pen, false otherwise.

FrmCloseAllForms Function ^TOP^

Purpose

Sends a frmCloseEvent to all open forms.

Declared In

Form.h

Prototype

void FrmCloseAllForms (
   void
)

Parameters

None.

Returns

Nothing.

Comments

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

See Also

FrmSaveAllForms()

FrmCopyLabel Function ^TOP^

Purpose

Copies the specified string into the data structure of the specified label in the specified form.

Declared In

Form.h

Prototype

void FrmCopyLabel (
   FormType *formP,
   uint16_t labelID,
   const char *newLabel
)

Parameters

formP
Pointer to the form.
labelID
Resource ID of the label.
newLabel
Pointer to a null-terminated string.

Returns

Nothing.

Comments

The length of the new label must not exceed the length of the string defined in the resource. When defining the string in the label 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 it is currently displayed on the screen.

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

Note that FrmCopyLabel() copies the passed string into memory already allocated for the label. Thus, the string doesn't need to remain in existence once FrmCopyLabel() returns.

See Also

FrmGetLabel()

FrmCopyTitle Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
newTitle
Pointer to the new title string.

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

Purpose

Creates a modal dialog from an alert resource and displays the dialog until the user taps a button in the alert dialog.

Declared In

Form.h

Prototype

uint16_t FrmCustomAlert (
   DmOpenRef database,
   uint16_t alertId,
   const char *s1,
   const char *s2,
   const char *s3
)

Parameters

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

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

Comments

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

Alert resources cannot be associated with window constraints resources, and usually a constraints resource is not necessary. The UI Library makes sure that the alert is always the same size and snaps to the bottom of the application area. If you need to set window creation attributes that you would normally set in a constraints resource, use FrmCustomAlertWithFlags().

See Also

FrmAlert(), FrmDoDialog(), FrmCustomResponseAlert(), FrmCustomAlertWithFlags()

FrmCustomAlertWithFlags Function ^TOP^

Purpose

Creates a modal dialog with the specified window attributes and alert resource. Displays the dialog until the user taps a button.

Declared In

Form.h

Prototype

uint16_t FrmCustomAlertWithFlags (
   DmOpenRef database,
   uint16_t alertId,
   WinFlagsType windowFlags,
   const char *s1,
   const char *s2,
   const char *s3
)

Parameters

database
Open database containing the alert resource.
alertId
Resource ID of the alert.
windowFlags
Window attributes to use when creating the dialog. See WinFlagsType. The attribute winFlagModal is set for you.
s1, s2, s3
Strings to replace ^1, ^2, and ^3. See the Comments in FrmCustomAlert() for more information.

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

Comments

Use this function in one of two circumstances:

  • You need the window created for the alert to be a transitional window so that you can draw to it outside of frmUpdateEvents. In this case set the winFlagBackBuffer bit in windowFlags.
  • You are displaying an alert outside of the application process and the alert should appear in the same window layer as all of the other windows in that process.

See Also

FrmCustomAlert(), FrmAlertWithFlags(), FrmCustomResponseAlertWithFlags()

FrmCustomResponseAlert Function ^TOP^

Purpose

Creates a modal dialog with a text field from an alert resource and displays it until the user taps a button in the alert dialog.

Declared In

Form.h

Prototype

uint16_t FrmCustomResponseAlert (
   DmOpenRef database,
   uint16_t alertId,
   const char *s1,
   const char *s2,
   const char *s3,
   char *entryStringBuf,
   int16_t entryStringBufLength,
   FormCheckResponseFuncPtr callback
)

Parameters

database
Open database containing the alert resource.
alertId
Resource ID of the alert.
s1, s2, s3
Strings to replace ^1, ^2, and ^3. See the Comments in FrmCustomAlert() for more information.
entryStringBuf
The string the user entered in the text field.
entryStringBufLength
The maximum length for the string in entryStringBuf.
callback
A callback function that processes the string. See FormCheckResponseFuncType(). Pass NULL if there is no callback.

Returns

The item number of the button the user selected. A button's item number is determined by its order in the alert dialog; the leftmost 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.

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.

Alert resources cannot be associated with window constraints resources, and usually a constraints resource is not necessary. The UI Library makes sure that the alert is always the same size and snaps to the bottom of the application area. If you need to set window creation attributes that you would normally set in a constraints resource, use FrmCustomResponseAlertWithFlags().

See Also

FrmAlert(), FrmDoDialog(), FrmCustomResponseAlertWithFlags()

FrmCustomResponseAlertWithFlags Function ^TOP^

Purpose

Creates a modal dialog with the specified window attributes and a text field from an alert resource. Displays the dialog until the user taps a button.

Declared In

Form.h

Prototype

uint16_t FrmCustomResponseAlertWithFlags (
   DmOpenRef database,
   uint16_t alertId,
   WinFlagsType windowFlags,
   const char *s1,
   const char *s2,
   const char *s3,
   char *entryStringBuf,
   int16_t entryStringBufLength,
   FormCheckResponseFuncPtr callback
)

Parameters

database
Open database containing the alert resource.
alertId
Resource ID of the alert.
windowFlags
Window attributes to use when creating the dialog. See WinFlagsType. The attribute winFlagModal is set for you.
s1, s2, s3
Strings to replace ^1, ^2, and ^3. See the Comments in FrmCustomAlert() for more information.
entryStringBuf
The string the user entered in the text field.
entryStringBufLength
The maximum length for the string in entryStringBuf.
callback
A callback function that processes the string. See FormCheckResponseFuncType(). Pass NULL if there is no callback.

Returns

The item number of the button the user selected. A button's item number is determined by its order in the alert dialog; the leftmost 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.

Comments

Use this function in one of two circumstances:

  • You need the window created for the alert to be a transitional window so that you can draw to it outside of frmUpdateEvents. In this case set the winFlagBackBuffer bit in windowFlags.
  • You are displaying an alert outside of the application process and the alert should appear in the same window layer as all of the other windows in that process.

See Also

FrmAlertWithFlags(), FrmCustomAlertWithFlags(), FrmCustomResponseAlert()

FrmDeleteForm Function ^TOP^

Purpose

Releases the memory occupied by a form. Any memory allocated to user interface elements in the form is also released.

Declared In

Form.h

Prototype

void FrmDeleteForm (
   FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

Nothing.

See Also

FrmInitForm(), FrmReturnToForm()

FrmDispatchEvent Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

Boolean FrmDispatchEvent (
   EventType *eventP
)

Parameters

eventP
Pointer to an event.

Returns

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

This function is called from most application event loops. It gives both the application and the UI Library a chance to handle any events sent to a form.

The event is dispatched to the appropriate form's handler. A form's event handler (FormEventHandlerType()) is registered by FrmSetEventHandler().

FrmDoDialog Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

uint16_t FrmDoDialog (
   FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

The resource ID of the button the user tapped.


NOTE: A default button press is simulated if the user switches to a different application while a modal dialog is active.

Comments

Before calling FrmDoDialog() you must call FrmInitForm() to load and initialize the dialog and you must set the event handler, if one is needed. After the call, read any values needed from the dialog's elements and then call FrmDeleteForm() to release the memory occupied by the dialog.

Forms displayed using FrmDoDialog() do not receive frmOpenEvent or frmCloseEvent.

Example

Use code similar to the following to display a modal dialog:


frmP = FrmInitForm(gDbP, MyDialogForm); 
FrmSetEventHandler(frmP, MyDialogEventHandler); 
/* initialize the dialog's controls here if necessary */ 
 
/* open the dialog, and wait until a button is pressed to 
close it. */ 
whichButton = FrmDoDialog(frmP); 
 
if (whichButton == DetailsOKButton) { 
  /* get data from controls on the form to save/apply changes  
  */ 
} 
FrmDeleteForm(frmP); 

See Also

FrmCustomAlert(), FrmCustomResponseAlert()

FrmDrawForm Function ^TOP^

Purpose

Draws all elements in a form and the frame around the form.

Declared In

Form.h

Prototype

void FrmDrawForm (
   FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

Nothing.

Comments

You do not need to call this function for most forms. FrmHandleEvent() does so for you. If the form requires custom drawing, call this in response to the frmUpdateEvent. Perform custom drawing after the call to FrmDrawForm().

Do not call this function outside of a frmUpdateEvent if the form uses an update-based window.

See Also

FrmEraseForm(), FrmInitForm()

FrmEraseForm Function ^TOP^

Purpose

Erases a form from the display.

Declared In

Form.h

Prototype

void FrmEraseForm (
   FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

Nothing.

FrmGetActiveField Function ^TOP^

Purpose

Returns the active field for a specified form.

Declared In

Form.h

Prototype

FieldType *FrmGetActiveField (
   const FormType *formP
)

Parameters

formP
Pointer to the form for which the active field should be returned, or NULL to obtain the active field on the active form.

Returns

A pointer to the active field. NULL if the form doesn't have an active field or if there is no active form.

See Also

FrmGetActiveForm()

FrmGetActiveForm Function ^TOP^

Purpose

Returns the currently active form.

Declared In

Form.h

Prototype

FormType *FrmGetActiveForm (
   void
)

Parameters

None.

Returns

A pointer to the active form.

Comments

You should not call the FrmGetActiveForm() function when a pop-up window is open.

See Also

FrmGetActiveField(), FrmGetActiveFormID(), FrmSetActiveForm()

FrmGetActiveFormID Function ^TOP^

Purpose

Returns the resource ID of the currently active form.

Declared In

Form.h

Prototype

uint16_t FrmGetActiveFormID (
   void
)

Parameters

None.

Returns

The active form's resource ID number or 0 if there is no active form.

See Also

FrmGetActiveForm()

FrmGetBitmapHandle Function ^TOP^

Purpose

Returns a handle to an internal bitmap structure that stores the bitmap in a format that can be displayed most efficiently. Caches the bitmap structure for future use.

Declared In

Form.h

Prototype

GcBitmapHandle FrmGetBitmapHandle (
   FormType *form,
   DmOpenRef database,
   DmResourceType bitmapType,
   DmResourceID bitmapID,
   uint32_t flags
)

Parameters

form
Pointer to the form.
database
Open database containing the bitmap resource.
bitmapType
The resource type of the bitmap resource, either bitmapRsc for a standard Palm OS bitmap or 'pngf' for a PNG resource.
bitmapID
The resource ID of the bitmap.
flags
One of the Bitmap Loading constants.

Returns

A GcBitmapHandle for the bitmap or NULL if a handle cannot be created for this bitmap.

Comments

This function returns a cached handle to the specified bitmap. The returned handle is suitable to pass to GcDrawBitmapAt() when you want to draw the bitmap to the screen. If the bitmap has not been previously cached, this function adds it to the cache, creates a bitmap handle for it, and returns the bitmap handle.

Do not use this function if you're performing animation, doing a slide show, or otherwise drawing a lot of bitmaps to the form. If you do, you may quickly fill the bitmap cache. Instead, use GcLoadBitmap() directly and release each bitmap as you finish with it.

See Also

FrmRemoveBitmapHandle()

FrmGetControlGroupSelection Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

uint16_t FrmGetControlGroupSelection (
   const FormType *formP,
   uint8_t groupNum
)

Parameters

formP
Pointer to the form.
groupNum
Group ID for this group of controls.

Returns

The item number of the selected control; returns frmNoSelectedControl if no item is selected.

Comments

When a group ID is assigned to a group of controls, those controls are mutually exclusive. Only one of the controls can be selected at a time. This function is the way you obtain the user selection for that group of controls.

Currently, only check boxes and push buttons can be grouped. It is more acceptable to group push buttons than check boxes.


NOTE: FrmSetControlGroupSelection() sets the selection in a control group based on a resource ID, not its index, which FrmGetControlGroupSelection() returns.

See Also

FrmGetObjectId(), FrmGetObjectPtr()

FrmGetControlValue Function ^TOP^

Purpose

Returns the current value of a control.

Declared In

Form.h

Prototype

int16_t FrmGetControlValue (
   const FormType *formP,
   uint16_t objIndex
)

Parameters

formP
Pointer to the form.
objIndex
Index of the control element in the form's data structure. You can obtain this by using FrmGetObjectIndex().

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.

See Also

FrmSetControlValue(), CtlGetValue()

FrmGetDefaultButtonID Function ^TOP^

Purpose

Gets the resource ID of the form's default button.

Declared In

Form.h

Prototype

uint16_t FrmGetDefaultButtonID (
   const FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

The resource ID of the button defined as the default, or 0 if the form has no default button.

Comments

Modal dialogs have a default button assigned. If the user decides to exit the application rather than respond to the modal dialog, the system enqueues a ctlSelectEvent for the default button, and the application should behave as if this button were tapped. Other types of forms do not have the default button assigned.

See Also

FrmSetDefaultButtonID(), FrmDoDialog()

FrmGetEventHandler Function ^TOP^

Purpose

Returns the form's event handler.

Declared In

Form.h

Prototype

FormEventHandlerType *FrmGetEventHandler (
   const FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

A pointer to the form's event handler. See FormEventHandlerType().

See Also

FrmSetEventHandler()

FrmGetFirstForm Function ^TOP^

Purpose

Returns the first form in the form list.

Declared In

Form.h

Prototype

FormType *FrmGetFirstForm (
   void
)

Parameters

None.

Returns

A pointer to a form, or NULL if there are no forms.

Comments

The form list is a LIFO stack. The last form created is the first form in the form list.

FrmGetFocus Function ^TOP^

Purpose

Returns the item (index) number of the element that has the focus.

Declared In

Form.h

Prototype

uint16_t FrmGetFocus (
   const FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

The index of the UI element that has the focus, or noFocus if no element has the focus. To convert the element's index to an ID, use FrmGetObjectId().

See Also

FrmGetObjectPtr(), FrmSetFocus()

FrmGetFormBounds Function ^TOP^

Purpose

Returns the current bounds of the form.

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
rP
Pointer to a RectangleType structure where the bounds are returned.

Returns

Nothing.

Compatibility

For forms with update-based or transitional windows, this function returns incorrect results until the winResizedEvent is received. It is acceptable to call this function in response to a frmUpdateEvent because winResizedEvent is sent before frmUpdateEvent.

See Also

FrmGetFormInitialBounds()

FrmGetFormId Function ^TOP^

Purpose

Returns the resource ID of a form.

Declared In

Form.h

Prototype

uint16_t FrmGetFormId (
   const FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

The form's resource ID.

See Also

FrmGetFormPtr()

FrmGetFormInitialBounds Function ^TOP^

Purpose

Returns the bounds of the form as specified in the form resource.

Declared In

FormLayout.h

Prototype

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

Parameters

formP
Pointer to the form.
rP
Pointer to a RectangleType structure where the bounds are returned.

Returns

Nothing.

Comments

The form may be larger or smaller than the bounds specified by rP; it may have been resized due to the user opening or closing the dynamic input area or displaying a slip window.

You may find this function useful when resizing your form in response to a winResizedEvent. If you always compare the bounds specified in the resized event to the form's original bounds as returned by this function, you'll avoid the slight rounding errors that may occur if you always compare the form's current size to the new size.

See Also

FrmGetFormBounds(), FrmGetObjectInitialBounds()

FrmGetFormPtr Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

FormType *FrmGetFormPtr (
   uint16_t formID
)

Parameters

formID
Resource ID number of the form.

Returns

A pointer to the form, or NULL if the form is not in memory.

See Also

FrmGetFormId()

FrmGetFormWithWindow Function ^TOP^

Purpose

Returns the form that uses the specified window.

Declared In

Form.h

Prototype

FormType *FrmGetFormWithWindow (
   WinHandle winH
)

Parameters

winH
The handle to a window.

Returns

A pointer to the form with the specified window or NULL if the form is not in memory.

See Also

FrmGetWindowHandle()

FrmGetGadgetData Function ^TOP^

Purpose

Returns the value stored in the data field of the gadget.

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
objIndex
Index of the gadget in the form's data structure. You can obtain this by using FrmGetObjectIndex().

Returns

A pointer to the custom gadget's data.

Comments

Gadgets provide a way for an application to attach custom gadgetry to a form. In general, the data field of a gadget contains a pointer to the custom element's data structure.

See Also

FrmSetGadgetData(), FrmSetGadgetHandler()

FrmGetHelpID Function ^TOP^

Purpose

Gets the resource ID of the form's help resource.

Declared In

Form.h

Prototype

uint16_t FrmGetHelpID (
   const FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

The resource ID of the form's help resource. The help resource is a String resource.

See Also

FrmSetHelpID()

FrmGetLabel Function ^TOP^

Purpose

Returns a pointer to the text of the specified label in the specified form.

Declared In

Form.h

Prototype

const char *FrmGetLabel (
   const FormType *formP,
   uint16_t labelID
)

Parameters

formP
Pointer to the form.
labelID
Resource ID of the label.

Returns

A pointer to the label string.

Comments

This function returns a pointer to the string itself, not a copy of it.

labelID must be a label. If not, a fatal error message is displayed.

See Also

FrmCopyLabel()

FrmGetLabelFont Function ^TOP^

Purpose

Gets the font used for a particular label that appears on a form.

Declared In

Form.h

Prototype

FontID FrmGetLabelFont (
   const FormType *formP,
   uint16_t labelID
)

Parameters

formP
Pointer to the form.
labelID
Resource ID of a label in the form (the element's type must be frmLabelObj).

Returns

The FontID of the font used for the label. If labelID is invalid or does not specify a label, this function returns 0.

See Also

FrmGetObjectType(), FrmSetLabelFont()

FrmGetMenuBarID Function ^TOP^

Purpose

Gets the resource ID of the form's menu bar.

Declared In

Form.h

Prototype

uint16_t FrmGetMenuBarID (
   const FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

The resource ID of the form's menu bar, or 0 if the form doesn't have a menu bar.

See Also

FrmSetMenu(), MenuGetActiveMenu()

FrmGetNumberOfObjects Function ^TOP^

Purpose

Returns the number of elements in a form.

Declared In

Form.h

Prototype

uint16_t FrmGetNumberOfObjects (
   const FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

The number of elements in the specified form.

See Also

FrmGetObjectPtr(), FrmGetObjectId()

FrmGetObjectBounds Function ^TOP^

Purpose

Retrieves the bounds of an element given its form and index.

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
objIndex
Index of an element in the form. You can obtain this by using FrmGetObjectIndex().
rP
Pointer to a RectangleType structure where the element bounds are returned. The bounds are in window-relative coordinates.

Returns

Nothing.

See Also

FrmGetObjectPosition(), FrmSetObjectPosition(), FrmGetObjectInitialBounds(), FrmSetObjectBounds()

FrmGetObjectId Function ^TOP^

Purpose

Returns the resource ID of the specified UI element.

Declared In

Form.h

Prototype

uint16_t FrmGetObjectId (
   const FormType *formP,
   uint16_t objIndex
)

Parameters

formP
Pointer to the form.
objIndex
Index of an element in the form. You can obtain this by using FrmGetObjectIndex().

Returns

The resource ID of the element or frmInvalidObjectId if the objIndex parameter is invalid.

See Also

FrmGetObjectPtr()

FrmGetObjectIdFromObjectPtr Function ^TOP^

Purpose

Returns the ID of a UI element given a pointer to that element.

Declared In

Form.h

Prototype

uint16_t FrmGetObjectIdFromObjectPtr (
   void *formObjP,
   FormObjectKind objKind
)

Parameters

formObjP
Pointer to a user interface element appearing on a form.
objKind
The form's type. Supply one of the values declared in the FormObjectKind enum.

Returns

The form's resource ID, or frmInvalidObjectID if objKind is not a valid value.

See Also

FrmGetObjectId(), FrmGetObjectPtr(), FrmGetObjectType()

FrmGetObjectIndex Function ^TOP^

Purpose

Returns the index of a UI element in the form's list of elements given the element's resource ID.

Declared In

Form.h

Prototype

uint16_t FrmGetObjectIndex (
   const FormType *formP,
   uint16_t objID
)

Parameters

formP
Pointer to the form.
objID
Resource ID of an element in the form.

Returns

The index of the specified element (the index of the first element is 0), or frmInvalidObjectId if the supplied element ID is invalid.

Comments

Bitmaps use a different mechanism for IDs than the rest of the forms. When finding a bitmap with FrmGetObjectIndex(), you need to pass the resource ID of the bitmap itself, not the resource ID of the form bitmap element that contains the bitmap. (Passing the ID of the form bitmap element may or may not give you the right element back, depending on how you created the elements.)

This means that if you've got the same bitmap in two different form bitmap elements on the same form, you won't be able to use FrmGetObjectIndex() to obtain the second one; it'll always return the first.

See Also

FrmGetObjectPtr(), FrmGetObjectId()

FrmGetObjectIndexFromPtr Function ^TOP^

Purpose

Returns the index of a UI element in the form's list of elements given a pointer to the element.

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
objP
Pointer to a UI element.

Returns

The index of the specified element (the index of the first element is 0), or frmInvalidObjectId if the supplied element pointer is invalid.

Comments

Normally, you use FrmGetObjectIndex() to obtain the index given a resource ID. Use FrmGetObjectIndexFromPtr() in cases where you do not know the resource ID of the element.

FrmGetObjectInitialBounds Function ^TOP^

Purpose

Returns the bounds specified when creating the UI element.

Declared In

FormLayout.h

Prototype

void FrmGetObjectInitialBounds (
   const FormType *formP,
   uint16_t objIndex,
   RectangleType *rP
)

Parameters

formP
Pointer to the form.
objIndex
Index of an element in the form. You can obtain this by using FrmGetObjectIndex().
rP
Pointer to a RectangleType structure where the bounds are returned. The bounds are in window-relative coordinates.

Returns

Nothing.

Comments

You must call FrmInitLayout() before calling this function.

You may find this function useful when resizing your form in response to a winResizedEvent. If you always use the initial bounds when computing offsets from the form's window, you'll avoid the slight rounding errors that can occur if you always compare the new bounds to the current bounds.

See Also

FrmGetFormInitialBounds(), FrmGetObjectPosition(), FrmGetObjectBounds()

FrmGetObjectPosition Function ^TOP^

Purpose

Returns the coordinates of the specified UI element relative to the form.

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
objIndex
Index of a UI element in the form. You can obtain this by using FrmGetObjectIndex().
x, y
Pointers where the window-relative x and y positions of the UI element are returned. These locate the top-left corner of the element.

Returns

Nothing.

See Also

FrmGetObjectBounds(), FrmSetObjectPosition()

FrmGetObjectPtr Function ^TOP^

Purpose

Returns a pointer to the data structure of an element in a form.

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
objIndex
Index of an element in the form. You can obtain this by using FrmGetObjectIndex().

Returns

A pointer to an element in the form.

See Also

FrmGetObjectId()

FrmGetObjectType Function ^TOP^

Purpose

Returns the type of a UI element.

Declared In

Form.h

Prototype

FormObjectKind FrmGetObjectType (
   const FormType *formP,
   uint16_t objIndex
)

Parameters

formP
Pointer to the form.
objIndex
Index of an element in the form. You can obtain this by using FrmGetObjectIndex().

Returns

The FormObjectKind of the item specified.

FrmGetObjectUsable Function ^TOP^

Purpose

Returns whether the UI element is usable.

Declared In

Form.h

Prototype

Boolean FrmGetObjectUsable (
   const FormType *formP,
   uint16_t objIndex
)

Parameters

formP
Pointer to the form.
objIndex
Index of an element in the form. You can obtain this by using FrmGetObjectIndex().

Returns

true if the element is usable, meaning that it is considered part of the user interface, or false if the element is not usable. Elements that are not usable never appear on the screen. The function FrmHideObject() clears an element's usable bit to hide that the element.

FrmGetTitle Function ^TOP^

Purpose

Returns a pointer to the title string of a form.

Declared In

Form.h

Prototype

const char *FrmGetTitle (
   const FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

A pointer to title string. NULL if there is no title string or there is an error finding it.

Comments

This is a pointer to the internal structure itself, not to a copy.

See Also

FrmCopyTitle(), FrmSetTitle()

FrmGetWindowHandle Function ^TOP^

Purpose

Obtains the form's window handle.

Declared In

Form.h

Prototype

WinHandle FrmGetWindowHandle (
   const FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

The handle to the form's window.

FrmGotoForm Function ^TOP^

Purpose

Sends a frmCloseEvent to the current form; sends a frmLoadEvent and a frmOpenEvent to the specified form.

Declared In

Form.h

Prototype

void FrmGotoForm (
   DmOpenRef database,
   uint16_t formID
)

Parameters

database
Open database containing the form resource.
formID
Resource ID of the form to display.

Returns

Nothing.

Comments

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

See Also

FrmPopupForm()

FrmHandleEvent Function ^TOP^

Purpose

Handles the event that has occurred in the form.

Declared In

Form.h

Prototype

Boolean FrmHandleEvent (
   FormType *formP,
   EventType *eventP
)

Parameters

formP
Pointer to the form.
eventP
Pointer to the event data structure (see EventType).

Returns

true if the event was handled, or false if it was not.

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 20.1 provides an overview of how FrmHandleEvent() handles different events.

Table 20.1  FrmHandleEvent() Actions 

When FrmHandleEvent() receives...

FrmHandleEvent() performs these actions...

ctlEnterEvent

Passes the event to CtlHandleEvent() for the control specified in the event.

ctlRepeatEvent

Passes the event to CtlHandleEvent() for the control specified in the event.

ctlSelectEvent

Checks if the control is a pop-up trigger. If it is, the list associated with the pop-up 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 or a table has the focus and passes the event to the appropriate handler (FldHandleEvent() or TblHandleEvent()). The table is also a container that may contain a field. If TblHandleEvent() receives a field event, it passes the event to the field contained within it.

frmCloseEvent

Erases the form using FrmEraseForm() and releases any memory allocated for it using FrmDeleteForm().

frmControlPrvRefreshEvent

Passes the event to CtlHandleEvent() for the control specified in the event.

frmGadgetEnterEvent

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

frmGadgetMiscEvent

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

frmScrollPrvRefreshEvent

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

frmTitleEnterEvent

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

FrmHandleEvent() does not block until the pen is lifted; it merely ensures that all future pen events are within the bounds of the title until a penUpEvent is received. Because of the multiprocessing nature of Palm OS Cobalt, a frmTitleSelectEvent is not guaranteed to be immediately preceded by an frmTitleEnterEvent.

frmTitleSelectEvent

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

frmUpdateEvent

Redraws the dirty region of the form. If the entire form needs to be redrawn, calls FrmDrawForm().

insertionPointOffEvent

Passes the event on to the field that has the focus.

insertionPointOnEvent

Passes the event on to the field that has the focus.

keyDownEvent

Passes the event to the handler for the element that has the focus. If no element has the focus and the event is a result of the user pressing one of the hardware buttons on the device, simulates a default button push if the form has a default button defined.

lstEnterEvent

Passes the event and a pointer to the element the event occurred in to LstHandleEvent().

menuCmdBarOpenEvent

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

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

If this form doesn't currently have the focus, calls WinRequestFocus(), which requests the focus. If the form receives focus, a winFocusGainedEvent is sent to the form.

Checks the list of UI elements 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.

penMoveEvent

Forwards to the event handler for the UI element that is tracking the pen.

penUpEvent

Forwards to the event handler for the UI element that is tracking the pen.

popSelectEvent

Sets the label of the pop-up trigger to the current selection of the pop-up list.

sclEnterEvent or
sclRepeatEvent

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

tblEnterEvent

Passes the event and a pointer to the element the event occurred in to TblHandleEvent(). The element's pointer is obtained from the event data.

tblExitEvent

Releases the focus.

tsmFepButtonEvent

Passes the event on to the field with the focus (if any).

tsmFepChangeEvent

Passes the event on to the field with the focus (if any).

tsmFepModeEvent

Passes the event on to the field with the focus (if any).

tsmFepSelectOptionEvent

Passes the event on to the field with the focus (if any).

winFocusGainedEvent

If the pen was tapped within a text field, gives focus to that field.

winFocusLostEvent

If a text field previously had focus, the focus is released from the field.

winResizedEvent

If FrmInitLayout() had been called on this form, calls FrmPerformLayout() to automatically rearrange and resize the elements on the form.

winUpdateEvent

Sends a frmUpdateEvent to the form's event handler.

FrmHelp Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

void FrmHelp (
   DmOpenRef database,
   uint16_t helpMsgId
)

Parameters

database
Open database containing the help string resource.
helpMsgId
Resource ID of help message string.

Returns

Nothing.

Comments

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

FrmHelpWithFlags Function ^TOP^

Purpose

Displays the specified help message until the user taps the Done button in the help dialog. Uses the attributes in windowFlags to create the help dialog.

Declared In

Form.h

Prototype

void FrmHelpWithFlags (
   DmOpenRef database,
   uint16_t helpMsgId,
   WinFlagsType windowFlags
)

Parameters

database
Open database containing the help string resource.
helpMsgId
Resource ID of help message string.
windowFlags
Window attributes to use when creating the dialog. See WinFlagsType. You must set winFlagModal to make the help dialog modal.

Returns

Nothing.

Comments

FrmHandleEvent() uses this function to create a help dialog if the dialog that contains the help trigger ("i" button) is in a window layer other than the normal layer. You should not need to use this function directly.

See Also

FrmHelp()

FrmHideObject Function ^TOP^

Purpose

Erases the specified UI element and sets its attribute data so that it does not redraw or respond to the pen.

Declared In

Form.h

Prototype

void FrmHideObject (
   FormType *formP,
   uint16_t objIndex
)

Parameters

formP
Pointer to the form.
objIndex
Index of a UI element in the form. You can obtain this by using FrmGetObjectIndex().

Returns

Nothing.

Comments

For forms using update-based windows, the element may not be hidden immediately. This function invalidates the region of the form that displayed the element. The element will be hidden during the next drawing update cycle. In either case, the element is hidden by filling its region with the color set for UIFormFill.

See Also

FrmShowObject()

FrmInitForm Function ^TOP^

Purpose

Loads and initializes a form resource.

Declared In

Form.h

Prototype

FormType *FrmInitForm (
   DmOpenRef database,
   uint16_t rscID
)

Parameters

database
Open database containing the form resource.
rscID
Resource ID of the form.

Returns

A pointer to the form data structure.

Comments

This function does not draw the form (use FrmDrawForm() to draw the form) nor does it 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. FrmHandleEvent() does this for you in response to frmCloseEvent. Alternatively, you can free the active form by calling FrmReturnToForm().

On debug ROMs, FrmInitForm() displays an error message if the form has already been initialized.

See Also

FrmInitForm()

FrmInitFormWithFlags Function ^TOP^

Purpose

Loads and initializes a form resource.

Declared In

Form.h

Prototype

FormType *FrmInitFormWithFlags (
   DmOpenRef database,
   uint16_t rscID,
   WinFlagsType windowFlags
)

Parameters

database
Open database containing the form resource.
rscID
Resource ID of the form.
windowFlags
Window attributes to use when creating the form. See WinFlagsType.

Returns

A pointer to the form data structure.

Comments

You typically specify the window attributes in the WINDOW_CONSTRAINTS_RESOURCE associated with your form and call FrmInitForm() instead of this function. It is used by other functions (such as FrmAlertWithFlags()) that create forms with window attribute flags.

On debug ROMs, FrmInitFormWithFlags() displays an error message if the form has already been initialized.

See Also

FrmDoDialog(), FrmDeleteForm(), FrmReturnToForm()

FrmInitLayout Function ^TOP^

Purpose

Prepares the form for automatic resizing by FrmPerformLayout().

Declared In

FormLayout.h

Prototype

status_t FrmInitLayout (
   FormType *formP,
   const FormLayoutType *formLayoutP
)

Parameters

formP
Pointer to the form.
formLayoutP
An array of FormLayoutType structures that specify the resizing rule for each element in the form. Use 0 as the last element in the array.

NOTE: This array must exist for the entire life of the form.

Returns

errNone upon success or sysErrNoFreeRAM if there is not enough memory available to initialize the layout structures.

Comments

Call this function if you want your form automatically resized in response to the winResizedEvent. Call it as soon after FrmInitForm() as possible, which means you typically call this in response to frmLoadEvent. It's important to call it before the first winResizedEvent is received.

If you need to rearrange UI elements on the form, do so before you call FrmInitLayout(). FrmInitLayout() stores the position of each element in the form. If you move an element after calling FrmInitLayout(), it will snap back to its initial position and size upon the next winResizedEvent.

On debug ROMs, this function displays a fatal error message if called more than once.

frmLayoutRule Macro ^TOP^

Purpose

Builds a rule that specifies how a UI element should be resized when its form is resized.

Declared In

FormLayout.h

Prototype

#define frmLayoutRule (
   left,
    top,
    right,
    bottom
)

Parameters

left, top, right, bottom
One of the "Form Basic Layout Constants." See the Comments for more information.

Returns

A constant that should be assigned to the rule field of a FormLayoutType structure.

Comments

This macro is used to construct the Form Layout Constants. The provided constants should be sufficient.

The top and bottom parameters work together to specify the vertical resizing rule. If both are frmAttachLeftTop, the element stays in a fixed location. If both are frmAttachRightBottom, the element moves but remains the same size. If top is frmAttachLeftTop and bottom is frmAttachRightBottom, the element resizes at the same rate as the form resizes. If top is frmAttachRightBottom and bottom is frmAttachLeftTop, the element lengthens when the form shortens and shortens when the form lengthens.

The left and right parameters work together to specify the horizontal resizing rule in a similar manner.

See Also

FrmInitLayout(), FrmPerformLayout()

FrmNewBitmap Function ^TOP^

Purpose

Creates a new form bitmap element dynamically.

Declared In

Form.h

Prototype

FormBitmapType *FrmNewBitmap (
   FormType **formPP,
   DmOpenRef database,
   uint16_t 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.
database
Open database containing the bitmap that is to be displayed in the form bitmap element.
rscID
Resource ID of the bitmap that should be displayed in this form bitmap. This value must be unique within the application scope.
x
Horizontal coordinate of the upper-left corner of the bitmap's boundaries, relative to the window in which it appears.
y
Vertical coordinate of the upper-left corner of the bitmap's boundaries, relative to the window in which it appears.

Returns

A pointer to the new bitmap, or 0 if the call did not succeed. The most common cause of failure is lack of memory.

See Also

FrmRemoveObject()

FrmNewForm Function ^TOP^

Purpose

Creates a new form dynamically.

Declared In

Form.h

Prototype

FormType *FrmNewForm (
   uint16_t formID,
   const char *titleStrP,
   Coord x,
   Coord y,
   Coord width,
   Coord height,
   Boolean modal,
   uint16_t defaultButton,
   DmOpenRef helpDatabase,
   uint16_t helpRscID,
   DmOpenRef menuDatabase,
   uint16_t 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 standard coordinates.
height
Height of the form, expressed in standard coordinates.
modal
true specifies that the form is a modal dialog.
defaultButton
Resource ID of the button that provides the form's default action.
helpDatabase
Open database containing the help string resource.
helpRscID
Resource ID of a help string resource that provides help for using this form. Only modal dialogs can have help resources.
menuDatabase
Open database containing the menu resource.
menuRscID
Resource ID of the form's menu.

Returns

A pointer to the new form, or 0 if the call did not succeed. The most common cause of failure is lack of memory.

Comments

This function creates a form with a legacy window that does not resize as the user opens and closes a dynamic input area. To create a form that dynamically resizes, use FrmNewFormWithConstraints().

See Also

FrmValidatePtr(), WinValidateHandle(), FrmRemoveObject()

FrmNewFormWithConstraints Function ^TOP^

Purpose

Creates a new form dynamically using the specified window attributes.

Declared In

Form.h

Prototype

FormType *FrmNewFormWithConstraints (
   uint16_t formID,
   const char *titleStrP,
   uint32_t win_flags,
   const WinConstraintsType *constraints,
   uint16_t defaultButton,
   DmOpenRef helpDatabase,
   uint16_t helpRscID,
   DmOpenRef menuDatabase,
   uint16_t 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.
windowFlags
Window attributes to use when creating the form. See WinFlagsType.
constraints
Size constraints to use when creating the form. See WinConstraintsType.
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 standard coordinates.
height
Height of the form, expressed in standard coordinates.
modal
true specifies that the form is a modal dialog.
defaultButton
Resource ID of the button that provides the form's default action.
helpDatabase
Open database containing the help string resource.
helpRscID
Resource ID of a help string resource that provides help for using this form. Only modal dialogs can have help resources.
menuDatabase
Open database containing the menu resource.
menuRscID
Resource ID of the form's menu.

Returns

A pointer to the new form, or 0 if the call did not succeed. The most common cause of failure is lack of memory.

See Also

FrmNewForm(), FrmValidatePtr(), WinValidateHandle(), FrmRemoveObject()

FrmNewGadget Function ^TOP^

Purpose

Creates a new gadget dynamically and installs it in the specified form.

Declared In

Form.h

Prototype

FormGadgetType *FrmNewGadget (
   FormType **formPP,
   uint16_t 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 standard coordinates. Valid values are 1 - 160.
height
Height of the gadget, expressed in standard coordinates.Valid values are 1 - 160.

Returns

A pointer to the new gadget or 0 if the call did not succeed. The most common cause of failure is lack of memory.

See Also

FrmRemoveObject()

FrmNewGsi Function ^TOP^

Purpose

Creates a new shift indicator dynamically and installs it in the specified form.

Declared In

Form.h

Prototype

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

Parameters

formPP
Pointer to a pointer to the form in which the new shift indicator is installed. This value is not a handle; that is, the old formPP value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the new formPP value returned by this function.
x
Horizontal coordinate of the upper-left corner of the shift indicator's boundaries, relative to the window in which it appears.
y
Vertical coordinate of the upper-left corner of the shift indicator's boundaries, relative to the window in which it appears.

Returns

A pointer to the new shift indicator or 0 if the call did not succeed. The most common cause of failure is lack of memory.

Comments

If the device has a dynamic input area, the currently active pinlet displays the shift state (called the pinlet input mode). Forms with text fields should still include a shift indicator if they might be run on devices that do not have a dynamic input area, for example, if the device has a keyboard instead of an input area.

FrmNewLabel Function ^TOP^

Purpose

Creates a new label dynamically and installs it in the specified form.

Declared In

Form.h

Prototype

FormLabelType *FrmNewLabel (
   FormType **formPP,
   uint16_t 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
FontID of the bitmapped font with which to draw the label text.

Returns

A pointer to the new label or 0 if the call did not succeed. The most common cause of failure is lack of memory.

See Also

CtlValidatePointer(), FrmRemoveObject()

FrmPerformLayout Function ^TOP^

Purpose

Resizes or rearranges the elements in the form according to the layout rules specified for them in FrmInitLayout().

Declared In

FormLayout.h

Prototype

void FrmPerformLayout (
   FormType *formP,
   const RectangleType *newBounds
)

Parameters

formP
Pointer to a form.
newBounds
The bounds to which the form is being resized. See RectangleType.

Returns

Nothing.

Comments

FrmHandleEvent() calls this function in response to the winResizedEvent if FrmInitLayout() was called when the form was loaded.

See Also

frmLayoutRule(), FormLayoutType

FrmPointInTitle Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
x, y
Window-relative x and y coordinates.

Returns

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

FrmPopupForm Function ^TOP^

Purpose

Enqueues a frmLoadEvent and a frmOpenEvent for the specified form.

Declared In

Form.h

Prototype

void FrmPopupForm (
   DmOpenRef database,
   uint16_t formID
)

Parameters

database
Open database containing the form resource.
formID
Resource ID of form to open.

Returns

Nothing.

Comments

This function is intended to display modal dialogs only. It differs from FrmGotoForm() in that the current form is not closed before the new one is opened. You can call FrmReturnToForm() to close a form opened by FrmPopupForm().

FrmRemoveBitmapHandle Function ^TOP^

Purpose

Removes a bitmap handle from the form's bitmap cache.

Declared In

Form.h

Prototype

void FrmRemoveBitmapHandle (
   FormType *form,
   DmOpenRef database,
   DmResourceType bitmapType,
   DmResourceID bitmapID,
   uint32_t flags
)

Parameters

form
A pointer to the form.
database
Open database containing the bitmap resource.
bitmapType
The resource type of the bitmap resource.
bitmapID
The resource ID of the bitmap.
flags
One of the Bitmap Loading constants. These must be the same flags you passed to FrmGetBitmapHandle().

Returns

Nothing.

Comments

Call this function to remove a previously cached bitmap from the form's cache after you no longer need it. As with all other form storage, the bitmap cache is freed when the form is freed, so making a separate call to this function is usually not necessary.

See Also

FrmGetBitmapHandle()

FrmRemoveObject Function ^TOP^

Purpose

Removes the specified UI element from the specified form.

Declared In

Form.h

Prototype

status_t FrmRemoveObject (
   FormType **formPP,
   uint16_t objIndex
)

Parameters

formPP
Pointer to a pointer to the form from which this function removes an element. 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 index of the element to remove. Use the FrmGetObjectIndex() function to obtain this value.

Returns

errNone if no error.

Comments

You can use this function to remove any dynamically created element (a bitmap, control, list, and so on) and free the memory allocated to it within the form data structure. The data structures for most elements are embedded within the form data structure memory chunk. This function frees that memory and moves the other element, 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 element, such as the memory allocated to the string in an editable field element.

See Also

FrmNewBitmap(), FrmNewForm(), FrmNewGadget(), FrmNewLabel(), CtlNewControl(), FldNewField(), LstNewList()

FrmRestoreActiveState Function ^TOP^

Purpose

Restores the active window and form state.

Declared In

Form.h

Prototype

status_t FrmRestoreActiveState (
   FormActiveStateType *stateP
)

Parameters

stateP
A pointer to the FormActiveStateType structure that you passed to FrmSaveActiveState() when you saved the state.

Returns

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

FrmReturnToForm Function ^TOP^

Purpose

Erases and deletes the currently active form and make the specified form the active form.

Declared In

Form.h

Prototype

void FrmReturnToForm (
   uint16_t formID
)

Parameters

formID
Resource ID of the form to return to.

Returns

Nothing.

Comments

Use this function to close a form that was displayed by FrmPopupForm(). It is assumed that the form being returned to is already loaded into memory and initialized. That is, unlike FrmGotoForm(), FrmReturnToForm() does not generate frmLoadEvent or frmOpenEvent for formID.

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

FrmSaveActiveState Function ^TOP^

Purpose

Saves the active window and form state.

Declared In

Form.h

Prototype

status_t FrmSaveActiveState (
   FormActiveStateType *stateP
)

Parameters

stateP
A pointer to a FormActiveStateType structure that is used to save the state. Pass the same pointer to FrmRestoreActiveState() to restore the state. Treat the structure like a black box; that is, don't attempt to read it or write to it.

Returns

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

FrmSaveAllForms Function ^TOP^

Purpose

Sends a frmSaveEvent to all open forms.

Declared In

Form.h

Prototype

void FrmSaveAllForms (
   void
)

Parameters

None.

Returns

Nothing.

See Also

FrmCloseAllForms()

FrmSetActiveForm Function ^TOP^

Purpose

Sets the active form. All input (key and pen) is directed to the active form, and all drawing occurs there until the next WinSetDrawWindow() call.

Declared In

Form.h

Prototype

void FrmSetActiveForm (
   FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

Nothing.

Comments

This function calls WinSetActiveWindow(), which enqueues winExitEvent and winEnterEvents and requests that formP be granted text input focus. Input focus is granted asynchronously and might not be granted if another process requests the input focus for a window in a higher layer at the same time. The form receives the winFocusGainedEvent when it is granted the input focus. Before this occurs, a winFocusLostEvent is sent to the window that had the text input focus before this function was called. Keep in mind that this window might have been part of another process.

See Also

FrmGetActiveForm()

FrmSetCategoryLabel Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

void FrmSetCategoryLabel (
   const FormType *formP,
   uint16_t objIndex,
   char *newLabel
)

Parameters

formP
Pointer to the form.
objIndex
Index of an element in the form. You can obtain this by using FrmGetObjectIndex().
newLabel
Pointer to the name of the new category.

Returns

Nothing.

Comments

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

FrmSetControlGroupSelection Function ^TOP^

Purpose

Sets the selected control in a group of controls.

Declared In

Form.h

Prototype

void FrmSetControlGroupSelection (
   const FormType *formP,
   uint8_t groupNum,
   uint16_t controlID
)

Parameters

formP
Pointer to the form.
groupNum
Control group number.
controlID
Resource ID of control to set.

Returns

Nothing.

Comments

This function unsets all the other controls in the group.

This function updates the display. For forms using update-based windows, the region displaying the control is invalidated so that it will be redrawn in the next update cycle.


NOTE: FrmGetControlGroupSelection() returns the selection in a control group as an element index, not as a resource ID, which FrmSetControlGroupSelection() uses to set the selection.

FrmSetControlValue Function ^TOP^

Purpose

Sets the current value of a control. If the control is visible, it's invalidated for later redrawing.

Declared In

Form.h

Prototype

void FrmSetControlValue (
   const FormType *formP,
   uint16_t objIndex,
   int16_t newValue
)

Parameters

formP
Pointer to the form.
objIndex
Index of the control in the form. You can obtain this by using FrmGetObjectIndex().
newValue
New value to set for the control. For sliders, specify a value between the slider's minimum and maximum. For graphical controls, push buttons, or check boxes, specify 0 for off, nonzero for on.

Returns

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

FrmSetDefaultButtonID Function ^TOP^

Purpose

Sets the default button for a modal dialog.

Declared In

Form.h

Prototype

void FrmSetDefaultButtonID (
   FormType *formP,
   uint16_t defaultButton
)

Parameters

formP
Pointer to the form.
defaultButton
Resource ID of the button that should be the default.

Returns

Nothing.

Comments

Modal dialogs have a default button assigned. If the user decides to exit the application rather than respond to the modal dialog, the system enqueues a ctlSelectEvent for the default button, and the application should behave as if this button were tapped. Other types of forms do not have the default button assigned.

You normally set the form's default button in the resource file. Use this function if you need to change the value at runtime.

See Also

FrmGetDefaultButtonID(), FrmDoDialog()

FrmSetEventHandler Function ^TOP^

Purpose

Registers the event handler callback routine for the specified form.

Declared In

Form.h

Prototype

void FrmSetEventHandler (
   FormType *formP,
   FormEventHandlerType *handler
)

Parameters

formP
Pointer to the form.
handler
Address of the form event handler function, FormEventHandlerType().

Returns

Nothing.

Comments

FrmDispatchEvent() calls this handler whenever it receives an event for a specific form.

FrmSetEventHandler() must be called during the frmLoadEvent. The callback routine it registers is the mechanism for dispatching events to an application.

FrmSetFocus Function ^TOP^

Purpose

Sets the focus of a form to the specified UI element.

Declared In

Form.h

Prototype

void FrmSetFocus (
   FormType *formP,
   uint16_t fieldIndex
)

Parameters

formP
Pointer to the form.
fieldIndex
Index of the element to get the focus in the form or noFocus to specify that no element has the focus. Obtain an element's index by using FrmGetObjectIndex().

Returns

Nothing.

Comments

You can set the focus to a field or table. If the focus is set to a field, this function turns on the insertion point in the field.

See Also

FrmGetFocus()

FrmSetGadgetData Function ^TOP^

Purpose

Stores a data value in the data field of the gadget.

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
objIndex
Index of the gadget. You can obtain this by using FrmGetObjectIndex().
data
Application-defined value. This value is stored into the data field of the gadget data structure (FormGadgetType).

Returns

Nothing.

Comments

Gadgets provide a way for an application to attach custom gadgetry to a form. Typically, the data field of a gadget contains a pointer to the custom element's data structure.

See Also

FrmGetGadgetData(), FrmSetGadgetHandler()

FrmSetGadgetHandler Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
objIndex
Index of the gadget. You can obtain this by using FrmGetObjectIndex().
attrP
Address of the callback function. See FormGadgetHandlerType().

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.

See Also

FrmGetGadgetData(), FrmSetGadgetData()

FrmSetHelpID Function ^TOP^

Purpose

Designates the string resource that is to act as the form's help resource.

Declared In

Form.h

Prototype

void FrmSetHelpID (
   FormType *formP,
   DmOpenRef database,
   uint16_t helpRscID
)

Parameters

formP
Pointer to the form.
database
Open database containing the help string resource.
helpRscID
The resource ID of the string resource that is to be the form's help resource.

Returns

Nothing.

Comments

You normally set the form's help resource in the resource file. Use this function if you need to change the value at runtime.

See Also

FrmGetHelpID()

FrmSetLabelFont Function ^TOP^

Purpose

Sets the font used for a particular label that appears on a form.

Declared In

Form.h

Prototype

void FrmSetLabelFont (
   FormType *formP,
   uint16_t labelID,
   FontID fontID
)

Parameters

formP
Pointer to the form.
labelID
Resource ID of a label in the form (the element's type must be frmLabelObj).
fontID
FontID of the bitmapped font to be used for the label.

Returns

Nothing.

Comments

This function does nothing if either labelID is invalid or if the element indicated by labelID has a type other than frmLabelObj.

See Also

FrmGetObjectType(), FrmGetLabelFont()

FrmSetMenu Function ^TOP^

Purpose

Changes a form's menu bar and makes the new menu active.

Declared In

Form.h

Prototype

void FrmSetMenu (
   FormType *formP,
   DmOpenRef database,
   uint16_t menuRscID
)

Parameters

formP
Pointer to the form.
database
Open database containing the menu resource.
menuRscID
Resource ID of the menu.

Returns

Nothing.

See Also

MenuGetActiveMenu()

FrmSetObjectBounds Function ^TOP^

Purpose

Sets the bounds or position of a UI element.

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
objIndex
Index of an element in the form. You can obtain this by using FrmGetObjectIndex().
bounds
Window-relative bounds (see RectangleType). For the following elements, this sets only the position of the top-left corner: label, bitmap, and shift indicator.

Returns

Nothing.

Comments

This function doesn't update or invalidate the form.

If you use this function, do not use FrmInitLayout() and FrmPerformLayout() to do automatic resizing in response to the winResizedEvent. FrmInitLayout() stores the initial position of a UI element. If you call it and then call FrmSetObjectBounds(), the new location or size is ignored during the next winResizedEvent.

See Also

FrmGetObjectPosition(), FrmGetObjectBounds()

FrmSetObjectPosition Function ^TOP^

Purpose

Sets the position of a UI element.

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
objIndex
Index of an element in the form. You can obtain this by using FrmGetObjectIndex().
x
Window-relative horizontal coordinate.
y
Window-relative vertical coordinate.

Returns

Nothing.

See Also

FrmGetObjectPosition(), FrmGetObjectBounds()

FrmSetPenTracking Function ^TOP^

Purpose

Sets whether an element in the form is tracking the pen.

Declared In

Form.h

Prototype

void FrmSetPenTracking (
   FormType *formP,
   Boolean track,
   const void *frmObj
)

Parameters

formP
Pointer to the form.
track
true to track the pen or false otherwise.
frmObj
A pointer to the UI element that is tracking the pen.

Returns

Nothing.

Comments

This function is used internally to keep track of the UI element that is tracking the pen. Applications should only call it for a gadget that needs to track the pen. Make the call in the gadget's event handler in response to frmGadgetEnterEvent.

This function is used in FrmHandleEvent() to set the form's internal pen tracking structures. If you call it outside of FrmHandleEvent(), you must pass an element that is part of the form's internal list of elements. If you don't, the function attempts to set the form's internal pen tracking index to specify the correct user interface element. This correction works most of the time; however, it is best to avoid calling this function except for the circumstances described above.

See Also

FrmAmIPenTracking()

FrmSetTitle Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

void FrmSetTitle (
   FormType *formP,
   char *newTitle
)

Parameters

formP
Pointer to the form.
newTitle
Pointer to the new title string.

Returns

Nothing.

Comments

This function invalidates the region that displays the title so that it is redrawn in the next update cycle.

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

See Also

FrmGetTitle(), FrmCopyTitle(), FrmCopyLabel()

FrmShowObject Function ^TOP^

Purpose

Sets a form element as usable. If the form is visible, invalidates the region that displays the element so that it is redrawn.

Declared In

Form.h

Prototype

void FrmShowObject (
   FormType *formP,
   uint16_t objIndex
)

Parameters

formP
Pointer to the form.
objIndex
Index of an element in the form. You can obtain this by using FrmGetObjectIndex().

Returns

Nothing.

Comments

For forms using update-based windows, the UI element may not be displayed immediately. It will be displayed during the next drawing update cycle.

See Also

FrmHideObject()

FrmUIAlert Function ^TOP^

Purpose

Displays an alert that is stored in the UI library's resource database.

Declared In

Form.h

Prototype

uint16_t FrmUIAlert (
   uint16_t alertId
)

Parameters

alertId
Resource ID of the alert. The header file UIResources.h contains a list of alerts that can be displayed by this function.

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

FrmAlert()

FrmUpdateForm Function ^TOP^

Purpose

Sends a frmUpdateEvent to the specified form.

Declared In

Form.h

Prototype

void FrmUpdateForm (
   uint16_t formID,
   uint16_t updateCode
)

Parameters

formID
Resource ID of form to update.
updateCode
An application-defined code that can be used to indicate what needs to be updated. Specify the code frmRedrawUpdateCode to indicate that the whole form should be redrawn.

Returns

Nothing.

Comments


WARNING! This function is for compatibility purposes only. Do not use it for forms with update-based windows. It does not produce the graphics context needed to draw to an update-based window. Use WinInvalidateRect(), WinInvalidateRectFunc(), or WinInvalidateWindow() instead.

If the frmUpdateEvent posted by this function is handled by the default form event handler, FrmHandleEvent(), the updateCode parameter is ignored. FrmHandleEvent() always redraws the form.

If you handle the frmUpdateEvent in a custom event handler, you can use the updateCode parameter any way you want. For example, you might use it to indicate that only a certain part of the form needs to be redrawn. If you do handle the frmUpdateEvent, be sure to return true from your event handler so that the default form handler does not also redraw the whole form.

If you do handle the frmUpdateEvent in a custom event handler, be sure to handle the case where updateCode is set to frmRedrawUpdateCode, and redraw the whole form. This event (and code) is sent by the system when the whole form needs to be redrawn because the display needs to be refreshed.

FrmUpdateScrollers Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

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

Parameters

formP
Pointer to the form.
upIndex
Index of the scroll up button. You can obtain this by using FrmGetObjectIndex().
downIndex
Index of the scroll down button. You can obtain this by using FrmGetObjectIndex().
scrollableUp
Set to true to make the up scroll arrow active (shown), or false to hide it.
scrollableDown
Set to true to make the down scroll arrow active (shown), or false to hide it.

Returns

Nothing.

FrmValidatePtr Function ^TOP^

Purpose

Returns true if the specified pointer references a valid form.

Declared In

Form.h

Prototype

Boolean FrmValidatePtr (
   const FormType *formP
)

Parameters

formP
Pointer to be tested.

Returns

true if the specified pointer is a non-NULL pointer to an element having a valid form structure.

Comments

This function is intended for debugging purposes only. Do not include it in released code.

FrmVisible Function ^TOP^

Purpose

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

Declared In

Form.h

Prototype

Boolean FrmVisible (
   const FormType *formP
)

Parameters

formP
Pointer to the form.

Returns

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

See Also

FrmDrawForm(), FrmEraseForm()

Application-Defined Functions ^TOP^

FormCheckResponseFuncType Function ^TOP^

Purpose

Callback function for FrmCustomResponseAlert().

Declared In

Form.h

Prototype

Boolean FormCheckResponseFuncType (
   int16_t button,
   char *attempt
)

Parameters

button
The ID of the button that the user tapped or a constant specifying an action that the callback should take. See the Comments section for details.
attempt
The string that the user entered in the alert dialog.

Returns

true if the dialog should be dismissed. Returns 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.

FormEventHandlerType Function ^TOP^

Purpose

The event handler callback routine for a form.

Declared In

Form.h

Prototype

Boolean FormEventHandlerType (
   EventType *eventP
)

Parameters

eventP
Pointer to the event.

Returns

true if this routine handled the event, otherwise false.

Comments

This function is where you respond to all of the events that the form receives other than frmLoadEvent.

FrmDispatchEvent() calls this handler whenever it receives an event for the form.

This callback routine is the mechanism for dispatching events to particular forms in an application. The callback is registered by the routine FrmSetEventHandler().

FormGadgetHandlerType Function ^TOP^

Purpose

The event handler callback for an extended gadget.

Declared In

Form.h

Prototype

Boolean (
   FormGadgetHandlerType
) (
   struct FormGadgetTypeInCallback *gadgetP,
   uint16_t cmd,
   void *paramP
)

Parameters

gadgetP
Pointer to the gadget structure. See FormGadgetTypeInCallback.
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 in response to the frmUpdateEvent 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 flag for you. If you return false, it also clears the usable flag and invalidates the window region that displays the gadget so that it is erased on the next update cycle.
formGadgetHandleEventCmd
Sent by FrmHandleEvent() to indicate that a gadget event has been received. The paramP parameter contains the pointer to the EventType structure.
paramP
NULL except if cmd is formGadgetHandleEventCmd. In that case, this parameter holds the pointer to the EventType structure containing the event.

Returns

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 element'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 the following events:

  • frmGadgetEnterEvent (if a pen down occurs within the gadget's bounds)
  • frmGadgetMiscEvent (if the application specifically sends it)
  • penMoveEvent (if the gadget called FrmSetPenTracking() in response to frmGadgetEnterEvent)
  • penUpEvent (if the gadget called FrmSetPenTracking() in response to frmGadgetEnterEvent)
  • frmObjectFocusTakeEvent (if the user navigates to the gadget)
  • frmObjectFocusLostEvent (if the user navigates away from the gadget)
  • keyDownEvent containing vchrRockerxxx characters (if the gadget has the navigation focus)

See Also

FrmSetGadgetHandler()