Palm OS gui Wrapper Class

The gui wrapper class allows for quicker development of Palm OS programs by taking care of the nitty gritty details of setting up and using a graphical interface on Palm OS. The idea was to create a set of classes that would allow a programmer to set up their resources in a program like PilRC and then simply declare objects for each resource along with an event handler for that object (if it handles events). The object itself filters out events that it shouldn't handle and runs the user defined event handler. As an added benefit, the gui class can remember the objects last state. For instance, textfields information is stored in persistent memory so the system shuts off, or is reset, the user can more easily continue their process.

Up to this point, the gui class contains the following sub-classes: a form class, a dialog class, and a frmobject class. The frmobject class contains buttons, popuplists, menuitems, and textfields as sub-classes.

gui class

Static methods: The gui class is the parent class of all gui objects in this scheme. It contains a number of useful static methods.

static Boolean init(int AppID) – this routine initializes the gui static variables. It also creates or opens the guiDB. The guiDB is a database that stores the gui objects last state, such as a textfield's text.

static void MainEventLoop() - This replaced the main programs main event loop. It basically finds the current form, and asks that form to call each of its associated object's EventHandlerWrapper routine. The EventHandlerWrapper routine filters out inappropriate events for that object and runs the objects EventHandler routine.

static void setEventWait(Int32 wait) – Sets the wait time for an event. Use the evtWaitForever constant if you want to wait indefinitely for the next event. Setting a value here will cause a nilevent to be processed at least every "wait" number of ticks.

static Boolean flush() - closes the gui database. This is automatically called when an application stop event is encountered.

static DmOpenRef getDB() - returns a reference the the guiDB.

Public Methods: The following methods are inherited by all derived classes.

UInt16 getID() - This simply returns the reference ID of the resource associated with this gui object. All instantiated gui objects have an associated reference ID that is the ID of the resource.

virtual UInt16 setID(UInt16 refID) – Use this method to set the resource ID. This is usually called by the constructor for the object.

virtual UInt16 getFormID() - This returns the reference id of the form associated with the object.

virtual void setFormID(UInt16 ID) – Sets the form ID that this object is associated with. This routine is usually called by the forms setActiveForm method to initialize the object. There are certain things that can only be done once the form is in memory, such as drawing a textfield's contents. Overriding gui object methods usually put their code here to initialize the object after the form is in memory.

virtual short getType() - Returns the type of the object. The type is an enumeration that is used internally in the gui class. This method should generally not be called outside of the gui class.

virtual void setType(short Type) – Sets the type of the gui object. The type is an enumeration that is used internally in the gui class. This method should generally not be called outside of the gui class.

virtual FormEventHandlerPtr getEventHandler() - Returns a pointer to the objects event handler function.

virtual void setEventHandler(FormEventHandlerPtr handler) – This routine associates a static function with an object as its event handler.

virtual Boolean eventHandlerWrapper(EventPtr event) – This routine is overridden by each gui type to filter out events that are not approprate for that object.

virtual void cleanup() - This is a general cleanup routine. Right now it just makes sure the gui resource database is closed. It should be called before an application quits if gui::init() has been called.

form Class

Derived from the gui class.

Static Methods: There are a number of static methods that are declared for manipulating forms.

static void init() - This initializes the static variables. It should be called prior to using forms.

static Boolean allEvents(EventPtr event) – Checks to see if the current form is in memory and if so, passes the event to each of the form's object's event handler methods.

static Boolean setActiveForm(form *aform) – Sets the active form. This brings the form into memory, sets the forms event handler and runs each of the form's object's setFormID methods.

static void flush() - Runs the cleanup method of each of the form's objects.

static form *getCurrentForm() - Returns a pointer to the currently active form.

static form *getFormByID(UInt16 ID) – Returns a pointer to the form with the supplied resource ID.

static guiPtr getbuttonByID(UInt16 ID) – returns a pointer to the button with the supplied resource ID. Make sure you cast this pointer to a button.

