MorePalmOS
A development library for developing Palm OS applications
C: / Documents and Settings / steve / My Documents / cvsroot / morepalmos / morepalmos / Public

MoreForm.h File Reference

Functions for forms. More...

#include "MorePrefix.h"
#include "MoreTypes.h"
#include <Form.h>

Include dependency graph for MoreForm.h:

Include dependency graph

This graph shows which files directly or indirectly include this file:

Included by dependency graph

Go to the source code of this file.


Defines

#define MFrmSetFocusByIdx(formP, idx)   FrmSetFocus( formP, idx )

Functions

void MFrmHandleAppOpenFormEvt (ResourceID_t formID, FormEventHandlerType *handler)
 Call in response to a form open event to do initial setup of the form, such as loading it into memory and setting its event callback.
FrmObjectID_t MFrmHandleModalForm (ResourceID_t formID, FormEventHandlerType *handler)
 Call to display a modal dialog and wait for a response.
FrmObject_t * MFrmGetObjPtrByID (const FormType *formP, FrmObjectID_t id)
 Returns the pointer of an object specified by id.
FrmObject_t * MFrmGetObjPtrByIdx (const FormType *formP, FrmObjectIdx_t idx)
 Returns the pointer of an object specified by index.
FormObjectKind MFrmGetObjTypeByID (const FormType *formP, FrmObjectID_t id)
 Returns the kind of a form object specified by id.
FormObjectKind MFrmGetObjTypeByIdx (const FormType *formP, FrmObjectIdx_t idx)
 Returns the kind of a form object specified by index.
FormObjectKind MFrmGetObjTypeByPtr (const FormType *formP, FrmObject_t *objectP)
 Returns the kind of a form object specified by pointer.
FrmObject_t * MFrmGetObjPtrOfTypeByID (const FormType *formP, FrmObjectID_t id, FormObjectKind kind)
 Returns the kind of a form object specified by id if it is of the specified kind.
FrmObject_t * MFrmGetObjPtrOfTypeByIdx (const FormType *formP, FrmObjectIdx_t idx, FormObjectKind kind)
 Returns the kind of a form object specified by index if it is of the specified kind.
FrmObject_t * MFrmGetObjPtrOfTypeByPtr (const FormType *formP, FrmObject_t *ptr, FormObjectKind kind)
 Returns the kind of a form object specified by pointer if it is of the specified kind.
void MFrmSetObjVisibleByID (FormType *formP, FrmObjectID_t id, Boolean visible)
 Hides an object by form and object id.
void MFrmSetObjVisibleByIdx (FormType *formP, FrmObjectIdx_t idx, Boolean visible)
 Hides an object by form and object index.
void MFrmSetObjVisibleByPtr (FormType *formP, FrmObject_t *objectP, Boolean visible)
 Hides an object by form and object pointer.
void MFrmReload ()
 Forces the current form to reload.
void MFrmSetFocusByID (FormType *formP, FrmObjectID_t objectId)
 Sets focus to a field based on object id.
void MFrmSetFocusByPtr (FormType *formP, FrmObject_t *objectP)
 Sets focus to a field based on object pointer.
void MFrmNudgeObjXYByID (FormType *formP, FrmObjectID_t id, Coord deltaX, Coord deltaY, Boolean redraw)
 Relative reposition of form object by id.
void MFrmNudgeObjXYByIdx (FormType *formP, FrmObjectIdx_t idx, Coord deltaX, Coord deltaY, Boolean redraw)
 Relative reposition of form object by index.
void MFrmNudgeObjXYByPtr (FormType *formP, FrmObject_t *objectP, Coord deltaX, Coord deltaY, Boolean redraw)
 Relative reposition of form object by pointer.

Detailed Description

Functions for forms.

MoreForm provides functions for working with Palm OS forms in ways that the Palm OS SDK does not directly support. For instance, it includes a function for retrieving a form object by id, instead of by index, and for moving an object by a specified distance instead of to specific coordinates.

Definition in file MoreForm.h.

Define Documentation

#define MFrmSetFocusByIdx (  formP,
idx   )     FrmSetFocus( formP, idx )
 

