CodeWarrior for palm os

7/29/2019 CodeWarrior for palm os

1/96

Metrowerks Tutorial:

CodeWarrior for Palm OS

Revised:


2/96

Metrowerks Tutorial: CodeWarrior for Palm OS TPAL-2

Copyright 1993-2001. Metrowerks Corp. ALL RIGHTS RESERVED.

Metrowerks and the Metrowerks logo are trademarks or registered trademarks ofMetrowerks Corp. and/or its subsidiaries in the United States and other countries.

CodeWarrior, PowerPlant, Metrowerks University, CodeWarrior Constructor, Geekware, andDiscover programming are trademarks and/or registered trademarks of Metrowerks Corp. in

the United States and other countries.

Graffiti, HotSync, Palm OS and Palm Modem are registered trademarks, and Palm III, PalmIIIx, Palm V, Palm VII, Palm, More connected., Simply Palm, the Palm, Inc. logo, Palm IIIlogo, Palm IIIx logo, Palm V logo, Palm VII logo, and HotSync logo are trademarks of Palm,Inc. or its subsidiaries. All other trademarks are the property of their respective owners andare hereby recognized.

Documentation stored on the compact disk(s) may be printed by Licensee solely for personaluse. Except for the foregoing, no part of this documentation may be reproduced ortransmitted in any form by any means, electronic or mechanical, including photocopying,recording, or any information storage and retrieval system, without permission in writingfrom Metrowerks Corp.

ALL SOFTWARE AND DOCUMENTATION ON THE COMPACT DISK(S) ARE SUBJECT TOTHE LICENSE AGREEMENT IN THE CD BOOKLET.

If your current licensing key has restrictions, you may experience difficulty usingCodeWarrior, depending on those restrictions. Contact Metrowerks for more information andto obtain a full licensing key by sending email to [email protected] or by calling 800-377-5416 or +1-512-997-4700 (international).

How to Contact Metrowerks:

U.S.A. and International Metrowerks Corporation

9801 Metric Blvd., Suite #100Austin, TX 78758U.S.A.

World Wide Web http://www.metrowerks.comTechnical Support mailto: [email protected]

USA: 1-800-377-5416Intl.: +1-512-997-4700


3/96


Table of Contents

1 Introduction 7The Purpose. . . . . . . . . . . . . 7The Requirements . . . . . . . . . . . 7Choosing a Resource Editor . . . . . . . . 8Resetting the Device . . . . . . . . . . 8

Soft Reset . . . . . . . . . . . . 9No-notify Reset (Warm Reset) . . . . . . 9Hard Reset . . . . . . . . . . . . 9

How to Get the Most out of this Tutorial . . . . 9

Where to Get More Information . . . . . . 10CodeWarrior Documentation . . . . . . 10Palm Documentation . . . . . . . . . 10Sample Code . . . . . . . . . . . 11Knowledge Base . . . . . . . . . . 11Newsgroups and Forums . . . . . . . . 11

2 Setting Up the Project 13Create the Project . . . . . . . . . . . 13Modify the Stationery . . . . . . . . . . 15Compile, Debug, and Run . . . . . . . . 17Take a Look at the Code . . . . . . . . . 20

3 A Form and an Alert 23Set up the Resource File . . . . . . . . . 23Create a Form . . . . . . . . . . . . 25Create an Alert . . . . . . . . . . . . 26Compile and Run . . . . . . . . . . . 27Take a Look at the Code . . . . . . . . . 29

4 Two Buttons and Another Form 31Create a Button on the Main Form . . . . . . 31Create a New Form. . . . . . . . . . 32

Put a Button on the Create Form. . . . . . 33Compile and Run . . . . . . . . . . . 34Take a Look at the Code . . . . . . . . . 35

5 An About Form, Menus and Menu Bars 37Create an About Form . . . . . . . . . 37Create a Menu and a Menu Bar . . . . . . . 38Compile and Run . . . . . . . . . . . 39


4/96


Take a Look at the Code . . . . . . . . . 41

6 Labels and a Help String 43Add Labels to the About Form . . . . . . . 43Add a Help String to the Form . . . . . . . 44

Compile and Run . . . . . . . . . . . 45Take a Look at the Code . . . . . . . . . 46

7 Adding Bitmaps to the About Form 47Learn About Bitmap Families . . . . . . . 47Add Bitmaps to the About Form . . . . . . 48Compile and Run . . . . . . . . . . . 51Take a Look at the Code . . . . . . . . . 52

8 Add a Field to a Form 53Add a Field and a GSI . . . . . . . . . . 53Create an Edit Menu . . . . . . . . . . 54

Compile and Run . . . . . . . . . . . 55Take a Look at the Code . . . . . . . . . 55

9 A List, a Button, and an Alert 57Create and Populate a List . . . . . . . . 57Add a Button and an Alert . . . . . . . . 58Compile and Run . . . . . . . . . . . 59Take a Look at the Code . . . . . . . . . 60

10 Popup Trigger and Saving to a Database 63Create a Popup Trigger . . . . . . . . . 63

Add a Button and Two Alerts . . . . . . . 65Compile and Run . . . . . . . . . . . 66Take a Look at the Code . . . . . . . . . 67

11 Adding a View Form 71Create a Form with Push Buttons . . . . . . 71Add a Field and Two Buttons . . . . . . . 72Compile and Run . . . . . . . . . . . 73Take a Look at the Code . . . . . . . . . 74

12 A Form for Completion and Deletion 77

Create a Form, Buttons, and an Alert . . . . . 77Add Several Labels and Checkboxes . . . . . 78Compile and Run . . . . . . . . . . . 79Take a Look at the Code . . . . . . . . . 80

13 Selector Triggers for Reminders 83Put Selector Triggers on the Complete Form . . . 83Create a Form to be Triggered by the Selector . . 84Compile and Run . . . . . . . . . . . 85


5/96


Take a Look at the Code . . . . . . . . . 86

14 Wrapping Up the Application 89Copy a Bitmap From an External Editor . . . . 89Create a Large Application Icon . . . . . . . 90

Create a Small Application Icon . . . . . . . 91Compile and Run . . . . . . . . . . . 92Take a Look at the Code . . . . . . . . . 93Conclusion . . . . . . . . . . . . . 93


6/96



7/96


1Introduction

Welcome to the CodeWarrior for Palm OS Tutorial. In this section you will seeinformation on:

The Purpose The Requirements Choosing a Resource Editor Resetting the Device How to Get the Most out of this Tutorial Where to Get More Information

CodeWarrior for Palm OS Platform version 8.0 is a fully integrated development

environment for the Palm OS platform. It comes with the 4.0 SDK (the latest versionof the SDK available at the time this manual went to print), so you can develop forany device that runs any version of the Palm OS from the original 1.0 up to the recent4.0. This is done through the marriage of C or C++ code and the resources that makeup the user interface (UI). Resources include anything the user can interact with forms, menus, buttons, etc. In this section, you will see a list of the various UIelements that can be added to a Palm OS application.

Regardless of how well you already know C or C++, Palm development has its ownlearning curve. This is due to the fact that Palm, Inc., has created a comprehensiveApplication Programming Interface (API) for development for this OS. As a result, anew Palm OS developer must learn about creating and using the various resourcesproperly as well as learn about the Palm OS API that is used to control the resources.

The Purpose

The primary purpose of this tutorial is to show a new Palm OS developer how tocreate resources properly, and then discuss the code that is required to make themwork. This tutorial is not intended to teach the Palm OS API, though some calls will

be discussed in the process of discussing the code requirements. You will not writeany code, instead you will copy it from a folder that contains the updated source files.You will go through the steps of creating the resources, looking at the code, anddebugging the application.

This tutorial is broken down into chapters that cover a certain type of resource(s). Atthe end of each chapter you will have an application that is fully functional and hasmore features than it did at the end of the previous chapter. It is set up so that you can

work from beginning to end to learn progressively more difficult concepts. You canalso choose to jump to a specific chapter and begin there by simply copying the filesfrom the Tutorial folder for the chapter you are about to begin.

The Requirements

If you are reading this document, you most likely have CodeWarrior for Palm OSPlatform version 8.0. This is the first thing that is required to go through this tutorial.


8/96


Install it on your machine using the installer. Then you need to have a device thatruns the Palm OS or a ROM file from one of the Palm OS device vendors.

Now that you have the hardware and software necessary, begin with a goodunderstanding of either C or C++. You must be proficient in your desktopdevelopment environment. You should have used a Palm OS device before, and befamiliar with the way they act and look. You can use either a Macintosh or Windows