static guiPtr getlistByID(UInt16 ID) – returns a pointer to the list with the supplied resource ID. Make sure you cast this pointer to a list

static guiPtr gettextfieldByID(UInt16 ID) – returns a pointer to the textfield with the supplied resource ID. Make sure you cast this pointer to a textfield.

static guiPtr getmenuitemByID(UInt16 ID) – returns a pointer to the menuitem with the supplied resource ID. Make sure you cast this pointer to a menuitem.

static guiPtr getdialogByID(UInt16 ID) – returns a pointer to the dialog with the supplied resource ID. Make sure you cast this pointer to a dialog.

Public Methods:

UInt16 setID(UInt16 refID) – Sets the resource ID of the form. Also sets a reference to the form in the gui static class so that all forms can be searched.

guiPtr getobjectByID(short Type, UInt16 refID) – returns a guiptr to the object of type Type and resource ID refID if it is on this form. Use one of the static methods which set the type for you to find a gui object instead of this one.

void setFormID(UInt16 ID) – Sets the form ID by calling setFormID on each gui object that was added to this form.

Boolean eventHandlerWrapper(EventPtr event) – Filters out events not appropriate for the form from getting to the froms event handler. Allows frmGotoEvent, frmCloseEvent, frmCloseEvent, and nilEvent to be passed to the forms eventhandler.

void cleanup() - calls the cleanup routines of each of the forms objects.

void add(guiPtr g) – associates a gui object with a form. This must be done so the form's event handler can call the event handler function of each of its constituent objects.

frmobject Class

Derived from the gui class.

Public Methods:

virtual UInt16 getFormID() - Gets the id of the form that this object is associated with.

virtual void setFormID(UInt16 ID) – Sets the ID of the form that this object is associated with. This gets called automatically by form::setActiveForm().

textfield Class

Derived from the frmobject class.

Public Methods:

textfield(int ID) – Instantiates a textfield associated with resource ID.

void setFormID(UInt16 ID) – Tells this object which form it is associated with. Also associates the textfield with a database record in the guiDB. Warning, this must not be run before the form has been brought into memory. Let form::setActiveForm call it instead of calling it directly.

void cleanup() - Unlocks the textfield's database allocation. The textfield stores its data in persistent memory so it can be called upon across program runs.

void setText(char *newtext) – Sets the text to be displayed in the textfield. Also calls on the OS to redraw the field.

int textLength() - Retreives the number of bytes of the text in the textfield.

void getText(char *dst) – Copy the textfield's text into the character array at dst. This routine does not do any memory allocation so make sure there is enough room at dst.

control Class

Derived from the frmobject class.

Public Methods:

virtual Boolean eventHandlerWrapper(EventPtr event) – Filters out events other than a ctlSelectEvent.

button Class

Derived from the control class.

Public Methods:

button(int ID) – Instantiats a button object associated with resource ID.

menuitem Class

Derived from the frmobject class.

Public Methods:

menuitem(int ID) – Instantiates a menu object associated with resource ID.

virtual Boolean eventHandlerWrapper(EventPtr event) – Filters out events other than a menuEvent.

dialog Class

Derived from the gui class.

Public Methods:

dialog(int ID) - Instantiates a dialog object.

UInt16 getAnswer() - Returns the index of the button that was last pressed on this dialog.

void show() - Brings up the dialog on the screen.

popuplist Class

Derived from the frmobject class. Is a dynamic popup list.

Public Methods:

popuplist(UInt16 popID, UInt16 listID) – Instantiates a popuplist. The popID is the resource ID of the popup trigger, the listID is the ID of its associated list.

void appendItem(char *newitem) – Adds an item to the end of the popup list.

void setSelection(int index) – Sets the currently selected item in the list and changes the popup trigger's label to match its text.

UInt16 getSelected() - Returns the index of the currently selected item.

char *getSelectionText(int index) – Returns a pointer to the String that is stored at index. Be careful not to change the string returned.