PilRC

`About - Download - History - Archive - Manual - Contributors`

## PilRC v2.8 User Manual | Aaron Ardiri (aaron@ardiri.com) 1 May 2001

Check the PilRC Home Page for the latest version.

Description

PilRC | A resource compiler for the Palm Computing Platform

Table of Contents

Usage
Understanding the Manual
Resource Language Reference
International Support
Known Bugs
Further Reading

Usage

    pilrc   [-L LANGUAGE] [-I INCLUDE PATH] [-D MACRO(=VAL)] [-R RESFILE]
            [-q] [-V] [-Fh] [-Fj] [-F5] [-Fg] [-Fkm] [-Fkt] [-allowEditID] [-LE32]
    	file.rcp [output path]
    pilrcui [-L LANGUAGE] file.rcp

-L LANGUAGE | Generate resource files for target language, LANGUAGE.
-I INCLUDE PATH | Search INCLUDE PATH when looking for include or bitmap files. NOTE: multiple paths be repeating the -I option.
-D MACRO[=VAL] | Define a pre-processor symbol with an optional value. The macros defined with the -D option can be referenced in #ifdef statements in the resource file for conditional compilation. NOTE: if no value is specified, the symbol will given the value of 1.
-R RESFILE | Output a `.res` file specifying all the resources emitted by `PilRC`.
-H INCFILE | Output a `.h` file containing auto-generated resource item IDs for resource items that were defined without an ID previously. NOTE: If -H is not specified then undefined IDs are considered errors.
-q | Less noisy output, for you minimalists.
-V | Generate M$ (VS-style) warning/error output (default is GNU-style).
-Fh | Use Hebrew font widths for AUTO width calculations.
-Fj | Use Japanese font widths for AUTO width calculations.
-F5 | Use Chinese (Big5) font widhts for AUTO width calcuations.
-Fg | Use Chinese (GB) font widhts for AUTO width calcuations.
-Fkm | Use Korean font widhts for AUTO width calcuations (Hanme font)
-Fkt | Use Korean font widhts for AUTO width calcuations (Hantip font)
-allowEditID | Allow the use of "edit menu" ID values (10000-10007 inclusive).
-LE32 | Generate Little Endian 32 bits compatible resources (ARM, NT)
file.rcp | Input file describing the resources to be emitted. Each resource is written as a separate file in the output path directory. The output filename is constructed by appending the hexcode resource ID to the four character resource type.
output path | Directory where .bin files should be generated.

Example:

    pilrc myprogram.rcp
    pilrc -I c:\resources -L FRENCH myprogram.rcp
    pilrc -I c:\resources -L BIG5 -F5 -R myprogram.res myprogram.rcp c:\output

Understanding the Manual

Syntax

Items in all CAPS appear as literals in the file.
Items enclosed in "<" and ">" are required fields.
Items enclosed in "[" and "]" are optional fields.

Each field's required type is indicated by a suffix after the field name (see below for types).

Types

`.i` | identifier example: `kFoo`
`.c` | character (may contain normal C style character escapes) example: `"O"`
`.s` | string (may contain normal C style character escapes) example: `"Click Me"`
`.ss` | multi line string `PilRC` will concatenate strings on seperate lines example: `"Now is the time for all good " \` `"men to come and aid of their country"`
`.n` | number defined constant or simple arithmetic expression. Valid operators are "+", "-", "*" and "/". Precendence is left to right, unless changed with the use of parenthesis. NOTE: Math calculations are integer based. example: `23` `12+3+1` `12*(2+3)` `'PALM'`
`.p` | position co-ordinate may be a number, expression or one of the following keywords.
`AUTO` | Automatic width or height. Value is computed based on the text in the item.
`CENTER` | Centers the item either horizontally or vertically.
`CENTER@<coord.n>` | Centers the item at the co-ordinate following.
`RIGHT@<coord.n>` | Aligns the item at the right co-ordinate following.
`BOTTOM@<coord.n>` | Aligns the item at the bottom co-ordinate following.
`PREVLEFT` | Previous items left co-ordinate.
`PREVRIGHT` | Previous items right co-ordinate.
`PREVTOP` | Previous items top co-ordinate.
`PREVBOTTOM` | Previous items bottom co-ordinate.
`PREVWIDTH` | Previous items width.
`PREVHEIGHT` | Previous items height.
example: `PREVRIGHT+2` `CENTER@80/2` NOTE: `AUTO` and `CENTER` are not valid in arithmetic expressions.

Comments

Single line comments begin with "`//`".
Block comments exist between the "`/*`" and "`*/`" tokens.

NOTE: "`//`" comments within the definition of objects are treated as errors.

Include Files

The `.rcp` file may contain `#include` directives.
This allows a programmer to have one header file for their project containing pre-defined resource IDs. Source code can reference the symbols as can `PilRC`.

`PilRC` understands three include file formats.

`.h` | `#define <Symbol.i><Value.n>`
`.inc` | `<Symbol.i> equ <Value.n>`
`.java, .jav` | `package <PackageName> public class <ClassName> { public static final short <Symbol.i> = <Value.n>; }`

