Content

Introduction

Terms.

Operating frames.

Using Stylus    Using Graffiti

Operating Buttons.   Operating Jog Wheel

Additional forms.

Load Image     Preferences

Image Source     Game Options

Game Options     CLIE^TM Special

Miscellaneous

Puzzle Menu Items    Pausing

Top Controls

Using Custom Images.

Formats of custom images and size limitations

Creating custom images

What you need   Now do it!
And even simpler

Using custom palette (colour table)

Known bugs and troubleshooting

Introduction.

Should I really explain what is a jigsaw puzzle ?  For the current implementation the objective is the following: "All frames  on the desktop are parts of a single picture. You need to reconstruct the picture by placing each frame into its proper location on the board".

The application allows processing pictures larger than screen size. You can have a virtual  screen of up to 240x240 on  a regular Palm, or 480x480 on  Sony CLIE^TM, so that each time the actual screen is mapped onto a particular virtual screen area.

The application provides a variety of game options and  preferences. It  comes with  demo images and allows using  your  own  pictures in PalmOS^TM bitmap or PictureGear^TM formats . If your handheld  has an expansion slot, the application will take advantage of that by  reading image directly from an external memory source.

The latest release of the product,  additional images and more information are available from the application site http://justjigsaw.tripod.com

If you have questions, comments, or problems, please don't hesitate to  contact  me: palmcrust@yahoo.com   Please place 'jjig' somewhere in the subject for easy filtering.
 

Terms.

Buttons:  6 buttons located on the bottom of your Palm, typically used for Date Book,  Address Book, Page Up,  Page Down,  To Do List and Memo Pad by the Launcher.

Launcher: Top PalmOS^TM application that shows application icons by categories and starts other applications.

Jog Wheel: a wheel located on the left side of Sony CLIE^TM handheld used for scrolling lists, text etc.

Main form:  the form used form playing as opposed to additional forms (Preferences, Game Options etc)

Scrolling: changing view spot on the virtual screen.

Selection type:  STOP (red border) or GO (green border).  Selection  type depends on where you tap the frame, and can be changed by entering a button combination or tapping a  Top Control. It affects stylus, jog wheel and  some button operations.

Steering:  moving or rotating a frame.

Target: a board  place holder where current frame is expected to be successfully placed.

Top Controls:  Controls ('soft buttons') located on the top of the main form.

Virtual File System (VFS):  PalmOS^TM  extension that allows reading from an external memory card.

Virtual screen size: screen size of the play area (desktop). If virtual screen size exceeds the actual size, you can specify the view spot: which part of the virtual screen is shown on the actual screen
 
 

Operating frames.

When a frame gets reasonably close to its board location, it  is placed on he  board. Once the frame is placed, you can't move it any longer.
 

Using  Stylus.

.
Short move (slide).
Tap a frame near its centre, so that  its  borders are green. Drag frame in the appropriate direction.

Long move (jump).
Tap a frame near its centre, so that its borders are green. Lift pen and tap anywhere on the screen (you might need scrolling it). The frame moves so that its centre is positioned in specified place.

Rotation.
Tap a frame near its borders, so that the borders are red. Drag in the direction of rotation.
For  Right Angles rotation type (see  Game Options),  you can only rotate 90 degrees in each direction.

Changing current frame.
When frame borders are red,  just tap another frame. .

Hint:  To avoid hitch hiking (a frame is dragged along the board without a particular target, until is is placed somewhere), placing  a dragged frame is harder than placing a 'still' one. If you haves trouble with placement, use buttons for moving in the proximity of the target.
 

Using Graffiti®.

Scrolling.

If virtual screen size is bigger than the actual one, you can use Graffiti for moving within the virtual screen. For scrolling,  just tap numeric area as shown on the following diagram:

When Graffiti is enabled, it always operates for steering, when virtual screen is same as the actual one.

Steering.

An advantage of steering with Graffiti is that you shouldn't care about the selection type: the frame moves or rotates, depending on how you start moving the stylus: if you start from the centre of numeric area,  or moving toward the centre, frame moves, otherwise it rotates. Once the mode has been defined, it doesn't change until you lift the pen (you can even move it off Graffiti area), however you have to start from the numeric area.

If the above explanations don't appear quite clear, the following  sketch might be helpful:

Operating Buttons.

While entering a button combination, first button should be held, while pressing the following one, e.g. for  B1+Up ,  press  B1, and while holding it press Up.
 

Main form