platform for following this tutorial, though screenshots and pathnames will bespecified in Windows terms. The Macintosh equivalents are very similar to thosepresented here.

Choosing a Resource Editor

If you read the introduction, you understand that you will be learning to createresources, and you will see the code that must be created to make these resourcesfunction properly. These resources can be developed in a number of applications, sowhen you create a new application, youll want to decide which is right for yourproject. The resource editing options included with the CodeWarrior for Palm OSPlatform version 8.0 product are Constructor for Palm OS, PilRC, and Rez. In thefollowing paragraphs, youll see the strong and weak points of the various tools so

you can make an educated choice.

Constructor for Palm OS is a free tool provided and maintained by Palm, as part of theSDK. It is a graphical WYSIWYG (what you see is what you get) tool, so you are ableto see a representation of the form you are developing before you put it on an actualPalm device. Since this application was originally a port of the Constructor forMacintosh product, some Windows users find it non-intuitive and hard to use.Constructor creates files with a .rsrc extension.

PilRC is a free tool available under the GNU Public License (GPL), and is maintainedby Aaron Ardiri (a longtime member of the Palm OS developer community, butunaffiliated with Metrowerks or Palm). This tool is a text-based resource editor, soyou cant see a mockup of the form until you run the application on a device or theemulator. However, because it is text-based, the developer has a significant amount of

flexibility that isnt available with Constructor. PilRC creates files with a .rcpextension.

Rez is also a text-based tool, but it is based on the Apple Rez format for Macintoshresources. People who are familiar with the Rez format from programming for theMac OS may find this tool useful. If not, there is not very much Palm OS-specificdocumentation for using Rez, so if you would like to learn a text-based resourceformat for the Palm OS, you are better off to stick with PilRC. The Rez compilerexpects text files with a .r extension.

While these three resource editors all have their strong and weak points, you are notlimited to using only one of these tools. You can have .rsrc, .rcp, and .r files all in thesame project, and the PalmRez Post Linker will combine them all together for you.So, you are free to use the best tool for the job. In this tutorial, we will use

Constructor, as it tends to be the most straightforward for new users getting into PalmOS development.

Resetting the Device

Periodically during the development cycle, certain actions will require you to resetyour device. Most often this will happen if the debugger fails in its connection withthe device, or if there is a problem with your application that forces your device intoan infinitely resetting loop. There are ways of resetting the device to regain


9/96


functionality of the device that dont include sending it back to the manufacturer. Thethree main resets are

Soft Reset No-notify Reset (Warm Reset) Hard Reset

Soft ResetThis is the type of reset you will have to do if your debugger download fails. Whenyou start the download the serial port is opened for the debugger, and then if thatfails, the serial port is not closed. This type of reset will close the serial port on thedevice and clear the dynamic heap without disturbing the storage heap. This meansthe data on your device will be untouched, but there is a clean stack and globalvariable area, the drivers are restarted and the serial port is reset. Perform the reset byinserting the end of your stylus (some styli can have the top or the tip unscrewed toreveal a tool for resetting the device) or an opened paperclip into a small hole on the

back of the device, which is labeled Reset. All applications on the device willreceive a sysAppLaunchCmdReset launch code from the OS with this reset.

No-notify Reset (Warm Reset)

If an application is misbehaving, it can cause the device to get stuck in a soft reset.When the reset launch code is sent out to all applications, if one doesnt handle thecode properly, the device will continue to soft reset continually. To get out of thisstate, you need to do a no-notify reset, which is just like a soft reset, but thesysAppLaunchCmdReset code wont be sent out to the applications and no systempatches will be loaded. Perform this reset by pressing and holding the up button onthe device while poking the reset button on the back of the device. Once the devicehas reset properly, delete the application from memory to avoid further problems.

Hard ResetIf a soft reset and a no-notify reset are not enough to get your device back to aworking state, the last course of action is a hard reset. A hard reset will clear thestorage heap as well as all the actions of a soft reset. This has the effect that all the userdata and applications are removed from the device, rendering it back to the state it

was in when you first took it out of its box. Since hard resets are occasionallynecessary, it only makes sense to sync your device with the HotSync Manager beforebeginning your development. To perform a hard reset, press and hold the powerbutton on the device, while poking the reset button on the back of the device. Holdthe power button down until the Palm OS logo appears on the screen. If you havedone this correctly, you will get a confirmation for deleting all the data. Afterselecting yes (by pressing the up button), the device will complete its reset.

How to Get the Most out of this Tutorial

For a developer new to the Palm OS Platform, start with Chapter 1 and proceed to theend of this manual. Each chapter builds on what has been demonstrated in theprevious chapters, so if youve skipped a chapter or more, you may get lost. In eachchapter, modify your resource file according to the directions provided for theresource editor you have chosen. Then copy over the updated source code to handlethe new resources, and go through the discussion of the code that was added. Youshould look up some of the API calls in the Palm OS Reference manual. This will giveyou a feel for the way the API calls are documented and the way they are used in thecode. Debug the project, and step through the code until you understand what thecode is doing and why.

The code you will need for each chapter is found in the CodeWarrior Manuals\MWTutorial for Palm OS\Errand folder. Dont modify this folder. Instead, work in aseparate folder, and copy over the necessary files to a working directory (like a


10/96

Metrowerks Tutorial: CodeWarrior for Palm OS TPAL-

10

CodeWarrior Manuals\MW Tutorial for Palm OS\MyErrand folder) to modify them.In each of the Chapter folders is the information you will need to begin the specifiedchapter. Most of these folders contain a project file, Src folder and Rsc folder. If youwork the tutorial in the order it is presented you will be updating the resource fileand the project file as you progress. Therefore you will not need the project file or theinformation in the Rsc folder. Instead, you will only take the code from the Src folderand replace the sources in your working directory to be ready to work through the

next chapter. If you have a chapter that doesnt seem to work for you, or if you arenot working the tutorial chronologically, copy the entire contents of the chapter toyour MyErrand folder, and then begin working through the chapter.

Where to Get More Information

There are lots of resources that are available to you on the web and the CodeWarriorfor Palm OS Platform version 8.0 CD. A few of them are described in this section:

CodeWarrior Documentation Palm Documentation Sample Code Knowledge Base Newsgroups and Forums

CodeWarrior DocumentationDocumentation for using the CodeWarrior toolset is found in the CodeWarriorManuals\PDF\ folder of your installation. The manuals are written for the collectiveset of tools that Metrowerks produces, including the desktop, embedded, and gamestools. A brief synopsis of all the CodeWarrior manuals in your installation is below.

C Compilers Reference This manual discusses the pragmas and symbols used inMetrowerks implementation of C and C++. It alsoprovides information about the compiler settings panels.

IDE User Guide This manual tells you everything you could ever want toknow about the CodeWarrior project file, the editor, and

how to use the various features of the debugger.MSL C Reference This manual contains the description of all the headerfiles, extensions, and libraries included in the MetrowerksC implementation.

MSL C++ Reference Here you find out all about the C++ implementationMetrowerks has made.

Porting Reference This is a porting guide for developers moving code fromanother environment to CodeWarrior. There is nothingspecific for porting code to the Palm OS in this manual.

Profiler User Guide In this guide you can learn about the MetrowerksProfiler a tool that is hosted on the Mac OS, and workswith the format of information provided by the profileversion of the Emulator.

Scripting Reference In this manual you will discover how to extend thecapabilities of the IDE through VB, Apple, Perl, andCOM scripting.

Targeting Palm OSPlatform

This manual discusses the features of the product that arespecific to Palm OS development. Here you can findinformation on the settings in the various panels, thedifferences between project types, debugging andtroubleshooting information, and more.


11/96


11

Palm DocumentationThe documentation in the Palm Documentation\Palm OS 4.0 Docs folder is authored

by Palm, Inc., and is the most concentrated set of information you can find fordeveloping for the Palm OS. Below is a summary of each of the manuals you will findin your installation.

Constructor for PalmOS

This document discusses development with the Constructorresource-editing tool. Learn specifics about the varioussupported resources.

Development ToolsGuide

Here you can find out about the tools that Palm managesand puts out as part of the SDK, including the Palm OSEmulator (POSE), Simulator, Palm Debugger, PalmReporter, and the Overlay Tools.

Palm File FormatSpecification

This manual provides the specification for the various Palmfile formats the PRC (application), PDB (database), andPQA (web clipping) files.

Palm OS Companion(part 1)

This pair of manuals is great overview material. A newPalm OS programmer would do well to read most of thisfirst manual before ever writing a line of code. In part 1,learn about the Zen of Palm, how the event loop works,

