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
AlertTemplateType Struct
Purpose
Internal structure used to construct alert dialogs.
Declared In
Form.h
Prototype
typedef struct AlertTemplateTag AlertTemplateType
Fields
See Also
FrmAlert()
, FrmAlertWithFlags()
, FrmCustomAlert()
, FrmCustomAlertWithFlags()
, FrmCustomResponseAlert()
, FrmCustomResponseAlertWithFlags()
, FrmUIAlert()
FormActiveStateType Struct
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
Purpose
Defines the visible characteristics of a bitmap on a form.
Declared In
Form.h
Prototype
typedef struct FormBitmapType FormBitmapType
Fields
FormGadgetAttrType Struct
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 byFrmHideObject()
. -
extended
- If set, the gadget is an extended gadget. An extended gadget has the
handler
field defined in itsFormGadgetTypeInCallback
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
Purpose
A gadget that appears on a form.
Declared In
Form.h
Prototype
typedef struct FormGadgetType FormGadgetType
Fields
See Also
FrmSetGadgetData()
, FrmGetGadgetData()
FormGadgetTypeInCallback Struct
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()
andFrmSetGadgetData()
. -
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
Purpose
A label that appears on the form.
Declared In
Form.h
Prototype
typedef struct FormLabelType FormLabelType
Fields
FormLayoutType Struct
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
FormType Struct
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
FrmGraffitiStateType Struct
Purpose
Declared In
Form.h
Prototype
typedef struct FormGraffitiStateTag FrmGraffitiStateType
Fields
Form Constants
AlertType Enum
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
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
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
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
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
Gadget Actions
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 thevisible
flag for you. If you returnfalse
, it also clears theusable
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
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
frmCloseEvent
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
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:
Return false
from your event handler to get the default behavior from FrmHandleEvent()
.
frmGadgetEnterEvent
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
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
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
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
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
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
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
Purpose
Causes FrmDoDialog()
to exit with a simulated default button tap.
Declared In
EventCodes.h
Prototype
No data is passed with this event.
frmTitleEnterEvent
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
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
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
Comments
Applications do not normally respond to this event. FrmHandleEvent()
responds by displaying the form's menu.
frmUpdateEvent
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
ECFrmValidatePtr Macro
Purpose
Evaluates to true
if the specified pointer references a valid form.
Declared In
Form.h
Prototype
#define ECFrmValidatePtr (
formP
)
Parameters
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
FrmAlert Function
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 ( DmOpenRefdatabase
, uint16_talertId
)
Parameters
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
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 ( DmOpenRefdatabase
, uint16_talertId
, WinFlagsTypewindowFlags
)
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 attributewinFlagModal
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
frmUpdateEvent
s. In this case set the winFlagBackBuffer bit inwindowFlags
. - 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
Purpose
Returns true
if the specified element is tracking the pen.
Declared In
Form.h
Prototype
Boolean FrmAmIPenTracking ( FormType*formP
, uint16_tobjectID
)
Parameters
Returns
true
if the element is tracking the pen, false
otherwise.
FrmCloseAllForms Function
Purpose
Sends a frmCloseEvent
to all open forms.
Declared In
Form.h
Prototype
void FrmCloseAllForms ( void )
Parameters
Returns
Comments
Applications can call this function to ensure that all forms are closed cleanly before exiting PilotMain()
; that is, before termination.
See Also
FrmCopyLabel Function
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_tlabelID
, const char*newLabel
)
Parameters
-
→ formP
- Pointer to the form.
-
→ labelID
- Resource ID of the label.
-
→ newLabel
- Pointer to a null-terminated string.
Returns
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
FrmCopyTitle Function
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
Returns
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
FrmCustomAlert Function
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 ( DmOpenRefdatabase
, uint16_talertId
, 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
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 ( DmOpenRefdatabase
, uint16_talertId
, WinFlagsTypewindowFlags
, 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 attributewinFlagModal
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
frmUpdateEvent
s. In this case set the winFlagBackBuffer bit inwindowFlags
. - 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
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 ( DmOpenRefdatabase
, uint16_talertId
, const char*s1
, const char*s2
, const char*s3
, char*entryStringBuf
, int16_tentryStringBufLength
, FormCheckResponseFuncPtrcallback
)
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()
. PassNULL
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 andentryStringBuf
. The dialog is only dismissed if the callback returnstrue
. 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
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 ( DmOpenRefdatabase
, uint16_talertId
, WinFlagsTypewindowFlags
, const char*s1
, const char*s2
, const char*s3
, char*entryStringBuf
, int16_tentryStringBufLength
, FormCheckResponseFuncPtrcallback
)
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 attributewinFlagModal
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()
. PassNULL
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
frmUpdateEvent
s. In this case set the winFlagBackBuffer bit inwindowFlags
. - 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
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
Returns
See Also
FrmInitForm()
, FrmReturnToForm()
FrmDispatchEvent Function
Purpose
Dispatches an event to the application's handler for the form.
Declared In
Form.h
Prototype
Boolean FrmDispatchEvent (
EventType *eventP
)
Parameters
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
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
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
Purpose
Draws all elements in a form and the frame around the form.
Declared In
Form.h
Prototype
void FrmDrawForm (
FormType *formP
)
Parameters
Returns
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 Function
Purpose
Erases a form from the display.
Declared In
Form.h
Prototype
void FrmEraseForm (
FormType *formP
)
Parameters
Returns
FrmGetActiveField Function
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 Function
Purpose
Returns the currently active form.
Declared In
Form.h
Prototype
FormType *FrmGetActiveForm ( void )
Parameters
Returns
Comments
You should not call the FrmGetActiveForm()
function when a pop-up window is open.
See Also
FrmGetActiveField()
, FrmGetActiveFormID()
, FrmSetActiveForm()
FrmGetActiveFormID Function
Purpose
Returns the resource ID of the currently active form.
Declared In
Form.h
Prototype
uint16_t FrmGetActiveFormID ( void )
Parameters
Returns
The active form's resource ID number or 0 if there is no active form.
See Also
FrmGetBitmapHandle Function
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
, DmOpenRefdatabase
, DmResourceTypebitmapType
, DmResourceIDbitmapID
, uint32_tflags
)
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
FrmGetControlGroupSelection Function
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_tgroupNum
)
Parameters
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
Purpose
Returns the current value of a control.
Declared In
Form.h
Prototype
int16_t FrmGetControlValue ( const FormType*formP
, uint16_tobjIndex
)
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
Purpose
Gets the resource ID of the form's default button.
Declared In
Form.h
Prototype
uint16_t FrmGetDefaultButtonID (
const FormType *formP
)
Parameters
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
Purpose
Returns the form's event handler.
Declared In
Form.h
Prototype
FormEventHandlerType *FrmGetEventHandler (
const FormType *formP
)
Parameters
Returns
A pointer to the form's event handler. See FormEventHandlerType()
.
See Also
FrmGetFirstForm Function
Purpose
Returns the first form in the form list.
Declared In
Form.h
Prototype
FormType *FrmGetFirstForm ( void )
Parameters
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
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
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
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
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
FrmGetFormId Function
Purpose
Returns the resource ID of a form.
Declared In
Form.h
Prototype
uint16_t FrmGetFormId (
const FormType *formP
)
Parameters
Returns
See Also
FrmGetFormInitialBounds Function
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
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
Purpose
Returns a pointer to the form that has the specified ID.
Declared In
Form.h
Prototype
FormType *FrmGetFormPtr (
uint16_t formID
)
Parameters
Returns
A pointer to the form, or NULL if the form is not in memory.
See Also
FrmGetFormWithWindow Function
Purpose
Returns the form that uses the specified window.
Declared In
Form.h
Prototype
FormType *FrmGetFormWithWindow (
WinHandle winH
)
Parameters
Returns
A pointer to the form with the specified window or NULL
if the form is not in memory.
See Also
FrmGetGadgetData Function
Purpose
Returns the value stored in the data
field of the gadget.
Declared In
Form.h
Prototype
void *FrmGetGadgetData ( const FormType*formP
, uint16_tobjIndex
)
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
Purpose
Gets the resource ID of the form's help resource.
Declared In
Form.h
Prototype
uint16_t FrmGetHelpID (
const FormType *formP
)
Parameters
Returns
The resource ID of the form's help resource. The help resource is a String resource.
See Also
FrmGetLabel Function
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_tlabelID
)
Parameters
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
FrmGetLabelFont Function
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_tlabelID
)
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
Purpose
Gets the resource ID of the form's menu bar.
Declared In
Form.h
Prototype
uint16_t FrmGetMenuBarID (
const FormType *formP
)
Parameters
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
Purpose
Returns the number of elements in a form.
Declared In
Form.h
Prototype
uint16_t FrmGetNumberOfObjects (
const FormType *formP
)
Parameters
Returns
The number of elements in the specified form.
See Also
FrmGetObjectPtr()
, FrmGetObjectId()
FrmGetObjectBounds Function
Purpose
Retrieves the bounds of an element given its form and index.
Declared In
Form.h
Prototype
void FrmGetObjectBounds ( const FormType*formP
, uint16_tobjIndex
, 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
See Also
FrmGetObjectPosition()
, FrmSetObjectPosition()
, FrmGetObjectInitialBounds()
, FrmSetObjectBounds()
FrmGetObjectId Function
Purpose
Returns the resource ID of the specified UI element.
Declared In
Form.h
Prototype
uint16_t FrmGetObjectId ( const FormType*formP
, uint16_tobjIndex
)
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
FrmGetObjectIdFromObjectPtr Function
Purpose
Returns the ID of a UI element given a pointer to that element.
Declared In
Form.h
Prototype
uint16_t FrmGetObjectIdFromObjectPtr ( void*formObjP
, FormObjectKindobjKind
)
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
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_tobjID
)
Parameters
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
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
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
Purpose
Returns the bounds specified when creating the UI element.
Declared In
FormLayout.h
Prototype
void FrmGetObjectInitialBounds ( const FormType*formP
, uint16_tobjIndex
, 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
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
Purpose
Returns the coordinates of the specified UI element relative to the form.
Declared In
Form.h
Prototype
void FrmGetObjectPosition ( const FormType*formP
, uint16_tobjIndex
, 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
See Also
FrmGetObjectBounds()
, FrmSetObjectPosition()
FrmGetObjectPtr Function
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_tobjIndex
)
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
FrmGetObjectType Function
Purpose
Returns the type of a UI element.
Declared In
Form.h
Prototype
FormObjectKind FrmGetObjectType ( const FormType*formP
, uint16_tobjIndex
)
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
Purpose
Returns whether the UI element is usable.
Declared In
Form.h
Prototype
Boolean FrmGetObjectUsable ( const FormType*formP
, uint16_tobjIndex
)
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
Purpose
Returns a pointer to the title string of a form.
Declared In
Form.h
Prototype
const char *FrmGetTitle (
const FormType *formP
)
Parameters
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
FrmGetWindowHandle Function
Purpose
Obtains the form's window handle.
Declared In
Form.h
Prototype
WinHandle FrmGetWindowHandle (
const FormType *formP
)
Parameters
Returns
The handle to the form's window.
FrmGotoForm Function
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 ( DmOpenRefdatabase
, uint16_tformID
)
Parameters
Returns
Comments
The default form event handler (FrmHandleEvent()
) erases and disposes of a form when it receives a frmCloseEvent
.
See Also
FrmHandleEvent Function
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
Passes the event to |
|
Passes the event to |
|
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 |
|
Checks if a field or a table has the focus and passes the event to the appropriate handler ( |
|
Erases the form using |
|
Passes the event to |
|
Passes the event to the gadget's callback function if the gadget has one. See |
|
Passes the event to the gadget's callback function if the gadget has one. See |
|
Passes the event and a pointer to the element the event occurred in to |
|
Tracks the pen, without blocking, until it is lifted. If it is lifted within the bounds of the form title, adds a |
|
|
|
Adds a |
|
Redraws the dirty region of the form. If the entire form needs to be redrawn, calls |
|
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. |
|
Passes the event and a pointer to the element the event occurred in to |
|
Checks if a field or a table has the focus and passes the event to the appropriate handler ( |
|
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. |
|
|
If this form doesn't currently have the focus, calls |
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, |
|
Forwards to the event handler for the UI element that is tracking the pen. |
|
Forwards to the event handler for the UI element that is tracking the pen. |
|
Sets the label of the pop-up trigger to the current selection of the pop-up list. |
|
Passes the event and a pointer to the element the event occurred in to |
|
Passes the event and a pointer to the element the event occurred in to |
|
If the pen was tapped within a text field, gives focus to that field. |
|
If a text field previously had focus, the focus is released from the field. |
|
If |
|
Sends a |
FrmHelp Function
Purpose
Displays the specified help message until the user taps the Done button in the help dialog.
Declared In
Form.h
Prototype
void FrmHelp ( DmOpenRefdatabase
, uint16_thelpMsgId
)
Parameters
-
→ database
- Open database containing the help string resource.
-
→ helpMsgId
- Resource ID of help message string.
Returns
Comments
The help message is displayed in a modal dialog that supports scrolling the text if necessary.
FrmHelpWithFlags Function
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 ( DmOpenRefdatabase
, uint16_thelpMsgId
, WinFlagsTypewindowFlags
)
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 setwinFlagModal
to make the help dialog modal.
Returns
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
FrmHideObject Function
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_tobjIndex
)
Parameters
-
→ formP
- Pointer to the form.
-
→ objIndex
- Index of a UI element in the form. You can obtain this by using
FrmGetObjectIndex()
.
Returns
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
FrmInitForm Function
Purpose
Loads and initializes a form resource.
Declared In
Form.h
Prototype
FormType *FrmInitForm ( DmOpenRefdatabase
, uint16_trscID
)
Parameters
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
FrmInitFormWithFlags Function
Purpose
Loads and initializes a form resource.
Declared In
Form.h
Prototype
FormType *FrmInitFormWithFlags ( DmOpenRefdatabase
, uint16_trscID
, WinFlagsTypewindowFlags
)
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
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.
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
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
Purpose
Creates a new form bitmap element dynamically.
Declared In
Form.h
Prototype
FormBitmapType *FrmNewBitmap ( FormType**formPP
, DmOpenRefdatabase
, uint16_trscID
, Coordx
, Coordy
)
Parameters
-
↔ formPP
- Pointer to a pointer to the form in which the new bitmap is installed. This value is not a handle; that is, the old
formPP
value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the newformPP
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
FrmNewForm Function
Purpose
Creates a new form dynamically.
Declared In
Form.h
Prototype
FormType *FrmNewForm ( uint16_tformID
, const char*titleStrP
, Coordx
, Coordy
, Coordwidth
, Coordheight
, Booleanmodal
, uint16_tdefaultButton
, DmOpenRefhelpDatabase
, uint16_thelpRscID
, DmOpenRefmenuDatabase
, uint16_tmenuRscID
)
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
Purpose
Creates a new form dynamically using the specified window attributes.
Declared In
Form.h
Prototype
FormType *FrmNewFormWithConstraints ( uint16_tformID
, const char*titleStrP
, uint32_twin_flags
, const WinConstraintsType*constraints
, uint16_tdefaultButton
, DmOpenRefhelpDatabase
, uint16_thelpRscID
, DmOpenRefmenuDatabase
, uint16_tmenuRscID
)
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
Purpose
Creates a new gadget dynamically and installs it in the specified form.
Declared In
Form.h
Prototype
FormGadgetType *FrmNewGadget ( FormType**formPP
, uint16_tid
, Coordx
, Coordy
, Coordwidth
, Coordheight
)
Parameters
-
↔ formPP
- Pointer to a pointer to the form in which the new gadget is installed. This value is not a handle; that is, the old
formPP
value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the newformPP
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
FrmNewGsi Function
Purpose
Creates a new shift indicator dynamically and installs it in the specified form.
Declared In
Form.h
Prototype
FrmGraffitiStateType *FrmNewGsi ( FormType**formPP
, Coordx
, Coordy
)
Parameters
-
↔ formPP
- Pointer to a pointer to the form in which the new shift indicator is installed. This value is not a handle; that is, the old
formPP
value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the newformPP
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
Purpose
Creates a new label dynamically and installs it in the specified form.
Declared In
Form.h
Prototype
FormLabelType *FrmNewLabel ( FormType**formPP
, uint16_tID
, const char*textP
, Coordx
, Coordy
, FontIDfont
)
Parameters
-
↔ formPP
- Pointer to a pointer to the form in which the new label is installed. This value is not a handle; that is, the old
formPP
value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the newformPP
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
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
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
Purpose
Checks if a coordinate is within the bounds of the form's title.
Declared In
Form.h
Prototype
Boolean FrmPointInTitle ( const FormType*formP
, Coordx
, Coordy
)
Parameters
Returns
true
if the specified coordinate is in the form's title.
FrmPopupForm Function
Purpose
Enqueues a frmLoadEvent
and a frmOpenEvent
for the specified form.
Declared In
Form.h
Prototype
void FrmPopupForm ( DmOpenRefdatabase
, uint16_tformID
)
Parameters
Returns
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
Purpose
Removes a bitmap handle from the form's bitmap cache.
Declared In
Form.h
Prototype
void FrmRemoveBitmapHandle ( FormType*form
, DmOpenRefdatabase
, DmResourceTypebitmapType
, DmResourceIDbitmapID
, uint32_tflags
)
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
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
FrmRemoveObject Function
Purpose
Removes the specified UI element from the specified form.
Declared In
Form.h
Prototype
status_t FrmRemoveObject ( FormType**formPP
, uint16_tobjIndex
)
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 newformPP
value returned by this function. -
→ objIndex
- The index of the element to remove. Use the
FrmGetObjectIndex()
function to obtain this value.
Returns
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
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 toFrmSaveActiveState()
when you saved the state.
Returns
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
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
Returns
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
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 toFrmRestoreActiveState()
to restore the state. Treat the structure like a black box; that is, don't attempt to read it or write to it.
Returns
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
Purpose
Sends a frmSaveEvent
to all open forms.
Declared In
Form.h
Prototype
void FrmSaveAllForms ( void )
Parameters
Returns
See Also
FrmSetActiveForm Function
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
Returns
Comments
This function calls WinSetActiveWindow()
, which enqueues winExitEvent
and winEnterEvent
s 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
FrmSetCategoryLabel Function
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_tobjIndex
, 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
Comments
The pointer to the new label (newLabel
) is saved in the element.
FrmSetControlGroupSelection Function
Purpose
Sets the selected control in a group of controls.
Declared In
Form.h
Prototype
void FrmSetControlGroupSelection ( const FormType*formP
, uint8_tgroupNum
, uint16_tcontrolID
)
Parameters
-
→ formP
- Pointer to the form.
-
→ groupNum
- Control group number.
-
→ controlID
- Resource ID of control to set.
Returns
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
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_tobjIndex
, int16_tnewValue
)
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
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
Purpose
Sets the default button for a modal dialog.
Declared In
Form.h
Prototype
void FrmSetDefaultButtonID ( FormType*formP
, uint16_tdefaultButton
)
Parameters
Returns
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
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
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
Purpose
Sets the focus of a form to the specified UI element.
Declared In
Form.h
Prototype
void FrmSetFocus ( FormType*formP
, uint16_tfieldIndex
)
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 usingFrmGetObjectIndex()
.
Returns
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
FrmSetGadgetData Function
Purpose
Stores a data value in the data
field of the gadget.
Declared In
Form.h
Prototype
void FrmSetGadgetData ( FormType*formP
, uint16_tobjIndex
, 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
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
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_tobjIndex
, 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
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
Purpose
Designates the string resource that is to act as the form's help resource.
Declared In
Form.h
Prototype
void FrmSetHelpID ( FormType*formP
, DmOpenRefdatabase
, uint16_thelpRscID
)
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
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
FrmSetLabelFont Function
Purpose
Sets the font used for a particular label that appears on a form.
Declared In
Form.h
Prototype
void FrmSetLabelFont ( FormType*formP
, uint16_tlabelID
, FontIDfontID
)
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
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
Purpose
Changes a form's menu bar and makes the new menu active.
Declared In
Form.h
Prototype
void FrmSetMenu ( FormType*formP
, DmOpenRefdatabase
, uint16_tmenuRscID
)
Parameters
-
→ formP
- Pointer to the form.
-
→ database
- Open database containing the menu resource.
-
→ menuRscID
- Resource ID of the menu.
Returns
See Also
FrmSetObjectBounds Function
Purpose
Sets the bounds or position of a UI element.
Declared In
Form.h
Prototype
void FrmSetObjectBounds ( FormType*formP
, uint16_tobjIndex
, 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
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
Purpose
Sets the position of a UI element.
Declared In
Form.h
Prototype
void FrmSetObjectPosition ( FormType*formP
, uint16_tobjIndex
, Coordx
, Coordy
)
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
See Also
FrmGetObjectPosition()
, FrmGetObjectBounds()
FrmSetPenTracking Function
Purpose
Sets whether an element in the form is tracking the pen.
Declared In
Form.h
Prototype
void FrmSetPenTracking ( FormType*formP
, Booleantrack
, const void *frmObj
)
Parameters
-
→ formP
- Pointer to the form.
-
→ track
-
true
to track the pen orfalse
otherwise. -
→ frmObj
- A pointer to the UI element that is tracking the pen.
Returns
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
FrmSetTitle Function
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
Returns
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
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_tobjIndex
)
Parameters
-
→ formP
- Pointer to the form.
-
→ objIndex
- Index of an element in the form. You can obtain this by using
FrmGetObjectIndex()
.
Returns
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
FrmUIAlert Function
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
FrmUpdateForm Function
Purpose
Sends a frmUpdateEvent
to the specified form.
Declared In
Form.h
Prototype
void FrmUpdateForm ( uint16_tformID
, uint16_tupdateCode
)
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
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
Purpose
Visually updates (show or hide) the field scroll arrow buttons.
Declared In
Form.h
Prototype
void FrmUpdateScrollers ( FormType*formP
, uint16_tupIndex
, uint16_tdownIndex
, BooleanscrollableUp
, BooleanscrollableDown
)
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), orfalse
to hide it. -
→ scrollableDown
- Set to
true
to make the down scroll arrow active (shown), orfalse
to hide it.
Returns
FrmValidatePtr Function
Purpose
Returns true
if the specified pointer references a valid form.
Declared In
Form.h
Prototype
Boolean FrmValidatePtr (
const FormType *formP
)
Parameters
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
Purpose
Returns true
if the form is visible (is drawn).
Declared In
Form.h
Prototype
Boolean FrmVisible (
const FormType *formP
)
Parameters
Returns
true if the form is visible; false if it is not visible.
See Also
Application-Defined Functions
FormCheckResponseFuncType Function
Purpose
Callback function for FrmCustomResponseAlert()
.
Declared In
Form.h
Prototype
Boolean FormCheckResponseFuncType ( int16_tbutton
, 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 offrmResponseCreate
. 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 callTsmSetFepMode(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 returntrue
. If not, it should returnfalse
to give the user a chance to re-enter the string. - At the end of
FrmCustomResponseAlert()
, this function is called with a button ID offrmResponseQuit
. This gives the callback a change to perform any cleanup, such as re-enabling the Japanese FEP.
FormEventHandlerType Function
Purpose
The event handler callback routine for a form.
Declared In
Form.h
Prototype
Boolean FormEventHandlerType (
EventType *eventP
)
Parameters
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
Purpose
The event handler callback for an extended gadget.
Declared In
Form.h
Prototype
Boolean ( FormGadgetHandlerType ) ( struct FormGadgetTypeInCallback*gadgetP
, uint16_tcmd
, 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 thevisible
flag for you. If you returnfalse
, it also clears theusable
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. TheparamP
parameter contains the pointer to theEventType
structure. -
→ paramP
-
NULL
except ifcmd
isformGadgetHandleEventCmd
. In that case, this parameter holds the pointer to theEventType
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 calledFrmSetPenTracking()
in response tofrmGadgetEnterEvent
) -
penUpEvent
(if the gadget calledFrmSetPenTracking()
in response tofrmGadgetEnterEvent
) -
frmObjectFocusTakeEvent
(if the user navigates to the gadget) -
frmObjectFocusLostEvent
(if the user navigates away from the gadget) -
keyDownEvent
containingvchrRocker
xxx characters (if the gadget has the navigation focus)