.FLYINGHEAD PROGRAMMING POWER
.TITLE Resources, forms and controls
.DEPT
.SUMMARY Alan Jay Weiner continues his course in PalmPilot programming in this latest installment of Programming Power. All the user interface items you use on your PalmPilot, like menus and buttons, are called "resources". In this article, Alan shows you how you can implement resources in your programs.
.AUTHOR Alan Jay Weiner
Last month, we walked through a "simple" "hello, world" application. While we covered the code in almost tedious, thorough detail, I glossed over the resources somewhat. Resources are as important as the code itself; they’re intricately entwined together. So this month we’ll look at resources, forms, and controls. Grab a cup of coffee and let’s begin!
.H1 What are resources?
Resources are "things" that a program can use. A resource could be as simple as a text string or as complicated as a screen form with menus, buttons, fields, and other resource "things." Forms and controls are types of resources.
Resources are essentially data structures tacked onto the end of the program file. Some Palm OS APIs expect to use certain resources; others you use by requesting a pointer and using the data at that address. For example, you might want to display a bitmap with your company logo. With the bitmap attached as a resource, you’d get a pointer to it by calling DmGet1Resource(), then display the bitmap by calling WinDrawBitmap(). Attaching the bitmap as a resource saves you from using up precious limited data and program space. While the resource could simply be in a separate data file, attaching them to the program is convenient – they’re always there when you need them.
Resources can also be modified without changing the program itself. For example, if an application’s text messages are all resources, changing the messages to a different language involves just using a different set of resources, rather than recompiling the program.
Some resources can refer to other resources. For example, a form resource is built out of a collection of control resources (buttons, fields, lists, etc.). Rather than using each resource individually, you’d simply say "display the form" and the OS’s form-displayer knows to display all the other resources. That form might also have a "help" message which would point to a string resource. When the user hits the "i" on the menu bar, the form handler automatically displays the string resource.
After the program is compiled and linked, another tool builds the necessary data structures from a description of the resources, then attaches those structures to the program file. The program carries the resources on its back like a camper with a backpack full of supplies.
"Hello world" only used a few resources. It uses a couple of forms, a couple of menus, and a bitmap. Most programs use many more.
In fact, even the program’s code and data are stored as resources; the .PRC file is a header structure followed by everything else as various resources.
.H1 Resources are just data structures
For the most part, we don’t care about the resource’s structure itself; just what capabilities that resource has, how we refer to the resource, and what we can do with it.
String resources are just that: a text string. We can request a pointer to the string, and we can use the string (referenced via that pointer) or we can reference the string by another resource (as the ‘help’ message for a form, for example). Form resources are far more complex, but we simply refer to them by their identification number; we would call FrmGotoForm(1000) to go to form number 1000.
Each resource is identified by a resource type and an identification number. Palm has defined a number of resource types. Some of these will already be familiar to Macintosh programmers. Each resource type is a four-character name; the string resource above is ‘tSTR’. The resource-development tools handle all the name issues for us, but it’s useful to be familiar with them; occasionally you’ll see reference to "a Talt" or "a tAIN" resource. The sidebar "Resource Types" lists many of the common resource types.
.H1 Forms are a collection of resources
Each of the controls on a form can be a resource by itself, but when they’re built into a form, they become an integral part of the data structure defining that form. The form data structure contains information about the form itself (such things as height and width); the data structure for each control is concatenated to the form’s structure.
Other resources, such as the help message or the form’s menu, are separate resources within the application file but are referenced from the form’s data structure.
This all happens automatically. You don’t need to do anything special to make this happen. You simply build a form using the appropriate tools for your development environment. The tools build the right structures.
.H1 Building Resources
CodeWarrior and GCC use different tools to build resources.
CodeWarrior provides a graphical utility called "Constructor" while GCC uses a text script and the PilRC utility. Unfortunately, there’s no easy way to convert from one to the other. If you have a program written using one compiler, it’s pretty easy to compile it using the other, but the resources need to be recreated manually.
.H1 Building resources with CodeWarrior’s Constructor
While a complete tutorial on Constructor is beyond the scope of this column, the basics are described here.
You open a resource "project" which shows a list of the various resources for that application. Figure A shows the resource project for the "hello world" application. This project is different than the CodeWarrior IDE (Interactive Development Environment) project; the IDE project file uses an .MCP extension while the resource project is a .RSRC extension. The .RSRC file will be included in the IDE’s project as a dependent file.
.FIGPAIR A Constructor displays the .RSRC file as a list of resources.
Figure B shows the application’s main form. The left pane shows the form’s information. Simply click on a field to change it.
.FIGPAIR B The form resource. The left pane shows the form’s parameters.
As the form is changed, the right pane displays the form’s image. To place a control (i.e., a button) drag it from Constructor’s "catalog" window, as shown in Figure C, and drop it onto the form.
.FIGPAIR C The "catalog" of controls; drag-and-drop these onto forms.
Selecting a control by dropping it onto the form or by clicking on an existing control allows you to edit the control’s data. Figure D shows the form with the label control selected. The left pane shows the label’s data.
.FIGPAIR D The same form resource as in Figure 2, after clicking on the "hello world" label.
There are several glitches with Constructor, at least on the Windows version. These will likely be fixed in future releases, but I’ll list them here to save you some hair-pulling.
First, Constructor creates two .RSRC files: the first is a zero-length file, the second is in the Resource.frk directory beneath it. That second file is the one with the real information in it, but the IDE project should include the first (zero-length) file. If you accidentally include the lower file, you’ll get problems with linking. This is an anomaly due to the tools Metrowerks uses; the tools allow them to create both a Macintosh and Windows version. It’s odd, ugly, and the way things are. Just mentally ignore the copy in Resource.frk (the one with the actual data) and always refer to the zero-length file. If you have problems opening a resource project you may be opening the wrong one.
Second, no you can’t double-click on the resource file in the IDE and open up Constructor (as you would double-click on a source file to edit it). You need to start Constructor and select Open Project File from the File menu. Be sure to open the upper (zero-length) .RSRC file – Constructor knows to open the real one beneath it.
Third, creating an image using Windows Paint and cut-and-pasting it into a bitmap resource in Constructor will sometimes fail. When it does, you’ll see the image, but as if it’s been shifted horizontally. If this happens, change the Paint settings so you’re creating a color bitmap. Then you should be able to cut-and-paste it successfully.
Despite these problems, Constructor is convenient and fairly easy to use.
.H1 Building resources with GCC (PilRC)
GCC uses the PilRC utility to compile a text script into the resource data structures. You describe each resource with a series of commands.
Listing 1 shows the resource script (see http://www.component-net.com/pp-extras/mainform.html) for the "Hello World" application. The line starting with "LABEL" describes the same label displayed in Figure D.
The ID numbers are defined in the include file "hello.h"
One major advantage to PilRC is that this script is easily printed. It would be quite difficult to describe the Constructor-built resources in human-readable terms.
.H1 The user interface is mostly resources
Most of an application’s user interface will be built using resources. The "Hello World" application’s user interface consisted of two forms. Each form contained some text and a control or two. The main form used a menu resource. Only the "hello again" message was explicitly drawn; the rest of it all was resources.
Since forms are the basis for almost all the user interface, let’s finish this month with a detailed look at the main form resource.
.H1 The form resource in detail
A form has various attributes, such as its position (if smaller than full-screen), its height, width, and so on. As mentioned before, it can contain control resources within it, and may use certain other resources like a string resource as the help text, and a menu resource.
Looking again at Figure B (which we’ve redisplayed below), we see the main form as built in Constructor. This corresponds to the lines between "FORM ID MainForm" and "END" in Listing 1 (see http://www.component-net.com/pp-extras/mainform.html).
.FIGPAIR B The main form built in Constructor.
The attributes of the form are shown in the left pane. Each element may be edited by clicking on the value and typing in a new value. These are the elements in the form’s data structure itself; the control resources will be tacked on following this data. We don’t need to worry about the actual structure layout. That’s all handled by Constructor.
The left and top origin define the screen coordinate where the top-left corner of the form is placed. The physical screen is 160 pixels across and 160 pixels tall. The origin coordinates range from zero to 159. (0,0) is the top left of the screen.
The width and height define the size of the form in pixels. A full-screen form is 160 by 160. The main form of Hello World uses the full screen.
Most controls have a "usable" attribute. If it is not usable, it will not be drawn when the rest of the form is displayed. Since forms aren’t drawn until you explicitly switch to the form, they will always be marked "usable."
"Modal" indicates whether the form’s event handler should deal with pen events outside the form. A modal form will ignore any pen-taps outside itself. Modal forms also have a border – it’s drawn by the form displayer during the FrmDrawForm call. You might want to refer back to April’s Programming Power column to review the form-open events.
"Save Behind" tells Palm OS to save the portion of the screen which will be obscured by this form when it draws the form. When the form is closed, Palm OS will automatically restore that part of the screen. I’ve had odd results with this at times; sometimes things underneath the form show through when the form is first drawn. When that happens, typically setting "save behind" will fix it, even though "save behind" should cause things the other way around. It should leave garbage when the form is closed rather than mess it up when it’s first drawn.
"Form ID" is the resource’s identification number. Remember when I said resources have a type and an ID? This is the ID. The type is ‘tFRM’ by the way.
Constructor can create a header file with these IDs. See Listing 1 (see http://www.component-net.com/pp-extras/mainform.html); near the bottom where it says "header file name" and "auto generate header file" is checked; this tells Constructor to write all the IDs in a file called HelloRsc.H. In this case, the form name will be MainForm.
"Help ID" isn’t used in this particular form. That’s why it’s greyed out. If we wanted a help message for this form, we would make the ID a number other than zero, and we would define a string resource with the text. The Create button is a convenience; we could also go to the project window, click on "strings" and then create a new string by selecting New String Resource from the Edit menu command.
When a form has help text, the form displayer automatically makes the menu bar the full width of the form, and puts the "i" button at the right.
"Menu bar" indicates the identification number of the menu resource. Like Create for the help ID, the Edit button is a convenience. If the menu resource hasn’t been created, the edit button will be a Create button.
When the system closes a form automatically, as it would when it switches to another application, it will simulate pressing the "Default button ID" button. In this case, there is no default button.
Finally, the "form title" is just that: the title shown on the menu bar. The "hex" button displays the title text as hex values. This is convenient when using non-alphanumeric characters.
Looking at Listing 1 (see http://www.component-net.com/pp-extras/mainform.html), you can see how PilRC uses similar terminology to define the form. "FORM ID MainForm AT (0 0 160 160)" indicates the top and left origins and the height and width. "MENUID MainFormMenuBar" indicates the ID number of the menu resource, which is defined a few lines later.
.BEGIN_KEEP
.H1 Next month
Now that we’ve finished our coffee (and in a few cases, the whole pot!) we’ll tie things off here. Next month we’ll look at some of the user-interface controls; what they do and how to use them.
.BEGIN_SIDEBAR
.H1 Common Resource Types
Each resource is identified by a type and an ID number, as shown in Table A. These are some of the common types; you’ll occasionally see them mentioned in articles or newsgroup and maillist messages. For the most part, you won’t deal with the type codes; you’ll just deal with a resource of a particular variety. The type codes are case-sensitive.
.BEGIN_TAB_TABLE A Typical PalmPilot Resource Codes
.TAB_TABLE_HEADER Resource Description
.TAB_TABLE_ROW code program code
.TAB_TABLE_ROW data program data
.TAB_TABLE_ROW MBAR menu bar (typically referenced by a form resource)
.TAB_TABLE_ROW MENU menu options (referenced by a MBAR menu bar)
.TAB_TABLE_ROW tAIB icon bitmap; the icon displayed by the launcher
.TAB_TABLE_ROW tAIN application name; the name displayed on the launcher.
.TAB_TABLE_ROW tAIS application information string, a series of strings, typically passed to CategoryIntitialize() as the initial category names
.TAB_TABLE_ROW Talt "Alert" dialog
.TAB_TABLE_ROW Tbmp bitmap resource
.TAB_TABLE_ROW tBTN button control
.TAB_TABLE_ROW tCBX checkbox control
.TAB_TABLE_ROW tFBM form bitmap
.TAB_TABLE_ROW tFLD field control
.TAB_TABLE_ROW tFRM form
.TAB_TABLE_ROW tGDT gadget control
.TAB_TABLE_ROW tGSI graffiti shift indicator
.TAB_TABLE_ROW tLBL label
.TAB_TABLE_ROW tLST list box
.TAB_TABLE_ROW tPBN pushbutton control
.TAB_TABLE_ROW tPUL popup list
.TAB_TABLE_ROW tPUT popup trigger
.TAB_TABLE_ROW tREP repeating button control
.TAB_TABLE_ROW tSLT selector trigger
.TAB_TABLE_ROW tSTR String resource – simply a text string
.TAB_TABLE_ROW tTBL table
.TAB_TABLE_ROW tTTL title
.TAB_TABLE_ROW tver application version information
.END_TAB_TABLE
.END_SIDEBAR
.BIO Alan Weiner is an independent software developer and a Senior Engineer at Communica, Inc. His email address is alan@ajw.com.
.DISCUSS http://www.component-net.com/webx?13@@.ee6bed7
.END_KEEP