how memory and databases work, and get some strategiesfor debugging your applications.Palm OS Companion(part 2)

This second companion manual discusses methods of dataexchange, including beaming, serial communications,networks, internet connections, and telephony.

Palm OS API Reference Once you begin your own development, this manual willbe vital to your work. Here you find each API calldocumented fully, along with a Compatibility Guide thatlets you know which version of the Palm OS is required forthat API to be supported.

Virtual Phone Guide This manual introduces you to the virtual phone a cellphone simulator you can use with POSE to test yourtelephony applications.

Web Clipping Guide Here you see the information you need to create a Web

Clipping application, and see how to get the appropriateinformation from the web onto your device.

Sample CodeThere is a significant amount of source code that is part of your CodeWarriorinstallation. This is a great place to see how to do something specific or to look athow a particular call is used. The CodeWarrior Manuals\Palm OS 4.0 SDK Examplesfolder contains the applications provided by Palm as part of the SDK. This includesmost of the built-in apps for you to use as a guide. The CodeWarriorManuals\Metrowerks Sample Projects For Palm OS folder contains samples created orgathered by Metrowerks to supplement the examples from the SDK.

Knowledge BasePalm maintains a very large searchable database of source code, FAQs, and articleswritten by a variety of people. You can search the KB athttp://oasis.palm.com/dev/kb/ to find high-level and low-level discussions ofhow to properly code your application.

Newsgroups and ForumsCommunicating with other Palm developers is a crucial part of developing for thisplatform. You may be new to development for this platform, but that doesnt meanyou cant use the common pitfalls others have struggled through to make your lifeeasier. The most commonly used newsgroups for Palm developers using CodeWarrior


12/96


12

are the codewarrior.palm and pilot.programmer.codewarrior groups, both hostedthrough usenet. The highest volume of developer postings are found on the PalmDeveloper Forums described athttp://www.palmos.com/dev/tech/support/forums/. These forums can bereceived as emails, a once-daily digest or viewed through a newsreader, and theres aforum for every part of the development cycle and for most of the Palm OS licensees.They are monitored by Palm engineers, Metrowerks engineers, and many

experienced developers. Most beginning questions can be answered by a quicksearch through the archives, which are also referenced at this page.


13/96


14/96


14

4. Set the Location of the MyErrand project folder to this Tutorial folder. If youused the default location when you installed CodeWarrior, this locationshould be C:\Program Files\Metrowerks\CodeWarrior\CodeWarriorManuals\MW Tutorial For Palm OS\MyErrand. The New Project windowshould look like Figure 2.1

5. Click the OK button.6. In the Palm OS Application Wizard dialog, fill in the fields as follows.

Application Name MyErrandRelease PRC Filename MyErrand.prcDebug PRC Filename MyErrandD.prcNaming Prefix AppPalm OS Creator Code ErrDApplication Type Standard C applicationMinimum OS Version 3.0

The filled-in window should look like Figure 2.2. Then click Next.

Figure2.2: The wizard window filled in

7. In the next window, we dont need to use any of the 3 rd party SDKs orlibraries. Leave all the items unchecked and click Finish.

If you expand the various folders (called groups from now on) in the Files tab, youwill see several files. In the Source group, there is an AppMain.c file, which is thesource for this basic beginning to our project. The Headers group contains App.h, aheader file for the project, and AppRsc.h, the header generated for use with the

resource file. In the Resources group, you see the App.rsrc file, which is theConstructor resource file. In the System group, you see the PalmOSRuntime_2i_A5.libfile, which is the library we will need to compile against, and a BuildHeaders.mcp filethat was used by the wizard to create the App.rsrc file (we wont need that foranything further).

Other features of this project window can be cryptic if you dont know what they are,and very helpful if you do. Here we will talk about some of the most commonly usedones in Palm development, but you should refer to the IDE User Guide for moreinformation on some of the more powerful features of the project, targets, and the rest


15/96


15

of the IDE. In Figure 2.3, you can see the project window as we discuss some of thefeatures there.

Figure 2.3: The Project window

Red checkmarks next to the file names indicate that the fileneeds to be compiled.

The target dropdown shows you the current target andallows you to switch between targets in the project.

The settings button will take you to all the settings that arespecific to the current target.

The make button compiles and links the project.

The debug button prompts the IDE to debug theapplication to the emulator or device.

The run button prompts the IDE to load the application onthe emulator or device and launch it.

If you select the Segments tab, you can see how the files are broken down bysegment. Segments allow you to create Palm applications larger than 64K. Eachsegment in a Palm OS application can contain up to nearly 64K of code. We will onlyhave a single segment application in this tutorial, since this application is small.Another use of the Segments tab is to specify the link order. The files are linked fromtop to bottom in this list, and you can drag files around in this view to change thatorder.

Modify the Stationery

Youve seen how to create the project and understand what it means, so we need tomodify it for use in this tutorial. The settings we put in the wizard when we created


16/96


16

the project are sufficient for this project. We do need to change the source andresource files that will be used, however.

First, we need to remove the files that are currently in the project, so we can replacethem with our own.

1. Choose the Files tab on the project window.2. Select AppMain.c in the Source group.3. Hit the Delete key or right-click on the filename and choose Delete from

the menu.4. Choose OK on the confirmation window to delete it from the project.5. Repeat steps 1 through 3 with the App.h, AppRsc.h, App.rsrc and

BuildHeaders.mcp files.

Now there isnt anything in the project to create an application. However, we haventmade any changes to what actually exists on the hard drive, so we could always addthose files back into the project and have the wizard-generated app again. Instead, wewant to get rid of those files, since they are placeholders we dont want to use. OpenWindows Explorer and navigate to your CodeWarrior Manuals\MW Tutorial forPalm OS\MyErrand folder. Delete the contents of the Src and the Rsc folders,including the hidden Resource.frk folder. Leave the Src and Rsc folders on your diskso we can use this hierarchy throughout the tutorial.

In the CodeWarrior Manuals\MW Tutorial for Palm OS\Errand\Chapter 2\Src folder,copy the Errand.c and Errand.h files and paste them in your CodeWarriorManuals\MW Tutorial for Palm OS\MyErrand\Src folder. To tell the project aboutthis new source file, either drag the Errand.c file from Explorer into the projectwindow, or choose Project-Add Files and navigate to the CodeWarrior Manuals\MWTutorial for Palm OS\MyErrand\Src folder and select Errand.c. On the Add Filesdialog, make sure both the Release and Debug targets are selected and press OK. It isnot necessary to add header files to the project as they are included by the source file,

but add the Errand.h file anyway, because it will make it easier to view the contentsof that file later.

For our own organization in this project, it is helpful to put the source and headerfiles in appropriate groups. Click the Errand.c file once to select it, and drag it into theSource group as shown in Figure 2.4.


17/96


17

Figure 2.4: Moving a file into a group

Drag Errand.h into the Headers group. The Resources group is still empty, but wellleave that be until Chapter 3. Meanwhile, this completes our modification of the stockstationery project.

Compile, Debug, and Run

Now lets compile and debug our project to make sure the environment is set upproperly. First, compile and link the code to create the working application. Use theMake icon in the project window or choose Project-Make to compile the project. Youshould see a progress window appear giving you information about the compile and

link process. The project should compile and link without errors or warnings. If not,go back to the beginning of this chapter and go through the steps again, to make sureyou havent missed anything.

To debug the application, you will need either a device running the Palm OS or aROM file, which you can get from a device or off websites of companies thatdistribute devices with the Palm OS. There are big advantages to using ROM filesinstead of actual devices you can test your application on many different deviceswithout having to spend a gazillion dollars, and you get improved error checkingthrough the Palm OS Emulator (a GPLed tool available from Palm, called POSE fromhere on out) and debug versions of the ROMs on the websites. To get these ROMfiles, see below for a list of vendors and the appropriate websites:

Palm http://www.palmos.com/alliance/resources/

Handspring http://www.handspring.com/developers/tech_pose.jhtmlSony http://www.us.sonypdadev.com/top.htmlHandera http://www.handera.com/support/developsupport.aspSymbol http://software.symbol.com/devzone/Kyocera http://www.kyocera-wireless.com/partner/partner.htm

In order to get access to the ROM files, you will need to sign an agreement withany/all of these vendors. Even if you have a device to debug to now, you will needto get these ROM files to test your future applications to any reasonable degree.


18/96


18

In this tutorial, we will assume you are debugging to POSE with a ROM file youuploaded from a device or downloaded from one of these vendors websites. If youare debugging directly to a device, refer to the Targeting Palm OS Platform manual forstep-by-step directions for making that connection.

