


                                                                      






                                TOOLS FOR C
                      Application Development Package
                                 FUNCTION
                             REFERENCE MANUAL


                     Shareware Distribution Version 1.0





         This version of TOOLS FOR C and it's associated manuals and
         support files may be freely copied and distributed as long as
         it is distributed in it's entirety and no fees other than
         nominal handling fees are charged.  The routines in this
         library are NOT Public Domain.  This is copyrighted material. 
         The intent behind distributing this version of TOOLS FOR C is
         to allow you to use the package on a trial basis and determine
         if it meets your needs.  If you find yourself using this
         package, you MUST register by sending $45.00 to the address
         listed below.  Upon receipt of your registration fee we will
         send you an expanded manual, compiled libraries for all of the
         memory models available with your compiler, and the complete
         source code to the library. In NO EVENT may you use any of the
         routines in TOOLS FOR C for commercial purposes until you
         register your copy.  We feel that you will find the value of
         TOOLS FOR C far exceeds the registration fee and we at BP
         SOFTWARE SOLUTIONS, INC. thank you in advance for your
         support.







                        BP Software Solutions, Inc.
                        642 N. Commodore Drive
                        Plantation, Fl.  33325





                                          Copyright (C) 1987 
                                                BP Software Solutions Inc.
                                                       All Rights Reserved



                                                                     page 2


                             Table of Contents


                Screen and Cursor Control  . . . . . . . .    4
                     cls() . . . . . . . . . . . . . . . .    4
                     cursor()  . . . . . . . . . . . . . .    4
                     curs()  . . . . . . . . . . . . . . .    4
                     get_curs()  . . . . . . . . . . . . .    4
                     get_cursor()  . . . . . . . . . . . .    4
                     cursor_type() . . . . . . . . . . . .    5 
                     normal_cursor() . . . . . . . . . . .    5
                     block_cursor()  . . . . . . . . . . .    5
                     scroll()  . . . . . . . . . . . . . .    5
                Keyboard Functions . . . . . . . . . . . .    6
                     key() . . . . . . . . . . . . . . . .    6
                     shift_stat()  . . . . . . . . . . . .    6
                     char_waiting()  . . . . . . . . . . .    6
                Character Output . . . . . . . . . . . . .    7
                     write_a() . . . . . . . . . . . . . .    7
                     write_am()  . . . . . . . . . . . . .    7
                     write_ac()  . . . . . . . . . . . . .    7
                     write_al()  . . . . . . . . . . . . .    7
                     write_tty() . . . . . . . . . . . . .    8
                     write_str() . . . . . . . . . . . . .    8
                     print_string()  . . . . . . . . . . .    8
                     aprintf() . . . . . . . . . . . . . .    8
                String Functions . . . . . . . . . . . . .    9
                     delete_leading()  . . . . . . . . . .    9
                     del_lead_wht()  . . . . . . . . . . .    9
                     delete_trailing() . . . . . . . . . .    9
                     del_trl_wht() . . . . . . . . . . . .    9
                     right_just_str()  . . . . . . . . . .    9
                     left_just_str() . . . . . . . . . . .   10
                     center_str()  . . . . . . . . . . . .   10
                     insert_str()  . . . . . . . . . . . .   10
                Video Routines . . . . . . . . . . . . . .   11
                     vid_type()  . . . . . . . . . . . . .   11
                     save_scn()  . . . . . . . . . . . . .   11
                     rest_scn()  . . . . . . . . . . . . .   12
                     video_on()  . . . . . . . . . . . . .   12
                     video_off() . . . . . . . . . . . . .   12
                     change_att()  . . . . . . . . . . . .   12
                     h_line()  . . . . . . . . . . . . . .   13
                     v_line()  . . . . . . . . . . . . . .   13
                     vert_line() . . . . . . . . . . . . .   13
                     shuffle_image() . . . . . . . . . . .   14
                     draw_box()  . . . . . . . . . . . . .   14
                     draw_ex_box() . . . . . . . . . . . .   14
                     fill_area() . . . . . . . . . . . . .   15
                     fill_box()  . . . . . . . . . . . . .   15
                     set_vid_mode()  . . . . . . . . . . .   15
                     get_vid_mode()  . . . . . . . . . . .   15


                                                                     page 3



                Window Related Functions . . . . . . . . .   16
                     open_window() . . . . . . . . . . . .   16
                     open_ex_window()  . . . . . . . . . .   16
                     close_window()  . . . . . . . . . . .   16
                     clear_window()  . . . . . . . . . . .   16
                     activate()  . . . . . . . . . . . . .   17
                     create_window() . . . . . . . . . . .   17
                     title_window()  . . . . . . . . . . .   18
                     clear_wndw_title()  . . . . . . . . .   18
                     scroll_window() . . . . . . . . . . .   18
                     cursor_window() . . . . . . . . . . .   19
                     move_window() . . . . . . . . . . . .   19
                     wprint_string() . . . . . . . . . . .   19
                     wprint_string_att() . . . . . . . . .   19
                     wprintf() . . . . . . . . . . . . . .   20
                     fprint_window() . . . . . . . . . . .   20
                     fill_window() . . . . . . . . . . . .   20
                Menu Routines  . . . . . . . . . . . . . .   21
                     menu()  . . . . . . . . . . . . . . .   21
                Data Entry Functions . . . . . . . . . . .   23
                     get_field() . . . . . . . . . . . . .   23
                     edit_field()  . . . . . . . . . . . .   23
                     update_ins_flag() . . . . . . . . . .   24
                Index  . . . . . . . . . . . . . . . . . .   25


                                                                     page 4
                           Screen and Cursor Control



      
     FUNCTION NAME: cls() 
      
     SYNOPSIS: void cls(); 

     DESCRIPTION: 
          This function clears the screen and homes the cursor. 





      
     FUNCTION NAME: cursor() 
                    curs()

     SYNOPSIS: void cursor(col, row) 
                         int col; 
                         int row; 
               void curs(pos)
                         int pos;
     DESCRIPTION: 
          These functions place the cursor at the specified column and row
          or position.  cursor() places the cursor at the specified col and
          row.  curs() places the cursor at the position specified by the
          int "pos" where the high eight bits of "pos" are the row number
          and the low eight bits are the column number.  This is the same
          encoding returned by get_curs().  In the case of cursor() the
          upper left-hand corner of the screen is 0,0, for curs() it is 0. 





      
     FUNCTION NAME: get_curs() 
                    get_cursor() 

     SYNOPSIS: curs_pos = get_curs( void )
                         int curs_pos;  /* current col, row of cursor */ 
               void get_cursor( col, row );
                         int  *col;     /* pointer to column variable */
                         int  *row;     /* pointer to row variable    */
     DESCRIPTION: 
          These functions return the current position of the cursor.
          get_curs() returns an integer with the high 8-bits set to the row
          number and the low 8-bits set to the Column number.  get_cursor()
          places the current column and row position into the integer
          variables pointed to by col and row. 


                                                                     page 5


     FUNCTION NAME: cursor_type()

     SYNOPSIS: void cursor_type( curs_num )
                         int curs_num;    /* type code of desired cursor */
     DESCRIPTION:
          cursor_type() changes the hardware cursor size and shape to one
          of nine predefined cursors as selected by the parameter curs_num.
          The cursor is smallest when cur_num == 1 and grows steadily
          larger until it reaches the size of a full character block at
          curs_num == 8.  In the special case of curs_num == 0, the cursor
          is blanked.  
                          





     FUNCTION NAME: normal_cursor()
                    block_cursor()

     SYNOPSIS: void normal_cursor( void )
               void block_cursor( void )

     DESCRIPTION:
          These cursor shape control functions set the cursor to
          either a normal two bottom scan line cursor or a block
          occupying the full character position.







     FUNCTION NAME: scroll()

     SYNOPSIS: void scroll(u_col,u_row,l_col,l_row,lines,dir,attr);
                         int u_col;        /*  upper col                 */
                         int u_row;        /*  upper row                 */ 
                         int l_col;        /*  lower col                 */ 
                         int l_row;        /*  lower row                 */ 
                         int lines;        /*  number of lines to scroll */ 
                         int dir;          /*  direction to scroll       */ 
                         int attr;         /*  attribute                 */ 
     DESCRIPTION: 
          This function scrolls a region of the screen using the specified
          video attribute.  Lines refers to the number of lines to scroll. 
          If "lines" equals zero,  then the screen will clear using 'blank'
          characters (spaces) with the specified video attribute.  The 
          direction is specified with either 0=up or 1=down. 



                                                                     page 6
                           Keyboard Functions


     FUNCTION NAME: key()

     SYNOPSIS: ret_code = key( void );
                            int  ret_code;  /* integer return key code  */
     DESCRIPTION:  
          Returns the next character in the keystroke buffer.  If the buffer
          is empty, the routine waits for the next keystroke.  If the key is
          one of the normal ascii characters, it returns that integer value.
          If it is one of the extended keycodes ( function keys, cursor
          keys, etc. ), the high eight bits of the return integer contains
          the scan code for that key and the low eight bits contain zero. 
          KEY.H defines integer values to uniquely define most of the keys
          on an IBM compatible keyboard.

     RETURNS:
          An integer key_code.





     FUNCTION NAME: shift_stat()

     SYNOPSIS: ret_code = shift_stat( void )
                            int  ret_code;  /* integer status code  */
     DESCRIPTION:
          keybd_stat() returns and integer value with the current shift
          status of the keyboard as reported by the BIOS Get Shift Status
          function (INT 16 H, service 2).  The status of various keys can
          be determined by decoding the individual bits of the returned
          integer value as follows.
                        bit 0 == 1;  Right Shift key depressed 
                        bit 1 == 1;  Left Shift key depressed
                        bit 2 == 1;  Control key depressed
                        bit 3 == 1;  Alt key depressed
                        bit 4 == 1;  Scroll Lock is active
                        bit 5 == 1;  Num Lock is active
                        bit 6 == 1;  Caps Lock is active
                        bit 7 == 1;  Insert State is active





     FUNCTION NAME: char_waiting()

     SYNOPSIS: ret_code = char_waiting( void )
                            int  ret_code;  /* TRUE or FALSE  */
     DESCRIPTION:
          Returns TRUE (1) if a character is waiting in the keyboard
          buffer or FALSE (0) if not.






                                                                     page 7
                                Character Output


     FUNCTION NAME: write_a()

     SYNOPSIS: void write_a(ch,att) 
                         char ch; 
                         int  att; 
     DESCRIPTION:
          This function writes a character using a specified video attribute
          at the current cursor location.  The cursor is not moved. 




      
     FUNCTION NAME: write_am()

     SYNOPSIS: void write_am(ch,att,count); 
                         char ch; 
                         int  att; 
                         int  count; 
     DESCRIPTION: 
          This function writes multiple characters to the screen with a
          specified video attribute. This function is designed to write
          characters to the current row only. If the count is greater than
          the remaining spaces on that row, the results may be
          unpredictable. If the count is 'zero' (0) no characters will be
          written. 



     FUNCTION NAME: write_ac()

     SYNOPSIS: void write_ac( ch, att )
                         char ch;
                         int  att;
     DESCRIPTION: 
          This function writes a character with specified attribute and
          advances the cursor one position, wrapping to a new line if
          needed.  The screen will not scroll, however, and the cursor will
          not advance past the last position of line 25.

      


     FUNCTION NAME: write_al()

     SYNOPSIS: void write_al(col, row, attr, ch); 
                         int col; 
                         int row; 
                         int attr; 
                         char ch;
     DESCRIPTION: 
          This function writes a character with the specified attribute at
          the specified location. The location of the cursor makes no
          difference as it is not checked or used by this routine.  


                                                                     page 8

     FUNCTION NAME: write_tty()

     SYNOPSIS: void write_tty( ch );
                         char ch; 
     DESCRIPTION: 
          This function writes a specified character to the screen using the
          bios function "write character as TTY".  No attribute is written
          with the character, however, the cursor is advanced. This function
          recognizes the 'Bell', 'Backspace', 'Return' &  'Line-Feed' ascii
          characters. 




     FUNCTION NAME: write_str()

     SYNOPSIS: void write_str(col,row,string,att) 
                         int col,row;
                         char *string;
                         int att;
     DESCRIPTION: 
          Writes a string to specified location on the screen using the
          specified attribute. The position of the cursor is of no
          importance as it is not used or moved by this function.  Lines
          will wrap to the next line if one is available. The screen will
          not scroll at the end of the last line.  If you attempt to write
          past the end of the last line, those characters are lost.




     FUNCTION NAME: print_string()

     SYNOPSIS: void print_string( string,att )
                         char *string;
                         int att;
     DESCRIPTION: 
          This function prints a string with a given attribute beginning at
          the current cursor position. The '\n', '\t', and '\r' characters
          are supported. The string wraps at the end of the line and scrolls
          at the end of the screen. The cursor is left positioned one
          character to the right of the last character in the string.




     FUNCTION NAME: aprintf()

     SYNOPSIS: void aprintf(att, string, arg(s)...);
 
     DESCRIPTION:  
          This routine prints a string and expands all arguments, exactly
          like printf, and writes the string to the screen starting at the
          current cursor position using the supplied attribute "att".



                                                                     page 9
                               String Functions 


     FUNCTION NAME: delete_leading()
                    del_lead_wht()

     SYNOPSIS: void delete_leading(str)
                         char *str;
               void del_lead_wht(str)
                         char *str;

     DESCRIPTION:
          These routines remove any leading white space or control
          characters from a string.  In the case of del_lead_wht() any space
          or tab characters are deleted from the front of a string until the
          first non space/tab is reached. del_leading() does the same for
          any character with an ascii value below 21h.





     FUNCTION NAME: delete_trailing()
                    del_trl_wht()


     SYNOPSIS: void delete_trailing(str)
                         char *str;
               void del_trl_wht(str)
                         char *str;
     DESCRIPTION:
          These functions remove any white space or control codes from the
          end of a string.  del_trl_wht() removes any space or tab
          characters from the end of a string until a non space/tab is
          reached.  delete_trailing() does the same for any character below
          ascii 21h.






     FUNCTION NAME: right_just_str()

     SYNOPSIS: void right_just_str(text,outbuffer,width)
                         char *text;
                         char *outbuffer;
                         int  width;
     DESCRIPTION: 
          Pads the output string with spaces and copies the text string to
          the output buffer so that the end of the text winds up at end of
          the output string.  If the text string is longer than the
          specified width, the text is truncated to fit.  The output buffer
          must be at least one character longer than "width" to allow for
          the null byte at the end of the string.


                                                                     page 10



     FUNCTION NAME: left_just_str()

     SYNOPSIS: void left_just_str(text,outbuffer,width)
                         char *text;
                         char *outbuffer;
                         int  width;
     DESCRIPTION:  
          Pads spaces to the end of a string to the specified width. If the
          string already is as long as or longer than the specified width,
          the string is truncated to that width.  The output buffer must be
          at least one character longer than "width" to allow for the null
          byte at the end of the string.





     FUNCTION NAME: center_str()

     SYNOPSIS: void center_str(text,outbuffer,width)
                         char *text;
                         char *outbuffer;
                         int  width;
     DESCRIPTION:
          Produces a string in "outbuffer" with the specified text string
          centered between enough spaces to make the output string length
          equal to "width"(excluding the null byte).  If the text string
          length is longer than the specified width, then the text is
          truncated to fill the buffer.  The output buffer is assumed to
          be long enough to hold the centered string.  If the string is to
          be centered between an odd number of characters, the extra
          character is placed at the end of the string.





     FUNCTION NAME: insert_str()

     SYNOPSIS: int insert_str( text1, text2, out_buffer, n)
                         char *text1;
                         char *text2;
                         char *out_buffer;
                         int  n;
     DESCRIPTION:
          Inserts text2 into text1 immediately following the n'th
          character of text1, depositing the combined string in
          "out_buffer". It is the  caller's responsibility to ensure that
          the output buffer is large enough.  This function returns the
          combined length of the result string.  If text1 is shorter than
          n, text2 is concatenated to text1.


                                                                     page 11

                                 Video Routines




     FUNCTION NAME: vid_type()

     SYNOPSIS: ret_code = vid_type( void )
                        int  ret_code;

     DESCRIPTION:
          This is the routine used to determine the current video
          configuration of the machine.  It checks the current video mode
          to determine if it is 2, 3, or 7.  If the current mode is 7
          (Monochrome), then the global variables reflecting the present
          screen configuration are left set for a monochrome card.  If the
          mode is 2 (BW80) or 3 (CO80), the variables are set to reflect a
          CGA card.  The "_color" variable is only set if the current mode
          is 3.  The function normally returns OK (zero). If any mode other
          than 2, 3, or 7 is set, the function returns ERROR (-1).





     FUNCTION NAME: save_scn()

     SYNOPSIS: void save_scn(ucol, urow, lcol, lrow, buff_address) 
                         int  ucol;
                         int  urow;
                         int  lcol;
                         int  lrow;
                         char *buff_address;
     DESCRIPTION:  
          This routine saves the portion of the screen defined by the
          boundary variables to the buffer pointed to by buff_address.  No
          checking is or can be done to ensure that the buffer is big
          enough.  vid_type() must be called at least once before calling
          this function to properly set the global variables which tell it 
          where the screen buffer is and whether or not to wait for retrace.



                                                                     page 12

     FUNCTION NAME: rest_scn()

     SYNOPSIS: void rest_scn(ucol, urow, lcol, lrow, buff_address) 
                         int  ucol;
                         int  urow;
                         int  lcol;
                         int  lrow;
                         char *buff_address;
     DESCRIPTION:  
          This  routine is the opposite of save_scn().  It takes a
          previously saved screen image and returns it to the specified
          location.  As in save_scn, vid_type must be called at least once
          before calling this routine.





     FUNCTION NAME:      video_on()
                         video_off()

     SYNOPSIS: void video_on( void );
               void video_off( void );

     DESCRIPTION:

          These two functions turn the video on and off on a Color Graphics
          card to allow writing to the screen without snow.  If the mode is
          set for a Monochrome card, they simply return and no action is
          taken. vid_type() must be called at least once before calling
          either of these routines to determine what mode is presently set.






     FUNCTION NAME: change_att()

     SYNOPSIS: old_att = change_att(col,row,len,att)
                         int old_att; /* old attribute at start location  */
                         int col;     /* start column                     */
                         int row;     /*  start row                       */
                         int len;     /*  number of characters to change  */
                         int att;     /*  new attribute                   */
     DESCRIPTION:  
          Changes the video attribute, starting at the specified col and
          row, for the number of characters "len".  It returns the attribute
          byte found at the starting point.






                                                                     page 13

     FUNCTION NAME: h_line()

     SYNOPSIS: void h_line(col, row, attr, char, int count);
                         int  col;      /* start column               */
                         int  row;      /* start row                  */
                         int  attr;     /* display attribute          */
                         int  char;     /* line character             */
                         int  count;    /* line length                */
     DESCRIPTION: 
          Writes multiple copies of the character using the attribute
          specified.  They will wrap to the next line if necessary.  If the
          count is zero, no characters are written.



     FUNCTION NAME: v_line()

     SYNOPSIS: void v_line( col, row, attr, char,  number);
                         int  col;      /* start column               */
                         int  row;      /* start row                  */
                         int  attr;     /* display attribute          */
                         int  char;     /* line character             */
                         int  count;    /* line length                */
     DESCRIPTION:  
          Draws a vertical line starting at col, row, down "number" of
          characters using attribute "attr".
      





     FUNCTION NAME: vert_line()

     SYNOPSIS: void vert_line(char,attr,count);
                         int  char;  /* char to use for vertical line */
                         int  attr;  /* display attribute of line     */
                         int  count; /* length of line                */
     DESCRIPTION:
          Draws a vertical line starting at the current cursor position,
          down the "count" number of characters, using the specified
          character and display attribute. 


                                                                     page 14

     FUNCTION NAME: shuffle_image()

     SYNOPSIS: void shuffle_image(pointer,temp)
                         WNDW *pointer;
                         char *temp;
     DESCRIPTION:
          Takes a pointer to a window and a pointer to a temporary storage
          area as arguments.  The storage area must be as large as the
          window's image buffer.  The routine stores the present screen
          image at the window location in the window's image buffer and puts
          the old contents of the image buffer back on the screen.  This
          routine is called by activate() to bring an overlaid window to the
          top.







     FUNCTION NAME: draw_box()
                    draw_ex_box()

     SYNOPSIS: void draw_box(lcol,urow,rcol,lrow,box,linea,filla)
                         int  lcol;     /* left column                */
                         int  urow;     /* upper row                  */
                         int  rcol;     /* right column               */
                         int  lrow;     /* lower row                  */
                         WNDW *box;     /* pointer to window structure*/
                         int  linea;    /* border video attribute     */
                         int  filla;    /* fill video attribute       */

               void draw_ex_box(lcol,urow,rcol,lrow,box,linea,filla,speed)
                         int  lcol;     /* left column                */
                         int  urow;     /* upper row                  */
                         int  rcol;     /* right column               */
                         int  lrow;     /* lower row                  */
                         WNDW *box;     /* pointer to window structure*/
                         int  linea;    /* border video attribute     */
                         int  filla;    /* fill video attribute       */
                         int  speed;    /* exploding box drawing speed*/
     DESCRIPTION:
          These functions draw a box on the screen.  draw_box() simply draws
          the box on the screen while draw_ex_box() repetitively draws
          bigger and bigger boxes, starting at the apparent center of the
          box expanding outwards until the final box size is achieved. No
          screen saving is done here. Both routines take as arguments the
          upper left and lower right corner cursor locations, the address of
          a window structure where the correct characters for the border and
          fill can be found, the border attribute and fill character
          attribute.  draw_ex_box() takes another argument, "speed", which
          controls the rate at which the box grows. 0 is the fastest speed,
          16000 is the slowest.


                                                                     page 15


     FUNCTION NAME: fill_area()

     SYNOPSIS: void fill_area(lcol,urow,rcol,lrow,ch,attr)
                         int  lcol;     /* left column       */
                         int  urow;     /* upper row         */
                         int  rcol;     /* right column      */
                         int  lrow;     /* left row          */
                         int  ch;       /* character to fill */  
                         int  attr;     /* video attribute   */
     DESCRIPTION:
          Quickly fills the rectangular area of the screen defined by the
          parameters with the specified character and video attribute.





     FUNCTION NAME: fill_box()

     SYNOPSIS: void fill_box(lcol,urow,rcol,lrow,ch,attr)
                         int  lcol;     /* left column       */
                         int  urow;     /* upper row         */
                         int  rcol;     /* right column      */
                         int  lrow;     /* left row          */
                         int  ch;       /* character to fill */  
                         int  attr;     /* video attribute   */
     DESCRIPTION:
          Much like fill_area() except that fill_box() fills the interior
          of the box specified by the bounding rows and columns with any
          character and attribute. Please note that the area filled is
          inside, not on, the specified rows and columns.





     FUNCTION NAME: set_vid_mode()
                    get_vid_mode()

     SYNOPSIS: void set_vid_mode( modenum )
                         int  modenum    /* video mode number  */ 

               modenum = get_vid_mode( void)
                         int  modenum    /* current video mode */
     DESCRIPTION:
          These routines simply either return the int value of the current
          video mode or change it as specified.



                                                                     page 16

                            Window Related Functions



     FUNCTION NAME: open_window()
                    open_ex_window()

     SYNOPSIS: int open_window(wind)
                         WNDW *wind;
               int open_ex_window(wind,speed)
                         WNDW *wind;
                         int speed;
     DESCRIPTION:
          Takes a pointer to a window structure as an argument and calls
          create_window().  They then draw the box on the screen and fill it
          using the characters and attributes found in the structure. 

          In the case of open_ex_window() the box is drawn in an exploding
          fashion, starting at the center of the box, growing outward to
          it's final size. The speed of the growth is determined by the
          variable "speed", with 16,000 being the slowest and 0 the
          fastest.




     FUNCTION NAME: close_window()

     SYNOPSIS: void close_window(wind)
                         WNDW *wind;
     DESCRIPTION:
          Closes the window pointed to by "wind".  If the window is not the
          active window, it is first activated. Finally memory allocated to
          it's screen buffer is then freed.  Attempting to close a window
          that is not open will most likely crash the system.  As a matter
          of fact, you can count on it!


 


     FUNCTION NAME: clear_window()

     SYNOPSIS: void clear_window( void )

     DESCRIPTION: 
          Clears the active window as cls() would do for the entire
          screen.  The cursor position is not affected, however.



                                                                     page 17





     FUNCTION NAME: activate()

     SYNOPSIS: void activate(wind)
                         WNDW *wind;
     DESCRIPTION:
          Checks to see if "wind" is currently the active window.  If it is
          not, it is made the active window, overlying any other windows
          which may have been overlaying it. Upon leaving activate_wind(),
          the doubly linked list of open_windows is updated so that "wind"
          is last and the global "last_wndw" points to it.






     FUNCTION NAME: create_window()

     SYNOPSIS: ret_code = create_window(new_window)
                         WNDW *new_window;   /* window pointer        */
                         int  ret_code;      /* OK or ERROR           */
     DESCRIPTION:
          Is called by open_window() or open_ex_window().  It calculates
          the size of the image buffer and allocates memory for it. It then
          adds the new window to the end of the doubly linked list of open
          windows and saves the image at the window position.  The
          structure variables for image size, image buffer pointer,
          previous and next windows are updated here.  Nothing is drawn on
          the screen in this routine. 

     RETURNS:
          ERROR (-1) if malloc is unable to allocate the storage for the
          image buffer, otherwise, OK (zero).



                                                                     page 18
     FUNCTION NAME: title_window()

     SYNOPSIS: void title_window(window,string,attr,just_code)
                         WNDW *window;       /* pointer to window     */
                         char *string;       /* pointer to title text */
                         int  attr;          /* text display attribute*/
                         int  just_code;     /* justification code    */
     DESCRIPTION: 
          Prints the string to the top of the specified window using the
          supplied attribute. The justification code is as follows...

          1 == Top-Left;      2 == Top-Center;    3 == Top-Right;
          4 == Bottom Left;   5 == Bottom Center; 6 == Bottom Right;

          e.g. If the code is ONE, the string is left justified.  If it is
          TWO, the string is right justified, etc.  Strings longer than the
          window length minus two characters are truncated. The window is
          activated if it is not already active.






     FUNCTION NAME: clear_wndw_title()

     SYNOPSIS: void clear_wndw_title(window,row)
                         WNDW *window;       /* window pointer        */
                         int  row;           /* upper or lower row    */
     DESCRIPTION: 
          Redraws the top or bottom of the specified window with the default
          border chars and attr for that window.  The window is activated if
          it is not already active. "row" is decoded as follows:
               0 == Top-Row;
               1 == Bottom-Row;






     FUNCTION NAME: scroll_window()

     SYNOPSIS: void scroll_window(num,dir)
                         int  num;      /* number of lines to scroll  */
                         int  dir;      /* direction of scroll        */
     DESCRIPTION: 
          scrolls the active window "num" lines in direction "dir" where:
               dir == 0,  scroll up;
               dir == 1,  scroll down;



                                                                     page 19
     FUNCTION NAME: cursor_window()

     SYNOPSIS: void cursor_window(col,row)
                         int  col;
                         int  row;
     DESCRIPTION:
          Moves the cursor to the specified column and row relative to the
          window.  0,0 is the upper left hand corner of the window, just
          inside the border.  If a row or col argument is specified which is
          larger than the number of rows or columns in the window, that row
          or column position is set to the maximum value which will keep the
          cursor just inside the window border.





     FUNCTION NAME: move_window()

     SYNOPSIS: void move_window(window,direction,count)
                         WNDW *window;
                         int  direction;
                         int count;
     DESCRIPTION: 
          Moves the window "count" spaces in the direction indicated, where
                 1 = LEFT
                 2 = UP
                 3 = RIGHT
                 4 = DOWN
          If the "count" argument is greater than the number of spaces
          available on the screen, the window is only moved the number of
          spaces where all of the window will still be displayed.





     FUNCTION NAME: wprint_string()
                    wprint_string_att()

     SYNOPSIS: void wprint_string( string )
                         char *string;
               void wprint_string_att( string,att )
                         char *string;
                         int att;
     DESCRIPTION:
          wprint_string() writes a string to the currently active window
          using that window's fill attribute as it's attribute.  Lines wrap
          at the window border, and scroll on the last line. The characters
          '\n', '\t', and '\r' are supported.

          wprint_string_att() is identical, except that the specified
          attribute is used instead of the window's fill attribute.

          These routines are significantly faster than wprintf()


                                                                     page 20

     FUNCTION NAME: wprintf()

     SYNOPSIS: char_num = wprintf( control, arg(s);
                         char *control;
                         indeterminate arg(s);
                         int char_num;
     DESCRIPTION: 
          Formats a printf type string with a variable number of arguments
          and  writes it to the currently  active window.  The formatted
          sting is stored in a 256 byte global buffer "temp_str".  There is
          no checking to see if the returned string exceeds this value. 

     RETURNS:
          An integer value set to the number of characters in the formatted
          string.






     FUNCTION NAME: fprint_window()

     SYNOPSIS: void fprint_window(window, text, arg1, ...)
                         WNDW *window;       /* window pointer        */
                         char *text;         /* text spring pointer   */
                         indeterminate arg1; /* beginning of argument */
                                             /* list, if any          */
     DESCRIPTION:  
          Much like wprintf, except that instead of writing to the
          currently active window, any open window can be specified.  That
          window is then activated if it is not already the active window.






     FUNCTION NAME: fill_window()

     SYNOPSIS: fill_window( wind_ptr )
                         WNDW *wind_ptr;

     DESCRIPTION:
          Quickly fills the interior of the window using the fill character
          and fill attribute defined in the window structure.



                                                                     page 21
                                 Menu Routines


     FUNCTION NAME: menu()

     SYNOPSIS: ret_val = menu(menu_ptr)
                         MENU *menu_ptr;     /* pointer to menu struct*/
                         int  ret_val;       /* OK or ERROR           */
     DESCRIPTION:

          Only one parameter is required to execute a menu, a pointer to a
          struct MENU.  This structure contains, or points to, all of the
          information necessary to open a menu window, make a selection,
          then run the appropriate program or routine.  Error handling and
          context sensitive help are included.

          Struct MENU contains pointers to a window structure, a window
          title text string, and a screen writing function.  It also
          contains integer values for default video attributes, a menu
          cursor type code, and a window title justification code.  These
          items define the menu's video display.  The function pointers to
          help and error functions, and the integer values for the exit and
          help hot keys define the menu's behavior.  The last two items, a
          pointer to the first structure in an array of SEL structures and
          the number of SELs in the array, define the individual menu
          selections.

          Struct SEL contains a pointer to the selection text. The start
          column & row where this text will be displayed in the menu window
          (the position is referenced to the window, not the full screen).
          Integer values for select and unselect attributes if the default
          values defined in the MENU structure are not to be used (set to
          zero to use the defaults). Integer values for 2 activate keys.
          A pointer to a function to be called or a program to be executed 
          (one of these must be set to a NULL depending on which is not
          used).  A pointer to a help function (this must be a NULL pointer
          if none is provided).  Finally an integer which, if zero,
          signifies that the menu should be reentered after completion of
          the selected routine or program.  If non_zero, then the menu is
          exited and control passes back to the routine which called it.
          whether the return to the menu or the menu's caller should be
          executed at the end of the function.  

          Three types of pseudo cursors are supported. If pcursor_type == 0
          then the cursor is as long as the selected text string.  If
          pcursor_type == 1 then the cursor is as long as the longest text
          string in the selection list.  If pcursor_type == 2 then the
          cursor is as long as the window is wide.  All sections functions
          must return an integer value.. this  value should be zero for a
          normal return and any other value for an error condition.  This
          integer is passed to the menu's user defined error function where
          it must be decoded by the programmer.  If the error function is
          called with a parameter of zero a key stroke error is indicated.



                                                                     page 22



          Calling the menu routine is easy.  Setting up all of the
          necessary structures and arrays of structures, then stuffing them
          with the appropriate values is not.  We understand how difficult
          and error prone hand coding the menu structures would be, so we
          have included in the package MENUGEN.EXE which automates the
          process.  While using MENUGEN you interactively define the menu
          on screen.  When complete, MENUGEN writes the control structures
          to a file which you then include in your source code.  The
          operation of MENUGEN is covered more thoroughly in it's own
          section.

     RETURNS:
          An int value. OK (zero) or ERROR ( -1)


 
                        Listings of typedef MENU and SEL


     typedef struct MENU { 
        struct WNDW *menu_window;    /* Pointer to the menu window structure */
        int   default_non_select_att;/* Usually the same as window fill attr */    
        int   default_cursor_att;    /* Attribute of items when selected     */ 
        int   title_format;          /* Position of menu title on border(1-6)*/
        int   window_title_att;      /* Video attribute of menu title        */
        char  *window_title_text;    /* Pointer to menu title text string    */
        int   pcursor_type;          /* Type of selection cursor (0-2)       */
        int   exit_key;              /* Hot key to exit menu, Usually ESC    */
        int   help_key;              /* Hot key to call help function, if any*/
        int   (*menu_text)();        /* Ptr to function to write text to scrn*/
        int   (*error_fn)();         /* Ptr to user supplied error handler   */
        struct SEL *sel_list;        /* Ptr to the first in array of SELs    */ 
        int   num_sel;               /* Number of menu selections            */   
        }    MENU; 
    
     typedef struct SEL{ 
        char *text;               /* Pointer to item selection text string  */
        int  start_col;           /* Starting col in window for text string */
        int  start_row;           /* Starting row in window for text string */
        int  sel_att;             /* Item sel video attr, Zero for default  */ 
        int  unsel_att;           /* Item unselected video attribute or Zero*/ 
        int  activate_key_1;      /* First Activate hot key                 */
        int  activate_key_2;      /* Second Activate hot key                */
        int  (*do_function)();    /* Ptr to selected function or NULL       */ 
        char *exe_call;           /* Ptr to program name string or NULL     */ 
        int  (*help_function)();  /* Ptr to optional help fctn or NULL      */ 
        int  exit;                /* exit menu after command, Zero if no    */ 
        } SEL; 



                                                                     page 23
                              Data Entry Functions


     FUNCTION NAME: get_field()

     SYNOPSIS: ch = get_field(buffer,length,attr,just_code,under_line)
                         char *buffer;    /* pointer to data buffer      */
                         int  length;     /* maximum length of data      */
                         int  attr;       /* on screen attribute         */
                         int  just_code;  /* left(0) or right(1) justify */
                         int  under_line; /* underline(1) field or not(0)*/
                         int  ch;         /* last keycode as def in key.h*/
     DESCRIPTION:
          Gets a string into a data buffer, allowing editing and writing to
          the screen using attributes.  Left or right justification is
          supported.  The buffer MUST be length + 1 byte long.
          Justification codes are 0 = left, 1 = right. The routine exits
          whenever a keystroke with a return code less than 32 (space) or
          greater than 256 (as defined in KEY.H) is entered or the cursor
          reaches the end of the field.

     RETURNS:
          It returns a code indicating the last keystroke or a zero if the
          end of the field was reached.






     FUNCTION: edit_field()

     SYNOPSIS: ch = edit_field(buff,length,attr,underline)
                         char *buff;         /* storage buffer   */
                         int  length;        /* field length     */
                         int  attr;          /* display attribute*/
                         int  underline;     /* underline code   */
                         int  ch;            /* last keystroke   */
     DESCRIPTION:
          This function is similar to get_field() except that it first
          displays at the current cursor position the contents of "buff"
          which can then be edited. Only left justification is supported. 

     RETURNS:
          It returns a code indicating the last keystroke or a zero if the
          end of the field was reached.


                                                                     page 24




     FUNCTION NAME: update_ins_flag()

     SYNOPSIS: void update_ins_flag()

     DESCRIPTION: 
          This function is called each time the insert key is pressed while
          in the get_field() data input function. This one is a null routine
          which can be replaced by one of your own.  This is useful for
          doing things like updating an on screen prompt to reflect the
          current state of the global insert/overwrite flag "insert_flag".



                                                                     page 25










                                INDEX




         activate() . . . . . (17)         left_just_str()  . . (10)
         aprintf()  . . . . . ( 8)         menu() . . . . . . . (21)
         block_cursor() . . . ( 5)         move_window()  . . . (19)
         center_str() . . . . (10)         normal_cursor()  . . ( 5)
         change_att() . . . . (12)         open_ex_window() . . (16)
         char_waiting() . . . ( 6)         open_window()  . . . (16)
         clear_window() . . . (14)         print_string() . . . ( 8)
         clear_wndw_title() . (18)         rest_scn() . . . . . (11)
         close_window() . . . (16)         right_just_str() . . ( 9)
         cls()  . . . . . . . ( 4)         save_scn() . . . . . (11)
         create_window()  . . (17)         scroll() . . . . . . ( 5)
         curs() . . . . . . . ( 4)         scroll_window()  . . (18)
         cursor() . . . . . . ( 4)         set_vid_mode() . . . (15)
         cursor_window()  . . (19)         shift_stat() . . . . ( 6)
         del_lead_wht() . . . ( 9)         shuffle_image()  . . (14)
         del_trl_wht()  . . . ( 9)         title_window() . . . (18)
         delete_leading() . . ( 9)         update_ins_flag()  . (24)
         delete_trailing()  . ( 9)         v_line() . . . . . . (13)
         draw_box() . . . . . (14)         vert_line()  . . . . (13)
         draw_ex_box()  . . . (14)         vid_type() . . . . . (11)
         edit_field() . . . . (23)         video_off()  . . . . (12)
         fill_area()  . . . . (15)         video_on() . . . . . (12)
         fill_box() . . . . . (15)         wprint_string()  . . (19)
         fill_window()  . . . (20)         wprint_string_att()  (19)
         fprint_window()  . . (20)         wprintf()  . . . . . (20)
         get_curs() . . . . . ( 4)         write_a()  . . . . . ( 7)
         get_cursor() . . . . ( 4)         write_ac() . . . . . ( 7)
         get_field()  . . . . (23)         write_al() . . . . . ( 7)
         get_vid_mode() . . . (15)         write_am() . . . . . ( 7)
         h_line() . . . . . . (12)         write_str()  . . . . ( 8)
         insert_str() . . . . (10)         write_tty()  . . . . ( 8)
         key()  . . . . . . . ( 6)