Definition at line 191 of file MoreForm.h.

Function Documentation

FrmObject_t* MFrmGetObjPtrByID (  const FormType *  formP,
FrmObjectID_t  id
) 
 

Returns the pointer of an object specified by id.

Virtually every Palm OS application has some version of this function. Applications tend to reference form objects by ID, but many Palm OS calls require object pointers.

Notes:

  • Returns NULL if the object couldn't be found in a release build. How (or if) you deal with that condition is entirely up to you.

Definition at line 53 of file MoreForm.c.

00054 {
00055         _validate_const_form_ptr( formP );
00056         return FrmGetObjectPtr( formP, _validate_object_idx( formP,
00057                                 FrmGetObjectIndex( formP, id ) ) );
00058 }

FrmObject_t* MFrmGetObjPtrByIdx (  const FormType *  formP,
FrmObjectIdx_t  idx
) 
 

Returns the pointer of an object specified by index.

Given a form pointer and a object index, returns the pointer corresponding to that object.

Notes:

  • Returns NULL if the object couldn't be found in a release build. How (or if) you deal with that condition is entirely up to you.

Definition at line 60 of file MoreForm.c.

00061 {
00062         _validate_const_form_ptr( formP );
00063         return FrmGetObjectPtr( formP, idx );
00064 }

FrmObject_t* MFrmGetObjPtrOfTypeByID (  const FormType *  formP,
FrmObjectID_t  id,
FormObjectKind  kind
) 
 

Returns the kind of a form object specified by id if it is of the specified kind.

If the object exists but is of the wrong kind, NULL is returned.

Definition at line 68 of file MoreForm.c.

00070 {
00071         FrmObjectIdx_t idx = FrmGetObjectIndex( formP, _validate_object_id( formP, id ) );
00072         _validate_object_idx( formP, idx );
00073         if ( ( idx != frmInvalidObjectId ) && ( FrmGetObjectType( formP, idx ) == kind ) )
00074                 return FrmGetObjectPtr( formP, idx );
00075         else
00076                 return NULL;
00077 }

FrmObject_t* MFrmGetObjPtrOfTypeByIdx (  const FormType *  formP,
FrmObjectIdx_t  idx,
FormObjectKind  kind
) 
 

Returns the kind of a form object specified by index if it is of the specified kind.

If the object exists but is of the wrong kind, NULL is returned.

Definition at line 79 of file MoreForm.c.

00081 {
00082         _validate_object_idx( formP, idx );
00083         if ( ( idx != frmInvalidObjectId ) && ( FrmGetObjectType( formP, idx ) == kind ) )
00084                 return FrmGetObjectPtr( formP, idx );
00085         else
00086                 return NULL;
00087 }

FrmObject_t* MFrmGetObjPtrOfTypeByPtr (  const FormType *  formP,
FrmObject_t *  ptr,
FormObjectKind  kind
) 
 

Returns the kind of a form object specified by pointer if it is of the specified kind.

If the object exists but is of the wrong kind, NULL is returned.

Definition at line 89 of file MoreForm.c.

00091 {
00092         FrmObjectIdx_t idx = FrmGetObjectIndexFromPtr( formP, _validate_object_ptr( ptr ) );
00093         _validate_object_idx( formP, idx );
00094         if ( ( idx != frmInvalidObjectId ) && ( FrmGetObjectType( formP, idx ) == kind ) )
00095                 return FrmGetObjectPtr( formP, idx );
00096         else
00097                 return NULL;
00098 }

FormObjectKind MFrmGetObjTypeByID (  const FormType *  formP,
FrmObjectID_t  id
) 
 

Returns the kind of a form object specified by id.

Definition at line 102 of file MoreForm.c.

00103 {
00104         _validate_object_id( formP, id );
00105         return FrmGetObjectType( formP, _validate_object_idx( formP,
00106                                         FrmGetObjectIndex( formP, id ) ) );
00107 }

FormObjectKind MFrmGetObjTypeByIdx (  const FormType *  formP,
FrmObjectIdx_t  idx
) 
 

Returns the kind of a form object specified by index.

Definition at line 109 of file MoreForm.c.