GO selection mode:

Up	Move current frame 1 pixel up.
Down	Move current frame  1 pixel down
Left	Move current frame  1 pixel left.
Right	Move current frame  1 pixel right
Left+Up	Move current frame up-left (1 pixel in both dir-s)
etc.

STOP selection mode:

Up	Turn 1.4 degrees clockwise.
Down	Turn 1.4 degrees counter clockwise.
B2+Up	Turn 11.25 degrees clockwise
B2+Down	Turn 11.25 degrees counter clockwise.
B3+Up	Turn 90 degrees clockwise
B3+Down	Turn 90 degrees counter clockwise

For rotation type  Right Angles (see Game options), angles are 90 degrees for each combination.
 

Both modes:
 

B1+B2	Flip
B1+Up	Undo
B1+Down	Select next frame
B1+B3	Toggle selection type
B1+B4	Preview (while pressed)
B4+Up	Scroll view up
B4+Down	Scroll view down
B4+Left	Scroll view left
B4+Right	Scroll view right

Load Image form
 

B1	Game Options
B2	Image Source
Up	Select previous list item
Down	Select next list item
B3	Cancel
B4	Select image

Help
 

Up	Scroll help text 1 line up
Down	Scroll help text  1 line down
B1+Up	Move 1 page up
B1+Down	Move 1 page down
Left	Go back (previous item)
Right	Go forward (next item)
B4	Leave help -  when pressed from the help index; Go to help index - when pressed elsewhere.

Other forms
 

B3	Cancel
B4	Accept

 

Operating Jog Wheel.

Main form

GO selection mode:

Up	Move current frame 1 pixel up.
Down	Move current frame 1 pixel down
Up pressed	Move current frame 1 pixel left.
Down pressed	Move current frame 1 pixel right

STOP selection mode:

Up	Turn 1.4 degrees clockwise.
Down	Turn 1.4 degrees counter clockwise
Up pressed	Turn 11.25 degrees clockwise
Down pressed	Turn 11.25 degrees counter clockwise

Both modes:

Back button

Toggle selection type

Load Image form
 

Up	Select previous list item
Down	Select next list item
Press	Select image
Back button	Cancel

Help
 

Up	Scroll help text 1 line up
Down	Scroll help text  1 line down
Up pressed	Move 1 page up
Down pressed	Move 1 page down
Back button	Leave help -  when pressed from the help index; Go to help index - when pressed elsewhere.

Other forms
 

Press	Accept
Back button	Cancel

Additional forms.

This form allows selecting to start another puzzle with another picture  and/or game options.
The form displays the list of images. Images located on an external source are painted blue.

The buttons below are:

 

	Game Options
	Image Source
	Cancel
	Accept

Preferences Form.

Enable Sound  (true)
Enable game sound. If game sound is enabled, the volume is determined  by Prefs Game Sound parameter (Prefs is a PalmOS^TM  standard accessory). If Prefs Game Sound is off,  but the sound is enabled for the correct application, low volume is used.

Show content while dragging (false)
Show frame content (not border only) when moving or turning. Enabling this option may result in a big drawing latency.

Store completed puzzle (false)
If you quit when puzzle is completed, it won't be saved, so that next time the application starts with the image list. If you enable this option, a completed  puzzle is saved, and appears, when application restarts.

Auto-scroll  (true).
Shown,  if virtual  screen exceeds actual one.  When  enabled,   virtual screen view spot is shifted automatically, when current frame goes out of sight.

Numeric Graffiti area use (Scroll)
One of  two ways of using Graffiti area  (see  Using Graffiti ), or  Disabled  - Graffiti strokes are processed by the system.

Bottom Button Layout (Right)
Button layout (see  Operating Buttons),  or Disabled - buttons are processed by the system.
 

Image Source Form.

Use 16bpp image if available.
This  option  is enabled by default, however you might turn it off for using  a 256-colour image, even when  a true-colour equivalent is available.

Enable Virtual File System.
Disable VFS only if you have troubles with your expansion slot.

VFS Image file directories.
In case VFS is enabled, you can set up to 3 directories to look up the images.  The directories are processed in specified order.
 

Game Options Form.

Virtual screen.

 

Regular Palm 16bpp:	180x180
Regular Palm 8bpp:	240x240
Sony CLIE (any):	480x480

Low resolution where possible. (Sony CLIE only)
When enabled, high screen resolution is used only for big virtual screen sizes, where low resolution cannot be used. If disabled, high resolution is always used.

