PilRC / PilRCUI v1.8
User Manual

Wes Cherry (wesc@ricochet.net)
13 Nov 97

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.

Ideally, PilRC and PilRCUI would be the same program, but I don't know how to create a program which conditionally runs in a console window or as a Win32 windows window.

If anyone knows how to do this, let me know.

Table of Contents

Usage
Understanding the Manual
Resource Language Reference
International Support
Known Bugs

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.
	PREVLEFT   : Previous items left coordinate
	PREVRIGHT  : Previous items right coordinate
	PREVWIDTH  : Previous items width
	PREVTOP    : Previous items top coordinate
	PREVBOTTOM : Previous items bottom coordinate
	PREVHEIGHT : Previous items height
	
	example: PREVRIGHT+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 Bitmap
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>]
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: 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 (This is a cliff notes version of AlarmHack's resource)

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" ID 601 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:" ID 601 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> <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]
Example:
BITMAP ID 100 "mybitmap.bmp" COMPRESS

 

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