00110 {
00111         _validate_object_idx( formP, idx );
00112         return FrmGetObjectType( formP, idx );
00113 }

FormObjectKind MFrmGetObjTypeByPtr (  const FormType *  formP,
FrmObject_t *  objectP
) 
 

Returns the kind of a form object specified by pointer.

Definition at line 115 of file MoreForm.c.

00116 {
00117         return FrmGetObjectType( formP, FrmGetObjectIndexFromPtr( formP, objectP ) );
00118 }

void MFrmHandleAppOpenFormEvt (  ResourceID_t  formID,
FormEventHandlerType *  handler
) 
 

Call in response to a form open event to do initial setup of the form, such as loading it into memory and setting its event callback.

Frequently, applications have a long switch statement where they pick an event handler out of the list, then do this initialization at the bottom of the switch. By putting this in a procedure you call instead, you can more easily pass through events refering to forms that aren't yours.

Definition at line 24 of file MoreForm.c.

00026 {
00027         FormType* formP = FrmInitForm( formID );
00028         FrmSetActiveForm( formP );              
00029         FrmSetEventHandler( formP, handler );
00030 }

FrmObjectID_t MFrmHandleModalForm (  ResourceID_t  formID,
FormEventHandlerType *  handler
) 
 

Call to display a modal dialog and wait for a response.

Definition at line 34 of file MoreForm.c.

00036 {
00037         FormType* previousFormP = FrmGetActiveForm( );
00038         FormType* dialogP = FrmInitForm( formID );
00039         UInt16 button;
00040         FrmSetActiveForm( dialogP );
00041         if ( handler )
00042         {
00043                 FrmSetEventHandler( dialogP, handler );
00044         };
00045         FrmPopupForm( formID );
00046         button = FrmDoDialog( dialogP );
00047         FrmReturnToForm( previousFormP ? FrmGetFormId( previousFormP ) : 0 );
00048         return button;
00049 }

void MFrmNudgeObjXYByID (  FormType *  formP,
FrmObjectID_t  id,
Coord  deltaX,
Coord  deltaY,
Boolean  redraw
) 
 

Relative reposition of form object by id.

Moves a form object (specified by id) the distance specified. Optionally forces redraw of the object.

Definition at line 173 of file MoreForm.c.

00175 {
00176         _validate_object_id( formP, id );
00177         MFrmNudgeObjXYByIdx( formP, FrmGetObjectIndex( formP, id ),
00178                         deltaX, deltaY, redraw );
00179 }

void MFrmNudgeObjXYByIdx (  FormType *  formP,
FrmObjectIdx_t  idx,
Coord  deltaX,
Coord  deltaY,
Boolean  redraw
) 
 

Relative reposition of form object by index.

Moves a form object (specified by index) the distance specified. Optionally forces redraw of the object.

Definition at line 181 of file MoreForm.c.

00183 {
00184         Coord x, y;
00185         _validate_object_idx( formP, idx );
00186 
00187         FrmGetObjectPosition( formP, idx, &x, &y );
00188 
00189         if ( redraw )
00190         {
00191                 FrmHideObject( formP, idx );
00192         }
00193 
00194         FrmSetObjectPosition( formP, idx, x + deltaX, y + deltaY );
00195 
00196         if ( redraw )
00197         {
00198                 FrmShowObject( formP, idx );
00199         }
00200 }

void MFrmNudgeObjXYByPtr (  FormType *  formP,
FrmObject_t *  objectP,
Coord  deltaX,
Coord  deltaY,
Boolean  redraw
) 
 

Relative reposition of form object by pointer.

Moves a form object (specified by pointer) the distance specified. Optionally forces redraw of the object.

Definition at line 202 of file MoreForm.c.

00204 {
00205         _validate_object_ptr( objectP );
00206         MFrmNudgeObjXYByIdx( formP, FrmGetObjectIndexFromPtr( formP, objectP ),
00207                         deltaX, deltaY, redraw );
00208 }

void MFrmReload (   ) 
 

Forces the current form to reload.

Causes the current form to be reloaded, including all events for the form. Do not use this with dialogs!

Definition at line 151 of file MoreForm.c.

