PilRC / PilRCUI v2.3 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. -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. (NOT IMPLEMENTED!) 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.
For example, a FORM (tFRM) with formid of 15 would be written as tfrm000f.bin.output path Directory where .bin files should be generated.
Examples
pilrc -I c:\resources -L FRENCH -R myprogram.res myprogram.rcp c:\output
pilrc -I c:\resources -L BIG5 -F5 -R myprogram.res myprogram.rcp c:\output
pilrc -I c:\resources -L JAPAN -Fj -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. Precedence can be changed by grouping subexpressions with parenthesis examples: 23 12+3+1 12*4 14*3+5/2 12+(2*3) constants may also be 'AAAA' 4CC style. .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
Note that when the -rtl flag is specified the | operator will cause the expression to evaluate the the value to the right of the | operator. example: 3|4 will evaluate to 3 if the -rtl flag isn't specified and 4 if it is.
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 SMALLICON Icon bitmap BITMAP.BITMAPGREY Bitmap TRAP Trap (HackMaster) FONT User defined font 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
Any user defined fonts defined by FONT >= 128 and FONT <= 255 must appear above the FORM via the FONT command.
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> STRING ID <StringResourceId.n> FILE <StringFile.s>
Examples
STRING ID 100 "This is a very long string that demonstrates carriage retuns\n" \ "as well as continued .ss syntax strings" STRING ID 101 FILE "string.txt"
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 32x32 or 22x22 monochrome bitmap to tAIB Pilot icon resources with ID 1000.
ICON <IconFileName.s>
Example
ICON "myicon.bmp"
Converts a Microsoft Windows style 15x9 monochrome bitmap to tAIB Pilot icon resources with ID 1001.
SMALLICON <IconFileName.s>
Example
SMALLICON "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
(Font compiler and this section written by David Turnbull dpt@newsguy.com)
To compile a font into you application you need to add a directive to your resource file. FONTID must be between 128 (per the Palm 3.0 SDK) and 255 (a limit of the compiler).
FONT ID <FontResourceId.n> FONTID <FontId.n> <FontFileName.s>
Example:
FONT ID 1000 FONTID 128 "font.txt"A font must be compiled (declared first in the .rcp file) before it can be used in any forms. Designing forms with user defiend fonts will only work on a V3.0 PalmOS. Please refer to the V3.0 PalmOS documentation on how to use these fonts. I still don't have a Palm III so this is untested, but basically you would do something like this:
FontPtr font128; font128=MemHandleLock(DmGetResource('NFNT', 1000)); FntDefineFont(128, font128);OS versions prior to (and including) V3.0 can be tricked into using your font. However, you can only use the SDK calls to use this font, it is not supported for use in forms. The following demonstrates how to do this.
void * font128; font128=MemHandleLock(DmGetResource('NFNT', 1000)); UICurrentFontPtr = font128;FONT FILE
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. I tried getting more information about the font structure from Palm Computing, but they did not respond to any of my emails. All of the information I used is from inspection of the fonts in the ROMs and from the NFNT font type on the Macintosh. There are a lot of unknowns that hopefully will be understood soon. Until then, you can feel comfortable ignoring them as they will default to harmless values. The ASCII file consists of two parts, the header and the font data. There are three types of lines in the file, a comment line, a token/value line, and bitmap data. Comment lines begin with //. Token/value lines contain a keyword token and a value that can be decimal or a character enclosed in single quotes. Bitmap lines contain a minus or period to indicate a not-set bit and any other character to indicate a set bit. A very simple font would look like this:
// An overly simple fontfontType 36864 ascent 3 descent 1 GLYPH 32 -- -- -- --GLYPH 'A' OFFSET 0 -X-- XXX- X-X- ----GLYPH 'B' WIDTH 3 ##- ##- ##- ---A full font is included in the pilrc distribution. See example\font.txt
HEADER
The header has the following fields:
fontType I'm not sure what this does. I have inspected many ROM fonts and they all have type 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". I'm not sure what this does or even if it is used. nDescent Defined as "negative of descent". This is not set in any of the ROMs I've inspected. 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. It is strongly recommended this be set. descent The number of rows that make up the descending part of the glyphs. Descent plus ascent equals fRectHeight. It is strongly recommended this be set. leading Don't know it's function and if it's used by the Pilot. I can assume it has something to do with kerning, but that may be totally wrong. GLYPHS
Each glyph has a bitmap, and offset, and a width associated with it. The WIDTH can be overridden if needed, but it's effects are unknown at this time. Normally it is set automatically. Some of the special characters in the ROMs had the WIDTH different than the number of bits stored in the bitmap. The function of OFFSET is unknown as well. Font #1 (boldFont) has all of it's characters as OFFSET 1 and a few characters in the symbol fonts has values as well. Once again, I believe this has something to do with kerning.
NOTES
For support, I strongly recommend you go to these newsgroups. I'm sure I won't be able to answer any questions I haven't answered in this document, so unless you have comments or a bug to report it's probably no use contacting me directly.
news://news.massena.com/pilot.programmer
news://news.massena.com/pilot.programmer.gccIf you can supply any more information about how the fonts are used by PalmOS please send me email. Hint, hint, you Palm Computing folks!!!
- David Turnbull dpt@newsguy.com
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