Once defined, a symbol can be used in place of any number.
NOTE: `#ifdef` derivatives are ignored by `PilRC`.

Resource Language Reference

The `.rcp` file may contain the following object definitions:

FORM | Form Resource
MENU | Form Menu Bar
ALERT | Alert Dialog Resource
VERSION | Version String
STRING | String Resource
STRINGTABLE | String List Resource
CATEGORIES | Default Category Names
APPLICATIONICONNAME | Application Icon Name
APPLICATION | Application Creator Identification
LAUNCHERCATEGORY | Default launcher Category Name
ICON ICONFAMILY | Icon Bitmap Resource
SMALLICON SMALLICONFAMILY | Small Icon Bitmap Resource
BITMAP BITMAPGREY BITMAPGREY16 BITMAPCOLOR16 BITMAPCOLOR BITMAPCOLOR16K BITMAPCOLOR24K BITMAPCOLOR32K BITMAPFAMILY BITMAPFAMILYSPECIAL BOOTSCREENFAMILY | Bitmap Resource
TRAP | HackMaster Trap Resource
FONT | User Defined Font Resource
FONTINDEX | Font Index table for Font Resource
HEX | Binary Resource (Hex/String based)
DATA | Binary Resource (Data File based)
INTEGER | 2-byte Integer Value
BYTELIST | 1-byte Integer Value List
WORDLIST | 2-byte Integer Value List
LONGWORDLIST | 4-byte Integer Value List
PALETTETABLE | Color List Resource
FEATURE | System reserved
GRAFFITIINPUTAREA | System reserved
COUNTRYLOCALISATION | System reserved
KEYBOARD | System reserved
MIDI | Copy .aif to a Palm midi Resource
TRANSLATION | Language String Translation Resource

FORM (tFRM)

    FORM ID <FormResourceId.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>)
      [FRAME] [NOFRAME]
      [MODAL]
      [SAVEBEHIND] [NOSAVEBEHIND]
      [USABLE]
      [HELPID <HelpId.n>]
      [DEFAULTBTNID <BtnId.n>]
      [MENUID <MenuId.n>]
    BEGIN
      <OBJECTS>
    END

Where `<OBJECTS>` is one or more of:

`TITLE` | `<Title.s>`
`BUTTON` | `<Label.s> ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE] [DISABLED] [LEFTANCHOR] [RIGHTANCHOR] [FRAME] [NOFRAME] [BOLDFRAME] [FONT <FontId.n>] [GRAPHICAL] [BITMAPID <BitmapId.n>] [SELECTEDBITMAPID <BitmapId.n>]`
`PUSHBUTTON` | `<Label.s> ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE] [DISABLED] [LEFTANCHOR] [RIGHTANCHOR] [FONT <FontId>] [GROUP <GroupId.n>] [GRAPHICAL] [BITMAPID <BitmapId.n>] [SELECTEDBITMAPID <BitmapId.n>]`
`CHECKBOX` | `<Label.s> ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE] [DISABLED] [LEFTANCHOR] [RIGHTANCHOR] [FONT <FontId.n>] [GROUP <GroupId.n>] [CHECKED]`
`POPUPTRIGGER` | `<Label.s> ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE] [DISABLED] [LEFTANCHOR] [RIGHTANCHOR] [FONT <FontId.n>] [GRAPHICAL] [BITMAPID <BitmapId.n>] [SELECTEDBITMAPID <BitmapId.n>]`
`SELECTORTRIGGER` | `<Label.s> ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE] [DISABLED] [LEFTANCHOR] [RIGHTANCHOR] [FONT <FontId.n>] [GRAPHICAL] [BITMAPID <BitmapId.n>] [SELECTEDBITMAPID <BitmapId.n>]`
`REPEATBUTTON` | `<Label.s> ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE] [DISABLED] [LEFTANCHOR] [RIGHTANCHOR] [FRAME] [NOFRAME] [BOLDFRAME] [FONT <FontId.n>] [GRAPHICAL] [BITMAPID <BitmapId.n>] [SELECTEDBITMAPID <BitmapId.n>]`
`LABEL` | `<Label.s> ID <Id.n> AT (<Left.p> <Top.p>) [USABLE] [NONUSABLE] [FONT <FontId.n>]`
`FIELD` | `ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE] [DISABLED] [LEFTALIGN] [RIGHTALIGN] [FONT <FontId.n>] [EDITABLE] [NONEDITABLE] [UNDERLINED] [SINGLELINE] [MULTIPLELINES] [DYNAMICSIZE] [MAXCHARS <MaxChars.n>] [AUTOSHIFT] [NUMERIC] [HASSCROLLBAR]`
`POPUPLIST` | `ID <ControlId.n> <ListId.n>`
`LIST` | `<Item.s> ... <Item.s> ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE] [DISABLED] [VISIBLEITEMS <NumVisItems.n>] [FONT <FontId.n>]`
`FORMBITMAP` | `AT (<Left.p> <Top.p>) [BITMAP <BitmapId.n>] [USABLE] [NONUSABLE]`
`GADGET` | `ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE]`
`TABLE` | `ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [ROWS <NumRows.n>] [COLUMNS <NumCols.n>] [COLUMNWIDTHS <Col1Width.n> ... <ColNWidth.n>]`
`SCROLLBAR` | `ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE] [VALUE <Value.n>] [MIN <MinValue.n>] [MAX <MaxValue.n>] [PAGESIZE <PageSize.n>]`
`GRAFFITISTATEINDICATOR` | `AT (<Left.p> <Top.p>)`
`SLIDER` | `ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE] [DISABLED] [VERTICAL] [FEEDBACK] [THUMBID <BitmapId.n>] [BACKGROUNDID <BitmapId.n>] [VALUE <Value.n>] [MIN <MinValue.n>] [MAX <MaxValue.n>] [PAGESIZE <PageSize.n>]`

