1. Introduction to Systems Programming (CS 0449) PalmOS Events Handling Events OS–AppEventLoop() – Event Handlers

2. Palm OS - Handling Events UInt32 PilotMain (UInt16 cmd, MemPtr cmdPBP, UInt16 launchFlags) { //This function is the starting point for every palm program Error; switch (cmd) //cmd is the launch code for your program there are many launch { //codes that might be be sent to your program for different // reasons but here we will only cover one. case sysAppLaunchCmdNormalLaunch: //this is the launch code for a normal start error = AppStart(); //this function currently just returns that there is no error //but in other cases it might be used to initialize or retrieve data //if (error) this is just a little statement return error; //saying if something went wrong exit the program with //the reason FrmGotoForm(MainForm); //this puts an event in the event queue that tells it to open AppEventLoop(); //This function is a continuous loop that will direct events in //the event queue to the right event handler for your program AppStop(); //all this function does right now is close all the forms but in //other cases it might be used to do some cleanup for your program break; default: break; } return errNone; }

3. Palm OS - Handling Events PilotMain( ) AppStart ( ) AppEventLoop ( ) AppStop ( ) Event Queue Retrieve from AppLaunchCodeCmd AddRecord DisplayAlarm Find Goto NormalLaunch SystemReset Launch Codes

4. Palm OS – Processing AppEventLoop() Event Queue Event Event Loop OS EvtGetEvent

5. Palm OS–AppEventLoop() – Event Handlers Event Loop SysHandleEvent MenuHandleEvent AppHandleEvent FrmDispatchEvent -Handle System Event User pressing power button to turn off the handheld Battery low notification Global Find function Interrupts -Handle Menu Event User tapping menu silk-screened button. Selecting a displayed menu item. Taps inside a menu to activate a menu item (open). Taps outside a displayed menu (close)—remove menu from the screen. -Handle Application Event Programmer writes this function. To handle FrmLoadEvent. Loads and activates form resources. Application sets up a callback function to handle current active form. -Handle Form Dispatch Event Miniature AppEventLoop(). Passes events to active form’s event handler (which was set up in AppHandleEvent). Passes events to MainFormHandleEvent calback Function. On success, it returns execution to event loop.

6. PalmMain ( ) #include #include "helloRsc.h" UInt32 PilotMain(UInt16 cmd, MemPtr cmdPBP, UInt16 launchFlags) { Err error; switch (cmd){ case sysAppLaunchCmdNormalLaunch: error = AppStart(); if (error) return error; FrmGotoForm(MainForm); AppEventLoop(); AppStop(); break; } return errNone; }

7. AppStart() and AppStop() static Err AppStart ( void ) { // This function is used to initialize databases and retrieve user preferences return errNone; } static void AppStop ( void ) { // Used for any cleanup that your program might need like closing // databases or saving preferences FrmCloseAllForms (); }

8. Application Main Event Loop AppEventLoop() static void AppEventLoop(void) { EventType event; Err error; do { EvtGetEvent(&event, evtWaitForever); if ( ! SysHandleEvent (&event) ) if ( ! MenuHandleEvent (0, &event, &error) ) if ( ! AppHandleEvent (&event)) FrmDispatchEvent (&event); } while ( event. eType != appStopEvent ); }

9. Event Driven Architecture PalmMain() AppEventLoop() AppHandleEvent() MainFormHandleEvent() FrmDispatchEvent() frmColseEvent FrmHandleEvent() Events frmLoadEvent FrmInitForm() FrmSetActiveForm() FrmSetEventHandler() frmOpenEvent FrmDrawForm()

10. Palm OS Event Driven Architecture PalmMain() AppStart()AppStop() AppEventLoop() AppHandleEvent() MainFormHandleEvent() FrmDispatchEvent() Events GUI event handling (Buttons, Fields,...) SysHandleEvent() MenuHandleEvent() MainMenuHandleEvent()

11. Application Event Handler static Boolean AppHandleEvent (EventType *event){ //Initializing resources and setting up event handlers for forms. FormType *form; UInt16 formID; Boolean handled = false; if (event -> eType == frmLoadEvent) { formID = event->data. frmLoad. formID; //these few lines form = FrmInitForm( formID ); //are getting some data FrmSetActiveForm( form ); //from the event structure switch (formID) { case MainForm: FrmSetEventHandler( form, MainFormHandleEvent ); break; } handled = true; } return handled; }

12. Form Event Handler static Boolean MainFormHandleEvent (EventType *event) { Boolean handled = false; FormType * form; switch (event -> eType) { case frmOpenEvent: form = FrmGetActiveForm (); FrmDrawForm (form); handled = true; break; default: break; } return handled; }

13. Handling Events on Selecting/Pressing Buttons (Palm OS Bible, Chapter 8, page 265) // Code from the form event handler procedure if( event -> eType == ctlSelectEvent ) { switch ( event -> data. ctlSelect. controlID ){ case MyOKButton : // OK was tapped... break; case MyCancelButton : // Cancel was tapped... break; }

14. Handling Alerts UInt16 tappedButton ; tappedButton = FrmAlert ( MyAlertID ); switch ( tappedButton ) case 0 : // the first button was tapped... break; case 1 : // the second button was tapped... break; } Resource file (.rcp) ALERT ID MyAlertID INFORMATION BEGIN TITLE "Hello, world" MESSAGE "Good day to you, ^1." BUTTONS "OK" END

15. FrmAlert ( ) -- Function Purpose Create a modal dialog from an alert resource and display it until the user selects a button in the dialog. Declared In Form.h Prototype UInt16 FrmAlert ( UInt16 alertId ) Parameters → alertId -- ID of the alert resource. Returns Returns the item number of the button the user selected. A button's item number is determined by its order in the alert dialog; the first button has the item number 0 (zero).

16. FrmCustomAlert( ) Function Purpose Create a modal dialog from an alert resource and display the dialog until the user taps a button in the alert dialog. Declared In Form.h Prototype UInt16 FrmCustomAlert (UInt16 alertId, const Char *s1, const Char *s2, const Char *s3 ) Parameters → alertId Resource ID of the alert. → s1, s2, s3 Strings to replace ^1, ^2, and ^3 (see Comments). Returns Returns the number of the button the user tapped (the first button is zero). Comments A button's item number is determined by its order in the alert template; the first button has the item number zero. Up to three strings can be passed to this routine. They are used to replace the variables ^1, ^2 and ^3 that are contained in the message string of the alert resource. If the variables ^1, ^2, and ^3 occur in the message string, do not pass NULL for the arguments s1, s2, and s3. If you want an argument to be ignored, pass the empty string (""). In Palm OS 2.0 or below, pass a string containing a space (" ") instead of the empty string.