PilRC / PilRCUI v2.0a
User Manual

Wes Cherry (wesc@ricochet.net)
1 Jan 98

Check the PilRC Home Page for the latest version.

Description

PilRC A resource compiler for the US Robotics Pilot
PilRCUI A form previewer. It launches a window which previews a close approximation of forms as they would appear on the Pilot. Clicking in the content window of PilRCUI will cause it to reload the current script.

Table of Contents

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

Usage

pilrc [-L LANGUAGE] [-I INCLUDE PATH] [-R RESFILE] [-q] 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 to search may be specified by repeating the -I option.
-R RESFILE Output a .res file specifying all the resources emitted by pilrc. This file may be included in your PilA or JUMP program.
-H INCFILE Output a .h file containing auto-generated resource item IDs for IDs not previously defined.. If -H is not specified then undefined IDs are considered errors.
-q Less noisy output, for you minimalists.
file.rcp Input file describing the resources to be emitted. Each resource is written as a seperate file in the [output path] directory. The output filename is constructed by appending the hexcode resource id to the four character resource type.
For example, a FORM (tFRM) with formid of 15 would be written as tfrm000f.bin.
output path Directory where .bin files should be generated.

Example

pilrc -I c:\resources -L FRENCH -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
.s  = string (may contain the following character escapes: \t (tab) \n (cr) or \nnn where nnn is an octal character code)
      example:  "Click Me"

.ss = multi line string.  PilRC will concatenate strings on seperate lines 
      enclosed with quotes and terminated by the \ character
      example:  "Now is the time for all good "\ 
                "men to come to the aid of their country"

.n = number, defined constant or simple arithmetic expression.  Valid operators are + - * /.  
      precedence is left to right. math is integer.
      examples: 23 12+3+1 12*4 14*3+5/2

.p = position coordinate.  Which may be either a number, expression or one 
     of the following keywords
AUTO
Automatic width or height. The width/height of the item is computed based on the text in the item. Valid only for widths or heights of items.
CENTER
Centers the item either horizontally or vertically. Only valid for left or top coordinate of an item.
CENTER@<coord.n>
Centers the item at the coordinate following.
RIGHT@<coord.n>
Aligns the item at the right coordinate. Only valid for left coordinate of items
BOTTOM@<coord.n>
Aligns the item at the bottom coordinate. Only valid for top coordinate of items.
PREVLEFT
Previous items left coordinate
PREVRIGHT
Previous items right coordinate
PREVTOP
Previous items top coordinate
PREVBOTTOM
Previous items bottom coordinate
PREVWIDTH
Previous items width
PREVHEIGHT
Previous items height
	example: PREVRIGHT+2 
		 CENTER@80/2
	
	NOTE:  AUTO and CENTER must stand alone and are not valid in 
        arithmetic expressions
Comments
Comments are single line and begin with //
Note that they are only allowed at the outer scope.  Comments within a FORM or MENU or other command 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 resource IDs. Source code can reference the symbols as can PilRC.

PilRC understands three include file formats. Following is the fairly limited syntax for each of them:

.h #define <Symbol.i> <Value.n>
.inc <Symbol.i> equ <Value.n>
.java, .jav package <Package name>;

[public] class <Class name>
{
public static final short
<Symbol.i> = <Value.n>;
}

Each symbol may then be used in place of any number.
NOTE: #ifdefs are ignored by PilRC.

Resource Language Reference

The .rcp file may contain the following commands:

FORM Pilot Form
MENU Menu bar
ALERT Alert dialog box
VERSION Version string
STRING String
APPLICATIONICONNAME Application Icon's Name
APPLICATION Application four character type
ICON Icon bitmap
BITMAP.BITMAPGREY Bitmap
TRAP Trap (HackMaster)
TRANSLATION Language string translation

 

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

<OBJECTS>: one or more of: (Defaults are colored BLUE)

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>]
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>]
CHECKBOX <Label.s> ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE] [DISABLED] [LEFTANCHOR] [RIGHTANCHOR] [FONT <FontId>] [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>]
SELECTORTRIGGER <Label.s> ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) [USABLE] [NONUSABLE] [DISABLED] [LEFTANCHOR] [RIGHTANCHOR] [FONT <FontId.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>]
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]
POPUPLIST ID <Id.n> <IdList.n>
LIST <Item.s> <Item2.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] [NONUSABE]
TABLE ID <Id.n> AT (<Left.p> <Top.p> <Width.p> <Height.p>) ROWS <NumRows.n> COLUMNS <NumCols.n> COLUMNWIDTHS <Col1Width.n> <Col2Width.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>)
Notes: New in v1.9: ID <Id.n> may be replaced with AUTOID. PilRC will assign an identifier for each control which doesn't specifies AUTOID. This is useful for controls which you won't refer to in your code, LABELs being the most common. Auto ID's begin at at 9000 and increase sequentially.

The bitmap referenced by FORMBITMAP must appear as a seperate resource in the rcp file via the BITMAP command.