Notes:

- `ID <Id.n>` can be replaced with `AUTOID`. `PilRC` will assign an identifier for each control which specifies `AUTOID`. This is useful for controls which you won't refer to within the application (ie: LABEL's). Auto ID's begin at at 9000 and increase sequentially.
- The bitmap referenced by the `FORMBITMAP` tag must appear as a seperate resource in the rcp file via the `BITMAP` tag.
- `MAXCHARS` is required for `FIELD` tag to work properly.

- Any user defined fonts defined by `FONT` >= 128 and `FONT` <= 255 must be before above the FORM definition using the `FONT` tag.

- Any translations defined in the must be declared before the FORM definition using the `TRANSLATION` tag.

Example:

    FORM ID 1 AT (2 2 156 156)
      USABLE MODAL
      HELPID 1
      MENUID 1
    BEGIN
      TITLE "AlarmHack"
      LABEL "Repeat Datebook alarm sound" AUTOID AT (CENTER 16)
      PUSHBUTTON "1" ID 2001 AT (20 PrevBottom+2 12) AUTO GROUP 1
      PUSHBUTTON "2" ID 2002 AT (PrevRight+1 PrevTop PrevWidth PrevHeight) GROUP 1
      PUSHBUTTON "3" ID 2003 AT (PrevRight+1 PrevTop PrevWidth PrevHeight) GROUP 1

      LABEL "times. Ring again every" AUTOID AT (CENTER PrevBottom+2) FONT 0

      PUSHBUTTON "never" ID 3000 AT (13 PrevBottom+2 32 12) GROUP 2
      PUSHBUTTON "10 sec" ID 3001 AT (PrevRight+1 PrevTop PrevWidth PrevHeight) GROUP 2
      PUSHBUTTON "30 sec" ID 3002 AT (PrevRight+1 PrevTop PrevWidth PrevHeight) GROUP 2
      PUSHBUTTON "1 min" ID 3003 AT (PrevRight+1 PrevTop PrevWidth PrevHeight) GROUP 2

      LABEL "Alarm sound:" AUTOID AT (24 PrevBottom+4)
      POPUPTRIGGER "" ID 5000 AT (PrevRight+4 PrevTop 62 AUTO) LEFTANCHOR
      LIST "Standard" "Bleep" ID 6000 AT (PrevLeft PrevTop 52 1) VISIBLEITEMS 2 NONUSABLE
      POPUPLIST ID 5000 6000

      BUTTON "Test" ID 1202 AT (CENTER 138 AUTO AUTO)
      GRAFFITISTATEINDICATOR AT (100 100)
    END

MENU (MBAR)

    MENU ID <MenuResourceId.n>
    BEGIN
      <PULLDOWNS>
    END

Where `<PULLDOWNS>` is one or more of:

    PULLDOWN <PullDownTitle.s>
    BEGIN
      <MENUITEMS>
    END

Where `<MENUITEMS>` is one or more of:

    MENUITEM <MenuItem.s> ID <MenuItemId.n> [AccelChar.c]
    MENUITEM SEPARATOR

Example:

    MENU ID 100
    BEGIN
      PULLDOWN "File"
      BEGIN
        MENUITEM "Open..." ID 100 "O"
        MENUITEM SEPARATOR
        MENUITEM "Close..." ID 101 "C"
      END
      PULLDOWN "Options"
      BEGIN
        MENUITEM "Get Info..." ID 200 "I"
      END
    END

ALERT (Talt)

    ALERT ID <AlertResrouceId.n>
      [HELPID <HelpId.n>]
      [DEFAULTBUTTON <ButtonIdx.n>]
      [INFORMATION] [CONFIRMATION] [WARNING] [ERROR]
    BEGIN
      TITLE <Title.s>
      MESSAGE <Message.ss>
      BUTTONS <Button.s> ... <Button.s>
    END

Notes:

- The `DEFAULTBUTTON` tag can be used to specify the button number to select if the user switches to another application without pressing any button in the alert. The argument is the index of the button, where the left-most button is at index '0'.

Example:

    ALERT ID 1000
      HELPID 100
      DEFAULTBUTTON 1
      CONFIRMATION
    BEGIN
      TITLE "AlarmHack"
      MESSAGE "Continuing will cause you 7 years of bad luck\n" \
              "Are you sure?"
      BUTTONS "Ok" "Cancel"
    END

VERSION (tver)

    VERSION ID <VersionResourceId.n> <Version.s>
    VERSION <Version.s>

Notes:

