To use these skins, they must first be converted to *.prc files. To do so,
use the make-skin script and the skin2prc program in the palmos directory.
The skin2prc program prepares the skin data structures and generates a shell
script, which, in turn, uses netpbm to generate BMP-formatted bitmap files
for the skin and each of the keys and annunciators; the make-skin script
runs skin2prc, then runs the BMP-creation shell script generated by skin2prc,
and finally it runs pilrc to combine everything into a PalmOS-compatible prc
file.
In order to use make-skin, you need:
1) A Unix-like environment, such as Linux or Cygwin;
2) A Bourne-compatible shell, such as bash, to run the make-skin script and
   the BMP-creation script generated by skin2prc;
3) A C++ compiler to compile skin2prc;
4) The NetPBM tool
5) The PilRC resource compiler.

Assuming everything is in place, and you have compiled skin2prc.cc, run
make-skin as follows:

./make-skin SkinName.layout SkinName.gif SkinID BitmapID depths density \
	    name dither sections

The parameters are as follows:

For SkinName.layout and SkinName.gif, substitute your skin's layout and gif file
names.

SkinID is the resource ID used for the generated 'Skin' resource; this must
usually be 1000; however, if you're building skins that you intend to compile
into the Free42 executable, you must use SkinID 100, 101, etc.
The reason is that when Free42 searches its own resources for built-in skins,
it looks for Skin resources with ID 100, then 101, then 102, and so on; it
stops looking when no match is found for an ID. So, built-in skins must have
consecutively numbered IDs starting with 100.
When Free42 opens an external skin, it simply looks for a Skin resource with
ID 1000. No other IDs are even attempted.

BitmapID is the first ID used for the bitmap resources that are generated; in
principle, you can use any value you like here, as long as it doesn't clash
with any other bitmap IDs.
Note that a skin contains at least 89 bitmaps: 1 for the calculator skin
itself, plus 74 for all keys in both "up" and "down" states, plus 14 for all
annunciators in both "on" and "off" states; if the skin is too large to fit in
1 bitmap (because of the 64 kilobyte resource size limit), that means
additional bitmaps will be needed; also, customized skins that define
additional keys will requires 2 additional bitmaps for each additional key.
Also, if multiple depths are generated (see below, the 'depths' parameter),
all these bitmaps will be generated for each of those depths, so the number
of bitmaps can easily be in the hundreds!
The free42/palmos/Makefile uses BitmapID = 500 for the "Original" skin, which
gets compiled into the executable; it is recommended to use BitmapID = 600,
700, etc., for any additional built-in skins, and to use BitmapID = 2000 for
external skins.

The 'depths' parameter specifies which types of bitmaps are to be generated.
Allowed values are 1 (monochrome), 4 (16 grays), 5 (16 colors), 8 (256 colors),
and 16 (true color); you may specify any combination of these as a comma-
separated list. Note that specifying multiple depths leads to a larger skin
file, and it consumes more bitmap IDs (the latter is relevant if you're
building Free42 and intend to compile multiple skins into the executable). On
the other hand, specifying multiple depths also means the skin is more likely
do look good on a large variety of devices. The combination 1,4,8 is a good
compromise for most color skins; 1,4,5 can be worth a try if the skin uses only
a few colors, and those colors match the standard Palm 16-color palette. For
grayscale skins, use 1,4; for monochrome skins, use 1.

The 'density' parameter specifies the skin's bitmap density. This must be
either 72 for standard-density skins (suitable for all Palm screens) or 144 for
high-density skins (suitable for 320x320 and 320x480 screens only). Other
densities are currently not supported.

The 'name' parameter specifies the name that will appear in Free42's Skin menu
when the skin is installed; it is also used as the name for the generated prc
file (with ".prc" appended, of course).

The 'dither' parameter specifies whether or not to perform dithering when
converting the skin's GIF file to depths 1, 4, 5, or 8 (see 'depths', above).
Theoretically, this can improve a skin's appearance if its original colors do
not match the available colors on the target device, but in practice, the
artefacts it tends to introduce can be distracting, particularly on
low-resolution screens.
Possible values are "on" and "off".

The 'sections' parameter specifies into how many pieces the main bitmap should
be cut. You'll usually want to try 1 at first, but if PilRC warns that a bitmap
resource is to large (you'll see a message like "Resource 'Tbmp' 2000, 81256
bytes, exceeds safe HotSync size limit of 65000 bytes"), you should try using 2
sections. Keep on trying successively larger values until the warning goes
away. I have never had to use more than 2 for the skins in the Free42 source
repository, but that doesn't mean it can never happen!

-------------------------------------------------------------------------------

Free42 skin description (*.layout) file format:
Anything from a '#' until the end of the line is a comment
Non-comment lines contain the following information:

(Note: rectangles are given as "x,y,width,height"; points are "x,y".)

Skin: the portion of the skin bitmap to be rendered as the actual faceplate
Display: describes the location, size, and color of the display; arguments
  are: top-left corner, x magnification, y magnification, background color,
  foreground color. Colors are specified as 6-digit hex numbers in RRGGBB
  format.
Key: describes a clickable key; arguments are: keycode, sensitive rectangle
  (i.e. the rectangle where mouse-down events will cause the key to be
  pressed), display rectangle (i.e. the rectangle that changes when a key is
  pressed or released), and the location of the top-left corner of the active-
  state bitmap (since the active-state bitmap must have the same size as the
  display rectangle, only its position, not its width and height, are
  specified).
  Keycodes in the range 1..37 correspond to actual calculator keys; keycodes
  38..255 can be used to define "macro" keys. For each such keycode, there must
  be a corresponding "Macro:" line in the layout file.
  You may specify two keycodes (two numbers separated by a comma); if you do,
  the first is used when the calculator's shift (indicated by the shift
  annunciator) is inactive, and the second is used when the calculator's shift
  is active. This feature allows you to have a key's shifted function be
  something different than it is on the original HP-42S keyboard.
Macro: for keys with keycodes in the range 38..255, this defines the sequence
  of HP-42S keys (keycodes 1..37) that is to be pressed; arguments are:
  keycode, followed by zero or more keycodes in the range 1..37. See below for
  an example.
Annunciator: describes an HP-42S annunciator; arguments are: code (1=updown,
  2=shift, 3=print, 4=run, 5=battery, 6=g, 7=rad), display rectangle, and the
  location of the top-left corner of the active-state bitmap.

For examples, look at the *.layout and *.gif files in this directory.

Macro example:
To define a key for the FIX command, using key code 38: the sequence of
calculator keys for FIX is Shift (28), E (16), Sigma+ (1), so...

Key: 38 <sens_rect> <disp_rect> <active_pt>
Macro: 38 28 16 1
