Documentation  |   Table of Contents   |  < Previous   |  Next >  

49    Form.h

Porting Applications to Palm OS® Cobalt

Exploring Palm OS®

The Form APIs have undergone a general cleanup. This involved the removal of unused declarations and the hiding of structure contents that developers had previously been warned not to rely on.

In order to deal with the fact that Palm OS Cobalt doesn't support a resource search chain, a number of functions now take an additional parameter through which you explicitly identify the resource database that contains a needed resource.

Deleted APIs ^TOP^

Table 49.1  Deleted functions

Deleted API

Use instead

FrmActiveState()

Nothing. This function was documented as "System Use Only."

FrmAddSpaceForObject()

Nothing. This function was documented as "System Use Only."

FrmGetDIAPolicyAttr()

Nothing; your application now controls the state of the input area directly, so this function is no longer needed. See Exploring Palm OS: Input Services for more information on controlling the input area.

FrmGetUserModifiedState()

Nothing. This function was documented as "System Use Only."

FrmSetDIAPolicyAttr()

PINSetInputAreaState(). See Exploring Palm OS: Input Services for more information on controlling the input area.

FrmSetNotUserModified()

Nothing. This function was documented as "System Use Only."

Table 49.2  Deleted macros

Deleted API

Use instead

FrmRestoreActiveState()

Nothing. This macro simply called a function that was documented as "System Use Only."

FrmSaveActiveState()

Nothing. This macro simply called a function that was documented as "System Use Only."

Table 49.3  Deleted structures 

Deleted API

Use instead

FormAttrType

Nothing. This structure was only needed by the FormType structure, the internals of which are now private. Applications should not have been accessing this structure directly.

FormFrameType

Nothing. This structure was defined but not used by any of the APIs exposed in the last pre-Palm OS Cobalt SDK.

FormLineType

Nothing. This structure was defined but not used by any of the APIs exposed in the last pre-Palm OS Cobalt SDK.

FormObjAttrType

Nothing. This structure was only used by structures who's contents are no longer publicly exposed. Applications should not have been accessing this structure directly.

FormObjectType

Nothing. This structure was defined but only used by FormObjListType, which was not used by any of the APIs exposed in the last pre-Palm OS Cobalt SDK.

FormObjListType

Nothing. This structure was defined but not used by any of the APIs exposed in the last pre-Palm OS Cobalt SDK.

FormPopupType

Nothing. This structure was defined but only used by FormObjectType, which was not used by any of the APIs exposed in the last pre-Palm OS Cobalt SDK.

FormRectangleType

Nothing. This structure was defined but not used by any of the APIs exposed in the last pre-Palm OS Cobalt SDK.

FormTitleType

Nothing. This structure was defined but only used by FormObjectType, which was not used by any of the APIs exposed in the last pre-Palm OS Cobalt SDK.

Table 49.4  Deleted #defines

Deleted API

Use instead

FORM_GADGET_TYPE_IN_CALLBACK_DEFINED

Nothing. In Palm OS Cobalt the FormGadgetTypeInCallback structure is always defined.

frmDIAPolicyCustom

Nothing; your application now controls the state of the input area directly, so this #define is no longer needed. See Exploring Palm OS: Input Services for more information on controlling the input area.

frmDIAPolicyStayOpen

Nothing; your application now controls the state of the input area directly, so this #define is no longer needed. See Exploring Palm OS: Input Services for more information on controlling the input area.

Table 49.5  Deleted enumerated types

Deleted API

Use instead

AlertType

Formerly an enum, this is now a typedef that takes one of the values defined by the alertTypes enum.

FormObjectKind

Formerly an enum, this is now a typedef that takes one of the values defined by the formObjects enum.

Modified APIs ^TOP^

Table 49.6  Modified functions 

Modified API

Description of change

uint16_t FrmAlert (DmOpenRef, uint16_t)

Now contains an additional parameter through which you explicitly identify the resource database that contains the alert resource.

uint16_t FrmCustomAlert (DmOpenRef, uint16_t, const char *, const char *, const char *)

Now contains an additional parameter through which you explicitly identify the resource database that contains the alert resource.

uint16_t FrmCustomResponseAlert (DmOpenRef, uint16_t, const char *, const char *, const char *, char *, int16_t, FormCheckResponseFuncPtr)

Now contains an additional parameter through which you explicitly identify the resource database that contains the alert resource.

void FrmGotoForm (DmOpenRef, uint16_t)