- The ID can be 1 or 1000 - either will be accepted by the default launcher.

Example:

    VERSION ID 1 "1.0 beta"
    VERSION "1.0 beta"

STRING (tSTR)

    STRING ID <StringResourceId.n> <String.ss>
    STRING ID <StringResourceId.n> FILE <StringFile.s>

Example:

    STRING ID 100 "This is a very long string that shows escape characters \n" \
                  "as well as continued .ss syntax strings"
    STRING ID 101 FILE "string.txt"

STRINGTABLE (tSTL)

    STRINGTABLE ID <StringTableResourceId.n> <PrefixString.ss>  ... <String.ss>

Notes:

- Using the `tSTL` resource:

  .. in a LIST

    [source.rcp]
    STRINGTABLE stringTableMetric
      "" "Litres" "Meters" "Celsius"    "Newtons"     "Kilograms"

    [source.c]
    MemHandle memHandle, memStringList;
    MemPtr    ptrTable;
    UInt16    count;

    memHandle = DmGetResource('tSTL', stringTableMetric);
    ptrTable  = (MemPtr)MemHandleLock(memHandle);

    // get the string count <-- "messy"
    count     =
      (*((UInt8 *)(ptrTable + StrLen((Char *)ptrTable) + 1)) << 8) |
       *((UInt8 *)(ptrTable + StrLen((Char *)ptrTable) + 2));

    // get the handle to an array of strings
    memStringList =
      SysFormPointerArrayToStrings(ptrTable + StrLen((Char *)ptrTable) + 3, count);

    // NOTE: the "prefix" is ignored here
    ...

    MemHandleUnlock(memHandle);
    DmReleaseResource(memHandle);

.. to get a single STRING

    [source.rcp]
    STRINGTABLE stringTableTypes
      "Units are:" "Metric" "Imperial"

    [source.c]
    Char string[32];
    SysStringByIndex(stringTableTypes, 0, string, 32);

- a limitation of 384 strings apply

  Example:

    STRINGTABLE ID 100 "" "One" "Two" "Three" "Four"
    STRINGTABLE ID 100 "-" "One" "Two" "Three" "Four"

CATEGORIES (tAIS)

    CATEGORIES ID <CategoryResourceId.n> <Category1.s> ... <Category2.s>

Notes:

- The CATEGORIES tag can be used to specify the default category names for the application.
  This resource can then be passed to the "CategoryInitialize()" API function function to create the category strings in the application info block.

Example:

    CATEGORIES ID 100 "Unfiled" "Business" "Personal"

APPLICATIONICONNAME (tAIN)

    APPLICATIONICONNAME ID <AINResourceId.n> <ApplicationName.s>

Example:

    APPLICATIONICONNAME ID 100 "AlarmHack"

APPLICATION (APPL)

    APPLICATION ID <ApplResourceId.n> <APPL.s>

Notes:

- `<APPL.s>` must be 4 characters long.
- `<APPL.s>` represents the creator id for the application, which can be registered at http://www.palm.com/

Example:

    APPLICATION ID 1 "PALM"

LAUNCHERCATEGORY (taic)

    LAUNCHERCATEGORY [ID <LaunchCatResourceId.n>] <APPL.s>

Example:

    LAUNCHERCATEGORY "Games"
    LAUNCHERCATEGORY ID 1000 "Games"

ICON (tAIB)

    ICON [ID <IconResourceId.n>] <IconFileName.s>
    ICONFAMILY [ID <IconResourceId.n>]
               <BitmapFileName.s> ... <BitmapFileName.s>
               [NOCOLORTABLE] [COLORTABLE]
               [TRANSPARENT r g b] [TRANSPARENTINDEX index]

Notes:

- The bitmap must be 32x32, 32x22 or 22x22 in dimension.
- Compression is not available for ICONS.
- A `tAIB` resource with ID 1000 is created unless an alternate ID is specified.
- `ICON` creates a monochrome icon resource.
- `ICONFAMILY` creates a multibit (1bpp, 2bpp, 4bpp and 256 color) icon resources.
- The inclusion of the bitmap color table is not recommended as it slows down system performance. PilRC implements a simple color table matching algorithm to match the bitmaps colortable to the system palette.
- When an alternate ID is used for the ICON resource, bitmap size is not checked.

Example:

    ICON "myicon.bmp"
    ICONFAMILY "icon1bpp.bmp" "icon2bpp.bmp"
    ICONFAMILY "icon1bpp.bmp" "icon2bpp.bmp" "icon4bpp.bmp" "icon8bpp.bmp"
    ICONFAMILY "icon1bpp.bmp" "" "" "icon8bpp.bmp" TRANSPARENTINDEX 255

SMALLICON (tAIB)

    SMALLICON [ID <IconResourceId.n>] <IconFileName.s>
    SMALLICONFAMILY [ID <IconResourceId.n>]
                    <BitmapFileName.s> ... <BitmapFileName.s>
                    [NOCOLORTABLE] [COLORTABLE]
                    [TRANSPARENT r g b] [TRANSPARENTINDEX index]

Notes:

