





			     Documentation for WINDOW.LIB
			     ============================

			     Last Update : 112887- DLM

			     Modified/New in this release:

                             Turbo C port
                             Aztec-like 'scr' functions
                             get_ansi_sequence() - bug fix
                             relocate_window()
                             move_window()
                             change_border()
                             remove_title()

                             keyboard_handler() Turbo C only
                             window_mover()       "      "
                             sys_move_window()    "      "
                             sys_move_help()      "      "
                             sys_show_coords()    "      "

                             Placed system into Public Domain
                             w/complete source.
                              (weren't you sick of "Shareware"?!)


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

    move_window(direction,count)
    int direction,count;

    direction - direction to move window (UP/DN/LF/RT - see window.h)
    count - must always be 1 in this release. Other values will be supported
            in future releases.

    This function moves the current window 1 cursor position in the direction
    indicated.  If the move would position the window partially off the screen
    the move IS NOT performed.  Handles shadowed and unshadowed windows. Nice
    for smooth scrolling movements.

    returns - 0 if move was performed.
             -1 if move could not be performed

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

    relocate_window(row,col)
    int row,col;

    row - target row
    col - target column

    This function attempts to move the current window pointed to by the global
    'li' to the requested row & col.  This guy is VERY fast.

    return - 0 success.
            -1 if no window to move.
            -2 if target coords would cause part of window to be off screen.

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

    change_border(border_type)
    int border_type;

    border_type - 1 of 12 valid border types (see window.h)

    Changes the border of the window pointed to by 'li' to border_type.
    Titles are preserved.  NOTE: There is a small bug that will trash titles
    written on a border type of 'blank' or 'none'. This will be fixed in the
    next release of the sources and library. Until then you can:

      a) Refrain from using border types 'blank' & 'none'  or
      b) Rewrite the titles after issuing a change_border() call or
      c) Fix the bug yourself or
      d) Hate "C", me, and PC's, sell out and buy a Commodore 64 (no drive -
         cassette tape only!) or maybe a Macinwish! (or is it Macinslop?)
         ( ... Macinjoke?)

    returns - nothing

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

    remove_title(x)
    int x;

    x - Either TOP or BOT

    Removes the top or bottom title of the window pointed to by 'li'.

    returns - nothing

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

    window_mover(x)  : Only available if compiled w/TURBO C
    int x;

    x - Either ON or OFF (see window.h)

    Enable or disable window mover.  If enabled pressing ALT + CTRL will
    bring up the built-in window mover.  The window pointed to by 'li' may
    be moved about on the screen via the cursor keys.  Exit via ESCAPE.

    returns - ON -mover is on, ALT+CTRL combination is active.
             OFF -mover is off, ALT+CTRL combination non-active.

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

    qwritef(row,col,attr,places,decimals,fnum)  /* write a float to the screen */
    int row,col,attr,places;
    float fnum;

    row    -  row to write numer on
    col    -  column to write number at
    attr   - packed attribute to write number with
    places - specifies number of digits to the left of the decimal place
	     including sign.
    decimals - specifies the number of digits to the right of the decimal point
    fnum   - a floating point number

    If fnum cannot be expressed in the field width requested the field will
    be filled with asterisks.

    returns - nothing.

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

    qwrited(row,col,attr,places,decimals,dnum) /* write a double to the screen */
    int row,col,attr,places;
    double dnum;

    row    - row to write number at
    col    - column to write number at.
    attr   - packed attribute to write number with
    places - specifies number of digits to the left of the decimal point
	     including sign.
    decimals - specifies the number of digits to the right of the decimal point
    dnum   - a double number .

    If dnum cannot be expressed in the field width requested the field is
    filled with asterisks.

    returns - nothing.

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

    directory(dir_name,mask)
    char *dir_name, *mask;


    *dir_name   -  pointer to a string containing the full path of
                   the directory to be listed.

     *mask      -  pointer to a mask to be used when listing files.
                   Use the global variable 'all_files' if your mask is "*.*".


     Returns:

              -1 if path could not be opened/found.      
               0 if path was valid.
        dir.key will contain the last key pressed upon exiting the 
                function.

        dir.indx will contain the index into dir_list[][0] of the 
                 last filename chosen.

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

    init_window(attr)
    int attr;

    attr -  starting color attribute.


	Initializes all window system variables.  Call this (once) before
    using any of the other functions in this library.

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

    make_window(row,col,rows,cols,wattr,battr,border_select)
    int row - start row of window;
    int col - start column of window;
    int rows - number of rows in window;
    int cols - number of columns in window;
    int wattr - color attribute inside window frame;
    int battr - color attribute of window border;
    int border_select - border type
    {

     Make_window() opens a window using the passed parms.  The screen 
     area where the window will open is saved.

     Returns:

             -1  if cannot allocate anymore windows (30 max).  Deallocate
                 some other windows then proceed.

             -2  if window size/placement is invalid.

              0  if window was opened successfully.

              The global variable "li" will be set on return to
              point at the structure describing the opened window.


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

    remove_window()
    {

    This function removes the currently opened window (actually the
    window pointed at by "li") and restores the screen.  Also now restores
    the cursor coordinates.

    title_window(just,buf,attr,border)
    int just   - justification flag (can be left,right,center)
    char *buf  - pointer to title message to display
    int attr   - color attribute to use
    int border - flag indicating which border to use (TOP or BOT)

    Returns: nothing.

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

    scroll_window(begin,end,dir)
    int begin - starting row to scroll
    int end   - end row to scroll
    int dir   - direction of scroll (up or down)

    Returns: nothing.

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

    title_window(just,buf,attr,border)
    int just   - justification flag;
    char *buf  - pointer to title to write;
    int attr   - color attribute to use;
    int border - flag indicating where to put title;
    {

    This function puts a title on the currently active window.  JUST 
    is a flag to indicate how the tile is to be justified.  Use the 
    globally defined right,left,and center flags to justify right, 
    left and center.

    Border is a flag to indicate where to place the title - on the top
    or bottom borders.  Use the globally defined TOP or BOT flags as 
    appropriate.

    Returns: nothing.

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

    delay(x)
    int x - amount of delay


    This function provides a simple means to generate timed delays.  
    Experiment to find the correct amount of delay by altering the 
    number passed.

    Returns: nothing.

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

    ega_check()
    {

    This function returns the value of the graphics adapter card 
    installed as found in 0040:0049 on the system var page.  A value 
    of 7 is returned if a mono board is installed and currently 
    active.  All other values indicate a CGA/EGA board is installed.

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

    clr_window(color)
    int color - color attribute of window background;
    {

    This function will clear the currently active window using the 
    color attribute passed in color.  The character found in the global
    variable CLEAR_CHAR will be used (defaults to space ).

    Returns: nothing.

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

    attr(foreground,background)
    int foreground - color of foreground;
    int background - color of background;
    {

    This function takes a for/back ground color combination and 
    returns it as a single packed integer.  

    Returns: packed color integer.

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

    qinit()
    {

    This function does first time initilaization of system variables.  
    It is called automatically by the init_window function.  If your 
    application does not use windows but you wish to use the other 
    routines in this package you must call this routine first.

    Returns: nothing.

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

    qwritelv(row,col,attr,length,str)
    int row - row to write string;
    int col - column to write string at;
    int attr - packed color attribute;
    int length - length of string to write;
    char *str - pointer to string to write;
    {

    This function writes a string pointed to by str directly to video 
    memory for a length passed in length.  This is most useful for 
    writing partial or imbedded strings.

    Returns: length written.

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

    qwrite(row,col,attr,str)
    int row - row to write string on
    int col - column to write string on;
    int attr - packed color attribute;
    char *str - pointer to string;
    {

    This function writes null-terminated string directly to video 
    memory at the row and column indicated. Note that the string MUST 
    be null-terminated.

    Returns: nothing.

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

    qwritev(row,col,attr,chr)
    int row - row to write character;
    int col - column to write character;
    int attr - packed color attribute;
    char chr - character to write;
    {

    This function writes a single character and attribute directly to 
    video memory at the row & column indicated.

    Returns: nothing.

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

    qwritecv(row,coll,colr,attr,str)
    int row - start row to write string;
    int coll- left column boundry;
    int colr - right column boundry;
    int attr - packed color attribute;
    char *str - pointer to string to write;
    {

    This function writes a null terminated string directly to cideo 
    memory.  The string is automagically centered between the left and 
    right boundries passed.  

    Returns: -1 if unsuccessful.
              0 if successful.

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

    qfillc(row,coll,colr,rows,cols,attr,ch)
    int row - start row;
    int col - start column;
    int rows - number of rows to fill;
    int cols - number of columns to fill;
    int attr - packed color attribute;
    char ch - character to write;
    {

    This function does repetitive filling of a single character and
    attribute.  The block filled is automagically centered between the 
    column boundries passed.

    Returns: -1 if unsuccessful.
              0 if successful.

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

    qfill(row,col,rows,cols,attr,ch)
    int row - start row of fill;
    int col - start column of fill;
    int rows - number of row to fill;
    int cols - number of columns to fill;
    int attr - packed color attribute;
    char ch - character to fill;
    {

    This function does repetitive fill of a block with a single
    character and attribute.

    Returns: nothing.

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

    qattr(row,col,rows,cols,attr)
    int row - start row of fill;
    int col - start column of fill;
    int rows - number of rows to fill;
    int cols - number of columns to fill;
    int attr - packed color attribute;
    {

    This function does repetitive filling of an attribute.  Useful for 
    changing the color of an area.

    Returns: nothing.

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

    qsave(row,col,rows,cols)
    int row - start row of save;
    int col - start column of save;
    int rows - number of rows in area to save;
    int cols - number of columns in area to save;
    {

    This function snapshots the screen and saves it on the heap. This
    is a low-level primitive and should only be called directly if you 
    good understanding of heap management.

    Returns: a long 0 if the heap space is exhausted.
	     a long pointer to unsigned char if save was success. This
             pointer must be saved to release the allocated memory later.

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

    qrestore()
    {

    This function removes the currently active window and restores the 
    screen area that was originally under the window.

    Returns: nothing.

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

    get_addr(row,col)
    int row - row number;
    int col - column number;
    {

    This is a low-level prim that takes a row/column and returns the 
    absolute offset into the screen matrix.

    Returns: integer offset.

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

    qbox(row,col,rows,cols,wattr,battr,border_type);
    int row - start row of box;
    int col - start column of box;
    int rows - number of rows in box (including border);
    int cols - number of columns in box (including border);
    int wattr - packed color attribute of window area;
    int battr - packed color attribute of borders;
    int border_type - type of border to use (0 - 11)
    {

    This function builds a box on the screen using the coords and 
    sizes passed.  This routine does not preserve the area under the
    box first.  Twelve possible border types are now implemented (see window.h)

    Returns: nothing.

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

    change_wcolor(window,border)
    int window - packed color attribute of window area;
    int border - packed color attribute of borders;
    {

    This function changes the color of an entire window using the parms
    passed. If the window has a border type of "none" the entire window
    area will be colored with the 'window' attribute.

    Returns: nothing.

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

    cursor(x)
    int x - on/off flag;
    {

    This function turns the cursor on or off.  Use the globally 
    defined ON & OFF flags with this function.

    Returns: nothing.

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

    get_ansi_color(color)
    int color - packed color attribute;
    {

    This function takes a packed foreground/background attribute 
    and generates the full ANSI escape sequence necessary to change the 
    system for/back ground colors.  AZTEC's "scr" functions do not modify 
    the system attributes since these are maintained/changed within the 
    ANSI.SYS driver code. There are ways to locate the driver and do 
    absolute writes to the driver block, but this is a simpler and 
    more portable approach.           

    On return the complete string is in ansi_seq[] and may be printed 
    using the standard C printf() routine.

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



         ----------------end-of-author's-documentation---------------

                        Software Library Information:

                   This disk copy provided as a service of

                        The Public (Software) Library

         We are not the authors of this program, nor are we associated
         with the author in any way other than as a distributor of the
         program in accordance with the author's terms of distribution.

         Please direct shareware payments and specific questions about
         this program to the author of the program, whose name appears
         elsewhere in  this documentation. If you have trouble getting
         in touch with the author,  we will do whatever we can to help
         you with your questions. All programs have been tested and do
         run.  To report problems,  please use the form that is in the
         file PROBLEM.DOC on many of our disks or in other written for-
         mat with screen printouts, if possible.  The P(s)L cannot de-
         bug programs over the telephone.

         Disks in the P(s)L are updated monthly, so if you did not get
         this disk  directly from the P(s)L,  you should be aware that
         the files in this set may no  longer be the current versions.

         For a copy of the latest monthly software library newsletter
         and a list of the 1,000+ disks in the library, call or write

                        The Public (Software) Library
                              P.O.Box 35705 - F
                           Houston, TX 77235-5705
                               (713) 665-7017