Cut strips.

Rules

Flip.
if enabled, some frames appear flipped. To place them on board, you need to 'unflip' using  Flip control (see Top Controls), or Flip button combination (see  Operating Buttons ).

Hide cutting lines
When  ticked, the board appears 'plane' without cutting lines.

Straight cuts
Avoid curly cuts along specified direction(-s). With straight cuts  along  both directions, frames are rectangular, which makes it really hard. Straight cuts are applied to small frames even though this option might not be set.

Rotation.

None	disables rotation originally and in the game;
Right angles	originally each frame is turned on a multiple of 90 degrees (i.e. 0, 90, 180 or 270 degrees);  only 90 degree turns are allowed within the game
Free	the default mode:  rotate at any angle at any time

CLIE^TM Special Form.

If Jog Wheel  is enabled, you can also  specify,  if back button is also used for the application. If back button is enabled, you have to use Launcher silk screen button (top left near Graffiti) to quit the application.

See  Operating Jog Wheel  for using jog wheel and back buttons with application.
 

Status Form.

Puzzle Menu Items.

Puzzle / Restart  - restores current puzzle to its original position.

Puzzle / Terminate - give up. All frames are placed and puzzle terminates.
 

Pausing.

Top Controls

 

- scroll	- undo	- flip
- move	- rotate	- view
	- stop

Undo.
As the name suggests. Up to 20 consecutive moves can be withdrawn.

Flip.
Vertical flip. Appears if flips are enabled (see  Game options ).
Hint:  horz.flip = vert.flip + 180 degrees turn

Move.
Tap control in the centre for changing selection type to GO.  Tapping outside the centre, in addition,  moves current frame in appropriate direction.  The speed increases while approaching the control boundary.

Rotate.
Tap control  in the centre for changing selection type to STOP.   Tapping  the bottom part  rotates  frame clockwise, while tapping the top part rotates   counter clockwise.  Rotation  speed increases from right to left.

View.
Tap the control control to view the picture. An  image exceeding screen size is shown scaled 1 :  1.5 (i.e. squeezed 1.5 times) .  Lift the stylus for returning to game.

Stop.
Replaces Rotate control, in case rotations are  disabled (see  Game Options ). Used for changing selection type to STOP.
 

Using Custom Images.

FYI. You must be a registered user to use custom images with the application.
 
 

Formats of  custom images and size limitations.

• PalmOS^TM bitmap images: this resource data base consists of images in compressed or uncompressed PalmOS bitmap format  It also includes string resources that give readable names to bitmaps. Several images are can be stored in a single resource file.
• PictureGear^TM Pocket Format (PGPF) images, created and maintained by Sony CLIE^TM bundled software. A PGPF resource presumably stores a single image, however it may have several bitmaps for different size and depth.  A PGPF image can be  processed on a regular Palm,  provided its size satisfies PalmOS limitations (see below).

•  180 x 180  for true colour (16bpp) images
•  240 x 240  for  256-colour (8bpp) images

Creating custom images

What you need

Alternatively,  you can download the software from their official  cites:

Palm resource compiler (pilrc)  (Wes Cherry & Aaron Ardiri):   http://www.ardiri.com
Palm database archiver (par)   (David Williams): http://djw.org

If you are a PalmOS^TM developer, you  might prefer using build-prc (a prc-tools component) to par,  simply because this doesn't require any additional downloading. The examples  with build-prc are also given below.

Let's do it !

You can  use  Linux,  cygwin,  MS Windows^TM or even MS DOS.

Images

You obviously need images. The accepted formats are  .bmp (MS Windows^TM Bitmap)  and  .ppm (Portable Pixmap).
In case of using .bmp files the  recommended format is  8bit indexed .bmp (for  8bpp PalmOS bitmap)  or  RGB .bmp (for 16bpp PalmOS bitmap).
Don't use RLE encoding with .bmp,  and don't rely on pilrc depth reduction: use your graphic editor for that.

Create a separate directory (folder in MS jargon) and place all required images there.
This is where you should also place a  source file for pilrc, discussed below.
 

Pilrc source file

Use any text editor (like Notepad)  to create a file with extension .rcp (e.g. myimages.rcp) that contains something like  this:
 

VERSION ID  1 "1.0"

STRING 1 "Rose"
BITMAPCOLOR    ID 1001 "rose256.bmp" COMPRESS COLORTABLE
BITMAPCOLOR16K ID 2001 "rose.bmp" COMPRESS

