|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ResultReturns a pointer to the field object of the active field, or NULL if the form doesn't have an active field or if there is no active form. CommentsThis function will most often be called with a NULL parameter to obtain the active field on the active form. CompatibilityImplemented only if 4.0 New Feature Set is present. See Also
FrmGetActiveForm
PurposeReturn the currently active form. PrototypeFormType *FrmGetActiveForm (void) Parameters
ResultReturns a pointer to the form object of the active form. CommentsYou should not call the FrmGetActiveForm function when a popup window is open. There is no active form while a popup is displayed, and the value returned from FrmGetActiveForm in this situation has no meaning. See AlsoFrmGetActiveField, FrmGetActiveFormID, FrmSetActiveForm
FrmGetActiveFormID
PurposeReturn the ID of the currently active form. PrototypeUInt16 FrmGetActiveFormID (void) Parameters
ResultReturns the active form's ID number. See Also
FrmGetControlGroupSelection
PurposeReturn the item number of the control selected in a group of controls. PrototypeUInt16 FrmGetControlGroupSelection (const FormType *formP, UInt8 groupNum) Parameters
ResultReturns the item number of the selected control; returns frmNoSelectedControl if no item is selected. CommentsThe item number is the index into the form object's data structure. NOTE: FrmSetControlGroupSelection sets the selection in a control group based on an object ID, not its index, which FrmGetControlGroupSelection returns. CompatibilityOn versions prior to 3.5, this function returned a Byte instead of UInt16. See AlsoFrmGetObjectId, FrmGetObjectPtr, FrmSetControlGroupSelection
FrmGetControlValue
PurposeReturn the current value of a control. PrototypeInt16 FrmGetControlValue (const FormType *formP, UInt16 objIndex) Parameters
ResultReturns 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. CommentsThe caller must specify a valid index. This function is valid only for push button and check box control objects. See Also
FrmGetFirstForm
PurposeReturn the first form in the window list. PrototypeFormType *FrmGetFirstForm (void) Parameters
ResultReturns a pointer to a form object, or NULL if there are no forms. CommentsThe window list is a LIFO stack. The last window created is the first window in the window list.
FrmGetFocus
PurposeReturn the item (index) number of the object that has the focus. PrototypeUInt16 FrmGetFocus (const FormType *formP) Parameters
ResultReturns the index of the object (UI element) that has the focus, or returns noFocus if none does. To convert the object index to an ID, use FrmGetObjectId. See Also
FrmGetFormBounds
PurposeReturn the visual bounds of the form; the region returned includes the form's frame. Prototypevoid FrmGetFormBounds (const FormType *formP, RectangleType *rP) Parameters
ResultReturns nothing. The bounds of the form are returned in r.
FrmGetFormId
PurposeReturn the resource ID of a form. PrototypeUInt16 FrmGetFormId (const FormType *formP) Parameters
ResultSee Also
FrmGetFormPtr
PurposeReturn a pointer to the form that has the specified ID. PrototypeFormType *FrmGetFormPtr (UInt16 formId) Parameters
ResultReturns a pointer to the form object, or NULL if the form is not in memory. See Also
FrmGetGadgetData
PurposeReturn the value stored in the data field of the gadget object. Prototypevoid *FrmGetGadgetData (const FormType *formP, UInt16 objIndex) Parameters
ResultReturns a pointer to the custom gadget's data. CommentsGadget objects provide a way for an application to attach custom gadgetry to a form. In general, the data field of a gadget object contains a pointer to the custom object's data structure. See AlsoFrmSetGadgetData, FrmSetGadgetHandler
FrmGetLabel
PurposeReturn pointer to the text of the specified label object in the specified form. Prototypeconst Char *FrmGetLabel (const FormType *formP, UInt16 labelID) Parameters
ResultReturns a pointer to the label string. CommentsDoes not make a copy of the string; returns a pointer to the string. The object must be a label. See Also
FrmGetNumberOfObjects
PurposeReturn the number of objects in a form. PrototypeUInt16 FrmGetNumberOfObjects (const FormType *formP) Parameters
ResultReturns the number of objects in the specified form. See AlsoFrmGetObjectPtr, FrmGetObjectId
FrmGetObjectBounds
PurposeRetrieve the bounds of an object given its form and index. Prototypevoid FrmGetObjectBounds (const FormType *formP, UInt16 objIndex, RectangleType *rP) Parameters
ResultReturns nothing. The object's bounds are returned in r. See AlsoFrmGetObjectPosition, FrmSetObjectPosition
FrmGetObjectId
PurposeReturn the ID of the specified object. PrototypeUInt16 FrmGetObjectId (const FormType *formP, UInt16 objIndex) Parameters
ResultReturns the ID number of an object or frmInvalidObjectId if the objIndex parameter is invalid. See Also
FrmGetObjectIndex
PurposeReturn the index of an object in the form's objects list. PrototypeUInt16 FrmGetObjectIndex (const FormType *formP, UInt16 objID) Parameters
ResultReturns the index of the specified object (the index of the first object is 0), or frmInvalidObjectId if the supplied object ID is invalid. CommentsBitmaps use a different mechanism for IDs than the rest of the form objects. When finding a bitmap with FrmGetObjectIndex, you need to pass the bitmap's resource ID, not the ID of the form bitmap object. (Passing the ID of the form bitmap object may or may not give you the right object back, depending on how you created the objects.) This means that if you've got the same bitmap in two different form bitmap objects on the same form, you won't be able to use FrmGetObjectIndex to get at the second one; it'll always return the first. See AlsoFrmGetObjectPtr, FrmGetObjectId
|
-> formP | Pointer to a FormType. |
-> objP | Pointer to an object. |
Returns the object's index. frmInvalidObjectId is returned if objP is not associated with the form.
Many form functions (FrmGetObjectType, FrmHideObject, and FrmGetObjectBounds, for example) take an object index as one of their arguments. The most common way to get an object's index is to call FrmGetObjectIndex. FrmGetObjectIndex takes a form ID and returns the form object's index. This is the routine one should use in most cases, because the application usually knows the object ID. However, gadgets and specifically extended gadgets, have APIs with callbacks that pass back the gadget pointer and not the ID. In those cases, the only way to get the object index (so one can use the FrmGetObject* APIs) is to use the function FrmGetObjectIndexFromPtr.
If you need the same functionality on pre-Palm OS 4.0 systems then you can accomplish the same thing with the following code snippet.
UInt16 index; UInt16 objIndex = frmInvalidObjectId; UInt16 numObjects = FrmGetNumberOfObjects(frmP) for (index = 0; index < numObjects; index++) { if (FrmGetObjectPtr(index) == myObjPtr) { // Found it objIndex = index; break; } }
Return the coordinates of the specified object relative to the form.
void FrmGetObjectPosition (const FormType *formP, UInt16 objIndex, Coord *x, Coord *y)
-> formP | Pointer to the form object (FormType structure). |
-> objIndex | Index of an object in the form. You can obtain this by using FrmGetObjectIndex. |
<- x, y | Pointers where the window-relative x and y positions of the object are returned. These locate the top-left corner of the object. |
FrmGetObjectBounds, FrmSetObjectPosition
Return a pointer to the data structure of an object in a form.
void *FrmGetObjectPtr (const FormType *formP, UInt16 objIndex)
-> formP | Pointer to the form object (FormType structure). |
-> objIndex | Index of an object in the form. You can obtain this by using FrmGetObjectIndex. |
Returns a pointer to an object in the form.
FormObjectKind FrmGetObjectType (const FormType *formP, UInt16 objIndex)
-> formP | Pointer to the form object (FormType structure). |
-> objIndex | Index of an object in the form. You can obtain this by using FrmGetObjectIndex. |
Returns FormObjectKind of the item specified. See FormObjectKind.
Return a pointer to the title string of a form.
const Char *FrmGetTitle (const FormType *formP)
-> formP | Pointer to the form object (FormType structure). |
Returns a pointer to title string, or NULL if there is no title string or there is an error finding it.
This is a pointer to the internal structure itself, not to a copy.
Return the window handle of a form.
WinHandle FrmGetWindowHandle (const FormType *formP)
-> formP | Pointer to the form object (FormType structure). |
Returns the handle of the memory block that contains the form data structure. Since the form structure begins with the WindowType, this is also a WinHandle.
Send a frmCloseEvent to the current form; send a frmLoadEvent and a frmOpenEvent to the specified form.
void FrmGotoForm (UInt16 formId)
-> formId | ID of the form to display. |
The default form event handler (FrmHandleEvent) erases and disposes of a form when it receives a frmCloseEvent.
Handle the event that has occurred in the form.
Boolean FrmHandleEvent (FormType *formP, EventType *eventP)
-> formP | Pointer to the form object (FormType structure). |
-> eventP | Pointer to the event data structure (EventType). |
Returns true if the event was handled.
Never call this function directly. Call FrmDispatchEvent instead. FrmDispatchEvent passes events to a form's custom event handler and then, if the event was not handled, to this function.
Table 11.1 provides an overview of how FrmHandleEvent handles different events.
When FrmHandleEvent receives... |
FrmHandleEvent performs these actions... |
---|---|
Passes the event and a pointer to the object the event occurred in to CtlHandleEvent. The object pointer is obtained from the event data. If the control is part of an exclusive control group, it deselects the currently selected control of the group first. |
|
Passes the event and a pointer to the object the event occurred in to CtlHandleEvent. The object pointer is obtained from the event data. |
|
Checks if the control is a Popup Trigger Control. If it is, the list associated with the popup trigger is displayed until the user makes a selection or touches the pen outside the bounds of the list. If a selection is made, a popSelectEvent is added to the event queue. |
|
Checks if a field object or a table object has the focus and passes the event to the appropriate handler (FldHandleEvent or TblHandleEvent). The table object is also a container object, which may contain a field object. If TblHandleEvent receives a field event, it passes the event to the field object contained within it. |
|
Erases the form and releases any memory allocated for it. |
|
Passes the event to the gadget's callback function if the gadget has one. See FormGadgetHandler. |
|
Passes the event to the gadget's callback function if the gadget has one. See FormGadgetHandler. |
|
Tracks the pen until it is lifted. If it is lifted within the bounds of the form title, adds a frmTitleSelectEvent event to the event queue. |
|
Adds a keyDownEvent with the vchrMenu character to the event queue. |
|
Calls FrmDrawForm to redraw the form. |
|
Passes the event to the handler for the object that has the focus. If no object has the focus, the event is ignored. |
|
Passes the event and a pointer to the object the event occurred in to LstHandleEvent. The object pointer is obtained from the event data. |
|
Checks if a field object or a table object has the focus and passes the event to the appropriate handler (FldHandleEvent or TblHandleEvent), broadcasts the notification sysNotifyMenuCmdBarOpenEvent, and then displays the command toolbar. |
|
Checks if the menu command is one of the system edit menu commands. The system provides a standard edit menu that contains the commands Undo, Cut, Copy, Paste, Select All, and Keyboard. FrmHandleEvent responds to these commands. |
|
penDownEvent; pen position in the bounds of the form object |
Checks the list of objects contained by the form to determine if the pen is within the bounds of one. If it is, the appropriate handler is called to handle the event, for example, if the pen is in a control, CtlHandleEvent is called. If the pen isn't within the bounds of an object, the event is ignored by the form. If the pen is within the bounds of the help icon, it is tracked until it is lifted, and if it's still within the help icon bounds, the help dialog is displayed. |
Sets the label of the popup trigger to the current selection of the popup list. |
|
Passes the event and a pointer to the object the event occurred in to SclHandleEvent. |
|
Passes the event and a pointer to the object the event occurred in to TblHandleEvent. The object pointer is obtained from the event data. |
FrmHandleEvent only handles frmTitleSelectEvent, menuCmdBarOpenEvent, frmGadgetEnterEvent, and frmGadgetMiscEvent if 3.5 New Feature Set is present.
Display the specified help message until the user taps the Done button in the help dialog.
void FrmHelp (UInt16 helpMsgId)
-> helpMsgId | Resource ID of help message string. |
The help message is displayed in a modal dialog that supports scrolling the text if necessary.
Erase the specified object and set its attribute data (usable bit) so that it does not redraw or respond to the pen.
void FrmHideObject (FormType *formP, UInt16 objIndex)
-> formP | Pointer to the form object (FormType structure). |
-> objIndex | Index of an object in the form. You can obtain this by using FrmGetObjectIndex. |
Prior to OS version 3.2, this function did not set the usable bit of the object attribute data to false. On an OS version prior to 3.2 you can work around this bug by directly setting this bit to false yourself.
On versions of Palm OS prior to 3.5 this function doesn't affect lists or tables. On Palm OS 3.5 it operates correctly on lists but doesn't have any effect on tables. On Palm OS 4.0 it operates correctly on both lists and tables.
If 3.5 New Feature Set is present and the object is an extended gadget, this function calls the gadget's callback with formGadgetEraseCmd. See FormGadgetHandler.
Load and initialize a form resource.
FormType *FrmInitForm (UInt16 rscID)
-> rscID | Resource ID of the form. |
Returns a pointer to the form data structure.
When using debug ROMs, FrmInitForm displays an error message if the form has already been initialized.
This function does not affect the display (use FrmDrawForm to draw the form) nor make the form active (use FrmSetActiveForm to make it active).
For each initialized form, you must call FrmDeleteForm to release the form memory when you are done with the form. Alternatively, you can free the active form by calling FrmReturnToForm.
FrmDoDialog, FrmDeleteForm, FrmReturnToForm
Create a new form bitmap dynamically.
FormBitmapType *FrmNewBitmap (FormType **formPP, UInt16 ID, UInt16 rscID, Coord x, Coord y)
<-> formPP | Pointer to a pointer to the form in which the new bitmap is installed. This value is not a handle; that is, the old formPP value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the new formPP value returned by this function. |
-> ID | Symbolic ID of the bitmap, specified by the developer. By convention, this ID should match the resource ID (not mandatory). |
-> rscID | Numeric value identifying the resource that provides the bitmap. This value must be unique within the application scope. |
-> x | Horizontal coordinate of the upper-left corner of the bitmap's boundaries, relative to the window in which it appears. |
-> y | Vertical coordinate of the upper-left corner of the bitmap's boundaries, relative to the window in which it appears. |
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.
Implemented only if 3.0 New Feature Set is present.
Create a new form object dynamically.
FormType *FrmNewForm (UInt16 formID, const Char *titleStrP, Coord x, Coord y, Coord width, Coord height, Boolean modal, UInt16 defaultButton, UInt16 helpRscID, UInt16 menuRscID)
-> formID | Symbolic ID of the form, specified by the developer. By convention, this ID should match the resource ID (not mandatory). |
-> titleStrP | Pointer to a string that is the title of the form. |
-> x | Horizontal coordinate of the upper-left corner of the form's boundaries, relative to the window in which it appears. |
-> y | Vertical coordinate of the upper-left corner of the form's boundaries, relative to the window in which it appears. |
-> width | Width of the form, expressed in pixels. Valid values are 1 -160. |
-> height | Height of the form, expressed in pixels.Valid values are 1 -160. |
-> modal | true specifies that the form ignores pen events outside its boundaries. |
-> defaultButton | Symbolic ID of the button that provides the form's default action, specified by the developer. |
-> helpRscID | Symbolic ID of the resource that provides the form's online help, specified by the developer. Only modal dialogs can have help resources. |
-> menuRscID | Symbolic ID of the resource that provides the form's menus, specified by the developer. |
Returns a pointer to the new form object, or 0 if the call did not succeed. The most common cause of failure is lack of memory.
Implemented only if 3.0 New Feature Set is present.
FrmValidatePtr, WinValidateHandle, FrmRemoveObject
Create a new gadget dynamically and install it in the specified form.
FormGadgetType *FrmNewGadget (FormType **formPP, UInt16 id, Coord x, Coord y, Coord width, Coord height)
<-> formPP | Pointer to a pointer to the form in which the new gadget is installed. This value is not a handle; that is, the old formPP value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the new formPP value returned by this function. |
-> id | Symbolic ID of the gadget, specified by the developer. By convention, this ID should match the resource ID (not mandatory). |
-> x | Horizontal coordinate of the upper-left corner of the gadget's boundaries, relative to the window in which it appears. |
-> y | Vertical coordinate of the upper-left corner of the gadget's boundaries, relative to the window in which it appears. |
-> width | Width of the gadget, expressed in pixels. Valid values are 1 - 160. |
-> height | Height of the gadget, expressed in pixels.Valid values are 1 - 160. |
Returns a pointer to the new gadget object or 0 if the call did not succeed. The most common cause of failure is lack of memory.
A gadget is a custom user interface object. For more information, see "Gadget Resource".
Implemented only if 3.0 New Feature Set is present.
Create a new Graffiti shift indicator dynamically and install it in the specified form.
FrmGraffitiStateType *FrmNewGsi (FormType **formPP, Coord x, Coord y)
<-> formPP | Pointer to a pointer to the form in which the new Graffiti shift indicator is installed. This value is not a handle; that is, the old formPP value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the new formPP value returned by this function. |
-> x | Horizontal coordinate of the upper-left corner of the Graffiti shift indicator's boundaries, relative to the window in which it appears. |
-> y | Vertical coordinate of the upper-left corner of the Graffiti shift indicator's boundaries, relative to the window in which it appears. |
Returns a pointer to the new gadget object or 0 if the call did not succeed. The most common cause of failure is lack of memory.
In normal operation, the Graffiti shift indicator is drawn in the lower-right portion of the screen when the user enters the shift keystroke. You use this function if the Graffiti shift indicator needs to be drawn in a nonstandard location. For example, the form manager uses it to draw the shift indicator in a custom alert dialog that contains a text field (FrmCustomResponseAlert).
Implemented only if 3.5 New Feature Set is present.
Create a new label object dynamically and install it in the specified form.
FormLabelType *FrmNewLabel (FormType **formPP, UInt16 ID, const Char *textP, Coord x, Coord y, FontID font)
<-> formPP | Pointer to a pointer to the form in which the new label is installed. This value is not a handle; that is, the old formPP value is not necessarily valid after this function returns because the form may be moved in memory. In subsequent calls, always use the new formPP value returned by this function. |
-> ID | Symbolic ID of the label, specified by the developer. By convention, this ID should match the resource ID (not mandatory). |
-> textP | Pointer to a string that provides the label text. This string is copied into the label structure. |
-> x | Horizontal coordinate of the upper-left corner of the label's boundaries, relative to the window in which it appears. |
-> y | Vertical coordinate of the upper-left corner of the label's boundaries, relative to the window in which it appears. |
-> font | Font with which to draw the label text. |
Returns a pointer to the new label object or 0 if the call did not succeed. The most common cause of failure is lack of memory.
Implemented only if 3.0 New Feature Set is present.
CtlValidatePointer, FrmRemoveObject
Check if a coordinate is within the bounds of the form's title.
Boolean FrmPointInTitle (const FormType *formP, Coord x, Coord y)
-> formP | Pointer to the form object (FormType structure). |
-> x, y | Window-relative x and y coordinates. |
Returns true if the specified coordinate is in the form's title.
Implemented only if 2.0 New Feature Set is present.
Queues a frmLoadEvent and a frmOpenEvent for the specified form.
void FrmPopupForm (UInt16 formId)
-> formID | Resource ID of form to open. |
This routine differs from FrmGotoForm in that the current form is not closed. You can call FrmReturnToForm to close a form opened by FrmPopupForm.
Remove the specified object from the specified form.
Err FrmRemoveObject (FormType **formPP, UInt16 objIndex)
<-> formPP | Pointer to a pointer to the form from which this function removes an object. This value is not a handle; that is, the old formPP value is not necessarily valid after this function returns. In subsequent calls, always use the new formPP value returned by this function. |
-> objIndex | The object to remove, specified as an index into the list of objects installed in the form. You can use the FrmGetObjectIndex function to discover this value. |
You can use this function to remove any form object (a bitmap, control, list, and so on) and free the memory allocated to it within the form data structure. The data structures for most form objects are embedded within the form data structure memory chunk. This function frees that memory and moves the other objects, if necessary, to close up the memory "hole" and decrease the size of the form chunk.
Note that this function does not free memory outside the form data structure that may be allocated to an object, such as the memory allocated to the string in an editable field object.
Implemented only if 3.0 New Feature Set is present.
FrmNewBitmap, FrmNewForm, FrmNewGadget, FrmNewLabel, CtlNewControl, FldNewField, LstNewList
Macro that restores the active window and form state.
FrmRestoreActiveState (stateP)
-> stateP | A pointer to the FormActiveStateType structure that you passed to FrmSaveActiveState when you saved the state. |
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.
Implemented only if 3.0 New Feature Set is present.
Erase and delete the currently active form and make the specified form the active form.
void FrmReturnToForm (UInt16 formId)
-> formID | Resource ID of the form to return to. |
It is assumed that the form being returned to is already loaded into memory and initialized. Passing a form ID of 0 returns to the first form in the window list, which is the last form to be loaded.
FrmReturnToForm does not generate a frmCloseEvent when called from a modal form's event handler. It assumes that you have already handled cleaning up your form's variables since you are explicitly calling FrmReturnToForm.
Macro that saves the active window and form state.
<-> stateP | A pointer to a FormActiveStateType structure that is used to save the state. Pass the same pointer to FrmRestoreActiveState to restore the state. Treat the structure like a black box; that is, don't attempt to read it or write to it. |
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.
Implemented only if 3.0 New Feature Set is present.
Send a frmSaveEvent to all open forms.
None. |
Set the active form. All input (key and pen) is directed to the active form and all drawing occurs there.
void FrmSetActiveForm (FormType *formP)
-> formP | Pointer to the form object (FormType structure). |
A penDownEvent outside the form but within the display area is ignored.
In Palm OS releases earlier than 3.5, this function generated a winEnterEvent for the new form immediately following the winExitEvent for the old form. Starting in Palm OS 3.5, FrmSetActiveForm does not generate the winEnterEvent. The winEnterEvent does not occur until the newly active form is drawn.
Set the category label displayed on the title line of a form. If the form's visible attribute is set, redraw the label.
void FrmSetCategoryLabel (const FormType *formP, UInt16 objIndex, Char *newLabel)
-> formP | Pointer to the form object (FormType structure). |
-> objIndex | Index of an object in the form. You can obtain this by using FrmGetObjectIndex. |
-> newLabel | Pointer to the name of the new category. |
The pointer to the new label (newLabel) is saved in the object.
Set the selected control in a group of controls.
void FrmSetControlGroupSelection (const FormType *formP, UInt8 groupNum, UInt16 controlID)
-> formP | Pointer to the form object (FormType structure). |
-> groupNum | Control group number. |
-> controlID | ID of control to set. |
This function unsets all the other controls in the group. The display is updated.
Set the current value of a control. If the control is visible, it's redrawn.
void FrmSetControlValue (const FormType *formP, UInt16 objIndex, Int16 newValue)
-> formP | Pointer to the form object (FormType structure). |
-> objIndex | Index of the control in the form. You can obtain this by using FrmGetObjectIndex. |
-> newValue | New value to set for the control. For sliders, specify a value between the slider's minimum and maximum. For graphical controls, push buttons, or check boxes, specify 0 for off, nonzero for on. |
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.
Registers the event handler callback routine for the specified form.
void FrmSetEventHandler (FormType *formP, FormEventHandlerType *handler)
-> formP | Pointer to the form object (FormType structure). |
-> handler | Address of the form event handler function, FormEventHandler. |
FrmDispatchEvent calls this handler whenever it receives an event for a specific form.
FrmSetEventHandler must be called right after a form resource is loaded. The callback routine it registers is the mechanism for dispatching events to an application. The tutorial explains how to use callback routines.
Set the focus of a form to the specified object.
void FrmSetFocus (FormType *formP, UInt16 fieldIndex)
-> formP | Pointer to the form object (FormType structure). |
-> fieldIndex | Index of the object to get the focus in the form. You can obtain this by using FrmGetObjectIndex. You can pass the constant noFocus so that no object has the focus. |
You can set the focus to a field or table object. If the focus is set to a field object, this function turns on the insertion point in the field by calling FldGrabFocus internally.
Store a data value in the data field of the gadget object.
void FrmSetGadgetData (FormType *formP, UInt16 objIndex, const void *data)
-> formP | Pointer to the form object (FormType structure). |
-> objIndex | Index of an object in the form. You can obtain this by using FrmGetObjectIndex. |
-> data | Application-defined value. This value is stored into the data field of the gadget data structure (FormGadgetType). |
Gadget objects provide a way for an application to attach custom gadgetry to a form. Typically, the data field of a gadget object contains a pointer to the custom object's data structure.
FrmGetGadgetData, FrmSetGadgetHandler
Registers the gadget event handler callback routine for the specified gadget on the specified form.
void FrmSetGadgetHandler (FormType *formP, UInt16 objIndex, FormGadgetHandlerType *attrP)
-> formP | Pointer to the form object (FormType structure). |
-> objIndex | Index of a gadget object in the form. You can obtain this by using FrmGetObjectIndex. |
-> attrP | Address of the callback function. See FormGadgetHandler. |
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.
Implemented only if 3.5 New Feature Set is present.
FrmGetGadgetData, FrmSetGadgetData
Change a form's menu bar and make the new menu active.
void FrmSetMenu (FormType *formP, UInt16 menuRscID)
-> formP | Pointer to the form object (FormType structure). |
-> menuRscID | Resource ID of the menu. |
Implemented only if 2.0 New Feature Set is present.
Set the bounds or position of an object.
void FrmSetObjectBounds (FormType *formP, UInt16 objIndex, const RectangleType *bounds)
-> formP | Pointer to the form object (FormType structure). |
-> objIndex | Index of an object in the form. You can obtain this by using FrmGetObjectIndex. |
-> bounds | Window-relative bounds. For the following objects, this sets only the position of the top-left corner: label, bitmap, and Graffiti state indicator. |
Implemented only if 2.0 New Feature Set is present.
Set the position of an object.
void FrmSetObjectPosition (FormType *formP, UInt16 objIndex, Coord x, Coord y)
-> formP | Pointer to the form object (FormType structure). |
-> objIndex | Index of an object in the form. You can obtain this by using FrmGetObjectIndex. |
-> x | Window-relative horizontal coordinate. |
-> y | Window-relative vertical coordinate. |
FrmGetObjectPosition, FrmGetObjectBounds
Set the title of a form. If the form is visible, draw the new title.
void FrmSetTitle (FormType *formP, Char *newTitle)
-> formP | Pointer to the form object (FormType structure). |
-> newTitle | Pointer to the new title string. |
This function draws the title if the form is visible.
This function saves the pointer passed in newTitle; it does not make a copy. The value of newTitle must not be a pointer to a stack-based object.
Earlier versions of this function redrew the title without first erasing the old one. This problem was corrected in version 3.0 of Palm OS.
FrmGetTitle, FrmCopyTitle, FrmCopyLabel
Set a form object as usable. If the form is visible, draw the object.
void FrmShowObject (FormType *formP, UInt16 objIndex)
-> formP | Pointer to the form object (FormType structure). |
-> objIndex | Index of an object in the form. You can obtain this by using FrmGetObjectIndex. |
On versions of Palm OS prior to 3.5 this function doesn't affect lists or tables. On Palm OS 3.5 it operates correctly on lists but doesn't have any effect on tables. On Palm OS 4.0 it operates correctly on both lists and tables.
If 3.5 New Feature Set is present and the object is an extended gadget, this function calls the gadget's callback with formGadgetDrawCmd. See FormGadgetHandler.
Send a frmUpdateEvent to the specified form.
void FrmUpdateForm (UInt16 formId, UInt16 updateCode)
-> 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. |
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.
Visually update (show or hide) the field scroll arrow buttons.
void FrmUpdateScrollers (FormType *formP, UInt16 upIndex, UInt16 downIndex, Boolean scrollableUp, Boolean scrollableDown)
-> formP | Pointer to the form object (FormType structure). |
-> upIndex | Index of the up-scroller button. You can obtain this by using FrmGetObjectIndex. |
-> downIndex | Index of the down-scroller button. You can obtain this by using FrmGetObjectIndex. |
-> scrollableUp | Set to true to make the up scroll arrow active (shown), or false to hide it. |
-> scrollableDown | Set to true to make the down scroll arrow active (shown), or false to hide it. |
Return true if the specified pointer references a valid form.
Boolean FrmValidatePtr (const FormType *formP)
-> formP | Pointer to be tested. |
Returns true if the specified pointer is a non-NULL pointer to an object having a valid form structure.
This function is intended for debugging purposes only. Do not include it in released code.
To distinguish between a window and a form in released code, instead of using this function, look at the flag windowFlags.dialog in the WindowType structure. This flag is true if the window is a form.
Implemented only if 3.0 New Feature Set is present.
Return true if the form is visible (is drawn).
Boolean FrmVisible (const FormType *formP)
-> formP | Pointer to the form object (FormType structure). |
Returns true if the form is visible; false if it is not visible.
Callback function for FrmCustomResponseAlert.
Boolean FormCheckResponseFuncType (Int16 button, Char *attempt)
-> button | The ID of the button that the user tapped. |
-> attempt | The string that the user entered in the alert dialog. |
Return true if the dialog should be dismissed. Return false if the dialog should not be dismissed.
This function is called at these times during the FrmCustomResponseAlert routine:
At the beginning of FrmCustomResponseAlert, this function is called with a button ID of frmResponseCreate. This constant indicates that the dialog is about to be displayed, and your function should perform any necessary initialization. For example, on a Japanese system, a password dialog might need to disable the Japanese FEP. So it would call TsmSetFepMode(NULL, tsmFepModeOff) in this function.
When the user has tapped a button on the dialog. The function should process the attempt string. If the string is valid input, the function should return true. If not, it should return false to give the user a chance to re-enter the string.
At the end of FrmCustomResponseAlert, this function is called with a button ID of frmResponseQuit. This gives the callback a change to perform any cleanup, such as re-enabling the Japanese FEP.
Implemented only if 3.5 New Feature Set is present.
The event handler callback routine for a form.
Boolean FormEventHandlerType (EventType *eventP)
-> eventP | Pointer to the form event (FormType structure). |
Must return true if this routine handled the event, otherwise false.
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.
The event handler callback for an extended gadget.
Boolean (FormGadgetHandlerType) (struct FormGadgetType *gadgetP, UInt16 cmd, void *paramP)
-> gadgetP | Pointer to the gadget structure. See FormGadgetType. |
-> cmd | A constant that specifies what action the handler should take. This can be one of the following: |
formGadgetDeleteCmd | Sent by FrmDeleteForm to indicate that the gadget is being deleted and must clean up any memory it has allocated or perform other cleanup tasks. |
formGadgetDrawCmd | Sent by FrmDrawForm and FrmShowObject to indicate that the gadget must be drawn or redrawn. |
formGadgetEraseCmd | Sent by FrmHideObject to indicate that the gadget is going to be erased. FrmHideObject clears the visible and usable flags for you. If you return false, it also calls WinEraseRectangle to erase the gadget's bounds. |
formGadgetHandleEventCmd | Sent by FrmHandleEvent to indicate that a gadget event has been received. The paramP parameter contains the pointer to the EventType structure. |
-> paramP | NULL except if cmd is formGadgetHandleEventCmd. In that case, this parameter holds the pointer to the EventType structure containing the event. |
Return true if the event was handed successfully; false otherwise.
If this function performs any drawing in response to the formGadgetDrawCmd, it should set the gadget's visible attribute flag. (gadgetP->attr.visible = true). This flag indicates that the gadget appears on the screen. If you don't set the visible flag, the gadget won't be erased when FrmHideObject is called. (FrmHideObject immediately returns if the object's visible flag is false.)
Note that if the function receives the formGadgetEraseCmd, it may simply choose to perform any necessary cleanup and return false. If the function returns false, FrmHideObject erases the gadget's bounding rectangle. If the function returns true, it must erase the gadget area itself.
If this function receives a formGadgetHandleEventCmd, paramP points one of two events: frmGadgetEnterEvent or frmGadgetMiscEvent. The frmGadgetEnterEvent is passed when there is a penDownEvent within the gadget's bounds. This function should track the pen and perform any necessary highlighting. The frmGadgetMiscEvent is never sent by the system. Your application may choose to use it if at any point it needs to send data to the extended gadget. In this case, the event has one or both of these fields defined: selector, an unsigned integer, and dataP, a pointer to data.
Implemented only if 3.5 New Feature Set is present.
|