                          THE FORTHPAL TOOLKIT
                          ____________________


This is a small toolkit for use with HP-Pygmy Forth.  It assumes that
you have HP-Pygmy rel. 2 and are reasonably familiar with the Forth
language.

It's meant to make it a little easier to create Forth apps with the
look and feel of the built-ins or PAL-based programs.  For now, it
includes tools for allowing EMIT and most other Forth screen printing
words to work in graphics mode, and  has simple (I think) means to draw
the basic screen graphics (top title bar and function key labels),
write a title at the left, right or center of the bar, assign Forth
words to the F-keys, and label the F-keys.  Four sizes of graphic
cursor are set up (selected automatically when font size is chosen). 
Currently there's no support for pull-down menus, pop-up dialog boxes
etc.  I expect to add these whenever I get around to it  8-)

It'll almost certainly never include all the cool stuff the PAL
development team has done in C, but, hopefully it may make things
somewhat easier for the chosen few who like to program in Forth  <g>

There's support for all 4 font sizes on the palmtop.  (Yes, it includes
the tiny 6x8 font - if you can read it!).  

FORTHPAL includes a shadow block file to help explain the tools.

_______________________________________________________________________

INSTALLATION AND SETUP

Just copy FORTHPAL.SCR and FORTHPAL.DOW to your directory with HP-Pygmy
Forth.  FORTHPAL.DOW is the shadow block file with explanations of the
words in FORTHPAL.SCR

To use these together open FORTHPAL.SCR in a free even-numbered slot,
and FORTHPAL.DOW in the following odd-numbered one.  e.g.
" FORTHPAL.SCR" 8 OPEN
" FORTHPAL.DOW" 9 OPEN
To switch between these use CTRL-A when in the editor.

The extensions nust be loaded before loading FORTHPAL.  Graphic scroll
from the extensions (Block 3011) must also be loaded.  It's not loaded
by default.

The load block assumes you installed FORTHPAL as unit 8 (starting at
block# 8000).  Do 8001 LOAD to load the toolkit.  If you install it in
a different unit #, you'll need to edit the load block.  There's also
a useless demo/test of the tools called SAMPLE - and a simple Forth
source viewer that's faster than the editor, and could eventually be
the basis for a graphic mode editor (or maybe not...)

Files:

forthpal.txt      This document
forthpal.scr      Forth source block file
forthpal.dow      The shadow block file

_______________________________________________________________________

THE TOOLS

The tools are described here.  There are many variables, arrays, and
support words not listed here.  See the source and shadow blocks for 
info...


PADDING ( n  -) Sets interline padding (blank pixel lines between text
       lines).  Limited to 5 lines max - default = 0.

SETPOS ( x y  -) Stores the coordinates (in pixels) in text position
       variables.
G-TAB  ( x    -) Stores X-coordinate in a text position variable - 
       keeps existing Y coord.
G-AT   ( r c  - x y) Converts row/column coordinates to pixel coords. 
       Applies in the working area between the title bar and function
       key labels.  (Pixel coords  0,13 to 639,188).  Also stores x,y
       in the position variables.  Use this instead of AT, or redirect
       AT to G-AT  e.g.   ' G-AT IS AT  --  if you redirect, you'll
       need to restore the default with  ' (AT IS AT   Positioning 
       takes font size & interline padding into account.

SET-CURSOR ( -)  Initializes cursor data.  Cursor data array must
       contain valid cursor pattern.  Normally done automatically when
       choosing font size.
MOV-CURSOR ( x y  -)  Positions cursor at x,y  Used in graphic EMIT.
BLINK  ( -)  Enables cursor blinking if cursor is enabled.  Blink rate
       is preset at about 1S - can be changed.
NO-BLINK ( -)  Disables cursor blinking.
CURSOR-ON ( -)   Enables cursor display.
CURSOR-OFF ( -)  Disables cursor display.
TINY-CURSOR ( -)
SMALL-CURSOR ( -)
MEDIUM-CURSOR ( -)
LARGE-CURSOR ( -)  These select cursor size and initialize the cursor
       for each of the 4 font sizes.  Done automatically by the font
       selection words below.

TINY   ( -)
SMALL  ( -)
MEDIUM ( -)
LARGE  ( -)  These four select the font size, store the dimensions in
       variables, and set cursor size.

DO-CURSOR is a flag to control cursor repositioning after EMIT.  To use
       do  DO-CURSOR OFF to disable for better speed, or  DO-CURSOR ON
       for use when data entry is needed.  This does NOT control cursor
       display!

LFLAG  ( -)
RFLAG  ( -)  These set the annunciators (the symbols for Shift,
       Caps-lock etc.) to bottom left and right.  Graphic mode apps
       will want to use LFLAG to keep 'em away from the F-key labels.

GMODE  ( -) Enters graphic mode, sets annunciators to left side, and
       redirects EMIT to the graphic version.
TMODE  ( -) Returns to text mode. sets annunciators to right side, and
       restores the default EMIT.

NUL-FKEYS ( -) Initializes the 10 function key assignments to NOP so
       any unused F-keys simply do nothing.
>FNKEY ( a n  -) Takes the PFA of the Forth word to be assigned to an
       F-key and the key number, and makes the assignment.  Use either
       ' (tick) or ['] (bracket-tick-bracket) to get the PFA.  Tick is
       used outside definitions, bracket-tick-bracket inside.  Please
       read your favorite Forth book if you don't get it!
