# Resource Reference

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.

## Top-level properties

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`).

### Properties

Icon caption

  The string that will be displayed in the application launcher and the various statistics windows (e.g. the memory usage list)

Version

  The string displayed in the Version view of the Info window

Vendor ID

  The four character long, case-sensitive vendor ID's should be globally unique -- contact PalmOS.com to register your vendor ID.

Target machine

  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.

## RCP code fragment

As of version 2.0, Guikachu does not support every RCP feature. To handle this, you can store arbitrary RCP fragments in your Guikachu files. 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 fragments, but this pretty much takes away the whole point of Guikachu.

Note that you can store multiple fragments in a single Guikachu document, to make things more organized.

### Properties

Resource ID

  Unlike the ID's of "real" resources, the ID of a fragment resource is not used in any way in the RCP output. Instead, ID's simply provide a way for you to label your blobs.

## String

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);

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

String

  The contents of the string

## String list

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.
     */

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Prefix

  This string is prepended to every list item when items are retrieved by the `SysStringByIndex` function.

## Dialog

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.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Title

  The title of the dialog, displayed in the title bar

Type

  Specifies the icon shown in the dialog. Please see the PalmOS Reference for a detailed description on when to use which mode

Help ID

  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.

Text

  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.

Buttons

  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.

## Menu bar

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.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

## Bitmaps and Bitmap Groups

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.

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Type

  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

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).

### Properties

Resource ID

  A unique string ID used for accessing the resource at run-time from the program

Title

  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.

Help ID

  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.

Menu ID

  The ID of a menu resource associated with the form.

Modal

  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.

Frame

  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.

Save behind

  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.

Default button

  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.

X and Y

  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.

Width and height

  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.