To start up POSE, we need to need to configure a couple of things. In the IDE underthe Edit menu, choose Preferences. Select the PalmDebugger Settings panel, which is

the last

Figure 2.5: The PalmDebugger Settings panel configured for POSE debugging

one on the list. For the target choose Palm OS Emulator, and set the location bybrowsing to the Emulator.exe program, selecting it, and choosing Open from theChoose File dialog. If you check the box next to Always launch emulator on IDEstartup, then when you start the IDE, it will find POSE at the location youve specifiedand start it up too. When youre done, click the Apply button, and the panel shouldlook like Figure 2.5.

Click OK to close the Preference panel. Since the Always launch emulator on IDEstartup setting wasnt checked when we started the IDE at the beginning of thischapter, POSE is not running. To start it, choose Palm-Launch Emulator from the IDEmenu. If youve never run POSE before, you will see the dialog in Figure 2.6.


19/96


19

Figure 2.6: The startup POSE dialog

Select New to get theNew Session dialogin Figure 2.7. TheROM File field willsay None, and youcan select it a chooseOther to navigate to a

ROM file you havestored on yourmachine. The Devicefield will then limityou to devices thechosen ROM file canrun on. For the Skin,use Standard-English

or Standard-Japanese to see pretty pictures of the selected devices (if you chooseGeneric for the Skin, you will always see a PalmPilot Pro-like picture, but it wontaffect the way your program interacts with the chosen device). For the RAM size,select something that makes sense for the ROM file you have chosen. Most deviceshave 2 or 8 Megs of RAM.

Figure 2.7: The POSE New Session dialog

Once you click OK, POSE should come up, looking like the device you selected.When POSE is done launching, it should be displaying the Preferences screen, whichis an ideal state for the device to be in when debugging to it.

To debug the application, simply press the debug icon on the project window orchoose Project-Debug from the IDE menu. This will bring up the debugger, stoppedat an


20/96


20

Figure 2.8: the debugger window at the beginning of a debug session

automatic breakpoint at PilotMain(). You can compare what you see to what youshould see by looking at Figure 2.8.

To debug the application to the next breakpoint (we havent set any, so it will run theapplication normally), click the Debug icon in the debugger window. The debuggerwindow will go blank, and POSE should look blank, too. Kill the debugger byclicking the red X next to the debug icon. This will also reset POSE.

Once POSE is finished resetting, lets run the application two ways. First, click the

App Launcher icon in POSE to view the applications on the device. You shouldnotice one called MyErrand. Click it with your mouse to launch it. You will see thesame blank screen you saw when you debugged the application. Click the AppLauncher icon again to get out of the app. Another way to run the MyErrandapplication is from the project window. Back in the IDE, click the Run icon, and youshould see the same blank screen youve seen twice before.

You may have realized that this application doesnt do anything yet. We need to addfunctionality to it in future chapters.

Take a Look at the Code


21/96


21

Lets look at the code in this very simplistic example. As youve already seen, thisapplication doesnt actually do anything, but looking at the code will give you anidea of the flow of a Palm application. If you double-click on the Errand.c file, it willopen in the CodeWarrior editor for you to look at. Using the function pop-up menuin the source window depicted in Figure 2.9, jump to the Pilotmain function, andthats where we will begin.

Figure 2.9: Using the function pop-up menu

You will notice that the function names are colored in a different color than thestandard black. This is because of the browser (see the IDE User Guide for moreinformation on this feature). Besides turning the text pretty colors, this will make iteasier to navigate the code. If you right-click on a function name, you will see anoption to go to the function definition of that file.

If you look at the code, you will see that PilotMain calls StarterPalmMain. If youright-click on StarterPalmMain and jump to the function definition as shown inFigure 2.10, you will be able to easily navigate through the code as we discuss it.


22/96


22

Figure 2.10: Navigating using browser coloring

When MyErrand is launched, a launch code is sent to PilotMain. Our PilotMainfunction then sends that launch code to StarterPalmMain. In theStarterPalmMain function, we see that the only launch command we do anythingwith is the sysAppLaunchCmdNormalLaunch command the one the app gets if auser specifically launches the application. From the case for this launch command,AppStart gets called. IfAppStart has no error (which it wont in this little sample),then the AppEventLoop is called from StarterPalmMain. The AppEventLoop is thecontrol center of a Palm OS application. It gets new events from the user and asks thesystem, then the menu handler, then the application, and then the form handler tohandle the event that came in. The application gets the chance to handle the eventthrough the AppHandleEvent function. Right now our application doesnt doanything, so AppHandleEvent always tells the OS it didnt handle any events andreturns false. This will change as we add things in future chapters. Once an

appStopEvent is queued up (like when the user taps an icon or presses a hard key togo to another application), we exit the AppEventLoop, and go back toStarterPalmMain. Then AppStop is called, and we clean up any mess ourapplication has made. The application returns from AppStop to StarterPalmMain toPilotMain, and then it is finished.

Most Palm OS applications are significantly more complicated than this, but mostfollow this same set of basic steps.


23/96


23

3A Form and an Alert

Now that we have the base project created, were ready to get down to the creationof some resources. First, get the source files youll need for the new resources wecreate in Chapter 3 to work properly.

If you followed Chapter 2, go into the CodeWarrior Manuals\MW Tutorialfor Palm OS\Errand\Chapter 3\Src folder and copy the Errand.c, Errand.h,and Main.c files to your CodeWarrior Manuals\MW Tutorial for PalmOS\MyErrand\Src folder, overwriting the source files already there.

If you skipped Chapter 2, go to your CodeWarrior Manuals\MW Tutorial forPalm OS folder and create a folder called MyErrand. Copy all the files andfolders in the CodeWarrior Manuals\MW Tutorial for Palm

OS\Errand\Chapter 3 folder to your MyErrand folder.Open the project, and add the Main.c file to the project. Put this file in the Sourcegroup.In this chapter, you will go through the following steps:

Set up the Resource File Create a Form Create an Alert Compile and Run Take a Look at the Code

Set up the Resource FileTo create a form, we need a resource file, and were going to use Constructor forPalm OS to make that file. To open Constructor, use Windows Explorer to navigate toyour CodeWarrior for Palm OS installation folder. In the Palm Tools\Constructorfolder, open Constructor for Palm OS.exe. In the File menu, choose New Project File.In the bottom half of the window, you can see the Project Settings for the resourcefile. Check the box to Generate App Resources. This will enable several other fields.Set the Application Icon Name to MyErrand. Then check the Auto Generate Header

box. In the field below that, specify that the Header file name be ErrandRsc.h, andcheck the box to Include Details in header. Your project settings should now look likeFigure 3.1.


24/96


24

Figure 3.1: A new Constructor project file and settings

Thats all that is necessary to configure the resource file. Now we need to save the fileand add it and the resource header file to our project in the IDE. Under File, chooseSave. Navigate to the Tutorial/MyErrand/Rsc folder, name the file Errand, and clickSave. Then go back to the IDE and use Project-Add files to add Errand.rsrc andErrandRsc.h to the project. Be sure to add the files to both targets. For ourorganizational structure, drag Errand.rsrc to the Resources group and ErrandRsc.h tothe Headers group. After all this, your project window should look like Figure 3.2.


25/96


25

Figure 3.2: Project window with the resource files added

Create a Form

Go back to Constructor and the Errand.rsrc file that we just created. We are nowready to create the first form.

1. Select the Forms resource at the top of the screen, and choose Edit-New FormResource from the menu, or use ctrl-K to create it.

2. Click once in the title of the new form (currently labeled untitled).3. Type Main as the new title of the form and press Enter. Leave the ID at the

default value of 1000. Your resource file should look like Figure 3.3.

Figure 3.3: The new form resource in Constructor

4. Press Enter again or double-click to open the Main form for editing.5. Under the Layout menu, choose Hide Object IDs.6. Click once in the field to the right of the label Form Title.7. Type Errand Manager and press Enter.

Now you will see the title you just typed in show up as the title on the Palm devicescreen mockup. None of the other Fields listed in the Layout Properties of the Formshould be modified from their default values. Your form should look like the one inFigure 3.4.


26/96


26

Figure 3.4: The Main form in Constructor

Close the forms layout editor by clicking the X in the top right of the window. Thatform has been created.

Create an AlertAlerts are similar to forms in several ways. However, they are enough different towarrant their own resource type. Now that we have our form, lets create the alert.

1. Select Alerts in the Constructor project window and choose Edit-New AlertResource or press ctrl-K.