STRING 2 "Phoenix"
BITMAPCOLOR    ID 1002 "phoenix256www.bmp" COMPRESS
 

The following lines  define the images. As you can guess, this resource file will has two images named  "Rose" and "Phoenix".

Image "Rose" has two bitmaps:  one  8bpp (BITMAPCOLOR),  another  16bpp (BITMAPCOLOR16K).  Both are compressed to save space. Keyword COLORTABLE specifies that a  256-colour image for "Rose" uses a custom colour table (read Using Custom Palette section before use!) .

Image "Phoenix" has a single  8bpp bitmap created using a www-safe palette, therefore it doesn't need a custom colour table.  Www-safe palette is supported by some graphic editors like gimp in Linux  This a safer way of using 8bpp images, though it may not reproduce colours correctly.

As you can see from the example, there is no need to supply both  indexed and  true-colour images. In case only a 8bpp image is present, it will be used  on all platforms.  On the contrary, if only a 16bpp image is specified, it can be processed only on a handheld that supports true colours.

Notice the resource IDs!  The string resources are numbered from 1 forward  ( 1, 2, 3 etc ). This is  a preferred  way of choosing name  IDs.  You must use consecutive numbers starting from 1 if you want to read your images from an external source.  The bitmap IDs have to be always  1000+nameID, 2000+nameID , etc. Thus, in the above example,  1001 and 2001 are bitmap IDs for  "Rose" (image 1) and  1002 is the bitmap ID for Phoenix (image 2).
 

Getting all done

Once you created the .rcp file, you need to  compile it and bind into prc.

Place pilrc and par into one of PATH directories (usually   /usr/local/bin in Linux,  /usr/bin in cygwin,   C:\WINDOWS\COMMAND  or C:\WINNT\COMMAND  in MS Windows, and  C:\DOS in MS DOS).

Go to shell / command prompt and change to the directory containing the images and rcp file.
Now you say:

Linux or cygwin:
    pilrc -q  myimages.rcp
    par   c -a  "resource"  myimages.prc  "My Custom Images"   IMGE  JjIm *.bin
    rm   -f *.bin.

DOS / Windows:
    pilrc -q  myimages.rcp
    par   c -a  "resource"  myimages.prc  "My Custom Images"   IMGE  JjIm *.bin
    del  *.bin.

Comments.
First step compiles file  myimages.rcp  in the previous step and produces several .bin files.

The second step creates a Palm resource file myimages.prc from the bin files obtained from the compilation.
The file is created with data base name is "My Custom Images",   type 'IMGE',  creator ID  'JjIm' (for Jjig Images).

• Try using  a reasonably unique data base name to avoid clash.
• You  must use 'IMGE' for  data base type  and  'JjIm'  for  creator ID !

The last step removes all bin files.

After that you need to upload the .prc file to your Palm (with pilot-xfer or Palm Desktop). If the file is OK, you new images wll be listed when you restart Jjig .

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

Build-prc users need to replace the second line in the above examples with
    build-prc -t IMGE myimages.prc "My Custom Images" JjIm *.bin
 

Actually pilrc has -ro option to create a prc image straight away, though it doesn't appear to work. However -ro provides a neat way to create  the images with build-prc:

    pilrc -q -ro myimages.rcp  myimages.ro
    build-prc -t IMGE myimages.prc "My Custom Images" JjIm myimages.ro
    rm myimages.ro
 

And even simpler.

Linux or cygwin.

The following script assumes using ash - compatible shell  (ash, bsh, bash).
For csh and tcsh some minor changes are required.

Store the shell script below as  /usr/local/bin/jjigCreateImage. The file should have attributes 755:
    chmod 755 /usr/local/bin/JjigCreateImage

Now, to create Palm resource (.prc) file you change to the appropiate directory and type a single line like this:

    JjigCreateImage    myimages  "My Custom  Images"

This call compiles file  myimages.rcp and creates a resource file  myimages.prc with data base name "My Custom Images".
Note that you don't specify a file extension in the command.
 

The text of jjigCreateImage:

#! /bin/bash
#---------------------------------------------------------------------
# Create an image file (bash version)
# Synopsis:
#       JjigCreateImage prc_name db_name

filename=""
dbname=""

