.
Home    |    Palm Games   |  Tech SupportTable of Contents   |   About Us    |    Email Us  
Palm Programming
Palm Programming HomepageHello WorldEmail Us
.
Support
Palm    |    Windows   |    Unix
Your first palm program - Hello World Overview
This section applies to C programmers only.

The simple hello world program that we remember from the days of BASIC and DOS is no longer so simple.  Newer, GUI/Event driven operating systems like windows and palm require some extra code for program setup, event handling, window (form) creation, etc.  In this section we will discuss the contents of the simplest complete program - the hello world program.  The information contained here will apply regardless of the environment you are using (PRC-Tools or CodeWarrior).

HelloWorld used to be a one or two line affair - as this BASIC/DOS example shows:

10  PRINT "Hello World"
20  END


Thats was easy.  WAS being the operative word.  Those days are long gone.

The palm version of HelloWorld is a bit more complex:

(Don't waste too much time studying the program listing below, as we will go through it line by line on the next page)
Be sure to read the short overview at the bottom of this page (just below the sourcecode listing).

// =============================================================
// HelloWorld for palm example START
// This program presents the form frmMain on screen
// frmMain contains the "Hello World" messag
e

#include <PalmOS.h>
#include "HelloWorld_resource.h"

static int StartApplication(void);
static Boolean ApplicationHandleEvent(EventPtr event);
static void EventLoop(void);
static void StopApplication(void);
UInt32 PilotMain(UInt16 cmd, void *cmdPBP, UInt16 launchFlags);
Boolean frmMainHandleEvent(EventPtr event);

Boolean flagProgramExit=false;

static int StartApplication (void)
{
   FrmGotoForm(frmMain);
   return 0;
}

static Boolean ApplicationHandleEvent(EventPtr event)
{
   UInt16 formID;
   FormPtr form;
   Boolean handled=false;

   switch (event->eType)
   {
      case frmLoadEvent:
         formID=event->data.frmLoad.formID;
         form=FrmInitForm(formID);
         FrmSetActiveForm(form);
         switch (formID)
         {
            case frmMain:
               FrmSetEventHandler(form,(FormEventHandlerPtr)
frmMainHandleEvent

;
               break;
            default:
               break;
         }
         handled=true;
         break;
      default:
         break;
   }
   return handled;
}

static void EventLoop(void)
{
   UInt16 error;
   EventType event;
   do
   {
      EvtGetEvent(&event,evtWaitForever);
      if (!SysHandleEvent(&event))
      {
          if (!ApplicationHandleEvent(&event))
               FrmDispatchEvent(&event);
      }
   }
   while (event.eType != appStopEvent && !flagProgramExit);
}

static void StopApplication(void)
{
  FrmCloseAllForms();
}

UInt32 PilotMain(UInt16 cmd, void *cmdPBP, UInt16 launchFlags)
{
   int error;

   if (cmd == sysAppLaunchCmdNormalLaunch)
   {
      error=StartApplication();
      if (error)
         return error;

      EventLoop();

      StopApplication();
   }
}

Boolean frmMainHandleEvent(EventPtr event)
{
   FormPtr form;
   Boolean handled=false;

   switch (event->eType)
   {
      case frmOpenEvent:
         form=FrmGetActiveForm();
         FrmDrawForm(form);
         handled=true;
         break;

     case ctlSelectEvent:
        if (event->data.ctlEnter.controlID == cmdClose)
        {    
           flagProgramExit=true;
        }
        break;
   
      default:
         break;
   }
}

// HelloWorld for Palm example END
// ======================================================================
=

Whew, that was quite a bit of code to do such a simple task.  As a matter of fact, there is a bit more information required to compile it (a resource file, containing our form layout in this case - which we will discuss later), but the source listing above is all the required C code.  The resource file is created in your "drag and drop" IDE environment and will pose no challange for you.

I have left out all comments and extranious code (such as the menu functions, which the helloworld program does not use) leaving the smallest program to avoid complicating matters for your overview.  I have also left out any About windows or any possible bell or whistle.   The code is fully commented in the Line by Line analysis on the next page.


Before we discuss each line in detail we will go over the program sections:

1)
Includes: one for the PalmOS header (from the SDK) and one for the resource header (from a drag and drop form construction tool, or *gasp* manually done)

2)
PilotMain: when the PalmOS starts a program, it runs the PilotMain (which MUST exist).  Inside this procedure we run AppStart (to set some things up), EventLoop (which will retain control until the program is terminated), and AppStop (where we clean up before giving control back to the operating system)

3
)  AppStart: here we load our initial form, and may do any other "one time - start of program" things that we wish

4)
EventLoop: This procedure holds the main program loop.  I will continue to poll for events, handle those events, and run any code you desire, until program termination.

5)
ApplicationEventHandler: When an event is received, before letting the system handle it, we pass it to our own routine - the ApplicationEventHandler - to see if we can handle it.  We use this routine to handle the loading of forms (such as loading our initial form in AppStart) and for menus (not shown in the above example) - or any event we desire to intercept before the system processes it.

6)
frmMainEventHandler: The ApplicationEventHandler was used to set frmMainEventHandler as the event handling procedure for our form.  We use this routine to handle form level events such as button presses, data entry and display, etc.  In a larger program we would have more forms, and a form event handler procedure for each of them.

7)
AppStop: Our clean up routine.  Closes all forms.  May also include routines to release locked memory.


After reviewing the overview above, continue on to the Line by Line Analysis

After reading this section, continue on to the Line by Line Analysis