2. Tap the untitled identifier once, type Rom Incompatible, and press Enter.As with the form earlier, leave the ID of the alert at the default value of 1000.

3. Press Enter again or double click on Rom Incompatible to pull up the alerteditor.

4. Set the following fields:Alert Type ErrorHelp ID Leave at 0

Title Select Untitled and type System Incompatible insteadMessage Select The Message and replace it with System Version2.0 or greater is required to run this application.

ButtonTitles

Leave the default single button with text OK.

Once youve completed this, your Alert Properties should look like Figure 3.5.


27/96


27

Figure 3.5: The ROM Incompatible alert in Constructor

Close the alert layout information with the windows X button like we did with theform. Your Constructor resource file should now look like Figure 3.6.

Figure 3.6: Resource file with a form and an alert

Save the resource file and return to the IDE to test the new application.

Compile and Run

In the IDE, use the Make button or Project-Make to compile and link the project. Ifyou get an error about an undefined identifier, go back into the resource file andmake sure all of the resource values are typed correctly. Spacing doesnt matter, butcase does. The code we copied over at the beginning of the chapter expects theresources to be named a certain way.


28/96


28

Before running the application, it is important that no application is running on POSE(including earlier versions of this application). In POSE, make sure the device screenis displaying the App Launcher (Figure 3.7) or the Preferences screen (Figure 3.8). You

can get to the App Launcher by pressing the App Launcher silkscreen button ( ).Get to the Preferences screen by running the Prefs application, or by resetting thedevice with any of the reset types discussed in Chapter 1.

Figure 3.7: App Launcher screen Figure 3.8: Preferences screen

Now, on the project window, choose the Run button to start the application on POSE.If you run the application on a device/ROM image that runs a version of the Palm OSbefore version 2.0, you will see the alert we created, as in Figure 3.9. Clicking OK onthat alert will return you to the App Launcher. If you run the application on a newerversion of the OS (something with 2.0 or later), you will see the form we created, as inFigure 3.10. Tap on the App Launcher to leave the application.

Right now our app doesnt do much, but you can see how it displays the resourceswe created in Constructor. As an additional exercise, you could debug the app(instead of just running it), and step through the code to see how the code interactswith the resources. This interaction is discussed in detail in the next section, where weTake a Look at the Code.


29/96


29

Figure 3.9: App running ondevice with OS 1.0

Figure 3.10: App running on device withOS greater than 1.0


There are several files that have been modified to make these resources workproperly. We are going to look at those four files now to see the code that wascreated behind the scenes. Double-click on the filename in the IDE project window toopen the file in the editor.

ErrandRsc.hThis is the header file that Constructor creates for us (because we checked the AutoGenerate Header option). As you can see in the comments of this file, sinceConstructor creates this file automatically any modifications to it will be lost the nexttime the resource file is saved. There are a couple of pieces that should be explained,so you understand why these values are here.

After the comment header, you see a comment line://Resource: tFRM 1000

This comment tells you that the next group of#defines refer to a form resource(tFRM) with ID 1000. This was the default ID that we left alone in Constructor. Thenyou see:#define MainForm 1000

which is the line that defines the constant MainFormto reference this resource that hasID of 1000. This naming structure is pretty straight-forward. Because we named ourform Main, and Constructor knew it was a Form resource, it stuck the two wordstogether to create the identifier. This identifier is then used throughout the sourcecode to reference this resource. If we had specified the name of our form as Itsy BitsyTeeny Weeny in Constructor, this #define would have set an identifier name ofItsyBitsyTeenyWeenyForm. All spaces are pulled out, but the case you enter ispreserved.

The next comment line is:


30/96


30

//Resource: Talt 1000

This means the next #define grouping is about the alert resource with ID of 1000.The RomIncompatibleAlert is the define for the alert itself (remember we named itRom Incompatible, and now Constructor added the word Alert to the identifier).The RomIncompatibleOK identifier references the OK button we put on the alert.Together these two defines represent all the pieces that are part of this alert resource.

Close this file, and continue through the rest of the code discussion.

Errand.cOpen the Errand.c file, and take a look at some of the modifications that have beenmade. Starting in StarterPalmMain, notice that the code now calls an additionalfunction, RomVersionCompatible during the sysAppLaunchCmdNormalLaunchcase. If you navigate to this function, you will see that it finds the version of the OSthe device is running, and if its less than 2.0, calls FrmAlert to display theRomIncompatibleAlert we created. Then, due to a difference in the way the OSworked in version 1.0, the function calls AppLaunchWithCommand to switch to theApp Launcher manually once the alert is dismissed.

The next difference in StarterPalmMain is that we call FrmGotoForm(MainForm)

before going into the event loop. This tells the application which form to start with(our Main form). Now, when the AppEventLoop calls our AppHandleEventfunction, there is one event that we can handle the one to display our form.

In AppHandleEvent, we receive the frmLoadEvent for the form in question. Thenwe call FrmInitFormand FrmSetActiveFormto setup the form for display.Probably the most important part of this code, though, is the switch statement that setsthe event handler for the individual form. We call FrmSetEventHandler to do this, andgive it the name of the function that will deal with events on this particular form.Weve defined the function MainFormHandleEvent, which we will discuss in thesection on Main.c in a moment. In the AppEventLoop function, the system, menu,and application all get a chance to handle an event. But if none of these handlershandle the event, then FrmDispatchEvent is called. FrmDispatchEvent calls the

current form event handler, and then the form is allowed to work with the event.

In AppStop, we have added a call to FrmCloseAllForms. This is necessary torelease the memory referring to our open form(s), so we can exit the applicationcleanly. Close this file and move on to the next one in our discussion.

Main.cOne of the standard methods of breaking a Palm OS application into separate sourcefiles is to create a separate source file for each form. This is what we have done increating the Main.c file. This file is set up to handle anything that has to do with theMain form that we created in Constructor. In Errand.c, you saw that we set the formhandler for the Main form to MainFormHandleEvent, and that is the only function inthis file at this time. This function is called anytime FrmDispatchEvent is called fromthe AppEventLoop function while MainFormis the current form. Within the

MainFormHandleEvent function, the only event type we handle at this point is oneto open the form (a frmOpenEvent). So we use FrmGetActiveFormto get a pointerto the form resource, and pass that to FrmDrawFormto actually display the form.

Close this file and go on to the next and last file that was modified.Errand.h

In the header file for the project, you can see that we have added prototypes for theRomVersionCompatible function in Errand.c and the MainFormHandleEvent


31/96


31

function in Main.c. Beyond that, all the other components are exactly as we had themin the previous chapter.


32/96


32


33/96


33

4Two Buttons and Another Form

Now its time to make the application do something. First, copy over the source filesyoull need to handle the new resources were about to create.

If you followed Chapter 3, go into the CodeWarrior Manuals\MW Tutorialfor Palm OS\Errand\Chapter 4\Src folder and copy the Errand.c, Errand.h,Main.c, and Create.c files to your CodeWarrior Manuals\MW Tutorial forPalm OS\MyErrand\Src folder, overwriting the source files already there.

If you skipped Chapter 3, make sure you have a MyErrand folder created inthe CodeWarrior Manuals\MW Tutorial for Palm OS folder. Then go to theCodeWarrior Manuals\MW Tutorial for Palm OS\Errand\Chapter 4 folderand copy all the files and folders from that folder into your MyErrand folder.

Open the project, and add the Create.c file to the project. Put this file in the Sourcegroup.In this chapter, you will go through the following steps:

Create a Button on the Main Form Create a New Form Put a Button on the Create Form Compile and Run Take a Look at the Code

To get started, open the Errand.rsrc file in Constructor (if you didnt close it from the

previous chapter, just switch to Constructor to see your resource file).

Create a Button on the Main Form

Double-click on the Main form to open the Layout Properties for this form. To add abutton to the form, you will need the resource catalog (Figure 4.1), which you can getby choosing Window-Catalog from the Constructor menu.


34/96


34

Figure 4.1: The catalog window

Here you can see the list of thetypes of resources you can put ona form. To add a button to theform, click the Button from thecatalog to select it, and drag it ontothe form we opened earlier. Onceyou have done this, the left side of

the form window will show youthe properties of the button,instead of the form. Change thevalues to:

Object Identifier CreateButton ID 1001 (the

default)Left Origin 104Top Origin 38Width 45Height 12Usable checkedAnchor Left

checked

Frame checkedNon-bold Frame checkedFont StandardLabel Create

In the Layout Properties for the Button, your window in Constructor should look likeFigure 4.2.

Figure 4.2: Button properties for the Main form

Close the Main form window.