- The bitmap must be 15x9 in dimension.
- Compression is not available for SMALLICONS.
- A `tAIB` resource with ID 1001 is created unless an alternate ID is specified.
- `SMALLICON` creates a monochrome icon resource.
- `SMALLICONFAMILY` creates a multibit (1bpp, 2bpp, 4bpp and 256 color) icon resources.
- The inclusion of the bitmap color table is not recommended as it slows down system performance. PilRC implements a simple color table matching algorithm to match the bitmaps colortable to the system palette.
- When an alternate ID is used for the SMALLICON resource, bitmap size is not checked.

Example:

    SMALLICON "mysmicon.bmp"
    SMALLICONFAMILY "smic1bpp.bmp" "smic2bpp.bmp"
    SMALLICONFAMILY "smic1bpp.bmp" "smic2bpp.bmp" "smic4bpp.bmp" "smic8bpp.bmp"
    SMALLICONFAMILY "smic1bpp.bmp" "" "" "smic8bpp.bmp" TRANSPARENTINDEX 255

BITMAP (Tbmp) (tbsb)

    BITMAP       [<ResType.s>] ID <BitmapResourceId.n> <BitmapFileName.s>
                 [NOCOMPRESS] [COMPRESS] [FORCECOMPRESS]
    BITMAPGREY   [<ResType.s>] ID <BitmapResourceId.n> <BitmapFileName.s>
                 [NOCOMPRESS] [COMPRESS] [FORCECOMPRESS]
    BITMAPGREY16 [<ResType.s>] ID <BitmapResourceId.n> <BitmapFileName.s>
                 [NOCOMPRESS] [COMPRESS] [FORCECOMPRESS]
    BITMAPCOLOR16 [<ResType.s>] ID <BitmapResourceId.n> <BitmapFileName.s>
                 [NOCOMPRESS] [COMPRESS] [FORCECOMPRESS]
    BITMAPCOLOR  [<ResType.s>] ID <BitmapResourceId.n> <BitmapFileName.s>
                 [NOCOLORTABLE] [COLORTABLE]
                 [TRANSPARENT r g b] [TRANSPARENTINDEX index]
                 [NOCOMPRESS] [COMPRESS] [FORCECOMPRESS]
    BITMAPCOLOR16K [<ResType.s>] ID <BitmapResourceId.n> <BitmapFileName.s>
                 [TRANSPARENT r g b] [NOCOMPRESS] [COMPRESS] [FORCECOMPRESS]
    BITMAPFAMILY [<ResType.s>] ID <BitmapResourceId.n>
                 <BitmapFileName.s> ... <BitmapFileName.s>
                 [NOCOLORTABLE] [COLORTABLE]
                 [TRANSPARENT r g b] [TRANSPARENTINDEX index]
                 [NOCOMPRESS] [COMPRESS] [FORCECOMPRESS]
    BITMAPFAMILYSPECIAL [<ResType.s>] ID <BitmapResourceId.n>
                 <BitmapFileName.s> ... <BitmapFileName.s>
                 [NOCOLORTABLE] [COLORTABLE]
                 [TRANSPARENT r g b] [TRANSPARENTINDEX index]
                 [NOCOMPRESS] [COMPRESS] [FORCECOMPRESS]
    BOOTSCREENFAMILY [<ResType.s>] ID <BitmapResourceId.n>
                 <BitmapFileName.s> ... <BitmapFileName.s>
                 [NOCOLORTABLE] [COLORTABLE]
                 [TRANSPARENT r g b] [TRANSPARENTINDEX index]
                 [NOCOMPRESS] [COMPRESS] [FORCECOMPRESS]

Notes:

- `BITMAP` creates a monochrome bitmap resource.
- `BITMAPGREY` creates a 2bpp (4 color grayscale) bitmap resource.
- `BITMAPGREY16` creates a 4bpp (16 color grayscale) bitmap resource.
- `BITMAPCOLOR16` creates a 4bpp (16 color) bitmap resource.
- `BITMAPCOLOR` creates a 256 color bitmap resource.
- `BITMAPFAMILY` creates a multibit (1bpp, 2bpp, 4bpp and 256 color) icon resources.
- `BITMAPFAMILYSPECIAL` creates a multibit (1bpp, 2bpp, 4bpp color and 256 color) icon resources.
- `BOOTSCREENFAMILY` creates a multibit (1bpp, 2bpp, 4bpp color and 256 color) icon resources. In the header we found a size, a check sum and a BitmapFamily. The Resource created is a 'tbsb'.
- `BOOTSCREENFAMILY` is system reserved.
- The inclusion of the bitmap color table is not recommended as it slows down system performance. PilRC implements a simple color table matching algorithm to match the bitmaps colortable to the system palette.
- 16 COLOR GRAPHICS!
  A new exiting graphics mode is available for application developers who wish to use only a standard 16 color palette (running at 4bpp means half as much memory to copy). BITMAPCOLOR16 and BITMAPFAMILYSPECIAL can be used with the following code:

    {
      UInt32       depth;
      RGBColorType palette[] = {
                                 {  0, 0xff, 0xff, 0xff },
                                 {  1, 0x80, 0x80, 0x80 },
                                 {  2, 0x80, 0x00, 0x00 },
                                 {  3, 0x80, 0x80, 0x00 },
                                 {  4, 0x00, 0x80, 0x00 },
                                 {  5, 0x00, 0x80, 0x80 },
                                 {  6, 0x00, 0x00, 0x80 },
                                 {  7, 0x80, 0x00, 0x80 },
                                 {  8, 0xff, 0x00, 0xff },
                                 {  9, 0xc0, 0xc0, 0xc0 },
                                 { 10, 0xff, 0x00, 0x00 },
                                 { 11, 0xff, 0xff, 0x00 },
                                 { 12, 0x00, 0xff, 0x00 },
                                 { 13, 0x00, 0xff, 0xff },
                                 { 14, 0x00, 0x00, 0xff },
                                 { 15, 0x00, 0x00, 0x00 }
                               };

      // change to 4bpp grayscale
      depth = 4;
      WinScreenMode(winScreenModeSet,NULL,NULL,&depth,NULL);

      // and tweak to the 16 color palette
      WinPalette(winPaletteSet,0,16,palette);
    }

