
                                  SSTT  1.10
                                  ----------

                  Stevens Software Tools (Turbo)  'C' library
                  -------------------------------------------

    


                                   CONTENTS


    1.      Introduction . . . . . . . . . . . . . . . . . . . . . . . . .
      1.1        Copyright . . . . . . . . . . . . . . . . . . . . . . . .
      1.1.1           Legal notice . . . . . . . . . . . . . . . . . . . .
      1.2        Technical support . . . . . . . . . . . . . . . . . . . .
      1.3        Distribution  . . . . . . . . . . . . . . . . . . . . . .
        1.3.1         P.D.N . . . . . . . . . .  . . . . . . . . . . . . .
        1.3.2         NON COMMERCIAL use . . . . . . . . . . . . . . . . .
        1.3.3         COMMERCIAL use . . . . . . . . . . . . . . . . . . .
      1.4        Acknowledgements  . . . . . . . . . . . . . . . . . . . .


    2.      Configurable items . . . . . . . . . . . . . . . . . . . . . .
      2.1        Windows . . . . . . . . . . . . . . . . . . . . . . . . .
      2.2        Data entry  . . . . . . . . . . . . . . . . . . . . . . .
      2.3        Editor  . . . . . . . . . . . . . . . . . . . . . . . . .
      2.4        Help system . . . . . . . . . . . . . . . . . . . . . . .

    3.      Low level functions  . . . . . . . . . . . . . . . . . . . . .
      3.1        Video functions . . . . . . . . . . . . . . . . . . . . .
      3.2        Keyboard functions  . . . . . . . . . . . . . . . . . . .
      3.3        Mouse functions . . . . . . . . . . . . . . . . . . . . .
      3.4        String functions  . . . . . . . . . . . . . . . . . . . .
      3.5        Miscellaneous functions . . . . . . . . . . . . . . . . .

    4.      High level functions . . . . . . . . . . . . . . . . . . . . .
      4.1        Window functions  . . . . . . . . . . . . . . . . . . . .
      4.2        Menu functions  . . . . . . . . . . . . . . . . . . . . .
      4.3        Data entry functions  . . . . . . . . . . . . . . . . . .
      4.4        Editor functions  . . . . . . . . . . . . . . . . . . . .
      4.5        Help system functions . . . . . . . . . . . . . . . . . .




    1.  Introduction:
    -----------------


        This SSTT toolkit is provided to extend your C compilers standard
        run time library. It contains a substantial number of functions
        which provide a variety of capabilities.

        The toolkit may be used FREE of charge (i.e. dont send any money
        to me) for NON-COMMERCIAL use.  The fee for COMMERCIAL use has not
        been established yet but you may contact me regarding this for
        more information.

        The only compiler support for the moment is Turbo C, Turbo C++ and
        Borland C++ (however no C++ extensions have been used here).


        The toolkit has the following features.


        o       Low Level video support.
        o       Low Level keyboard support.
        o       Low level mouse support.
        o       Low level string manipulation
        o       High level windows system.
        o       High level pull down menus.
        o       High level formatted data entry.
        o       High level help system.
        o       High level simple editor interface.


        I would expect several small bugs to be floating around, so if you
        find any then please let me know, or better still try to fix them
        and tell me what to do.


        Thank you to Borland International for your fine range of
        Compiler products.




    1.1  Copyright:
    ---------------

        Documentation - (C)  Copyright  1991,1992  by Steven Lutrov.

        Source code   - (C)  Copyright  1991,1992  by Steven Lutrov.


        No patent liability is assumed with respect to the use of the
        information contained herein.

        You may develop any program you want by using the SSTT library.

        You may sell or give away your programs you develop using the
        toolkit including executable programs and their object modules.

        You may modify this code code to your hearts content for your
        own use.

        You may not publish this source code as your own work even if you
        have modified it.





    1.1.1  Legal notice:
    --------------------

        In no event shall Steven Lutrov or be liable to you or anyone else
        for any damages or costs, including, but not limited to, any lost
        profits, lost savings, lost income, lost information, loss of life,
        loss of spouses life, or any other incidental or consequential damages
        arising out of  the use or inability to use the SSTT library.






    1.2  Technical support:
    ----------------------


        Since I run a BBS system I am prepared to setup an Echomail
        support conference and any messages can be posted here where
        I or other users will try and answer any qeuries etc..

        Should you have any improvements additions or corrections to the
        source code, then by all means post them to me, they are extremely
        welcome here.

        Your name ( if you have no objections) will then added to the
        acknowledgements section.


        o       Land mail               Steven Lutrov
                                        P.O. Box 466
                                        Essendon 3040, VIC
                                        Australia

        o       Electronic mail         The Software Parlour BBS system
                                        phone  - 61-3-301-1877
                                        bauds  - V42bis,V32,V22bis,V22,V21

                                        Crash Mail - 24 hours

                                        Email  - 3:635/534@fido
                                                 58:4100/34@intlnet


     1.3.  Distribution:
     -------------------


     You are encouraged to  copy the toolkit files and  share  it  freely
     with others.  You have the luxury of trying out the complete programs
     at your own pace and in the comfort of  your  own home  or workplace.



     1.3.1.  P.D.N:
     --------------


     The  PDN  ( Programmers Distribution Network ) is   dedicated   to
     supporting programmers all  over the  world  and has  many notable
     programmers involved. The PDN distributes  source code, utilities,
     libraries .., shareware, public domain and freeware etc.


     This toolkit is also officially released to the PDN and shall meet
     all the requirements required by the PDN.


     More information may be obtained from the following..


     PDN International Coordinator    - Erik Vanriper
                                        1:260/230@fido.org




    1.3.2  NON-COMMERCIAL use:
    --------------------------

        You may use the SSTT toolkit in a NON-COMMERCIAL enviroment free
        of charge.




    1.3.3  COMMERCIAL use:
    ----------------------


        To use the SSTT toolkit in a COMMERCIAL enviroment, a commercail
        license must be obtained, otherwise it would be a breach of
        the copyright laws.

        For pricing information you will need to contact the author ,
        see section 1.2 .



    1.4  Acknowledgements:
    ----------------------


        Steven Lutrov     - Ver 1.0    ( initial release.)






    2.  Configurable items:
    -----------------------

        This section is used in assisting function call parameters.
        Basically they are descriptions of the constants declared
        in the header files and what they do.


        sstwin.h        - Window header
        sststr.h        - String header
        sstkey.h        - Keyboard header



    2.1 Windows:
    ------------


        Window areas.
        ------------

        WIN_BORDER                    - border or frame
        WIN_TITLE                     - title area
        WIN_ACCENT                    - accent or highlight bar
        WIN_FACE                      - all of the window face
        WIN_FLDFACE                   - fields in window face
        WIN_HOTKEY                    - hotkey char used in menu windows
        WIN_ALL                       - all above components


        Title justification.
        --------------------

        JUST_C                     - centre justify
        JUST_L                     - left justify
        JUST_R                     - right justify



        Border types.
        -------------

        BRD_SPACE                  - space filled box
        BRD_SINGLE                 - single line box
        BRD_DOUBLE                 - double line box
        BRD_DOUBLESIDE             - double sides & single top box
        BRD_DOUBLETOP              - double top & single sides dox
        BRD_DOUBLESIDE             - single top, double sides
        BRD_DOUBLESIDE             - single top, double sides
        BRD_DOUBLETOP              - single side, double top
        BRD_DOUBLETOP              - single side, double top

        BRD_PULLDOWN               - special used for pulldown menus


        Window intensity.
        -----------------

        BRIGHT                     - hight intensity
        DIM                        - low intensity





    2.2 Data entry:
    ---------------



        Field types.
        ------------

        FLD_ALNUM                   - alpha & numeric
        FLD_ALPHA                   - alpha only
        FLD_DIGIT                   - digit only
        FLD_ASCII                   - ascii char only
        FLD_PRINT                   - printable character
        FLD_XDIGIT                  - hexadecimal char
        FLD_DATE                    - date fromat char
        FLD_INT                     - integer
        FLD_CURR                    - currency format


        Field conversions.
        ------------------

        FLD_TOUPPER                    - convert field to upper case
        FLD_TOLOWER                    - convert field to lower case
        FLD_NFILL                    - fill blanks with space char
        FLD_ZFILL                    - fill blanks with zero char


        Field Help Types.
        -----------------


        HELP_NOWAIT                 - instant help on field
        HELP_WAIT                   - wait for HELP keypress on field
        HELP_DONE                   - help completed flag


    2.3   Editor:
    -------------



        Editing keystrokes.
        -------------------


        RETURN       - inserts carrage return.
        ESC          - exits the editor.
        TAB          - moves to the next tab stop.
        SHIFT_TAB    - moves to the previous tab stop.

        UP           - moves up one line.
        PGUP         - moves up one page.
        CTRL_PGUP    - moves to the top of the 1st page.

        DOWN         - moves down one line.
        PGDN         - moves down one page.
        CTRL_PGDN    - moves to the bottom of the last page.

        LEFT         - moves left on character.
        CTRL_LEFT    - moves to the previous word.

        RIGHT        - move forward on character.
        CTRL_RIGHT   - moves to the next word.

        HOME         - moves to the first column.
        CTRL_HOME    - moves to the first column and row on
                       the first page.

        END          - moves to the end of the last page.
        CTRL_END     - moves to the last column and row on
                       to the last page.

        INS          - toggles inserting mode.
        DEL          - deletes the predecessing character.

        CTRL_Y       - deletes the current line.
        CTRL_D       - deletes the predecessing word.

        F2           - Exits the editor.
        F3           - erases the edit buffer.
        F4           - reformats the current block.
        ALT_F7       - copies the current block.
        F7           - marks the block begining.
        F8           - marks the block end.
        ALT_F8       - move_block the current block;
        F9           - deletes the current block.
        F10          - unmark blocks.




    2.4 Help system:
    ----------------



        Documentation not yet finalised.




    3.  Low level functions:
    ------------------------

        The low level functions are mainly for video, keyboard and mouse
        functions.


    3.1  Video functions:
    ---------------------





    ------------------------------------------------------------------------
    NAME          ... vblinkbit

    DESCRIPTION   ... Enables or disables the blink bit in the video
                      register. The function tests for and EGA and VGA
                      system as these are the only systems that will
                      support this function.

    PROTOTYPE     ... int vblinkbit(int flag);

    ARGUMENTS     ... flag         - 1  blinking is enabled.
                                     0  intensity is enabled.

    RETURNS       ... !0           - If system supports blinking and
                                     intensity modes.
                       0           - Function not supported.


    ------------------------------------------------------------------------
    NAME          ... vclearrline

    DESCRIPTION   ... Clears the an entire line on the screen with an
                      attribute.

    PROTOTYPE     ... void vclearrline (unsigned char l, unsigned char a);

    ARGUMENTS     ... l            - The line to clear.
                      a            - The attribute to clear the screen with.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vcls

    DESCRIPTION   ... Clears the entire screen with an attribte by scrolling.

    PROTOTYPE     ... void vcls (unsigned char a);

    ARGUMENTS     ... a            - The attribute to clear the screen with.

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... vfill

    DESCRIPTION   ... Fills a rectangular area of the screen with a given
                      char and attribute.

    PROTOTYPE     ... void vfill(int x, int y, int yy, int xx, int c, int a);

    ARGUMENTS     ... x            - Starting column.
                      y            - Starting row.
                      yy           - Number of rows.
                      xx           - Number of columns.
                      c            - Char used for filling
                      a            - Attribute used for filling.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vget

    DESCRIPTION   ... Gets a character and attribute form the screen at the
                      given coordinates.

    PROTOTYPE     ... int vget(int x, int y);

    ARGUMENTS     ... x            - Starting column.
                      y            - Starting row.

    RETURNS       ... 16 bit word (integer) holding the char and attribute.
                      The high order 8 bits hold the attribute and the low
                      order 8 bits hold the char.


    ------------------------------------------------------------------------
    NAME          ... vgeta

    DESCRIPTION   ... Gets an attribute form the screen at the given
                      coordinates.

    PROTOTYPE     ... int vgeta(int x, int y);

    ARGUMENTS     ... x            - Starting column.
                      y            - Starting row.

    RETURNS       ... 16 bit word (integer) holding the attribute.



    ------------------------------------------------------------------------
    NAME          ... vgetac

    DESCRIPTION   ... Gets an attribute form the screen at the current
                      cursor coordinates.

    PROTOTYPE     ... int vgetac(void);

    ARGUMENTS     ... void

    RETURNS       ... 16 bit word (integer) holding the attribute.




    ------------------------------------------------------------------------
    NAME          ... vgetch

    DESCRIPTION   ... Gets a char form the screen at the given coordinates.

    PROTOTYPE     ... int vgetch(int x, int y);

    ARGUMENTS     ... x            - Starting column.
                      y            - Starting row.

    RETURNS       ... 16 bit word (integer) holding the char.



    ------------------------------------------------------------------------
    NAME          ... vgetchc

    DESCRIPTION   ... Gets a char form the screen at the current
                      cursor coordinates.

    PROTOTYPE     ... int vgetchc(void);

    ARGUMENTS     ... void

    RETURNS       ... 16 bit word (integer) holding the char.




    ------------------------------------------------------------------------
    NAME          ... vgetcur

    DESCRIPTION   ... Returns the current cursor positions. Make sure you
                      pass the address to the arguments.

    PROTOTYPE     ... void vgetcur(int *x, int *y);

    ARGUMENTS     ... x            - The column.
                      y            - The row.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vhidecur

    DESCRIPTION   ... Hides the cursor making it invisible to the screen.

    PROTOTYPE     ... void vhidecur(void);

    ARGUMENTS     ... void

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... visega

    DESCRIPTION   ... Test if an EGA adaptor is installed.

    PROTOTYPE     ... int visega(void);

    ARGUMENTS     ... void

    RETURNS       ... !0           - EGA adaptor present.
                      0            - EGA adaptor NOT present.


    ------------------------------------------------------------------------
    NAME          ... visvga

    DESCRIPTION   ... Test if an VGA adaptor is installed.

    PROTOTYPE     ... int visvga(void);

    ARGUMENTS     ... void

    RETURNS       ... !0          - VGA adaptor present.
                      0           - VGA adaptor NOT present.



    ------------------------------------------------------------------------
    NAME          ... vnormalcur

    DESCRIPTION   ... Makes the cursor appear in its normal state, as it
                      would from boot-up state.

    PROTOTYPE     ... void vnormalcur(void);

    ARGUMENTS     ... void

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... vpopcur

    DESCRIPTION   ... Pops the last saved cursor configuration and position
                      from the cursor save stack.

    PROTOTYPE     ... void vpopcur(void);

    ARGUMENTS     ... void

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vpopscreen

    DESCRIPTION   ... Pops the last saved screen from the screen save stack.

    PROTOTYPE     ... void vpopscreen(void);

    ARGUMENTS     ... void

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vpushcur

    DESCRIPTION   ... Saves the current cursor configuration and position
                      to the cursor save stack.

    PROTOTYPE     ... void vpushcur(void);

    ARGUMENTS     ... void

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... vpushscreen

    DESCRIPTION   ... Pushes (saves) an entire screen to the screen save
                      stack. The stack is allocated in the far heap , The
                      Turbo C enviroment (Turbo C editor & debugger) under
                      normal conditions does not leave you much memory
                      here, so you will have to change the options to make
                      more of the far heap available.

    PROTOTYPE     ... int vpopscreen(void);

    ARGUMENTS     ... void

    RETURNS       ... 0          - No errors.
                      -1         - Maximum screen saves exceeded.
                      -2         - Out of memory, (far heap).



    ------------------------------------------------------------------------
    NAME          ... vputch

    DESCRIPTION   ... Writes a char directly to the video memory with
                      a specified attribute.

    PROTOTYPE     ... void vputch(int x, int y, unsigned char a,
                                  register unsigned char c);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.
                      a            - The attribute to write in.
                      c            - The char to write.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vputf

    DESCRIPTION   ... Writes a string directly to the video memory with
                      a specified attribute, using a variable argument
                      convention.

    PROTOTYPE     ... void vputf(int x, int y, unsigned char a,
                                 char *fmt, ...);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.
                      a            - The attribute to write in.
                      fmt          - The formated string to write.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vputfc

    DESCRIPTION   ... Writes a centered string directly to the video memory
                      with  a specified attribute, using a variable argument
                      convention.

    PROTOTYPE     ... void vputfc(int y, unsigned char a, char *fmt, ...);

    ARGUMENTS     ... y            - The starting row.
                      a            - The attribute to write in.
                      s            - The formatted string to write.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vputs

    DESCRIPTION   ... Writes a string directly to the video memory with
                      a specified attribute.

    PROTOTYPE     ... void vputs(int x, int y, unsigned char a,
                                 register char *cp);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.
                      a            - The attribute to write in.
                      cp           - The string to write.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vputsc

    DESCRIPTION   ... Writes a centered string directly to the video memory
                      with  a specified attribute.

    PROTOTYPE     ... void vputsc(int y, unsigned char a, char *s);

    ARGUMENTS     ... y            - The starting row.
                      a            - The attribute to write in.
                      s            - The string to write.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vset25

    DESCRIPTION   ... Sets the video adaptor to display 25 lines per screen.

    PROTOTYPE     ... void vset25(void);

    ARGUMENTS     ... void

    RETURNS       ... void

    ------------------------------------------------------------------------
    NAME          ... vset43

    DESCRIPTION   ... Sets the video adaptor to display 43 lines per screen.
                      This is only possible on EGA and VGA systems.

    PROTOTYPE     ... void vset43(void);

    ARGUMENTS     ... void

    RETURNS       ... void

    ------------------------------------------------------------------------
    NAME          ... vset50

    DESCRIPTION   ... Sets the video adaptor to display 50 lines per screen.
                      This is only possible on EGA and VGA systems.

    PROTOTYPE     ... void vset50(void);

    ARGUMENTS     ... void

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vsetcur

    DESCRIPTION   ... Positions the cursor at the specified coordinates.

    PROTOTYPE     ... void vsetcur(int x, int y);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... vsetcurtype

    DESCRIPTION   ... Sets the cursor for a particular appearance. Refer to
                      the IBM manual on Interrupt 0x10 for charactersitics.

    PROTOTYPE     ... void vsetcurtype(unsigned t);

    ARGUMENTS     ... t            - The cursor type.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vshowcur

    DESCRIPTION   ... Unhides the cursor, this is usually called some time
                      after the vhidecur function to make the cursor
                      visible again.

    PROTOTYPE     ... void vshowcur(void);

    ARGUMENTS     ... void

    RETURNS       ... void






    3.2  Keyboard functions:
    ------------------------



    ------------------------------------------------------------------------
    NAME          ... kgetch

    DESCRIPTION   ... Gets a character from the keyboard and hooks to a
                      help function if the help key is pressed. The global
                      variable help_key is set to F1 by default, but may
                      be overwritten by re-assignment.

    PROTOTYPE     ... int kgetch(void);

    ARGUMENTS     ... void

    RETURNS       ... The character received.



    ------------------------------------------------------------------------
    NAME          ... kkeyhit

    DESCRIPTION   ... Tests if a key has been pressed.

    PROTOTYPE     ... int kkeyhit(void);

    ARGUMENTS     ... void

    RETURNS       ... !0          - Key has been hit.
                      0           - No key has been hit.



    ------------------------------------------------------------------------
    NAME          ... kstate

    DESCRIPTION   ... Test the state of all the special keys by using a bios
                      call. The function returns a 16 bit word holding the
                      state of the keys. The following constants may be used
                      in determining if a key is pressed by ANDing the
                      returned result.

                             K_RIGHTSHIFTDOWN     - right shift key is down.
                             K_LEFTSHIFTDOWN      - left shift key is down.
                             K_CTRLSHIFTDOWN      - ctrl shift keys are down.
                             K_ALTSHIFTDOWN       - alt shift keys are down.
                             K_SCROLLLOCKON       - scroll-lock key is on.
                             K_NUMLOCKON          - num-lock key is on.
                             K_CAPSLOCKON         - caps-lock key is on.
                             K_INSON              - insert key is on.
                             K_CTRLNUMLOCKON      - ctrl num-lock keys are on.
                             K_SCROLLLOCKDOWN     - scroll-lock key is down.
                             K_NUMLOCKDOWN        - num-lock key is down.
                             K_CAPSLOCKDOWN       - caps-lock key is down.
                             K_INSDOWN            - insert key is down.


    PROTOTYPE     ... int far *kstate(void);

    ARGUMENTS     ... void

    RETURNS       ... Far pointer to an integer (16 bit word) of the key
                      states.





    3.3  Mouse functions:
    ---------------------



    ------------------------------------------------------------------------
    NAME          ... msgetch

    DESCRIPTION   ... Suspends execution until a mouse button is pressed.

    PROTOTYPE     ... #define msgetch()  while(mspressed());

    ARGUMENTS     ... void

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... msgetpos

    DESCRIPTION   ... Gets the mouse coordinates.

    PROTOTYPE     ... void msgetpos(int *x, int *y);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... mshide

    DESCRIPTION   ... Hides the mouse cursor making it invisible.

    PROTOTYPE     ... void mshide(void);

    ARGUMENTS     ... void

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... msinstalled

    DESCRIPTION   ... Tests to see if the mouse driver is installed.

    PROTOTYPE     ... int msinstalled(void);

    ARGUMENTS     ... void

    RETURNS       ... !0           - Mouse is installed.
                      0            - Mouse is not installed.


    ------------------------------------------------------------------------
    NAME          ... msleftpressed

    DESCRIPTION   ... Tests if the left mouse button has been pressed.

    PROTOTYPE     ... #define msleftpressed()  (mspressed()&1)

    ARGUMENTS     ... void

    RETURNS       ... !0           - The left button has been pressed.
                      0            - The left button has not been pressed.



    ------------------------------------------------------------------------
    NAME          ... mspressed

    DESCRIPTION   ... Tests if the mouse buttons are pressed.

    PROTOTYPE     ... int mspressed(void);

    ARGUMENTS     ... void

    RETURNS       ... !0           -  The mouse buttons are pressed.
                      0            -  The mouse buttons are not pressed.



    ------------------------------------------------------------------------
    NAME          ... msreleased

    DESCRIPTION   ... Tests if a mouse button has been released.

    PROTOTYPE     ... int msreleased(void);

    ARGUMENTS     ... void

    RETURNS       ... !0           - The mouse button has been released.
                      0            - The mouse button has not been
                                      released.


    ------------------------------------------------------------------------
    NAME          ... msreset

    DESCRIPTION   ... Resets the mouse.

    PROTOTYPE     ... void msreset(void);

    ARGUMENTS     ... void

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... msrightpressed

    DESCRIPTION   ... Tests if the right mouse button has been pressed.

    PROTOTYPE     ... #define msrightpressed()   (mspressed()&2)

    ARGUMENTS     ... void

    RETURNS       ... !0           - The right button has been pressed.
                      0            - The right button has not been pressed.




    ------------------------------------------------------------------------
    NAME          ... mssetpos

    DESCRIPTION   ... Positions the mouse cursor at a specific location.

    PROTOTYPE     ... void mssetpos(int x, int y);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... mssettravel

    DESCRIPTION   ... Sets the mouse travel limits.

    PROTOTYPE     ... void mssettravel(int minx, int maxx,
                                           int miny, int maxy);

    ARGUMENTS     ... minx         - Minimum starting column.
                      maxx         - Maximum ending column.
                      miny         - Minimum starting row.
                      maxy         - Maximum ending row.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... msshow

    DESCRIPTION   ... Enables the mouse cursor, making it visible.

    PROTOTYPE     ... void msshow(void)

    ARGUMENTS     ... void

    RETURNS       ... void






    3.4  String functions:
    ----------------------



    ------------------------------------------------------------------------
    NAME         ... strchangechar

    DESCRIPTION  ... Finds all letters in a string matching one character
                     and replaces them with another, observing case when
                     replacing.

    PROTOTYPE    ... int  strchangechar(char *s, int a, int b);

    ARGUMENTS    ... s             - String to search.
                     a             - Char to search for.
                     b             - Char to replace with.

    RETURNS      ... The number of matches found.


    ------------------------------------------------------------------------
    NAME         ... strchangestr

    DESCRIPTION  ... Changes all occurrences of one string to another,
                     obsering case when replacing.

    PROTOTYPE    ... char *strchangestr(char *s, char *a, char *b);

    ARGUMENTS    ... s             -  String to search.
                     a             -  String to search for.
                     b             -  String to replace found strings.

    RETURNS      ... The address of the modified string, or NULL if no
                     matches were found.



    ------------------------------------------------------------------------
    NAME         ... strchecksum

    DESCRIPTION  ... Calculates the checksum of a string. The checksum is
                     calculated by adding up the ASCII values of each
                     character in the string.

    PROTOTYPE    ... unsigned long strchecksum(char *s);

    ARGUMENTS    ... s             -  String to checksum.

    RETURNS      ... The checksum of the input string.



    ------------------------------------------------------------------------
    NAME         ... strcode

    DESCRIPTION  ... Encodes/decodes a string. Call this function to encode
                     a string, then call again using the same key to decode
                     it.  When reading or writing from a disk file, be sure
                     to open the file in binary mode.


    PROTOTYPE    ... char *strcode(char *s, char *k);

    ARGUMENTS    ... s             -  String to encode/decode.
                     k             -  Key string.

    RETURNS      ... The address of the input string



    ------------------------------------------------------------------------
    NAME         ... strcountchar

    DESCRIPTION  ... Counts occurrences of a character in a string,
                     observing case of letters.

    PROTOTYPE    ... int  strcountchar(char *s, int c);

    ARGUMENTS    ... s             -  String to search.
                     c             -  Char to search for.

    RETURNS      ... The number of occurrences of the character in the
                     string.



    ------------------------------------------------------------------------
    NAME         ... strcountstr

    DESCRIPTION  ... Counts occurrences of one string within another,
                     observing case of letters.

    PROTOTYPE    ... int  strcountstr(char *a, char *s);

    ARGUMENTS    ... a             -  String to search for.
                     s             -  String to search.

    RETURNS      ... The number of times that string a occurs in
                     string s.


    ------------------------------------------------------------------------
    NAME         ... strcvt

    DESCRIPTION  ... Performs one or a number of conversions on a string,
                     according to the options provided. You can pass the
                     following pre-defined constants as the option
                     parameter and may OR them to perform multiple
                     operations.


                     RABLANKS        - remove all blanks
                     RANONALPHA      - remove all non alphabetic chars
                     RANONNUM        - remove all non numeric chars
                     RALEADBLANKS    - remove all leading blanks
                     RTRBLANKS       - remove trailing blanks
                     RAALPHA         - remove all alphabetic chars
                     RANUMERIC       - remove all numeric chars
                     RAPUNCT         - remove all punctuation
                     CMBTOBRD_SINGLE     - convert multiple blanks to single
                     CLCTOUPPER      - convert lower case chars to upper
                     CUCTOLOWER      - convert upper case chars to lower
                     UCWORDS         - capitalize all words
                     NUCWORDS        - un - capitalize all words


    PROTOTYPE    ... char *strcvt(char *d, char *s, int option, int ml);

    ARGUMENTS    ... d             -  Destination string.
                     s             -  Source string.
                     option        -  Option required.
                     ml            -  Maximum length of string.

    RETURNS      ... Address of the modified string, or NULL if substring
                     not found.



    ------------------------------------------------------------------------
    NAME         ... strdelete

    DESCRIPTION  ... Deletes a substring from within a string, observing
                     case when deleting.

    RETURNS      ... char *strdelete(char *a, char *s);

    ARGUMENTS    ... a             -  Substring to delete.
                     s             -  String to delete from.

    RETURNS      ... Address of the modified string, or NULL if substring
                     not found.




    ------------------------------------------------------------------------
    NAME         ... strdeleteall

    DESCRIPTION  ... Deletes all occurrences of a substring from within a
                     string, observing case of letters.

    PROTOTYPE    ... char *strdeleteall(char *a, char *s);

    ARGUMENTS    ... a             -  Substring to delete.
                     s             -  String to delete from.

    RETURNS      ... Address of the modified string, or NULL if substring
                     not found.




    ------------------------------------------------------------------------
    NAME         ... strichangestr

    DESCRIPTION  ... Changes all occurrences of one string to another,
                     ignoreing case when replacing.

    PROTOTYPE    ... char *strichangestr(char *s, char *a, char *b);

    ARGUMENTS    ... s             -  String to search.
                     a             -  String to search for.
                     b             -  String to replace found strings.

    RETURNS      ... The address of the modified string, or NULL if no
                     matches were found.



    ------------------------------------------------------------------------
    NAME         ... strichecksum

    DESCRIPTION  ... Calculates the checksum of a string. The checksum is
                     calculated by adding up the ASCII values of each
                     character in the string, all lower-case letters will
                     be translated as upper-case.

    PROTOTYPE    ... unsigned long strichecksum(char *s);

    ARGUMENTS    ... s             -  String to checksum.

    RETURNS      ... The checksum of the input string.



    ------------------------------------------------------------------------
    NAME         ... stricountchar

    DESCRIPTION  ... Counts occurrences of a character in a string,
                     ignoring case of letters.

    PROTOTYPE    ... int  stricountchar(char *s, int c);

    ARGUMENTS    ... s             -  String to search.
                     c             -  Char to search for.

    RETURNS      ... The number of occurrences of the character in the
                     string.


    ------------------------------------------------------------------------
    NAME         ... stricountstr

    DESCRIPTION  ... Counts occurrences of one string within another,
                     ignoring case of letters.

    PROTOTYPE    ... int  stricountstr(char *a, char *s);

    ARGUMENTS    ... a             -  String to search for.
                     s             -  String to search.

    RETURNS      ... The number of times that string a occurs in
                     string s.


    ------------------------------------------------------------------------
    NAME         ... stridelete

    DESCRIPTION  ... Deletes a substring from within a string, ingoring
                     case when deleting.

    RETURNS      ... char *stridelete(char *a, char *s);

    ARGUMENTS    ... a             -  Substring to delete.
                     s             -  String to delete from.

    RETURNS      ... Address of the modified string, or NULL if substring
                     not found.



    ------------------------------------------------------------------------
    NAME         ... strideleteall

    DESCRIPTION  ... Deletes all occurrences of a substring from within a
                     string, ignoring case of letters.

    PROTOTYPE    ... char *strideleteall(char *a, char *s);

    ARGUMENTS    ... a             -  Substring to delete.
                     s             -  String to delete from.

    RETURNS      ... Address of the modified string, or NULL if substring
                     not found.



    ------------------------------------------------------------------------
    NAME         ... striinc

    DESCRIPTION  ... Determines if and where one string is included within
                     another, ignoring case of letters.

    PROTOTYPE    ... char *striinc(char *a, char *s);

    ARGUMENTS    ... a             -  String to search for.
                     s             -  String to search.

    RETURNS      ... A pointer to the location in 's' that contains 'a',
                     or NULL if not found.


    ------------------------------------------------------------------------
    NAME         ... strinc

    DESCRIPTION  ... Determines if and where one string is included within
                     another, obseriving case of letters.

    PROTOTYPE    ... char *strinc(char *a, char *s);

    ARGUMENTS    ... a             -  String to search for.
                     s             -  String to search.

    RETURNS      ... A pointer to the location in 's' that contains 'a',
                     or NULL if not found.



    ------------------------------------------------------------------------
    NAME         ... strinsert

    DESCRIPTION  ... Inserts one string into another.

    PROTOTYPE    ... char *strinsert(char *a, char *s, int p);

    ARGUMENTS    ... a             -  String to insert.
                     s             -  String to receive insertion.
                     p             -  Starting position.

    RETURNS      ... The address of the modified string.



    ------------------------------------------------------------------------
    NAME         ... strisblank

    DESCRIPTION  ... Determines if a given string is blank (whitespace).

    PROTOTYPE    ... int  strisblank(char *s);

    ARGUMENTS    ... s             -  String to check.

    RETURNS      ... TRUE if string is blank, FALSE otherwise




    ------------------------------------------------------------------------
    NAME         ... strisrep

    DESCRIPTION  ... Searches for, and replaces one string within another,
                     ignoring case of letters.

    PROTOTYPE    ... char *strisrep(char *s, char *a, char *b);

    ARGUMENTS    ... s             -  String to search.
                     a             -  String to search for.
                     b             -  String to replace with.

    RETURNS      ... The address of the modified string, or NULL if the
                     search string wasn't found.


    ------------------------------------------------------------------------
    NAME         ... strleft

    DESCRIPTION  ... Create a new string from left or right by taking a
                     specified portion of a string from its left and
                     creates a new string.

    PROTOTYPE    ... char *strleft(char *s, int n);

    ARGUMENTS    ... s             -  String used for input.
                     n             -  Number of chars to copy.

    RETURNS      ... Address of the newly created string or a NULL if a
                     memory allocation error occurred.


    ------------------------------------------------------------------------
    NAME         ... strljust

    DESCRIPTION  ... Left justifies a string.

    PROTOTYPE    ... char *strljust(char *s);

    ARGUMENTS    ... s             -  String to justify.

    RETURNS      ... Address of the modified string.



    ------------------------------------------------------------------------
    NAME         ... strmiddle

    DESCRIPTION  ... Create a new string from part of an input string by
                     taking a section from input string starting at given
                     position and taking the given amount of characters
                     creating a new string.

    PROTOTYPE    ... char *strmiddle(char *s, int p, int n);

    ARGUMENTS    ... s             -  String used for input.
                     p             -  Position to start copying.
                     n             -  Number of chars to copy.

    RETURNS      ... Address of the newly created string or a NULL if a
                     memory allocation error occurred.



    ------------------------------------------------------------------------
    NAME         ... strresize

    DESCRIPTION  ... Adjusts the length of a string, either by truncation or
                     padding with spaces.

    PROTOTYPE    ... char *strresize(char *s, int n);

    ARGUMENTS    ... s             -  String use for input.
                     n             -  New length.

    RETURNS      ... Address of the modified string.



    ------------------------------------------------------------------------
    NAME         ... strright

    DESCRIPTION  ... Create a new string from left or right by takeing a
                     specified portion of a string from its right and
                     creates a new string.

    PROTOTYPE    ... char *strright(char *s, int n);

    ARGUMENTS    ... s             -  String used for input.
                     n             -  Number of chars to copy.

    RETURNS      ... Address of the newly created string or a NULL if a
                     memory allocation error occurred.


    ------------------------------------------------------------------------
    NAME         ... strrjust

    DESCRIPTION  ... Right justifies a string.

    PROTOTYPE    ... char *strrjust(char *s);

    ARGUMENTS    ... s             -  String to justify.

    RETURNS      ... Address of the modified string.



    ------------------------------------------------------------------------
    NAME         ... strrotleft

    DESCRIPTION  ... Rotates a string specified number of characters left.
                     The rotated characters wrap around to the opposite
                     side of the string.

    PROTOTYPE    ... char *strrotleft(char *s, int n);

    ARGUMENTS    ... s             -  String to rotate.
                     n             -  Count to rotate.

    RETURNS      ... Address of the modified string


    ------------------------------------------------------------------------
    NAME         ... strrotright

    DESCRIPTION  ... Rotates a string specified number of characters right.
                     The rotated characters wrap around to the opposite
                     side of the string.

    PROTOTYPE    ... char *strrotright(char *s, int n);

    ARGUMENTS    ... s             -  String to rotate
                     n             -  Count to rotate

    RETURNS      ... Address of the modified string.



    ------------------------------------------------------------------------
    NAME         ... strshiftleft

    DESCRIPTION  ... Shifts a string a specified number of characters left
                     Characters that shift past the beginning of the string
                     "drop off" and spaces are added to the right of the
                     string.

    PROTOTYPE    ... char *strshiftleft(char *s, int n);

    ARGUMENTS    ... s             -  String to shift.
                     n             -  Char count to shift.

    RETURNS      ... Address of the Modified string


    ------------------------------------------------------------------------
    NAME         ... strshiftright

    DESCRIPTION  ... Shifts a string a specified number of characters right
                     Characters that shift past the end of the string
                     "drop off" and spaces are added to the left of the
                     string.

    PROTOTYPE    ... char *strshiftright(char *s, int n);

    ARGUMENTS    ... s             -  String to shift.
                     n             -  Char count to shift.

    RETURNS      ... Address of the Modified string



    ------------------------------------------------------------------------
    NAME         ... strsrep

    DESCRIPTION  ... Searches for, and replaces one string within another,
                     observing case of letters.

    PROTOTYPE    ... char *strsrep(char *s, char *a, char *b);

    ARGUMENTS    ... s             -  String to search.
                     a             -  String to search for.
                     b             -  String to replace with.

    RETURNS      ... The address of the modified string, or NULL if the
                     search string wasn't found.




    ------------------------------------------------------------------------
    NAME         ... struplow

    DESCRIPTION  ... Converts a string to mixed upper & lowercase characters.
                     Characters are forced to upper or lowercase depending
                     upon the previous character in the string.

    PROTOTYPE    ... char *struplow(char *s);

    ARGUMENTS    ... s             -  String to convert

    RETURNS      ... Address of the modified string






    3.5  Miscellaneous functions:
    -----------------------------




    ------------------------------------------------------------------------
    NAME          ... mscbeep

    DESCRIPTION   ... Make a mscbeep noise, what else !

    PROTOTYPE     ... void mscbeep            (int mode);

    ARGUMENTS     ... mode         - !0 - Will make an error mscbeep.
                                     0  - Will make a pleasent mscbeep;

    RETURNS       ... void





    4.  High level functions:
    -------------------------

        The high level functions are mainly window functions and internally
        use the low level functions functions.






    4.1  Window functions:
    ----------------------


    ------------------------------------------------------------------------
    NAME          ... Wclear

    DESCRIPTION   ... Clears the contents of a window.

    PROTOTYPE     ... void Wclear(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Wcloseall

    DESCRIPTION   ... Closes all the windows by recursively calling the
                      Wdelete function.

    PROTOTYPE     ... void Wcloseall(void)

    ARGUMENTS     ... void

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Wcursor

    DESCRIPTION   ... Sets a windows cursor

    PROTOTYPE     ... void Wcursor(WINDOW *wnd, int x, int y)

    ARGUMENTS     ... wnd          - Window handle.
                      x            - The starting column.
                      y            - The starting row.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Wdelete

    DESCRIPTION   ... Deletes a window and frees all the memory that it
                      initially allocated.

    PROTOTYPE     ... void Wdelete(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Wemsg

    DESCRIPTION   ... Opens a little window with a title "Error" and puts
                      some text inside, used primarily for error messages.
                      See Wemsgclear for removing the window.

    PROTOTYPE     ... void Wemsg(char *s)

    ARGUMENTS     ... s            - Pointer to the text to be displayed.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Wemsgclear

    DESCRIPTION   ... Removes an Wemsg window if one exists.

    PROTOTYPE     ... void Wemsgclear(void)

    ARGUMENTS     ... void

    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... Westablish

    DESCRIPTION   ... Creats a new window.

    PROTOTYPE     ... WINDOW *Westablish (x int, y int, h int, w int)

    PARAMETERS    ... x            - The starting column of the window.
                      y            - The starting row of the box.
                      h            - The height of the window.
                      w            - The width of the window.

    RETURNS       ... A pointer to the new created window. It will return
                      NULL if memory allocation fails.




    ------------------------------------------------------------------------
    NAME          ... Wforefront

    DESCRIPTION   ... This will re position the window so that it is in
                      front of all the other windows.

    PROTOTYPE     ... #define Wforefront(wnd)

    ARGUMENTS     ... wnd          - The window handle.



    ------------------------------------------------------------------------
    NAME          ... Wgetsel

    DESCRIPTION   ... Allows the user to make a window selection.

    PROTOTYPE     ... int Wgetsel(WINDOW *wnd, int s, char *keys)

    ARGUMENTS     ... wnd          - Window handle.
                      s            - Selection.
                      keys         - A pointer to a string whoose charcaters
                                     are valid keystrokes

    RETURNS       ... The key pressed.




    ------------------------------------------------------------------------
    NAME          ... Whide

    DESCRIPTION   ... Hides a window, this only makes it invisible so it
                      can be restored.

    PROTOTYPE     ... void Whide(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Wmove

    DESCRIPTION   ... Moves a window and its contents.

    PROTOTYPE     ... #define Wmove(wnd,x,y)

    ARGUMENTS     ... wnd          - Window handle.
                      x            - The starting column.
                      y            - The starting row.



    ------------------------------------------------------------------------
    NAME          ... Wprintf

    DESCRIPTION   ... Writes a formatted variable argument to a window,
                      as with the printf function.

    PROTOTYPE     ... void Wprintf(WINDOW *wnd, char *ln, ...)

    ARGUMENTS     ... wnd          - Window handle.
                      ln           - The formatted line to write.

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Wprompt

    DESCRIPTION   ... Display a window prompt.

    PROTOTYPE     ... void Wprompt(WINDOW *wnd, int x, int y, char *s)

    ARGUMENTS     ... wnd          - Window handle.
                      x            - The starting column.
                      y            - The starting row.
                      s            - The prompt string.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Wputch

    DESCRIPTION   ... Outputs a character to a window, using the WIN_FACE
                      attributes.

    PROTOTYPE     ... void Wputch(WINDOW *wnd, int c)

    ARGUMENTS     ... wnd          - Window handle.
                      c            - The character to write.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Wputchat

    DESCRIPTION   ... Outputs a character and attribute to a window.

    PROTOTYPE     ... void Wputchar(WINDOW *wnd, int c, int bg, int fg,
                                    int i)

    ARGUMENTS     ... wnd          - Window handle.
                      c            - The character to write.
                      bg           - Background colour.
                      fg           - Foreground colour.
                      i            - Intensity (BRIGHT || DIM).

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Wrear

    DESCRIPTION   ... This will reposition a window so that it is the
                      very last window on the screen.

    PROTOTYPE     ... #define Wrear(wnd)

    ARGUMENTS     ... wnd          - Window handle.




    ------------------------------------------------------------------------
    NAME          ... Wresetvideo

    DESCRIPTION   ... Normalises the video attributes for a given window.
                      This would set the attributes to the default state.

    PROTOTYPE     ... #define Wresetvideo(wnd)

    ARGUMENTS     ... wnd          - Window handle.



    ------------------------------------------------------------------------
    NAME          ... Wrevvideo

    DESCRIPTION   ... Reverses the video attributes for a given window.

    PROTOTYPE     ... #define Wrevvideo(wnd)

    ARGUMENTS     ... wnd          - Window handle.



    ------------------------------------------------------------------------
    NAME          ... Wrmove

    DESCRIPTION   ... Moves a window and its contents, this is different to
                      the Wmove macro in that it will move a window and
                      remember which other windows are behind or in front of
                      it. It will move behind if it is not the active window.

    PROTOTYPE     ... #define Wrmove(wnd,x,y)

    ARGUMENTS     ... wnd          - Window handle.
                      x            - The starting column.
                      y            - The starting row.




    -------------------------------------------------------------------------
    NAME          ... Wsetborder

    DESCRIPTION   ... Sets a windows border to particular format.

    PROTOTYPE     ... void Wsetborder(WINDOW *wnd, int btype)

    ARGUMENTS     ... wnd          - Window handle.
                      btype        - Sets the border styles, see sec 2.1
                                     for border styles.

    RETURNS       ... void





    -------------------------------------------------------------------------
    NAME          ... Wsetcolour

    DESCRIPTION   ... Sets up the colors for a given window. If the video
                      adaptor is monochrome then the function uses its
                      default attributes (BLACK and WHITE) and returns.

    PROTOTYPE     ... void Wsetcolour (WINDOW *wnd, int area,
                                       int bg, int fg, int inten);

    PARAMETERS    ... wnd          - Pointer to the slected window.
                      area         - The area to repaint. See sec 2.1
                                     on Window areas.
                      bg           - Back ground attribute.
                      fg           - Fore ground attribute.
                      intlen       - Intensity. See sec 2.1 on Window
                                     intensity.

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Wsetintensity

    DESCRIPTION   ... Sets the intensity of a given window.

    PROTOTYPE     ... void Wsetintensity(WINDOW *wnd, int inten)

    ARGUMENTS     ... wnd          - Window handle.
                      inten        - The intensity to set to. See sec 2.1
                                     on Window intensity.
    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Wsettitle

    DESCRIPTION   ... Sets the title of a window.

    PROTOTYPE     ... void Wsettitle(WINDOW *wnd, char *title, int just)

    ARGUMENTS     ... wnd          - Window handle.
                      title        - Pointer to the string containing the
                                     title.
                      just         - The justification of the title. See
                                     sec 2.1 on Title justification.

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Wshow

    DESCRIPTION   ... Displays a window. The window must have already been
                      established using Westablish.

    PROTOTYPE     ... void Wshow(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void








    4.2  Menu functions:
    --------------------



    -------------------------------------------------------------------------
    NAME          ... Minit

    DESCRIPTION   ... This function sets all the configuration variables in
                      a pulldown menu to the default state. The colours are
                      all set to monochrome (BLACK and WHITE) , the title
                      string is NULL and the border is BRD_SINGLE. The functions
                      Msetborder(), Msettitle() and Msetcolour() can be
                      called to change the style.

    PROTOTYPE     ... void Minit (void);

    PARAMETERS    ... void

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Mselect

    DESCRIPTION   ... Opens and executes a pull-down type menu.
                      See sec 2.2 for the structure components.

    PROTOTYPE     ... void Mselect(MENU *mn)

    ARGUMENTS     ... md           - Pointer to the menu structure.
                      ms           - Structure that hold the menu style
                                     information.

    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... Msetborder

    DESCRIPTION   ... Sets up the border style for the current pull-down
                      menu.

    PROTOTYPE     ... void Msetborder (int btype);

    PARAMETERS    ... btype        -  The border style. See sec 2.1

    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... Msetcolour

    DESCRIPTION   ... Sets up the colors for the current pull-down menu.
                      If the adaptor is monochrome then the function uses
                      its default attributes (BLACK and WHITE) and ignore
                      the parameters you have passed.

    PROTOTYPE     ... void Msetcolour (int area, int bg, int fg,
                                       int inten);

    PARAMETERS    ... area         - The area to repaint. See sec 2.1
                                     on Window areas.
                      bg           - Back ground attribute.
                      fg           - Fore ground attribute.
                      intlen       - Intensity. See sec 2.1 on Window
                                     intensity.

    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... Msetfullwidth

    DESCRIPTION   ... Forces the pull-down menu to use the entire width of
                      the screen, or a calculated minimum width.

    PROTOTYPE     ... void Msetfullwidth(int f);

    PARAMETERS    ... f            -  0   - Use calculated screen width
                                      !0  - Use full screen width.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Msettitle

    DESCRIPTION   ... Sets the title for the current pull-down menu.

    PROTOTYPE     ... void Msettitle (char *title, int just);

    ARGUMENTS     ... title        - Pointer to the string containing the
                                     title.
                      just         - The justification of the title. See
                                     sec 2.1 on Title justification.

    RETURNS       ... void






    4.3  Data entry functions:
    --------------------------



    ------------------------------------------------------------------------
    NAME          ... Fcleartemplate

    DESCRIPTION   ... Clears a template to all blanks, see also
                      Fnulltemplate.

    PROTOTYPE     ... void Fcleartemplate(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Fdataentry

    DESCRIPTION   ... Process data entry for a screen template.

    PROTOTYPE     ... int Fdataentry(WINDOW *wnd, int p)

    ARGUMENTS     ... wnd          - Window handle.
                      p            - !0  - process all keystrokes. Returns
                                           PgUp, PgDown, Home , End etc.
                                     0   - preserve PgUp, PgDown, Home, End
                                           for internal use.

    RETURNS       ... The last keyboard keystroke.


    ------------------------------------------------------------------------
    NAME          ... Fdataview

    DESCRIPTION   ... Displays the data entry for a screen template.
                      This will not allow any editing and the cursor is
                      invisible inside this function.

    PROTOTYPE     ... int Fdataview(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... The last keyboard keystroke.


    ------------------------------------------------------------------------
    NAME          ... Fendfunction

    DESCRIPTION   ... This is a powerfull feature in field editing. This
                      function will allow you to specify a new function
                      that will determine which keys are valid for exiting
                      field edit sessions. The function must be set prior
                      to the Fdataentry function. For a sample take a look
                      at the default_ednstroke function in sstfield.c .

    PROTOTYPE     ... void  Fendfunction(int (*f) (int));

    ARGUMENTS     ... f            - Pointer to the new function to be
                                     used. If NULL it will use the
                                     default function.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Festablish

    DESCRIPTION   ... Establishes a field in a template. See sec 2.3
                      for more info on the structures.

    PROTOTYPE     ... FIELD *Festablish(WINDOW *wnd, int cl, int rw,
                                        char *msk, char *bf, int ty)

    ARGUMENTS     ... wnd          - Window handle.
                      cl           - The starting column of the field.
                      rw           - The starting row of the field.
                      msk          - The field input mask string.
                      bf           - The buffer that is updated upon
                                     editing.
                      ty           - The field type, see sec 2.3 on
                                     Field types.

    RETURNS       ... Pointer to the new created field. The function may
                      also return NULL if no memory could be allocated to
                      the field.



    ------------------------------------------------------------------------
    NAME          ... Finittemplate

    DESCRIPTION   ... Initialises all the variables needed to create an
                      entry template. The window must have already been
                      established to call this function.

    PROTOTYPE     ... void Finittemplate(WINDOW *wnd);

    ARGUMENTS     ... wnd          - Window handle;

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Fnulltemplate

    DESCRIPTION   ... Clears a template to all null chars, see also
                      Fcleartemplate.

    PROTOTYPE     ... void Fnulltemplate(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Fprotect

    DESCRIPTION   ... Protects a field by not allowing the user to edit
                      it. It is still displayed etc, but is skipped.

    PROTOTYPE     ... #define Fprotect(f,s)  f->fprot=s

    ARGUMENTS     ... f            - Pointer to the field.
                      s            - TRUE  - Protect.
                                     FALSE - Unprotect.



    ------------------------------------------------------------------------
    NAME          ... Fsethelp

    DESCRIPTION   ... Assigns a new help function to the specified field.
                      A help function may be diplayed for the particular
                      field upon pressing the help key (usually F1) or
                      instantly as soon as the field is selected,
                      see the argument "w" for more details.


    PROTOTYPE     ... void Fsethelp(FIELD *f, void (*h)(char *), int w);

    ARGUMENTS     ... f            - Pointer to the field.
                      h            - Pointer to the help function.
                      w            - Field help type. see sec 2.3 on field
                                     help types.




    ------------------------------------------------------------------------
    NAME          ... Fsethelpwin

    DESCRIPTION   ... Set a field's help window.

    PROTOTYPE     ... void Fsethelpwin(FIELD *fld, char *hwin, int x, int y)

    ARGUMENTS     ... fld          - Pointer to the field structure.
                      hwin         - Help tag string.
                      x            - The starting column.
                      y            - The starting row.

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Ftally

    DESCRIPTION   ... Displays all the fields in a window.

    PROTOTYPE     ... void Ftally(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Fvalidate

    DESCRIPTION   ... Assigns a validation function to a particular field.

    PROTOTYPE     ... #define Fvalidate(f,v) f->fvalid=v

    ARGUMENTS     ... f            - Pointer to the field structure.
                  ... v            - Pointer to the function to be used for
                                     validation.






    4.4  Editor functions:
    ----------------------


    ------------------------------------------------------------------------
    NAME          ... Eopen

    DESCRIPTION   ... Opens a text editing window. The window must first be
                      created using the Westablish function, and its
                      characteristics may be set eg (title and colours).
                      The window is to be displayed using the Wshow
                      function then you can call the Eopen function.
                      See sec 2.4 for the editing commands.

    PROTOTYPE     ... void Eopen(WINDOW *wnd, char *bf, int bsize)

    ARGUMENTS     ... wnd          - Window handle.
                      bf           - Pointer to the text buffer.
                      bsize        - The size of the text buffer.

    RETURNS       ... void






    4.5  Help system functions:
    ---------------------------


    ------------------------------------------------------------------------
    NAME          ... Hload

    DESCRIPTION   ... Loads a help definition file. If the help file is
                      unable to be opened for some reason the function
                      returns.

    PROTOTYPE     ... void Hload(char *hn)

    ARGUMENTS     ... hn           - The name of the help file.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Hset

    DESCRIPTION   ... Sets a particular help screen to be current and
                      active.

    PROTOTYPE     ... void Hset(char *s, int x, int y)

    ARGUMENTS     ... s            - The help title tag.
                      x            - Starting column of the help screen.
                      y            - Starting row of the help screen.

    RETURNS       ... void