Create a New Form

Now we need to make a new form that opens up when we tap that Create buttonwe just finished. If you remember how to create a form, do so. If not, go back toChapter 3 and look at how we created the Main form. Give the new form the name


35/96


35

Create and leave the resource ID as the default (1100). Open the Create form forediting. There is no need to change any of the default values, except for the FormTitle, which you should set to Create Errand List. The completed layout propertiesfor this new form should look like Figure 4.3.

Figure 4.3: Layout properties for the Create form

Put a Button on the Create Form

The same way you added a button to the Main form, add one from the catalog to theCreate form. Give this button the following properties:

Object Identifier DoneButton ID 1101 (leave as the default)Left Origin 10Top Origin 140Width 36Height 12Usable, Anchor Left, Frame, Non-boldFrame

leave all checked

Font StandardLabel DoneWhen you are finished, the properties of the button will look like those in Figure 4.4.


36/96


36

Figure 4.4: Buttonproperties for the Donebutton

Close the display for theCreate form and savethe Constructor file beforereturning to the IDE.

Compile and Run

Make the project. Make sure POSE is displaying the App Launcher or the Preferencesscreen and then run the application on your emulator session. It should compile

without error, and when you run it, should see the form labeled Errand Managerwith a button labeled Create (see Figure 4.5). When you click the Create button, theprogram should take you to the form labeled Create Errand List, which has a Done

button (see Figure 4.6). The Done button will take you back to the first form.

Figure 4.5: The Errand Managerform

Figure 4.6: The Create Errand List form



37/96


37

There are five files that were modified to make these new resources work this way.We will take a quick look through some of them, and a more in-depth look intoothers.

ErrandRsc.hThis header file, created by Constructor was updated when you modified and savedthe Errand.rsrc file in Constructor. There is now an identifier for the

MainCreateButton in the group with the tFRM1000 resource (our main form).Also, a new tFRM resource group was created for the CreateFormand theCreateDoneButton in this file.

Errand.cIf you drop down to the AppHandleEvent function, you will see that a new case has

been added for the CreateForm. Its event handler was set, and that form can beloaded as a result.

Main.cThe MainFormHandleEvent has a new case to allow it to respond toctlSelectEvents (like the one that gets sent when we press the Create button). Thistype of event sends us off to the MainFormDoCommand function for further processing.

This new function responds to the user selection of the MainCreateButton , and usesFrmGotoFormto close the MainFormand open the CreateForm.

Create.cThis new file was added, as mentioned in Chapter 3, to keep all functions related to acertain form in the same file. Since we added the CreateForm, we also added theCreate.c file to handle it. In this form you will see that there are two functions CreateFormHandleEvent and CreateFormDoButtonCommand. These are virtualcarbon copies of the analogous functions in the Main.c file for the MainForm. TheCreateFormHandleEvent function has been set up to handle frmOpenEvents (inorder to display the form) and ctlSelectEvents (to react to the button selections,like the CreateDoneButton). In the ctlSelectEvent case you can see thatCreateFormDoButtonCommand is called. This function has a case for the

CreateDoneButton that uses FrmGotoFormto take us back to the MainForm.

Errand.hIn the projects header file, three prototypes have been added for theMainFormDoCommand, CreateFormDoButtonCommand, and theCreateFormHandleEvent functions.


38/96


38


39/96


39

5An About Form, Menus and Menu

Bars

Whenever you create an application, it is helpful to have a screen that gives the usersome information about who created it. In the Palm OS world, this is done with anAbout screen. In this chapter, we will create an About screen and build a menu andmenu bar to access it.

If you followed Chapter 4, go into the CodeWarrior Manuals\MW Tutorialfor Palm OS\Errand\Chapter 5\Src folder and copy the Main.c file to yourCodeWarrior Manuals\MW Tutorial for Palm OS\MyErrand\Src folder,

overwriting the source file already there. If you skipped Chapter 4, make sure you have a MyErrand folder created inthe CodeWarrior Manuals\MW Tutorial for Palm OS folder. Then go to theCodeWarrior Manuals\MW Tutorial for Palm OS\Errand\Chapter 5 folderand copy all the files and folders from that folder into your MyErrand folder.

In this chapter, you will go through the following steps: Create an About Form Create a Menu and a Menu Bar Compile and Run Take a Look at the Code

To get started, open the Errand.rsrc file in Constructor (if you didnt close it from the

previous chapter, just switch to Constructor to see your resource file).

Create an About Form

Create a new form the same you have before. Set its name to About and leave theID at the default value of 1200. Open the About form for editing. Set the values to:

Left Origin 2Top Origin 32Width 156Height 126Usable checkedModal checkedSave Behind checked

Form ID, Help ID, Menu Bar ID, and DefaultButton ID leave default

Form Title AboutErrand

With this form, we have made it Modal. Visually, this means that the form has aborder, and generally fills the width of the screen, but not the height.Programmatically, it means that nothing else can be done with the application untilthe form is dismissed. Even though you will be able to see the MainFormin the

background, you wont be able to access it.


40/96


40

With the Catalog (Window-Catalog ifyouve forgotten), drag a button onto the

form, and giveit the following properties:ObjectIdentifier

Ok

Button ID leave default (1201)Left Origin 62Top Origin 108All other items leave as the default

value

Once these have been created, the layoutwill look like Figure 5.1. Close the formeditor.

Figure 5.1: The new About form

Create a Menu and a Menu Bar

Now, lets make a menu to take us to the About form we created. Menus are createdas part of a Menu Bar, and then the Menu Bar is associated with the appropriate form.This will make more sense as we proceed. First, in the resource summary window,

select the Menus resource type (see Figure 5.2) and press ctrl-K to create a new menu.Then go through the following steps.

Figure 5.2: Selecting the menu resource

1. Name the new menu Options and leave the ID as the default of 1000.2. Double-click this menu to open it for editing.3. Click on the menu text (that currently says Menu) and change the text to

Options.4. Type ctrl-K to create a new menu item, and change the text from untitled

item to About Errand.


41/96


41

When you have completed these steps, the menu editor should look like Figure 5.3.

Figure 5.3: Completed Options menu

Close the menu editor. Next, we need to create the Menu Bar that this menu will gowith.

5. Select Menu Bars and type ctrl-K to create a new Menu Bar resource.6. Change its title to Main Form and leave its ID as the default value of 1000.7. Double-click the new Main Form Menu Bar to open it for editing.8. Drag the Options menu item from the resource summary onto the menu bar

editor window. This associates the menu we created with this menu bar.

Your completed menu bar should look a lot like the completed menu in Figure 5.3.Close the menu bar editor. To associate the menu bar with the Main form, open theMain form for editing. Set the Menu Bar ID to match the ID of the menu bar wecreated ID 1000. Once you set this value, the button on the right should becomeenabled and say Edit. It wont be labeled Create, because Constructor recognizes thata menu bar with that ID exists. If you click that Edit button, you will see the menu

bar with the menu. Close the Main form, and save all the changes in Constructor.

Compile and Run

Return to the IDE. Make the project. Make sure POSE is displaying the App Launcheror the Preferences screen and then run the application on your emulator session. It

should compile without error, and when you run it, you should still see the ErrandManager form with its one button. The difference is, now you have a menu on thisform. If you are emulating a device with OS 3.3 or earlier, tap the menu silkscreen

button to get the menu to appear as in Figure 5.4. The silkscreen buttons are the fourto the left and right of the graffiti area on the device. The menu one is in the bottomleft corner of this area, as depicted in Figure 5.4. If you have a device running OS 3.5or later, you can tap the title bar of the form (where it says Errand Manager) to

bring up the menu.


42/96


42

Figure 5.4: The four silkscreen buttons and the menu

If you tap on the About Errandmenu item, that will bring up theAbout form we created earlier in

the chapter. Since this is a modalform that displays on top of the lastnon-modal form, you will see thetitle bar of the Main form in the

background, as shown in Figure5.5. Tapping in that area wont berecognized since the modal forms

button must be tapped before theuser can proceed.

Figure 5.5: The About form displayedwith the Main form in the background



43/96


43

Most of the resources we created in this chapter of the tutorial are managed by thePalm OS without any interaction with the program itself. Here we will look at thefiles that were modified to accommodate these changes in the program.

ErrandRsc.hIf you open the ErrandRsc.h file that is generated by Constructor, you will see the#defines for all the new resources we created in this chapter. There is a new tFRM1200 resource for the About form. The group for that resource looks like:

#define AboutForm 1200

#define AboutOkButton 1201