Example:

    BITMAP        ID 1 "bitmap.bmp" COMPRESS
    BITMAPGREY    ID 2 "bmp2bpp.bmp" COMPRESS
    BITMAPGREY16  ID 3 "bmp4bpp.bmp" COMPRESS
    BITMAPCOLOR16 ID 4 "bmp4bpc.bmp" COMPRESS
    BITMAPCOLOR   ID 4 "bmp8bpp.bmp" COMPRESS COLORTABLE
    BITMAPFAMILY  ID 5 "bmp1bpp.bmp" "bmp2bpp.bmp" COMPRESS
    BITMAPFAMILY  ID 6 "bmp1bpp.bmp" "bmp2bpp.bmp" "bmp4bpp.bmp" "bmp8bpp.bmp" COMPRESS
    BITMAPFAMILY  ID 7 "bmp1bpp.bmp" "" "" "bmp8bpp.bmp" COMPRESS
    BITMAPFAMILY  ID 8 "bmp1bpp.bmp" "" "" "bmp8bpp.bmp" COMPRESS TRANSPARENT 255 255 255
    BITMAPFAMILY  ID 9 "bmp1bpp.bmp" "" "" "bmp8bpp.bmp" COMPRESS TRANSPARENTINDEX 255

TRAP (TRAP)

    TRAP ID <TrapId.n> <TrapNumber.n>

Notes:

- DaggerWare's HackMaster required.
- `<TrapId.n>` must be greater than 1000.

Example:

    TRAP ID 1000 367

FONT (NFNT)

    FONT ID <FontResourceId.n> FONTID <FontId.n> <FontFileName.s>

FONT file format

The file containing the font information is plain ASCII. To understand how it works it is first necessary to understand how a font is arranged in memory. A font consists of four main parts, a header, a bitmap image, a bitmap location table, and an offset/width table. The bitmap image and location table are generated for you 100% automatically.

The ASCII file consists of two parts, the header and the font data (glyph objects). A full font file is provided with the PilRC distribution.

The FONT header has the following fields:

`fontType` | The purpose of this field is unknown. The ROM fonts define this value to be 36864.
`maxWidth` | Defined as "maximum character width". If not set it is automatically set to the width of the widest character.
`kernMax` | Defined as "negative of maximum kern value". The purpose of this field is unknown.
`nDescent` | Defined as "negative of descent". The purpose of this field is unknown, and is not used in the ROM fonts.
`fRectWidth` | Defined as "width of font rectangle". If not set it is automatically set to the width of the widest character.
`fRectHeight` | Defined as "height of font rectangle". If not set it is automatically set when the first glyph is defined. All characters must be exactly this height.
`ascent` | The number of rows that make up the ascending part of the glyphs. Ascent plus descent equals fRectHeight. This value should be set.
`descent` | The number of rows that make up the descending part of the glyphs. Descent plus ascent equals fRectHeight. This value should be set.
`leading` | The purpose of this field is unknown.

Each glyph has a bitmap, offset, and a width associated with it. The width can be overridden, however it is not recommended as it is set automatically. Notes:

- `FONT` declarations must be defined before the font is used.
- ALL font declaration must have as last glyph :

      GLYPH -1
      -----
      -----
      -----
      -----
      #####
      #---#
      #---#
      #---#
      #---#
      #---#
      #---#
      #####
      -----
      -----
      -----

- `<FontId.n>` must be between 128 and 255.
- Custom `FONT` declarations can only be used on Palm Operating System 3.0 and later.
- Palm Operating System 2.0 and before

    [source.rcp]
    FONT ID 1000 FONTID 128 "font.txt"

    [source.c]
    void *font128;
    font128=MemHandleLock(DmGetResource('NFNT', 1000));
    UICurrentFontPtr = font128;

- Palm Operating System 3.0+

    [source.rcp]
    FONT ID 1000 FONTID 128 "font.txt"

    [source.c]
    FontPtr font128;
    font128=MemHandleLock(DmGetResource('NFNT', 1000));
    FntDefineFont(128, font128);