MAXCHARS is required for FIELD to work properly

Example (See example\pilrctst.rcp for more examples):

FORM ID 1 AT (2 2 156 156)
USABLE
MODAL
HELPID 1
MENUID 1
BEGIN
	TITLE "AlarmHack"
	LABEL "Repeat Datebook alarm sound" ID 2000) 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" "Skip Along" "Beethoven" "EuroCop" "Cricket" "Bleep" "Computer2" ID 6000 AT (PrevLeft PrevTop 52 1) VISIBLEITEMS 10 NONUSABLE
	POPUPLIST ID 5000 6000

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

MENU (MBAR)

MENU ID <MenuResourceId>
BEGIN
	<PULLDOWNS>
END


<PULLDOWNS>: one or more of:

PULLDOWN <PulldownTitle.s>
BEGIN
	<MENUITEMS>
END

<MENUITEMS>: : 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 500 "I"
	END
END

ALERT (tALT)

ALERT ID <AlertResrouceId.n>
[HELPID <HelpId.n>]
[INFORMATION] [CONFIRMATION] [WARNING] [ERROR]
BEGIN
	TITLE <Title.s>
	MESSAGE <Message.ss>
	BUTTONS <Button.s> <BUTTON.s>...
END
Example
ALERT ID 1000
HELPID 100
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>
Example
VERSION ID 1 "0.09"

STRING (tSTR)

STRING ID <StringResourceId.n> <String.ss>
Example:
STRING ID 100 "This is a very long string that demonstrates carriage retuns\n" \
	"as well as continued .ss syntax strings"

APPLICATIONICONNAME (tAIN)

APPLICATIONICONNAME ID <AINResourceId.n> <ApplicationName.s>
Example
APPLICATIONICONNAME ID 100 "AlarmHack"

APPLICATION (APPL)

APPLICATION ID <ApplResourceId.n> <APPL.s> 
<APPL.s> must be 4 characters long
Example
APPLICATION ID 1 "ALHK"

ICON (tAIB)

Converts a Microsoft Windows style monochrome bitmap to tAIB Pilot icon resources with ID 1000.

ICON <IconFileName.s> 
Example
ICON "myicon.bmp"

BITMAP (Tbmp)

Converts The following monochrome bitmap formats to TBmp Pilot bitmap resources.

BMP, PBITM, XBM, PBM

Compression may be specified via COMPRESS or FORCECOMPRESS. COMPRESS will compress only if it results in a resource that is smaller than an uncompressed bitmap. FORCECOMPRESS compresses unconditionally.

BITMAP ID <BitmapResourceId.n> <BitmapFileName.s> [NOCOMPRESS] [COMPRESS] [FORCECOMPRESS]

Additionally, 16 color BMP files may be converted to 2bpp bitmaps using BITMAPGREY. The bitmap must be authored with only black, dark grey, light grey and white pixels. Compression may give unpredictable results with grey bitmaps. 2bpp bitmaps are written in the standard pilot bitmap format except the rowBytes field is 2x what it would be for 1bpp bitmaps. The PalmOS does not support 2bpp bitmaps. For a 2bpp replacement for the standard Win* drawing routines, check out ScumbySoft's Win2 2bpp Drawing Library. Information on 2bpp mode can also be found in Edward Keyes article Hacking the Pilot

BITMAPGREY ID <BitmapResourceId.n> <BitmapFileName.s>
Examples:
BITMAP ID 100 "mybitmap.bmp" COMPRESS
BITMAPGREY ID 101 "my16cbmp.bmp"

TRAP (TRAP)

Emits a HackMaster TRAP resource. For more info on Hackmaster system extensions check out DaggerWare's HackMaster. TrapIds must be greater than 1000.

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

Example:

TRAP ID 1000 367

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. (Yeah, I know this is a pretty cheezy way to do this, but it has worked so far.

The biggest problem is with positioning of controls. If you use AUTO, CENTER and PREVRIGHT et al it might not involve any position changing in your script. If you do need to change the position, right now the only workaround is to put some #ifdefs in your file and hook up a custom rule to preprocess your source file).

Note: The TRANSLATION section must appear first in the .rcp file, before any use of the strings to be translated.
Example
pilrc -L FRENCH myscript.rcp res

TRANSLATION

TRANSLATION <Language.s>
BEGIN
	<STRINGTRANSLATIONS>
END
Where <STRINGTRANSLATINOS> is one or more of:
<Original.s> = <Translated.ss>
TIP: For long strings define a short keyword and then define both 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

Further Reading

For an excellent expose on how to create dynamic resources on the fly, check out: Gary Desrosiers' "PalmPilot Dynamic UI Construction" at http://www.pcnet.com/~desrosi/DynamUI.html. This is a great primer on how resources are constructed on the pilot.

Check out RoadCoders for lots of samples and other pilot programming information. http://www.roadcoders.com/pilot/

Darrin Massena's site, though not updated frequently is another good starting point. http://www.massena.com