Now contains an additional parameter through which you explicitly identify the resource database that contains the form to be displayed.

void FrmHelp (DmOpenRef, uint16_t)

Now contains an additional parameter through which you explicitly identify the resource database that contains the help message string.

FormType *FrmInitForm (DmOpenRef, uint16_t)

Now contains an additional parameter through which you explicitly identify the resource database that contains the form.

FormBitmapType *FrmNewBitmap (FormType **formPP, DmOpenRef, uint16_t, Coord, Coord)

You no longer supply a symbolic ID for the bitmap. Also, there is now an additional parameter through which you explicitly identify the resource database that contains the bitmap.

FormType *FrmNewForm (uint16_t, const char *, Coord, Coord, Coord, Coord, Boolean, uint16_t, DmOpenRef, uint16_t, DmOpenRef, uint16_t)

Now contains two additional parameters through which you explicitly identify the resource databases that contain the form's online help and menus.

void FrmPopupForm (DmOpenRef, uint16_t)

Now contains an additional parameter through which you explicitly identify the resource database that contains the form to be opened.

void FrmSetMenu (FormType *, DmOpenRef, uint16_t)

Now contains an additional parameter through which you explicitly identify the resource database that contains the menu.

Table 49.7  Modified structures 

Modified API

Description of change

AlertTemplateType

The internals of this structure are now completely private.

FormActiveStateType

This structure has increased in size. Note that it remains, as it has always been, abstract; applications shouldn't ever try to access this structure's contents directly.

FormBitmapType

The internals of this structure are now completely private.

FormGadgetType

The internals of this structure are now completely private.

FormLabelType

The internals of this structure are now completely private.

FormType

The internals of this structure are now completely private.

FrmGraffitiStateType

The internals of this structure are now completely private.

Table 49.8  Modified #defines

Modified API

Description of change

#define noFocus (frmInvalidObjectId)

This #define is effectively unchanged, but note that it previously was defined as a constant value, and now its value is dependent on the value of frmInvalidObjectId.

Unchanged APIs ^TOP^

Table 49.9  Unchanged functions 

FrmCloseAllForms()

FrmCopyLabel()

FrmCopyTitle()

FrmDeleteForm()

FrmDispatchEvent()

FrmDoDialog()

FrmDrawForm()

FrmEraseForm()

FrmGetActiveField()

FrmGetActiveForm()

FrmGetActiveFormID()

FrmGetControlGroupSelection()

FrmGetControlValue()

FrmGetFirstForm()

FrmGetFocus()

FrmGetFormBounds()

FrmGetFormId()

FrmGetFormPtr()

FrmGetGadgetData()

FrmGetLabel()

FrmGetNumberOfObjects()

FrmGetObjectBounds()

FrmGetObjectId()

FrmGetObjectIndex()

FrmGetObjectIndexFromPtr()

FrmGetObjectPosition()

FrmGetObjectPtr()

FrmGetObjectType()

FrmGetTitle()

FrmGetWindowHandle()

FrmHandleEvent()

FrmHideObject()

FrmNewGadget()

FrmNewGsi()

FrmNewLabel()

FrmPointInTitle()

FrmRemoveObject()

FrmReturnToForm()

FrmSaveAllForms()

FrmSetActiveForm()

FrmSetCategoryLabel()

FrmSetControlGroupSelection()

FrmSetControlValue()

FrmSetEventHandler()

FrmSetFocus()

FrmSetGadgetData()

FrmSetGadgetHandler()

FrmSetObjectBounds()

FrmSetObjectPosition()

FrmSetTitle()

FrmShowObject()

FrmUpdateForm()

FrmUpdateScrollers()

FrmValidatePtr()

FrmVisible()

Table 49.10  Unchanged macros

ECFrmValidatePtr()

Table 49.11  Unchanged structures

FormGadgetAttrType

FormGadgetTypeInCallback

Table 49.12  Unchanged types

FormCheckResponseFuncPtr

FormEventHandlerPtr

FormPtr

Table 49.13  Unchanged #defines

formGadgetDeleteCmd

formGadgetDrawCmd

formGadgetEraseCmd

formGadgetHandleEventCmd

frmInvalidObjectId

frmNoSelectedControl

frmRedrawUpdateCode

frmResponseCreate

frmResponseQuit

Table 49.14  Unchanged enumerated types

alertTypes

formObjects

Table 49.15  Unchanged application-defined functions

FormCheckResponseFuncType()

FormEventHandlerType()

FormGadgetHandlerType()