00152 {
00153         FrmGotoForm( FrmGetActiveFormID( ) );
00154 }

void MFrmSetFocusByID (  FormType *  formP,
FrmObjectID_t  objectId
) 
 

Sets focus to a field based on object id.

A convenience function; FrmSetFocus requires an object index, but often you want to specify it with an id instead.

Definition at line 158 of file MoreForm.c.

00159 {
00160         _validate_object_id( formP, objectId );
00161         FrmSetFocus( formP, FrmGetObjectIndex( formP, objectId ) );
00162 }

void MFrmSetFocusByPtr (  FormType *  formP,
FrmObject_t *  objectP
) 
 

Sets focus to a field based on object pointer.

A convenience function; FrmSetFocus requires an object index, but often you want to specify it with a pointer instead.

Definition at line 164 of file MoreForm.c.

00165 {
00166         _validate_form_ptr( formP );
00167         _validate_object_ptr( objectP );
00168         FrmSetFocus( formP, FrmGetObjectIndexFromPtr( formP, objectP ) );
00169 }

void MFrmSetObjVisibleByID (  FormType *  formP,
FrmObjectID_t  id,
Boolean  visible
) 
 

Hides an object by form and object id.

Shows or hides an object based on its form, object id and a visibility flag.

Applications usually reference form objects by ID, but FrmShowObject( ) and FrmHideObject( ) only operate on object indexes. Also, it is often inconvenient to call a different function depending on whether or not you want to show or hide an object.

Limitations:

  • Behaviour on different versions of Palm OS varies:
    • Prior to Palm OS 3.5, did not work on lists or tables.
    • For Palm OS 3.5.x, worked on lists but not tables.
    • For Palm OS 4.0 and later, works on both tables and lists.

Definition at line 122 of file MoreForm.c.

00124 {
00125         _validate_object_id( formP, id );
00126 
00127         MFrmSetObjVisibleByIdx( formP, FrmGetObjectIndex( formP, id ), visible );
00128 }

void MFrmSetObjVisibleByIdx (  FormType *  formP,
FrmObjectIdx_t  idx,
Boolean  visible
) 
 

Hides an object by form and object index.

Shows or hides an object based on its form, object index and a visibility flag.

It is often inconvenient to call a different function depending on whether or not you want to show or hide an object. In those situations, MFrmSetObjVisibleByIdx lets you specify the new visibility with a Boolean instead of two different functions.

Limitations:

  • Behaviour on different versions of Palm OS varies:
    • Prior to Palm OS 3.5, did not work on lists or tables.
    • For Palm OS 3.5.x, worked on lists but not tables.
    • For Palm OS 4.0 and later, works on both tables and lists.

Definition at line 130 of file MoreForm.c.

00132 {
00133         _validate_object_idx( formP, idx );
00134         if ( visible )
00135                 FrmShowObject( formP, idx );
00136         else
00137                 FrmHideObject( formP, idx );
00138 }

void MFrmSetObjVisibleByPtr (  FormType *  formP,
FrmObject_t *  objectP,
Boolean  visible
) 
 

Hides an object by form and object pointer.

Shows or hides an object based on its form, object pointer and a visibility flag.

Applications usually reference form objects by ID, or cache their pointer. However, FrmShowObject( ) and FrmHideObject( ) only work with object indexes. Also, it is often inconvenient to call a different function depending on whether or not you want to show or hide an object. MFrmSetObjVisibleByIdx lets you refer to the object using a pointer, and specify the new visibility with a Boolean instead of two different functions.

Limitations:

  • Behaviour on different versions of Palm OS varies:
    • Prior to Palm OS 3.5, did not work on lists or tables.
    • For Palm OS 3.5.x, worked on lists but not tables.
    • For Palm OS 4.0 and later, works on both tables and lists.

Definition at line 140 of file MoreForm.c.

00142 {
00143         _validate_form_ptr( formP );
00144         _validate_object_ptr( objectP );
00145         MFrmSetObjVisibleByIdx( formP, FrmGetObjectIndexFromPtr( formP, objectP ),
00146                         visible );
00147 }

SourceForge.net Logo

Copyright © 2004 Steven Fisher