- FONT support in PilRC is not complete, and has been reverse engineered. FONTINDEX

    FONTINDEX ID <ResId.n>
    BEGIN
    	<FontType.s> <ResId.n>
    	...
    END

Notes:

- This resource is system reserved.

Example:

    FONTINDEX ID 1000
    BEGIN
    	"NFNT" 9001
    	"NFNT" 9002
    	"NFNT" 9003
    END

HEX

    HEX <ResType.s> ID <ResId.n> <Byte.n> | <String.s>

Notes:

- String values within the data DO NOT have implicit null termination. You must add a 0x00 hex value after the string if needed.

Example:

    HEX "junk" ID 1000
      0x00 0x00 0x00 0x23 "String" 0x00 "String2"
      0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00

DATA

    DATA <ResType.s> ID <ResId.n> <FileName.s>

Example:

    DATA "junk" ID 1000 "binary.bin"

INTEGER (tint)

    INTEGER ID <ResId.n> <Value.n>

Notes:

- `ResLoadConstant(..)` API can be used to load the 'tint' resource.

Example:

    INTEGER ID 1000 1974

BYTELIST (BLST)

    BYTELIST ID <ResId.n>
    BEGIN
    	<Value.n>
    	...
    END

Example:

    BYTELIST ID 1000
    BEGIN
    	23
    	3
    	205
    	55
    END

WORDLIST (wrdl)

    WORDLIST ID <ResId.n>
    BEGIN
    	<Value.n>
    	...
    END

Example:

    WORDLIST ID 1000
    BEGIN
    	23
    	1303
    	2505
    	2055
    END

LONGWORDLIST (DLST)

    LONGWORDLIST ID <ResId.n>
    BEGIN
    	<Value.n>
    	...
    END

Example:

    LONGWORDLIST ID 1000
    BEGIN
    	123456789
    	130300
    	78005
    	200055
    END

PALETTETABLE (tclt)

    PALETTETABLE ID <ResId.n>
    BEGIN
    	<index.n> <red.n> <green.n> <blue.n>
    	...
    END

Example:

    PALETTETABLE ID 1000
    BEGIN
    	0x00 0xFF 0xFF 0xFF
    	0x01 0x00 0x00 0x00
    END

FEATURE (feat)

    FEATURE ID <ResId.n>
    BEGIN
    	[CREATOR <creator.s>]
    	BEGIN
    		[ENTRY] [NUMBER<number.n>] [VALUE<value.n>]
    		...
    	END
    END

Example:

    FEATURE ID 1000
    BEGIN
    	[CREATOR <creator.s>]
    	BEGIN
    		ENTRY NUMBER 5 VALUE 0
    		ENTRY NUMBER 6 VALUE 0
    	END
    END

GRAFFITIINPUTAREA (silk)

    GRAFFITIINPUTAREA ID <GraffitiInputAreaId.n>
      [VERSION <version.n>]
      [CREATOR <creator.s>]
      [LANGUAGE <language.s>]
      [COUNTRY <conutry.s>]
    BEGIN
      <OBJECTS>
    END

Where `<OBJECTS>` is one or more of:

`AREA` | `AT (<Left.p> <Top.p> <Width.p> <Height.p>) [SCREEN] [GRAFFITI] [INDEX <index.n>]`
`BUTTON` | `AT (<Left.p> <Top.p> <Width.p> <Height.p>) [KEYDOWNCHR <keydownchr.n>] [KEYDOWNKEYCODE <keydownkeycode.n>] [KEYDOWNMODIFIERS <keydownmodifiers.n>]`

Notes:

- This resource is system reserved.
- `LANGUAGE` is one of this strings :
  "English", "French", "German", "Italian", "Spanish", "Japanese".
- `COUNTRY` is one of this strings :
  "Australia", "Austria", "Belgium", "Brazil", "Canada", "Denmark", "Finland", "France", "Germany", "HongKong", "Iceland", "Ireland", "Italy", "Japan", "Luxembourg", "Mexico", "Netherlands", "NewZealand", "Norway", "Spain", "Sweden", "Switzerland", "UnitedKingdom", "UnitedStates", "India", "Indonesia", "Korea", "Malaysia", "RepChina", "Philippines", "Singapore", "Thailand", "Taiwan".

Example:

    GRAFFITIINPUTAREA ID 10000
      VERSION 1
      CREATOR "psys"
      LANGUAGE "English"
      COUNTRY "UnitedStates"
    BEGIN
    	AREA AT (0 0 160 160) SCREEN INDEX 0
    	AREA AT (27 164 62 56) GRAFFITI INDEX 0
    	AREA AT (89 164 44 56) GRAFFITI INDEX 1
    	BUTTON AT (27 206 18 14) KEYDOWNCHR 272 KEYDOWNKEYCODE 0 KEYDOWNMODIFIERS 8
    	BUTTON AT (115 206 18 14) KEYDOWNCHR 273 KEYDOWNKEYCODE 0 KEYDOWNMODIFIERS 8
    	BUTTON AT (0 164 27 28) KEYDOWNCHR 264 KEYDOWNKEYCODE 0 KEYDOWNMODIFIERS 8
    	BUTTON AT (0 192 27 28) KEYDOWNCHR 261 KEYDOWNKEYCODE 0 KEYDOWNMODIFIERS 8
    	BUTTON AT (133 164 27 28) KEYDOWNCHR 267 KEYDOWNKEYCODE 0 KEYDOWNMODIFIERS 8
    	BUTTON AT (133 192 27 28) KEYDOWNCHR 266 KEYDOWNKEYCODE 0 KEYDOWNMODIFIERS 8
    END