Each of these #define statements represents components of the AboutForm. The firstis the form itself, with the second referencing the OK button at the bottom of theform.

A little further down the file, you will see a couple of new resource groups that havebeen created. The first is the MBAR resource, which contains the #define for themenu bar we built. Next is the MENU resource. This resource has two #defines onefor the menu title, and one for the one item we created on it.

Main.cClose ErrandRsc.h and open Main.c to see the modifications that were made to thisfile. In the MainFormHandleEvent function, a new event has been added to theswitch statement. The MainFormnow handlesmenuEvents. The sameMainFormDoCommand function is called that we created for the button presses, butthis time we send the menu ID to the function. The menu ID is the ID of the menuitem that the user selected.

In the MainFormDoCommand function, a new case has been added for theOptionsAboutErrand case. This case is entered anytime the user selects the AboutErrand item in the menu. Once we enter this case, we useMenuEraseStatus(NULL) to erase the menu display for the current menu. This waythere arent any drawing problems when we put up the new form. Then we useFrmInitFormto initialize the AboutForm. We use FrmDoDialog to display the formwe initialized. With a modal form, FrmDoDialog is generally sufficient, since it isntnecessary to have the extra event handling available to us if we had usedFrmGotoForm. Using FrmDoDialog means we dont need any event handler for thisform. Also, using FrmDoDialog leaves the old form there while showing the shortermodal form. Once the OK button is pressed on the form, FrmDeleteFormis used toget rid of any leftover traces of the form, and return to the MainFormwe haddisplayed earlier. Since weve handled everything necessary for this user interaction,we set handled to true before returning to the event handler for the form and theapplication.


44/96


44


45/96


45

6Labels and a Help String

Since the About screen we created in Chapter 5 is pretty bland, in this chapter we willadd some labels and a help string to it.

If you followed Chapter 5, there is nothing you need to do simply continuethrough the chapter.


In this chapter, you will go through the following steps:

Add Labels to the About Form Add a Help String to the Form Compile and Run Take a Look at the Code

To get started, open the Errand.rsrc file in Constructor (if you didnt close it from theprevious chapter, just switch to Constructor to see your resource file).

Add Labels to the About Form

Double-click on the About form to open it for editing. Open the Catalog again(Window-Catalog if youve forgotten), and drag a label onto this form. Give the label

these values:Object Identifier App NameLabel ID leave default (1202)Left Origin 23Top Origin 29Usable checkedFont BoldText Errand

Drag another label onto the form, and give it the following values:Object Identifier VersionLabel ID leave default (1203)Left Origin 10Top Origin 40

Usable checkedFont BoldText Version 1.0

Drag one more label to the form. Give it the following values:Object Identifier CompanyLabel ID leave default (1204)Left Origin 13Top Origin 92Usable checked


46/96


46

