Programming User Interface Elements Continued

Consider the code: 
if (buttonPressed == 0)
  FrmGotoForm (MainForm);

handled = true;
A FrmGotoForm queues up the following events in the queue:

1) frmCloseEvent - this is to the current form which closes the current form.

2) frmLoadEvent

3) frmOpenEvent

2 & 3 are used to open the form that you want to display.

Question: When FrmGotoForm (MainForm); is executed, is handled = true; executed immediately following FrmGotoForm or skipped? Why?

To date, we have used FrmAlert, FrmCustomAlert, and FrmGotoForm calls in our applications. FrmAlert and FrmCustomAlert display modal dialogs and usually have enough controls to handle most situations. The question arrises, what if we need more controls that these calls allow? The answer is that we need to write our own more complicated Modal Dialog Box using FrmPopupForm which needs its own event-handler. Further, unlike FrmGotoForm, FrmPopupForm does not send a frmCloseEvent to the current form; therefore, when creating the modal dialog box, check both modal and save behind; otherwise, the logic is similar to a regular form. One last thing. A FrmReturnToForm (0); returns to the last form loaded which is the form that displayed your modal dialog box.

Programming Objects on Forms

Read the section on Programming Objects on Forms.

The Palm OS treats a number of UI objects as "controls." What's nice about this is that the system treats these controls in a consistent manner. Thus understanding a few of these objects gives us an understanding of most.

Controls can be broken down into the following objects:

There are some default event-handlers such as FrmHandleEvent which takes care of things such as inverting a button when pressed to adding events to the queue for which your application can respond. Other event-handlers of interest include: CtlHandleEvent, FldHandleEvent, LstHandleEvent, MenuHandleEvent, SclHandleEvent, and TblHandleEvent.

To date, we have seen example of a select event such as the user tapping on a button. Once an object is selected, a select event can be tested and used.

Some sample select events include:

There are also enter events for responding to say the tapping of an object before it is selected and there are exit events. Bottom line, we are dealing with event-driven programming so there are all kinds of events driving the execution of our program.

Many times, when responding to an event, we want to know the resource ID of the object involved. Table 9.1 on 224-5 gives a good summary of where to find the resouce ID associated with the given event.

Last lecture, we programmed fields. We will continue to program fields and add other UI elements to our bag of tricks.

For the next two lectures we will implement the following Validate screen.

Things to note:

  1. This validate screen needs to be completely filled out and correct before going to the Main Form.
  2. Implement the person's title using a selector trigger and list.
  3. The Date Purchased field is to have today's date initially and allow the user to change the date to any valid date. Let's go over the logic for the SelectDay API call.
  4. The Terms of Use and Accept buttons are push buttons. They work a little differently than regular buttons in that when selected, they are highlighted. Once the user lifts the stylus, you need to unselect the push button. Remember, the push button is a control.
  5. In terms of functionality for the Terms of Use push button, I want a simple help form to come up showing the string "Terms of Use" for now.
  6. In terms of functionality for the Accept button, for now, simply check for a serial number of 12345. An invalid serial number should bring up an alert form saying "Invalid Serial Number, Please try again"
Note: In the near future, we need a way of storing the validate information which is where the databases come in to play.

Lists and Pop-up lists

List complexity is usually defined in terms of static versus dynamic lists. Static lists are very straight forward and pretty easy to program while dynamic lists are more complicated to program.

A user tapping within a list queues up a lstSelectEvent when the tap is released. The API call LstGetSelection can be used to determine which list item the user selected. The function prototype is:

Int16 LstGetSelection (const ListType *listP);
LstGetSelection takes a pointer to a list and returns the number of the item selected starting with item # zero. If no item is selected, then the constant noListSelection is returned as defined in the Palm OS header file.

Should you want the actual list text, use LstGetSelectionText which has the following function prototype:

Char *LstGetSelectionText (const ListType *listP, Int16 itemNum);
So how might we incorporate this into a program? Let's look at the following code:

case ctlSelectEvent:
	if (eventP->data.ctlEnter.controlID == MainTitleSelTrigger)
	{
		pForm = FrmGetActiveForm();
		wIDList =  FrmGetObjectIndex (pForm, MainTitleList);
		pList = (ListPtr) FrmGetObjectPtr(pForm, wIDList);

		whichone = LstPopupList(pList);
			 	
		label = LstGetSelectionText (pList, whichone);
			 	
		if (label == NULL)
			label = defaultValue;
			 		
		ctl = GetObjectPtr(MainTitleSelTrigger);
		CtlSetLabel(ctl,label);

		handled = true;
	}

Help

There are a couple of ways to supply help to the user.

Method 1: Use a Modal form which enables the Help ID option. The Help ID option allows the programmer to put in the string ID for the help to be displayed. A help icon shows up in the upper right hand corner of the display.

Method 2: We can code some form object to automatically display a help string in a help form. This is what I want to do with the "Terms of Use" push button.

Logic for Method 2 might look like:

else if (eventP->data.ctlEnter.controlID == ValidateTermsOfUsePushButton)
{
	FrmHelp (ValidateString);
	ctl = GetObjectPtr(MainTermsOfUsePushButton);
	CtlSetValue(ctl, 0);
	handled = true;
	break;
}