if (test $# = 1) ; then
    filename="$1"
    dbname="$1"
elif (test $# = 2) ; then
    filename="$1"
    dbname="$2"
fi

if ((test "$filename" = "") || (test "$dbname" = "")); then
    echo ""
    echo "Usage"
    echo "  JjigCreateImage prc_name db_name"
    echo ""
    echo "  where:"
    echo "  prc_name - name of resource file without an extension"
    echo "  tdb_name  - name of the data base"
    echo ""
    echo "Example"
    echo "  JjigCreateImage myimages \"My Custom Images\""
    echo ""
else
    echo "Compiling resource"
    pilrc -q $filename.rcp
    whichpar=`which par 2>/dev/null`
    if (test "$whichpar" = ""); then
      echo "Calling build-prc"
      build-prc -t IMGE $filename.prc "$dbname" JjIm *.bin
    else
      echo "Calling par"
      par c -a "resource" $filename.prc "$dbname" IMGE JjIm *.bin
    fi
    rm -f *.bin
fi
#-------------------------------------------------------------------------

MS DOS  or  MS Windows.

Store the script below as  jjimage.bat  in  one of PATH directories (e.g.  C:\WINDOWS\COMMAND,   C:\WINNT\COMMAND   C:\DOS)   .

Now, to create Palm resource (.prc) file you change to the appropiate directory and type a single line like this:

    jjimage   myimages  "My Custom  Images"

This call compiles file  myimages.rcp and creates a resource file  myimages.prc with data base name "My Custom Images".
Note that you don't specify a file extension in the command.
 

The text of jjigimage:

ECHO OFF
REM ---------------------------------------------------------------------
REM Create an image file (MS DOS version)
REM Synopsis:
REM jjimage prc_name db_name
REM ---------------------------------------------------------------------

SET FILENAME=%1
SET DBNAME=%2

if "%FILENAME%" == "" goto BadArg

if "%DBNAME%" == "" goto DBNameImplicit
goto DBNameExplicit

:DBNameImplicit
SET DBNAME=%FILENAME%

:DBNameExplicit

@ECHO Compiling resource
pilrc -q %FILENAME%.rcp

@ECHO ------------------
@ECHO Calling par
par c -a "resource" %FILENAME%.prc %DBNAME% IMGE JjIm *.bin
DEL *.bin
goto Exit
:BadArg
@ECHO .
@ECHO Usage
@ECHO jjimage prc_name db_name
@ECHO .
@ECHO where:
@ECHO prc_name - name of resource file without an extension
@ECHO tdb_name - name of the data base
@ECHO .
@ECHO Example
@ECHO jjimage myimages "My Custom Images"
@ECHO .

:Exit
REM ---------------------------------------------------------------------
 

Using custom palette (colour table).

As it was mentioned, using custom palette is not recommended, because:

• Palm gurus don't recommend that, because of performance issue.
• With custom colour table, some application icons will appear with wrong colours.

Be warned that official pilrc release has a bug that prevents from creating a compressed image with custom colour table, therefore your choice will be one of the following:

• Use uncompressed images
• Get pilrc fixed from Just Jigsaw site

To include a custom colour table, you just code COLORTABLE with BITMAPCOLOR directive as shown in the example above.
 
 

Known bugs and troubleshooting

Bitmap creation error

You may get  "Bitmap creating  error 502"  (please contact me with another code!) This means that you don't' have enough memory with creating bitmaps, or the memory is fragmented.  To fix the fragmentation problem,  just get out to Launcher and restart. If it still doesn't help, consider reducing the depth from 16 to 8bpp, or reducing bitmap size. Be aware that this application requires much more dynamic heap space than PictureGear^TM Pocket does.

Distorted screen or redundant screen redrawing.

Well, looks like redundant screen redrawing gets out of my control. It could be a bit better, and I hate any patches, due to unpredicted PalmOS behaviour (what I observe on the Emulator, is not what I get on my Palm).

As to distorted screen, I believe it all has been fixed, it case it wasn't, use  View / Redraw Screeen .

Bad colours with custom palette.

I should say that custom palette support is still in beta. Only few days ago I found time for fixing pilrc bug, while I couldn't do anything before that.  Anyway,  I am not going to redesign the icons, simply because I don't believe  it is so crucial. But something I positively don't like there, that you might not even notice !

Whoa, your application is big!

True, even without images, the application size is well over 100K. I am thinking of taking out build-in help into a separate file, so that you can include it optionally. Also I an going to supply incomplete versions, like "no VFS" or "no VFS and PGPF" for those who don't  need it. Visit the application site, or contact me in case you are worried about that.