Font BoldThe text for this label is a little different. It will say 2001 Metrowerks Corp. whenwere done with it, but the copyright symbol requires a couple extra steps. From aprogram called AsciiChart (available as freeware at http://www.palmgear.com),we can see that the Hex code for the copyright symbol is A9. This is what to use toget Constructor to recognize a non-keyboard character. Delete the untitled textcurrently in the field and check the box labeled Hex. Click in the area where the text

is input and type A9. Then uncheck the Hex box, and you should see the copyrightsymbol instead of the A9 letters. Click again in the text entry area and add a space and2001 Metrowerks Corp. after the copyright symbol. When you have completed this,your form layout should look like Figure 6.1.

Figure 6.1: Form layout with three labels

Add a Help String to the Form

Click on the About Errand title bar or any blank space on the form to select the formfor editing again. In the Help ID field, type 1000 and hit enter. If you look at thepicture of the form, you will notice a new graphic that appears in the top right corner

of the form that looks like this: . Now, click the Create button that becomesenabled across from it. This will bring up the String resource editor. Here you willtype the information that is to be displayed when the information icon is tapped bythe user. For this tutorial type the following as the text for this string resource.

This is the place where you might put information about your product, orwhere the user might find out more information about you or you mightadvertise other titles you've put out. Here, we've put our company's webaddress:www.metrowerks.com.


47/96


47

Your string editor should look like Figure 6.2. Once you are finished, close the Helpstring editor and save the resource file.

Figure 6.2: The string editor

Compile and Run

Return to the IDE. Make the project. Make sure POSE is displaying the App Launcheror the Preferences screen and then run the application on your emulator session. Itshould compile without error, and when you run it, you should still see the ErrandManager form with its one button. When you pull up the menu and choose AboutErrand, the new form will look like Figure 6.3.

On the About form, tap the information icon in the top right corner to see the screenin Figure 6.4. This is the Help string, and will always be labeled Tips. Tapping theDone button will take you back to the About form.

Figure 6.3: Errand form withlabels

Figure 6.4: The Tips form


48/96


48


None of the resources we created in this chapter required any code changes to work.Instead, the action of accessing the help string and returning to the form is handledcompletely by the OS. Simply creating the resources and putting the ID references inthe right places in Constructor makes them work properly. We will look at the new

resources that have been defined by Constructor for this chapter, though.

ErrandRsc.hOpen the ErrandRsc.h file in the editor. Under the tFRM 1200 resource group thereare three new items at the bottom of the group:

#define AboutAppNameLabel 1202

#define AboutVersionLabel 1203

#define AboutCompanyLabel 1204

These are for the three labels we placed on the form.

The last group in this file is also new. It was created for the tSTR resource, which isthe help string we added for display when the information icon was tapped. Noticethat its name is set up differently than some of the others: HelpID1000String. This

is a generic name that is used by Constructor when you dont change the title of aresource you create (like we didnt for this one we simply added the ID to the formand clicked create, avoiding the resource summary area in creating this resource). Acombination of the context the resource was created in (as a Help ID) and the IDnumber (1000 for this string) are used with the resource type (String) to create aunique name for the identifier. Since we dont reference this resource anywhere inour code, it wasnt necessary for us to create an identifier that was easy to recognizeand reference in code.


49/96


49

7Adding Bitmaps to the About

Form

Bitmaps get their own chapter, since bitmap creation can be a little tricky.

If you followed Chapter 6, there is nothing you need to do simply continuethrough the chapter.


In this chapter, you will go through the following steps: Learn About Bitmap Families Add Bitmaps to the About Form Compile and Run Take a Look at the Code


Learn About Bitmap Families

Because there are so many devices supporting all levels of color from black and whiteup through 16-bit color, Palm created bitmap families to make the developers lifeeasier. A bitmap family is a holding place for bitmaps of various depths. Within a

bitmap family, you can have one bitmap in black and white, the same bitmap in 2-bitgrayscale, another version in 4-bit grayscale, one in 8-bit color and one in 16-bitcolor. See Figure 7.1 for an example of one bitmap taken through the various depthlevels. Then, instead of the developer having to program which color depth todisplay, the OS will select the highest-level bitmap it can display on the currentdevice.

Figure 7.1: An array of bitmaps

At minimum, you will normally need to have a black and white image in yourfamily, unless you intend to only support devices with a higher display level. Thismight be the case with a custom internal application that will only run on certaindevices, or if youve chosen to support a limited feature set for your application. Mostof the time you will want a black and white image as well as a color image in your


50/96


50

family, so that your application looks good on color devices, instead of justdisplaying the same black and white image on color and monochrome devices.

Add Bitmaps to the About Form

Open the About form for editing. The position of the bitmap is controlled with a

Form Bitmap from the catalog. So, go to the catalog and drag a form bitmap onto theAbout form. Give it the following properties:Object ID leave default (1205)Object Identifier MW NameLeft Origin 10Top Origin 69Bitmap Resource 1100Usable checked

Now, on the form layout, you will see a gray square as shown in Figure 7.2. We willchange that momentarily.

Figure 7.2: The form bitmap on the About form

Across from where you set the Bitmap Resource ID to 1100, there is now an enabledCreate button. Click it to open the Bitmap Family editor. In this editor, set theWidth to 143 and the Height to 20. Your bitmap family editor should look like Figure7.3.


51/96


51

Figure 7.3: The bitmap family editor

In the bottom section of Figure 7.3, notice the section entitled Family Items. Bydefault, there is only one family item, and it is set with 1-bit color depth to create ablack and white image. Of the fields in Family Item 1 the only ones that need to bechanged are the Compression type and the Bitmap ID. Set the Compression type toScan Line. Bitmap IDs must be kept unique from bitmap family IDs and icon IDs.One way developers handle this is by using the bit depth as the last digit in theBitmap ID. So, for our bitmap family with ID 1100, the 1-bit bitmap will have an ID of1101. If we created a 16-bit bitmap, that bitmaps ID would be 1116, and the 2-bit, 4-

bit, and 8-bit bitmaps would be numbered similarly. For this bitmap, we will onlyhave a black and white image, so set the ID to 1101 and press the Create button to

bring up the bitmap editor.

In the bitmap editor, you seeseveral drawing tools down the

left side of the bitmap editor.These are pretty straightforward,as far as drawing tools go aselection tool, a text tool, adrawing tool, an eraser, a fill tool,a color detection tool, and severalfor drawing shapes. At the bottomleft of the screen are two sets ofselection boxes. One is used tochoose the fill pattern for the filltool to use (this is the largerselection box). The pair ofselection boxes is used todetermine the foreground and

background color to be used.When you click on the selectionbox to choose a color, your onlyoptions are black and white, sincethis is a 1-bit bitmap. If you werecreating a higher depth bitmap,selecting the color

Figure 7.4: The bitmap editor with thecompleted bitmap

palette would give you a much wider range of colors. In this way, Constructor helpsprotect you from creating a bitmap with the wrong color depth for your familyelement.


52/96


52

Draw the bitmap shown in Figure 7.4 and close the bitmap editor and the bitmapfamily editor. It actually doesnt matter what image you draw. This image is providedpurely as an example. On your form, you should see the bitmap you just created inplace of the shaded gray box.

Add a second form bitmap to your form from the catalog, and give it the followingvalues:

Object ID leave default (1206)Object Identifier LogoLeft Origin 82Top Origin 17Bitmap Resource 1200Usable checked

Open the bitmap family editor by clicking the Create button across from the BitmapResource property. Set the Width to 70 and the Height to 53. Change the Compressiontype to Scan Line. Set the Bitmap ID for Family Item 1 to 1201 and click theCreate button. Draw the image you see in Figure 7.5. Close the bitmap editor whenyou are finished. Then, we need to create a color version of that bitmap. Click onFamily Item 1 to select it, and press ctrl-K or use the menu to select Edit-New FamilyElement.

Figure 7.5: Black and whiteversion of the logo

Figure 7.6: 8-bit color version of thelogo

For Family Item 2, set the color depth to 8-bit (256 colors), the compression level toScan Line, and change the Bitmap ID to 1208. Click Create to make the colorversion of the bitmap, as seen in Figure 7.6. When you are finished, close the bitmapeditor and the bitmap family editor, and you should see the black and white versionof the bitmap on your form.

When all these steps are completed, your form should look like the one in Figure 7.7.


53/96


53

Figure 7.7: The completed Aboutform

Close the form editor and saveyour resource file in Constructor.

Compile and Run

Return to the IDE. Make the project. It should compile without error. Make surePOSE is displaying the App Launcher or the Preferences screen and then run theapplication on your emulator session. When you run it and choose the About

Errand menu item you should see the About form with both of the new bitmaps.Depending on whether you run the application on a black and white or coloremulated device, you will see Figure 7.8 or 7.9.


54/96


54

Figure 7.8: About form displayedon a black and white device

Figure 7.9: About form displayed ona color device


No code changes were made to cause the bitmaps to be displayed, nor for the colordevice to display the higher-depth version of the bitmap. Lets look at the new

resources that were added to the Constructor-generated header file.

ErrandRsc.hOpen the ErrandRsc.h file in the editor. In the middle of the tFRM 1200 resource,there are the following new entries:

#define AboutMWNameBitMap 1100

#define AboutLogoBitMap 1200

These two identifiers are for the bitmaps we created. Notice that they reference the IDnumber of the bitmap family we created, rather than the numbers we set up for theform bitmaps we dragged to the form. The names come from the names we gave theform bitmap resources, however.

As you scroll further down the header file, there are two new resource types. PICT isthe four-letter code for bitmaps (these are the bitmap family items). There are three ofthese, since we have one family that had just one bitmap in it and one family with a

black and white and a color bitmap. The tbmf type is used to represent bitmapfamilies. Two are listed in the header file for the two bitmap families that werecreated. These five resources are all generated with the generic resource name, justlike the Help ID string was in Chapter 6.


55/96


55

8Add a Field to a Form

Its time to add a textfield to the application. Using a field, we will start to see theapplication come together with data being entered. As before, get the sources first toget started.

If you followed Chapter 7, go into the CodeWarrior Manuals\MW Tutorialfor Palm OS\Errand\Chapter 8\Src folder and copy the Errand.c, Errand.h,and Create.c files to your CodeWarrior Manuals\MW Tutorial for PalmOS\MyErrand\Src folder, overwriting the source files already there.

If you skipped Chapter 7, make sure you have a folder named MyErrand inthe CodeWarrior Manuals\MW Tutorial for Palm OS folder. Then copy all thefiles and folders in the CodeWarrior Manuals\MW Tutorial for Palm

OS\Errand\Chapter 8 folder to your MyErrand folder.In this chapter you will go through the following steps:

Add a Field and a GSI Create an Edit Menu Compile and Run Take a Look at the Code


Add a Field and a GSI

With the Create form still open, drag a Field from the Catalog onto the form. Give thefield the following properties:

Object Identifier OtherField ID leave default (1102)Left Origin 10Top Origin 58Width 135Height 75Usable checkedEditable checkedUnderline checkedDynamic Size checkedMax Characters 256

Font StandardAuto Shift uncheckedHas Scroll Bar uncheckedNumeric unchecked

Then, anytime you have an editable field on a form, you must have a Graffiti ShiftIndicator (GSI) on the form as well. Drag it from the Catalog onto the form, and giveit the following values:

Object Identifier Other FieldLeft Origin 142


56/96


56

Top Origin 145Object ID leave default (1103)

Once these pieces are in place, your layout should look like Figure 8.1.

Figure 8.1: A field with a GSI

Create an Edit Menu

Finally, since there is a field on the form, it is important to have an Edit menu forvarious editing commands. Create a new Menu and change its name to Edit. Leavethe ID as the default value of 1100. Open the Edit menu for editing by double-clickingon it. In the menu editor, change the title from Menu to Edit. Then add the menuitems.

1. Press ctrl-K and type Cut. Tab once and enter the letter X to set theshortcut character for this item.

2. Press ctrl-K again, type Copy, tab and enter the letter C.3. Press ctrl-K again, type Paste, tab and enter the letter P. Unlike the other

shortcut characters, the one for pasting is not V like you might expect. Palmdecided that it was better to break with convention in this case, since GraffitiVs are often misentered as Us, causing unnecessary confusion.

4. Press ctrl-K again, type Undo, tab and enter the letter U.5. Press ctrl-K again, type Select All, tab and enter the letter S.

To associate this menu with a menu bar, close the menu editor and create a newMenu Bar Resource. Set its name to Create Form and open the menu bar editor forediting. Drag the newly-created Edit menu onto the menu bar editor, which shouldlook like Figure 8.2.


57/96


57

Figure 8.2: Edit menu onthe Create Form menu bar

Then, associate the menu bar withthe Create form. Open the Createform for editing and enter 1100 (the

ID of the menu bar resource) as theMenu Bar ID for the form. Thenclose the form editor and saveyour resource file before returningto the IDE.

Compile and Run

Make the project. Make sure POSE is displaying the App Launcher or the Preferencesscreen and then run the application on your emulator session. When you click on theCreate button, it will now take you to the updated create form with the field and thenew menu. You can enter text in the field with the keyboard, or use the mouse tocreate Graffiti strokes. If you use the mouse to create the Graffiti shift stroke (draw aline from bottom to top of the Graffiti area), you will see the GSI react and show up

appropriately. It will also display caps lock mode if you draw shift-shift in the Graffitiarea to create a locked shift situation.

You can use the menu items ortheir shortcut characters to modifythe text in the field (see Figure 8.3).Experiment with all the options Cut, Copy, Paste, Undo, and SelectAll. Try using the menu command

by selecting it from the menu andby using the shortcut key. To use

the shortcut characters, enter theshortcut Graffiti stroke (a diagonalline from the bottom left to the topright in the Graffiti area) followed

by the letter listed in the menu.

Figure 8.3: Choosing Select All on the field


While the Graffiti Shift Indicator is managed by the OS automatically, the field editingmenu items must be coded to have the desired effect. In the following paragraphs wewill look at the way the code was modified to give the appropriate functionality.

ErrandRsc.hOpen ErrandRsc.h in the editor. In the tFRM 1100 group, there are two newresources in the list:


58/96


58

#define CreateOtherField 1102

#define CreateOtherFieldGr

Documents

CodeWarrior for palm os