COUNTRYLOCALISATION (cnty)

    COUNTRYLOCALISATION ID <ResId.n>
    BEGIN
      BEGIN
        [NUMBER <number.n>]
        [NAME <name.s>]
        [DATEFORMAT <dateformat.n>]
        [LONGDATEFORMAT <longdateformat.n>]
        [WEEKSTARTDAY <weekstartday.n>]
        [TIMEFORMAT <timeformat.n>]
        [NUMBERFORMAT <numberformat.n>]
        [CURRENCYNAME <currencyname.s>]
        [CURRENCYSYMBOL <currencysymbol.s>]
        [CURRENCYUNIQUESYMBOL <currencyuniquesymbol.s>]
        [CURRENCYDECIMALPLACES <currencydecimalplaces.n>]
        [DAYLIGHTSAVINGS <daylightsavings.n>]
        [MINUTESWESTOFGMT <minuteswestofgmt.n>]
        [MEASUREMENTSYSTEM <measuresystem.n>]
      END
      BEGIN
      ...
      END
    END

Notes:

- This resource is system reserved.

Example:

    COUNTRYLOCALISATION ID 10000
    BEGIN
    	BEGIN
    		NUMBER 7
    		NAME "France"
    		DATEFORMAT 1
    		LONGDATEFORMAT 8
    		WEEKSTARTDAY 1
    		TIMEFORMAT 2
    		NUMBERFORMAT 2
    		CURRENCYNAME "Franc"
    		CURRENCYSYMBOL "F"
    		CURRENCYUNIQUESYMBOL "FRF"
    		CURRENCYDECIMALPLACES 2
    		DAYLIGHTSAVINGS 3
    		MINUTESWESTOFGMT 60
    		MEASUREMENTSYSTEM 1
    	END
    	BEGIN
    		NUMBER 23
    		NAME "United States"
    		DATEFORMAT 0
    		LONGDATEFORMAT 7
    		WEEKSTARTDAY 0
    		TIMEFORMAT 1
    		NUMBERFORMAT 0
    		CURRENCYNAME "US Dollar"
    		CURRENCYSYMBOL "$"
    		CURRENCYUNIQUESYMBOL "$US"
    		CURRENCYDECIMALPLACES 2
    		DAYLIGHTSAVINGS 1
    		MINUTESWESTOFGMT 1140
    		MEASUREMENTSYSTEM 0
    	END
    END

KEYBOARD (tkbd)

    KEYBOARD ID <ResId.n> <Value.n>

Notes:

- Supported Value are:
  if keyboard is for United State then value = 0
  if keyboard is for French then value = 1
  if keyboard is for Germany then value = 2
- This resource is system reserved.

Example:

    KEYBOARD ID 1000 0

MIDI (MIDI)

    MIDI ID <ResId.n> <string.s>

Notes:

- This not convert file to midi resource. The .aif file must be Palm Midi compliant

Example:

    MIDI ID 1000 "trompette.aif"

International Support

PilRC supports a limited form of international tokenization. It works by substituting strings in the resource definitions with replacements specified in a TRANSLATION section. Multiple translation blocks may be specified in a resource script. The active language is specified with the "-L" flag to PilRC.

Positioning of controls is a large problem if absolute values are used. It is recommended you use AUTO, CENTER and PREVRIGHT et al when defining the contents of your forms.

Example:

    pilrc -L FRENCH myscript.rcp res

TRANSLATION

    TRANSLATION <Language.s>
    BEGIN
      <STRINGTRANSLATIONS>
    END

Where `<STRINGTRANSLATIONS>` is one or more of:

    <Original.s> = <Translated.ss>

Notes:

- Declare a short keyword for long strings, and define native and foriegn translations for it.

Example:

    TRANSLATION "FRENCH"
    BEGIN
      "Repeat Datebook alarm sound" = "Répétitions Alarme Agenda"
      "Ring again every" = "Rappel tous les"
    END

Known Bugs

- LIST
  - DISABLED does not work.
  - VISIBLEITEMS may be required for list objects to show properly.
- FIELD
  - MAXCHARS required for field control to accept characters to work.
  - NUMERIC doesn't work in Palm Operating System prior to 3.0
- FORM
  - Using NOSAVEBEHIND on Palm Operating System prior to 3.0 may cause errors.
- FONT
  - Developed based on reverse-engineering.
    The complete operation of how Palm handles FONT manipulation is unknown.

Further Reading

For Palm Computing Platform reference information, be sure to also visit the following websites:

- http://www.palmos.com/
  Provided by Palm Computing.

- http://www.massena.com
  A great source of low level Palm Computing Platform information.
  Provided by David Massena.

- http://www.roadcoders.com
  Need some examples? This is a great resource to find plenty of source code for applications written on the Palm Computing Platform.