                      USING THE HP EXTENSION WORDS
                      ----------------------------

                               (release 2)

The extension source file, EXTEND.SCR includes a lot of words to use the
palmtop's int 5Fh graphics functions plus several system controls. 
EXTEND.SCR isn't loaded when you start HP-PYGMY.  It's open as unit 3 -
The load block is 3000.  You can choose which extensions you want loaded
from there.

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

                                 GRAPHICS

The basic procedure to use graphic functions starts with GM    This puts
the palmtop into graphics mode (640 X 200 monochrome), clears the screen,
and sets the defaults.  Next set the origin, pen color, replacement rule,
line type, fill pattern to your needs, if different from the defaults. 
(These settings can be changed at any time during the procedure).  Then
use any graphic words you want to draw or write...   When you're done,
finish with TM to return to text mode.

All coordinates in graphic mode are in pixels, and are relative to the
logical origin.  The default range is from 0,0 (top left) to 639,199
(bottom right).  Horizontal coordinates increase toward the right;
vertical toward the bottom.

The default settings after doing GM to change to graphics are:

       Logical origin      0,0  (Top left)
       Pen location        0,0  (Top left)
       Pen color           1  (Black)
       Replacement rule    FORCE
       Line-type           $FFFF  
       Fill mask           $FF,$FF,$FF,$FF,$FF,$FF,$FF,$FF

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

                            GRAPHIC FUNCTIONS

EXTEND.SCR includes the following words to support Int 5Fh graphics:

       GM ( --) Sets 640x200 graphics mode, clears screen, and sets the
        defaults (above)

       TM ( --) Returns to text mode and clears screen

       LINE (x y --) Draws a line from the "pen" position to x,y and
        leaves the "pen" at x,y

       POINT (x y --) Draws a single pixel dot at x,y and moves "pen"

       PEN (x y --) Moves the "pen" position to x,y

       LINE-P (n --) Sets the line pattern - (default=$FFFF)

   (Note: The 3 box drawing words are different from the first release)

    |  BOX (x1 y1 x2 y2 --) Draws a rectangle with one corner at
    |   x1,y1 and the opposite one at x2,y2.  Leaves the "pen" at x2,y2
    |
    |  S-BOX (x1 y1 x2 y2 --) Like BOX, but filled with "pen color"
    |
    |  P-BOX (x1 y1 x2 y2 --) Like BOX, but filled with a preset pattern

       BLACK ( --) Sets the "pen color" to black (default)

       WHITE ( --) Sets the "pen color" to white

       G-FORCE ( --) Sets the replacement rule to "force". Each point is
        plotted in the "pen color" regardless of background (default)

       G-AND ( --) Sets replacement rule to logically AND each point
        with existing background

       G-OR ( --) Logically OR each point with background

       G-XOR ( --) Logically XOR each point with background

       G-TXT ( --) For printing text. Similar to G-FORCE but faster

       PATTERN ( b b b b b b b b --) Sets fill pattern used by P-BOX

       P1 thru P12 ( --) A dozen sample fill patterns set up

       SMALLFONT ( --)   MIDFONT ( --)  LARGEFONT ( --) Select font size

       H-TEXT ( x y a --) Prints a null-terminated string located at
        address a at x,y

       V-TEXT (x y a --) Like H-TEXT but prints vertically

        The easiest way to use these is:
            x y " string to print" H-TEXT (or V-TEXT)

       ORG (x y --) Sets the logical origin to x,y  All pixel
        coordinates are relative to this. (Default= 0,0)

       CIRCLE (r x y --) Draws a circle of radius r at x,y  Changes the
        logical origin to x,y   Who says you need floating point math
        and trig functions to draw circles??   Note: circles appear as
        ellipses due to the HP's pixel aspect ratio.

       CCIRCLE (r x y --) Draws a visually correct circle (rather than
        one with correct pixel dimensions).

     * READ-POINT (x y --point) Returns 1 if the point x,y is black, or
        0 if it's white.

     * PUT-IMG (buffer x y rule --) Copies the contents of an image 
        buffer to the screen with x,y as the top left corner.  If the 
        image won't fit, nothing is copied. The replacement rule must be
        specified. This function doesn't use the set rule.  The rule is
        a number from 0 to 7.
                0  Force
                1  And
                2  Or
                3  Xor
                4  Invert/Force
                5  Invert/And
                6  Invert/Or
                7  Invert/Xor

     * PUT-ICON (x y --) (precede with " [path] youricon.icn")
        Displays an icon (.ICN) with the top left corner at x,y.
         e.g.
               30 75 " HP-PYGMY.ICN" PUT-ICON    or
               30 125 " A:\ICONS\STS.ICN" PUT-ICON 

     * SAVE-IMG (buffer x1 y1 x2 y2 --) Saves all or part of the graphic
        screen.  This copies the area between opposite corners x1,y1 & 
        x2,y2 to the buffer. REQUIRES A 16008 BYTE BUFFER TO HOLD A FULL
        SCREEN.  Setting up the buffer is your responsibility.

     * SCROLL (fill dist dir x2 y2 x1 y1 --) Scrolls the part of the
        graphic screen between x1,y1 & x2,y2 the number of pixels (dist) 
        up, down, left or right (dir). Fills in with either black or 
        white (fill).  Some support words are defined:
                WHITE-FILL
                BLACK-FILL
                LEFT
                RIGHT
                Up   (Note the lower case "p" - The word UP is different)
                DOWN
        e.g.  
        WHITE-FILL 10 Up 350 150 50 10 SCROLL    will scroll the area of
        the screen between 50,10 & 350,150 ten pixels up and fill in with
        white. 