DO-FNKEY ( key  -) Wants a keycode on the stack, and if its an F-key,
       executes the assigned word - otherwise tosses the keycode.
F-LABELS ( -) Draws the 10 blank F-key labels
>F     ( a n  -) Takes the address of a null-terminated string (7
       characters max) and the key number, and prints the key label.
SET-FKEYS ( PFA1...PFA10  -) Needs 10 PFAs on the stack, and assigns
       them to the F-keys.
SET-LABELS ( a1...a10  -) Needs 10 addresses of null-terminated strings
       (7 characters max), and prints 'em on the F-key labels.

TBAR   ( -) Draws blank black title bar at the top of the screen.
TITLE  ( a  -) Takes address of null-terminated string, and prints it
       left-justified in the title bar.
C-TITLE ( a  -) Same as TITLE, but prints in center of title bar.
R-TITLE ( a  -) Same as TITLE, but prints right-justified.

SET-SCREEN ( -) This is the basic word to start your app.  It enters
       graphic mode, initializes the F-keys to NOP, and draws the title
       bar and F-key blanks.

G-CLS  ( -) Clears the working area only, without affecting title bar
       or F-key labels.  Also sets print position to top line (0,0)
       Don't use CLS -  or else redirect CLS to G-CLS  e.g.
       ' G-CLS IS CLS
       If you do this, don't forget to do  ' (CLS IS CLS before exiting
       your app.

CLOCKUP ( -)  One version of a clock.  Prints in the right end of the
       title bar.  This version is formatted as:
       Day Date Month Year (4 digits)  Hour:Minutes am/pm 
       Does not update automatically.

_______________________________________________________________________

The basic procedure to use this stuff would be something like:

SET-SCREEN
" Your Title" TITLE (or C-TITLE or R-TITLE)
Set up function keys with >FNKEY and >F or SET-FKEYS and SET-LABELS
CLOCKUP (maybe)

 ...Code for your app...

TMODE (to restore text mode)

_______________________________________________________________________

Note:  Repositioning the cursor for each character is needed for data
input.  Unfortunately this doubles the screen-write time for 
graphic EMIT.  FORTHPAL has (yet another kludge!) a flag to enable or
disable cursor repositioning.  For general screen printing do:
DO-CURSOR OFF to disable cursor positioning for faster response.  When
data entry is needed do:  DO-CURSOR ON   Graphic emit is still somewhat
slower than in text mode.  For VERY fast output use the INT5Fh text
printing capability.

For printing strings, use 
  R C G-AT  " The quick brown fox jumps over the lazy dog" H-TEXT 
instead of
  R C G-AT 2DROP  ." The quick brown fox jumps over the lazy dog" 
where R and C are the row and column position.  

BTW - If you want to see the difference, load block 8021 and do SS2 and
SS3.  Hit ESC to get out of either one.  Try SS2 with DO-CURSOR both on
and off to see the effect...

_______________________________________________________________________


Peniel Romanelli
7 September 1999
