PilRC / PilRCUI v2.0a User Manual |
Wes
Cherry (wesc@ricochet.net) |
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
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
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
AUTOAutomatic 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. CENTERCenters 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. PREVLEFTPrevious items left coordinate PREVRIGHTPrevious items right coordinate PREVTOPPrevious items top coordinate PREVBOTTOMPrevious items bottom coordinate PREVWIDTHPrevious items width PREVHEIGHTPrevious 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.
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.
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 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 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 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 ID <VersionResourceId.n> <Version.s>
Example
VERSION ID 1 "0.09"
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 ID <AINResourceId.n> <ApplicationName.s>
Example
APPLICATIONICONNAME ID 100 "AlarmHack"
APPLICATION ID <ApplResourceId.n> <APPL.s><APPL.s> must be 4 characters long
Example
APPLICATION ID 1 "ALHK"
Converts a Microsoft Windows style monochrome bitmap to tAIB Pilot icon resources with ID 1000.
ICON <IconFileName.s>
Example
ICON "myicon.bmp"
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"
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
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 <Language.s> BEGIN <STRINGTRANSLATIONS> ENDWhere <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
SAVEBEHIND is the default for forms.
Turning this off with NOSAVEBEHIND may cause your program
to crash (or it may not)
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