A PalmOS resource file contains, unsurprisingly, resources. A "resource" is a general term for static data stored inside the application's executable. Each resource is described by various properties.
To access the resources from the application, each resource has a unique ID. This ID is, internally, an unsigned integer. To make programmers' life easier, the resources also have a human-readable, textual ID. Guikachu only stores the text ID's, the numerical ID's are created by PilRC when it compiles the RCP file. A supplemental C header is also created by PilRC that contains the mapping between the numerical and the textual ID's.
There are some singleton properties that are associated with the project itself, and not one of the resources. These are automatically used by the application, i.e. you don't need to do anything in your code to make these apply.
You can edit these by double-clicking on the root element of
the resource tree (the one that initially reads
Application).
The string that will be displayed in the application launcher and the various statistics windows (e.g. the memory usage list)
The string displayed in the Version view of the Info window
The four character long, case-sensitive vendor ID's should be globally unique -- contact PalmOS.com to register your vendor ID.
There are some differences between handheld platforms that use the RCP format to describe resources, most notably, the screen size and resolution of some devices are not the same as that of vanilla Palm handhelds. Set this property to the device your project is targeting.
You can either choose from a list of devices with pre-configured values, or choose "Custom machine" to create a custom definition.
As of version 1.0, Guikachu does not support every RCP feature. To handle this, you can store arbitrary RCP fragments in so-called "blobs". No effort is made to parse these, so you will have to check the syntax yourself. Of course, there's nothing to stop you from storing supported resources like Forms in blobs, but this pretty much takes away the whole point of Guikachu.
Note that you can store multiple blobs in a single Guikachu document, to make things more organized.
String resources are used to store static, user-visible strings, separated from the code. To access them from your application, use the following code:
Char *msg = MemHandleLock (DmGetResource (strRsc, string_id));
/* Do something with the string */
MemPtrUnlock (msg);
String lists contain several, usually related, strings. The following code shows how you can access the items of a string list from your application:
MemHandle my_table_handle;
MemPtr my_table_ptr;
Int16 prefix_length, item_count;
/* Read and lock string table resource */
my_table_handle = DmGetResource('tSTL', my_stringtable_id);
my_table_ptr = (MemPtr) MemHandleLock(memTableHandle);
prefix_lenght = StrLen ((Char*) my_table_ptr);
/* The number of items is stored in two bytes after the prefix */
item_count = (*((UInt8 *)(my_table_ptr + prefix_length + 1)) << 8) |
(*((UInt8 *)(my_table_ptr + prefix_length + 2)));
my_table_items = SysFormPointerArrayToStrings (my_table_ptr + prefix_length + 3, item_count);
/* The original resource handle is no longer needed */
MemHandleUnlock (my_table_handle);
DmReleaseResource (my_table_handle);
/*
* You are now only responsible for freeing my_table_items
* when you're done with it. Everything else has been properly
* cleared up.
*/
A dialog is a modal window, with a title, some text, an icon, and one or more buttons. It can also include a reference to a string resource that is used in the pop-up help.
A unique string ID used for accessing the resource at run-time from the program
The title of the dialog, displayed in the title bar
Specifies the icon shown in the dialog. Please see the PalmOS Reference for a detailed description on when to use which mode
The (optional) resource ID of a string that describes the usage of the dialog. If specified, the title bar of the dialog will include a ? button to display the help.
The text to be displayed in the dialog (to the right of the dialog icon). You can use up to three ^ marks (^1, ^2 and ^3 to indicate placeholders for strings that are filled at run-time.
The Buttons list is an ordered list of strings. Each of
these strings will create a button at the bottom of the
dialog. The return value of FrmAlert
will be the index of the button pressed (starting at 0).
If the user exits the dialog by switching to another
application, FrmAlert will return
with the default button's index.
A menu bar is a horizontal strip on the top of the screen, containing drop-down menus. Since selecting a menu item takes numerous clicks, often-used operations should be accessible through other means.
The menus are single-level deep. Each menu item has a unique ID, a user-visible label, and an optional shortcut letter, which can be accessed using the shortcut (/) graffiti sign.
The actual implementation of the menu items are done by
looking at the itemID in the
menuEvent handler of the form owning the menu bar.
Bitmaps are pictures stored inside resource files. They can be both accessed by the application pixel-by-pixel, or referenced in other parts of a resource file and thus displayed by PalmOS in forms. Guikachu is not a picture editing application, so you must first create the picture separately, then load it via Guikachu into a Bitmap or a Bitmap Group.
Bitmaps in PalmOS are stored in one of several color depths, including both greyscale and color ones. A Bitmap resource contains a single image in a single color depth. A Bitmap Group can contain more than one image, and PalmOS automatically chooses the best (most colorful) for the given device's capability.
Due to a limitation in PalmOS itself, 16-color greyscale and color images are mutually exclusive, so you can only store one of the two in any given Bitmap Group.
A unique string ID used for accessing the resource at run-time from the program
For single-bitmap resources, this property stores the type (color depth) of the image. The actual image data may contain more colors than specified here, and those colors will not be lost, but won't be used when displaying the image.
Form is the PalmOS term for windows. A form represents a rectangular area on the screen that can hold an arbitrary number of widgets. The maximum size of a form is 160 pixels high by 160 pixels wide: this is the same as the size of the Palm screen itself.
You can also use a form as a modal dialog via the
FrmDoDialog function. This works just like
FrmAlert and will block your application until a
button is pressed on the form. The return value of the
function will be the ID of the button pressed (or the
default button's
ID if the form is closed by switching to another application).
A unique string ID used for accessing the resource at run-time from the program
The title of the form, shown on the top of it. Its actual rendering is dependent on the form's modalness.
If not set, some form decorations are not drawn, thus giving you even more screen real estate to place your widgets on. Category selectors are often placed in the title area's right edge.
If this is set to a valid string resource, and the form is modal, a help button is displayed in the title area of the form, which, when clicked, pops up a dialog containing the help text.
The ID of a menu resource associated with the form.
Modal forms are used for "blocking" dialogs, when events outside the topmost form are not processed. Modal forms have different decoration than non-modal ones. Dialog resources provide an easy-to-use mechanism for displaying simple modal forms.
Non-modal forms can have an optional one-pixel wide frame. Modal forms always have a frame with a width of two pixels, regardless of this property's value.
If checked, the form will save the screen contents before it is drawn, and then restore it when closed. Use this for pop-up dialogs, otherwise they might cause artifacts on the screen.
It is possible to use a form as a custom modal
dialog via the
FrmCustomAlert function. In this case, this
property sets the button the function should return when
the users switches to another application instead of
clicking on a dialog button.
Horizontal and vertical position, in pixels, counted from left to right and top to bottom. Due to the size of the screen of PalmOS devices, both X and Y are integer values between 0 and 159.
Horizontal and vertical size, in pixels. Due to the size of the screen of PalmOS devices, both width and height are integer values between 1 and 160.
| Previous: Using the Form Editor | Index | Next: Widget Reference |