(The functions marked with a * are new in Release 2).

In the stack comments:
        x,y,x1,y1,x2,y2 are screen coordinates
        a is an address
        n is a number (16 bits)
        u is an unsigned number (16 bits)
        b is a single byte number
        r is the radius of a circle (in pixels - for CCTRCLE it's the x
         dimension.
        buffer or buf is the address of a buffer

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

Box drawing words now take four coordinates (opposite corners)

Printing text in graphics mode may need a little explaining.  You need to
select a font size first.  The words SMALLFONT, MIDFONT, or LARGEFONT do
this.  Screen coordinates are in pixels, and are for the upper left
corner of the first character.  The words for printing text are H-TEXT
and V-TEXT. To use these, choose a font, put the coordinates on the
stack, then the text in quotation marks (with a space after the open
quote).

For example:  LARGEFONT 30 0 " Print this text" H-TEXT will print the
string "Print this text" in the biggest font on the top of the screen
(30 pixels from the left).  V-TEXT is used the same way, but prints
from the bottom up.

To change the appearance of lines, you can use LINE-P.  This takes a single 
16-bit number on the stack.  The bit pattern is repeated over & over when 
the line is drawn.  For Example: $AAAA LINE-P will produce a line with 
alternate pixels on & off.  $AAAA = 1010101010101010 binary.

To leave graphics mode, clear the screen, and go back to text mode use TM

For a quick demonstration of several of the graphics extensions type
G-DEMO (Assuming it's already loaded).  Press [ESC] to exit the demo.  To
see how it works check out blocks 3020 and 3021.

You'll notice that vertical printing is much slower than horizontal, and
that left or right scroll is much slower than up or down.

PLEASE USE THE NEW GRAPHICS WORDS CAREFULLY.  IF ANY ITEM IS MISSING FROM
THE STACK, OR IF THE ORDER IS WRONG WHEN THESE ARE EXECUTED, IT'S
3-FINGER SALUTE TIME...   (SCROLL NEEDS 7 THINGS ON THE STACK, IN THE
RIGHT ORDER).  

* BEFORE USING SAVE-IMG, YOU'LL NEED TO SET UP A BUFFER TO HOLD THE IMAGE
DATA.  IT TAKES 16008 BYTES TO SAVE A COMPLETE SCREEN.  

I HAD TO DO A HARD REBOOT WHILE WORKING ON THIS STUFF, AND DIDN'T GET THE
CHOICE TO NOT REINITIALIZE DRIVE C  8-(   FORTUNATELY, THE IMPORTANT
STUFF WAS ALL ON THE FLASH CARD...

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

                     SYSTEM STATUS REPORT & CONTROL

EXTEND.SCR includes the following words to report or control the LX
system status:

       BATVOLT ( --) Reports voltage of main & backup batteries

       SET-ALKA ( --) Sets battery type to alkaline

       SET-NICD ( --) Sets battery type to NiCd (Rechargeable)

       CHARGE-OFF ( --) Disables charging

       CHARGE-ON ( --) Enables charging if NiCd is selected - error if
        alkaline

       POWERCHECK ( --) Reports battery voltages & charging status

     * LSLEEP?  ( --) Reports light sleep state

     * LSLEEPON ( --) Enables light sleep (normal state)

     * LSLEEPOFF ( --) Disables light sleep

     * POWERDOWN? ( --) Reports the time set for automatic powerdown

     * SET-PDTIME ( seconds --) Sets the powerdown time 60 - 3600 sec

     * SER-OFF ( --) Turns off the serial port

     * SER-WIRE ( --) Enables the wired serial port

     * SER-IR ( --) Enables the IR port

     * LXVER ( --) Reports the ROM & BIOS version and date

     * LXSTATUS ( --) Combined report of power, light sleep, & powerdown
        time

     * BUZ-X ( --) Reports speaker volume & Xtal frequency

     * STATS ( --) Combines all reports

(The functions marked with a * are new in Release 2).

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

                        RANDOM NUMBER GENERATOR

Block 3022 is a pseudo-random number generator that could be used for
games or anywhere else a series of random numbers are needed.  To use
this, put a number on the stack and do RAND. 

     e.g.  To generate random numbers between 0 and 100 do 100 RAND

The numbers will range from 0 up to, but not including the number you
specify.

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


                                                      Peniel Romanelli
                                                      peniel@web2000.net
                                                      4 September 1998