                    -----------------------------------
                    --WinLib Version 1.0 by Josh Hays--
                    -----------------------------------
                    --------Documentation File---------
                    -----------------------------------

                                  --------
                                  Contents
                                  --------

                       1. Introduction to the Package
                       2. Contents of the Package 
                       3. Usage Information
                       4. Syntax Information
                       5. Version History/Planned Updates
                       6. Usage Terms/Contact Information

 ---------------
 1. Introduction
 ---------------
 
     This is a library of programs that is intended for use by program
developers for the TI-92.  It allows programmers to create, move, and delete
windows in which they may edit the screen through the use of text and
graphics without disturbing the underlying graphics.

 -----------
 2. Contents
 -----------

     The Winlib package zip contains the following files:
          winlib.txt   -- This text file
          winlib.92g   -- 92 Group file containing Winlib binaries

     Winlib.92g contains the following 92 program files:
          winnew.92p   -- Creates a window, assigns a reference number, etc.
          winmove.92p  -- Moves a window to another position on the screen
          wintext.92p  -- Creates text in a window relative to its position
          winclear.92p -- Clears the contents of a window
          winkill.92p  -- Removes a window and its associated variables

     Also included is windemo.92p, a not-so-impressive demo to show the
usage of Winlib functions.  Look at the program for information on calling
Winlib functions if you don't understand the Syntax section of this document.

 --------
 3. Usage
 --------

     Winlib can be used in your programs in one of two ways.  You can leave
the win*.92p programs separate from your base and/or supplementary programs,
or you can declare the win*.92p programs as local within a base program.
Either way, you are free to use any or all of the programs you need, and are
encouraged to not include excess programs that aren't used by your program.

     To declare programs locally, have the win*.92p program of your choice
on your calculator (preferably in the same folder as your program).  In your
base program, add the win*.92p programs to your local statement(s).  For
instance, if you wanted to use winnew and winkill, and you had variables x
and y declared as local, you'd need the following statement:

          local x,y,winnew,winkill

     Once you've done this, you need to have the programs declared.  This
should be done at the beginning of a program since local programs can't be
used until they've been declared.  However, I like to declare the local
programs at the end, to reduce clutter at the beginning of a program.  To do
this, you'd jump to a label at the end of a program, where programs are
declared, and have it return to a label just after the jump.

          ...
          goto decl
          lbl retn
          ...{program code}...
          lbl decl
          ...{local program declarations}...
          goto retn
          endprgm

     Make sure you do this only after you've localized them with the local
statement; otherwise you'd have a copy of the declared program sitting in
the folder outside the base program.  Once you have the declaration area set
up, recall each of the programs you want to use into this area.  To do this,
use 2nd-sto, which is labeled "RCL".  This will copy everything in the
recalled program, from the prgm until the endprgm, into this area.  Position
the cursor before the prgm initiator, and type "define [prgmname(args)]=".
For example, to do winnew, you'd end up with a line:

          define winnew(n,r,c,w,h)=prgm
          ...{winnew() program}...
          endprgm

     Use the following list to determine what to put within the parentheses
as arguments for the programs:

          winnew   -- (n,r,c,w,h)
          winmove  -- (n,r,c)
          wintext  -- (n,rt,ct,t)
          winclear -- (n)
          winkill  -- (n)

     You MUST use these var names for argument definitions or the programs
will not function.

 ---------
 4. Syntax
 ---------

     Syntax for calling the programs is fairly basic and is based upon the
(row,column) coordinate calling system to coordinate with the pxl*
instructions on the 92.  This system is roughly equal to (-y,x), where x and
y begin at the upper left-hand corner of the screen, and each increment is
one pixel.

     Upon creating a window, you choose a number to reference it by.  This
number is used in all subsequent calls to window manipulation functions.
The syntax for the programs is as follows:

          winnew(number,row,column,width,highth)
          winmove(number,newrow,newcolumn)
          wintext(number,textrow,textcolumn,"text")
          winclear(number)
          winkill(number)

     Winkill should be called for each open window before exiting a program,
since it not only removes windows from the graph screen but also deletes
temporary variables that are associated with and needed to manipulate
windows.  Also, if one window is above another window, you MUST kill or move
the top window before killing the lower window.  Otherwise, unintended
things may happen, such as loss of background information or the contents of
the top window.

 ----------------------------------
 5. Version History/Planned Updates
 ----------------------------------

  Release  |  Notes
  ---------------------------------------------------------------------------
    1.0    |  First public version.  Contains winnew(), winmove(), wintext(),
           |  winclear(), and winkill().


 Planned Additions/Updates:

     Improved wintext() with bounds (string length) checking
     Improved winnew() and winmove() with automatic limits resizing.
          Currently bounds checking is implemented but three of the four
          window outlines disappear if the window continues outside the
          bounds of the screen
     Add winline(), winhorz(), winvert(), winpon(), winpoff(), and winpchg()
          programs, and the winptst() function.  Remember, added functions
          to Winlib won't necessarily change the size of your program.
          You can include as few or as many parts of Winlib as is necessary
          for your needs.
     If you can think of anything else, let me know.

 ----------------------------------
 6. Usage Terms/Contact Information
 ----------------------------------

     If you use Winlib in your program, please let me know.  I'd like to see
Winlib in action.  Also, please include a line in the program header and
information/documentation file(s) with something to the effect of the
following:

          Uses Winlib 1.0 (C)1996 Josh Hays

     I can be reached through email at: johays@brownell.edu.  If you need
other contact information, let me know.  I have a web page at
http://www.brownell.edu/~johays.  Right now I have 92 information on this
server at /~johays/ti92.html.  I plan to add a support page for Winlib in
the near future.  Feel free to contact me with your ideas, suggestions,
criticisms, etc.


Winlib is (C)1996 Josh Hays.  All rights reserved.



