
              _______
         ____|__     |               (R)
      --|       |    |-------------------
        |   ____|__  |  Association of
        |  |       |_|  Shareware
        |__|   o   |    Professionals
      -----|   |   |---------------------
           |___|___|    MEMBER










                                  AUTOSCREEN
                                 Version 1.20



The AUTOSCREEN system is a portable C based Library that provides a powerful,
 modern, multithreaded user interface to application programs in as little as
                              32K on the IBM PC.

 This product is supplied for use with the IBM range of personal computers or
                              100% compatibles.

This manual  assumes that  the reader  is conversant  with advanced C language
concepts such  as data  pointers, code  pointers, array initialization and the
distinction between  global, static and stack based variables. It also assumes
familiarity with  basic user interface concepts such as windows, pop-up, pull-
down and tear-off menus; accelerator keys, check boxes, switches, code buttons
and dialogues.  This text  is a  complete reference  to the AUTOSCREEN system.
Function prototypes  and other  technical advice is available both here and in
the Microsoft compatible help data-base file supplied with the product.

For a  fully detailed  insight into  the design  and coding  of the AUTOSCREEN
system (along  with detailed discussion of the product's use, providing object
extensions and a complete source code listing) programmers are referred to the
book from SIGMA PRESS:-

        "C User Interface Library" by Ted Pugh (ISBN: 1-85058-295-5).



























                                ACKNOWLEDGEMENTS

PC-DOS, XT and AT are trademarks and IBM is a registered trademark of
International Business Machines Corporation.

MS-DOS, PWB, Quick C, MASM, and Quick Basic are trademarks and Microsoft is a
registered trademark of Microsoft Corporation.

                            DEFINITION OF SHAREWARE

Shareware distribution gives users a chance to try software before buying it. If
you try a Shareware program and continue using it, you are expected to register.
Individual programs  differ on  details - some request registration while others
require it.  Some specify  a maximum  trial period.  With registration,  you get
anything from  the simple  right to  continue using  the software  to an updated
program with printed manual.

Copyright laws  apply  to  both  Shareware  and  commercial  software,  and  the
copyright holder  retains all  rights, with  a few specific exceptions as stated
below. Shareware  authors are  accomplished programmers,  just  like  commercial
authors, and  the programs  are of comparable quality. (In both cases, there are
good  programs  and  bad  ones!)  The  main  difference  is  in  the  method  of
distribution. The  author specifically  grants the  right to copy and distribute
the software, either to all and sundry or to a specific group. For example, some
authors require  written permission  before a  commercial disk  vendor may  copy
their Shareware.

Shareware is  a distribution  method, not  a type  of software.  You should find
software that  suits your  needs and  pocket-book, whether  it's  commercial  or
Shareware. The Shareware system makes fitting your needs easier, because you can
try before  you buy.  And because  the overhead  is low,  prices are  low  also.
Shareware has  the ultimate money-back guarantee - if you don't use the product,
you don't pay for it.

                             DISCLAIMER - AGREEMENT

Users of AUTOSCREEN must accept this disclaimer of warranty:-

AUTOSCREEN is  supplied as is. The author disclaims all warranties, expressed or
implied, including and without limitation, the warranties of merchantability and
of fitness  for any  purpose. The  author assumes  no liability  whatsoever  for
damages, direct or consequential, which may result from the use of AUTOSCREEN.

AUTOSCREEN is a "shareware program" and is provided at no charge to the user for
evaluation. Feel  free to  share it with your friends, but please do not give it
away altered  or as  part of  another system.  The essence  of  "user-supported"
software is  to provide  personal computer  users with  quality software without
high prices,  and yet  to provide  incentives for  programmers  to  continue  to
develop new  products. If  you find  this program  useful and  find that you are
using AUTOSCREEN  and continuing  to use  AUTOSCREEN after  a  reasonable  trial
period, you must make a registration payment of  30.00 to TRIDENT SOFTWARE. The
 30.00  registration fee  will license  one copy for use on any one computer at
any one  time. You must treat this software just like a book. An example is that
this software  may be  used by any number of people and may be freely moved from



                                       i


one computer  location to  another -  so long  as there  is no possibility of it
being used  at one  location while  it is  being used at another. Just as a book
cannot be read by two different persons at the same time.

Commercial users  of AUTOSCREEN  must register  and  pay  for  their  copies  of
AUTOSCREEN within  30 days  of first  use or  their license  is withdrawn. Site-
License arrangements may be made by contacting TRIDENT SOFTWARE.

Anyone distributing  AUTOSCREEN for  any kind of remuneration must first contact
TRIDENT SOFTWARE at the address below for authorization. This authorization will
be automatically  granted to  distributors  recognized  by  the  Association  of
Shareware Professionals  (ASP) as  adhering to  its  guide-lines  for  shareware
distributors, and  such distributors  may begin offering AUTOSCREEN immediately.
(However, TRIDENT  SOFTWARE must still be advised so that the distributor can be
kept up-to-date with the latest version of AUTOSCREEN.).

You are  encouraged to  pass a  copy of  AUTOSCREEN along  to your  friends  for
evaluation. Please encourage them to register their copy if they find it useful.
All registered users will receive a copy of the latest version of the AUTOSCREEN
system which  now provides full support for vertical and horizontal scroll bars;
list boxes; input character filtering; PC sound generation and improved dialogue
list support.

Registered  users can also obtain other TRIDENT library products at preferential
rates.  These  products  include DATAMAN (a professional data management library
providing support for RAM and disk-based linked-lists, stacks, queues, trees and
SSADM one-to-many and many-to-many relationships); a full number/date expression
parser  with  evaluator  for  use  with  AUTOSCREEN's input dialogues; and other
modules  designed to reduce the time spent coding advanced business applications.

                              OMBUDSMAN STATEMENT

Trident Software  is a  member of  the Association  of  Shareware  Professionals
(ASP). ASP wants to make sure that the shareware principle works for you. If you
are unable  to resolve  a  shareware-related  problem  with  an  ASP  member  by
contacting the  member directly,  ASP may be able to help. The ASP Ombudsman can
help you  resolve a  dispute or problem with an ASP member, but does not provide
technical support  for members'  products. Please  write to the ASP Ombudsman at
545 Grover  Road, Muskegon, MI 49442 or send a CompuServe message via CompuServe
Mail to ASP Ombudsman 70007,3536.

                               AUTOSCREEN SUPPORT

Free enduser  support, by  mail, is  provided  for  a  period  of  three  months
following the  product's registration  with the author. After this time, further
mail and/or  telephone support  can be provided at a prepaid rate of  30.00 per
quarter.

Trident Software  undertakes to answer questions and fix serious bugs during the
above three month period. For problems involving a specific hardware or software
environment or  feature, Trident  Software may choose not to modify the program.
In that  case, if a problem is reported within three months after purchase, then
the user will be offered a refund of the purchase price.

Any money  sent to  Trident Software to register an unsupported product shall be
promptly returned  with an explanation that the product in question is no longer
supported.

Known incompatibility  with other  software or  hardware, and  major or  unusual
program limitations,  is explicitly  noted in  any BUGS.DOC file that comes with
the Freely Distributed version of the product.


                                       ii








                            AUTOSCREEN REGISTRATION

In order  to register AUTOSCREEN, you should send a cheque (drawn on a UK bank),
UK postal  order or  International Money Order in the amount of  30.00 Sterling
and made payable to Trident Software at the following address:-

                               Trident Software,
                                337 Church Road,
                                  Thundersley,
                                   Benfleet,
                                Essex  SS7 3HJ,
                                    England.

In return  you will  receive a  full copy  of AUTOSCREEN  containing the  small,
compact, medium and large C memory model libraries plus Microsoft mixed-language
programming support  in the  form of medium and large memory model libraries for
use with  that company's  BASIC and  Pascal languages.  The C  medium and  large
memory models  can be  used with  Microsoft's FORTRAN  compiler. You  will  also
receive  the  source  code  for  a  full  number and date expression parser with
evaluator  for  use  with  AUTOSCREEN's  dialogue module. A copy of AUTOSCREEN's
high-level source code may  be purchased  for an  additional   50.00 to
enable the system's porting to other environments.

			      OTHER LANGUAGE MODELS

For   reasons  of  space,  only  the  C  Language  libraries  have  been  freely
distributed. Copies  of the  other libraries for use in Microsoft mixed-language
programming,  may  be  obtained  for  testing  direct from the author. To obtain
these  items  please send a UK cheque, postal order or International Money Order
in  the  amount  of    5.00 (plus  postage  for  addresses  outside  the UK and
Ireland) to the above address and enclose suitably addressed return packaging.


























                                      iii








                             AUTOSCREEN Version 1.2
         Copyright (C) 1989-92, Edward James Pugh. All Rights Reserved.


                               Table Of Contents


Introduction..........................................................1
    Compiler Support..................................................1
    Conventions.......................................................3
    Points To Note....................................................3

Installing The Libraries..............................................5

Using The Demo........................................................6

Getting Help..........................................................8

Concepts..............................................................9
    Windows...........................................................9
    Events............................................................9
    The Event Manager.................................................10
    Configuring AUTOSCREEN............................................10

Creating AUTOSCREEN Objects...........................................11
    Windows...........................................................11
    The Menu Title Bar................................................11
    Menus.............................................................12
    Switches..........................................................13
    Check Boxes.......................................................14
    Code Buttons......................................................14
    Dialogue Boxes....................................................15

Guide-Lines...........................................................17
    The main() Function...............................................17
    Process Modules...................................................18

Extended Process Thread Support.......................................20

Global Variables......................................................22

Data Structures.......................................................26

Function Prototypes...................................................34

Index.................................................................59











                                       iv





                                                                    Introduction


                                  Introduction



AUTOSCREEN is a powerful C based programmers' library designed to fully automate
the inclusion of a modern, multithreaded interface. It is primarily aimed at
programmers developing business applications on the IBM PC and who require a
portable means of providing a common user interface to all their programs.

Unlike other products in this area, AUTOSCREEN is not just a windowing tool-kit;
it is a totally integrated system that (in just 32K on the IBM PC) provides
automatic mouse and hot-key support for a comprehensive range of screen based
objects, unlimited process threads and dialogues parsed in real-time. It is also
easy to use.

Based on the concept of a window, programmers simply specify the required screen
coordinates, describe objects to be contained in the window and then make a call
to DoObjects(). The whole system is then on auto-pilot - managing all
interaction with the program's user transparently.

Using AUTOSCREEN, end-users can move directly to any object in the active
window; either by using the mouse, an accelerator-key, or a combination of grey
keys. In a similar manner, users can move between windows, select menu options,
launch other processes, move and re-size the active window or a pop-up menu.
None of these facilities require any action by the programmer - they are all
totally transparent.

Unique to the AUTOSCREEN system is its treatment of menu options. With
AUTOSCREEN, each code module associated with a menu item is executed as an
independent process thread. In conjunction with the ability to switch menu items
on or off at will, the programmer can therefore decide whether a module should
terminate after completing its task, remain in existence throughout the whole of
the user session, or allow further copies of itself to be run.

Gone are the days of forcing users to leave what they are doing and escape back
up a menu tree to perform a new task. AUTOSCREEN provides them with the ability
to simply launch the required process in a separate window and to return to what
they were doing at the touch of a key. There is no limit to the number of active
tasks that can exist at any one time - and like everything else with this
system: such facilities are totally transparent to the programmer.

Compiler Support


The AUTOSCREEN libraries have been developed using a combination of Microsoft C
version 6.00 and Microsoft MASM. They are therefore compatible with all that
company's language products and any compiler produced by other manufacturers
adopting the Microsoft conventions.

Included in the package are medium and large memory models designed to
facilitate mixed language programming. These extend support to Microsoft BASIC
and Pascal programmers. The C based medium and large memory libraries can be
used with Microsoft's FORTRAN compiler.




                                       1





                                                                Compiler Support


AUTOSCREEN makes use of the following Microsoft C standard library calls:

     atof()    atoi()     fflush()  free()
     kbhit()   malloc()   strlen()  vsprintf()
     int86()   _nmalloc() _nfree()

Non Microsoft compiler support should pose no problem for most of these, but you
may have to supply your own int86(), _nmalloc() and _nfree() routines if they
are not provided by your compiler. The latter calls have been used in the
library's ibmpc module. Prototype details are as follows:-

a) int int86( int intnum, union REGS *inregs, union REGS *outregs );

Comments: int86() returns the value of the AX register. The REGS union is
constructed as follows:-

          struct BYTEREGS{
                    unsigned char al, ah;
                    unsigned char bl, bh;
                    unsigned char cl, ch;
                    unsigned char dl, dh;
                    };

          struct WORDREGS{
                    unsigned int ax;
                    unsigned int bx;
                    unsigned int cx;
                    unsigned int dx;
                    unsigned int si;
                    unsigned int di;
                    unsigned int cflag;
                    };

          union REGS{
               struct WORDREGS x;
               struct BYTEREGS h;
               };

b) void _near *_nmalloc( size_t size );

Comments: _nmalloc() grabs a block of memory from within the default data
segment - as specified by the DS register contents. _nmalloc() and _nfree() have
been used in allocating stack space in the thread module to provide
compatibility with Microsoft's standard library which assumes a segment set up
of SS == DS (thus enabling the compiler to access stack variables with a near
assembly MOV instruction).

c) void _nfree( void _near *memblock );

Comments: _nmalloc() counterpart. See b).

Some of AUTOSCREEN's data structures are defined in terms of unnamed struct and
union types. If your compiler does not recognise such definitions you will have
to rewrite these in terms that it can understand. Be sure, however, to keep the



                                       2





                                                                Compiler Support


fields in the correct order. AUTOSCREEN assumes system data structure packing on
even byte boundaries - the default with most compilers.

In order to implement threads, some of the functions contained in the thread
module require calling with a Pascal/FORTRAN type convention. This in effect
means that the routine's name is not case significant, and that the called
procedure is responsible for clearing up the stack before returning. Your
compiler therefore needs to support such facilities.

Conventions


In order to avoid possible conflicts with other library function naming
conventions, the AUTOSCREEN system uses an uppercase letter to begin each word
in a routine's label. For instance:-

     PutChar()  NewThread()  InitUI()

Public variables are all in upper case as are non function based macros and
#defines.  For example:-

     CURWINDOW  ACTWINDOW  MYATTRIB()

Structure field names follow the function labelling convention, with the
exception of generic data structure types. These are contained in the llist
module and are rendered in lower case only.  Therefore:-

     mywindow->Border    mylist->length

Leading underscores are reserved for #defines used in controlling conditional
compilation or inclusion. Such #defines are made in upper case.

     __SMALL  __MEDIUM  _IBMPC_INCL

Type and enumerated definitions follow the normal C conventions of appending a
_t and _s respectively.

     Thread_t  Window_t  WObj_s  GreyKey_s

Enumerated members are always specified in uppercase.

     typedef enum{SCREEN_W, OBJECT_W, MENU_BAR_W, POP_UP_W}Wind_s;

Points To Note


When allocating process stacks to take advantage of AUTOSCREEN's multithreaded
support, be sure you provide enough space for their use by DOS interrupts and
the pushing of register variables by your compiler (in addition to setting up a
local stack frame). If your program hangs unexpectedly, you can be virtually
certain that the failing process has been allocated insufficient stack space.






                                       3





                                                                  Points To Note


As a general rule of thumb, practise has shown that small memory models rarely
need more than 1024 bytes of stack space and large models no more than 2
kilobytes. Medium models fall somewhere in between the two - depending upon the
weighting of data and code pointer usage.

Your program is certain to hang on task switching if you have not defined the
necessary memory model label when compiling (__SMALL, __MEDIUM, __COMPACT or
__LARGE). The thread structure definitions need to know the memory model you are
using before they can allocate the correct amount of space for register storage.
See the include file THREAD.H.















































                                       4





                                                        Installing The Libraries


                            Installing The Libraries



The Shareware product is supplied on one 360K DS/DD floppy disk which contains
the system header files, four memory model libraries and Microsoft compatible
.HLP file. The disk also contains a test stub for the user's assistance in
reviewing the product.

It is assumed that you have a C compiler installed on your system and that the
INCLUDE and LIB environment variables are present. The supplied include files
use the: #include <filename>, convention for standard library include files and:
#include "filename", for those supplied. It is therefore recommended that you
set up a temporary working directory to bench-test the product and copy the
entire contents of the disk to it.










































                                       5





                                                                  Using The Demo


                                 Using The Demo



Compile the demo in the normal way by specifying a small memory model, defining
__SMALL as a compiler option and linking with ascreens.lib.

With WINDRV.EXE in your default directory, type: WINDRV at the system prompt.
You will be presented with a menu title bar at the top of the screen containing:
Objects, Threads and Quit.

To access a pull down menu, either click on it using the mouse or (if you are
using the keyboard) hold down the ALT key whilst simultaneously pressing one of
the bright characters contained in the menu titles.

To select a menu option you can either move the highlight bar using the grey
keys or repeat the previous method.

With the required option highlighted, press [Enter], click the mouse on the
subject or input its accelerator key combination again. The chosen process will
then be launched.

When working with any of the processes in the Objects menu you can use the
mouse, an ALT+letter accelerator or the grey keys to select objects in the
active window. You can also gain access to the main menu bar using the
appropriate ALT+letter combination.

Switch between process windows using either [F6] to bring the bottom window
forward or hold down the [SHIFT] and [ALT] keys while pressing the highlighted
letter in the desired window's title. If you are using the mouse, click on the
window desired. To close a process window use the [F10] key or click the mouse
on the close window icon located in the top left border area.

Pressing [F9], or clicking the mouse in the window's border, allows you to move
and re-size the current window. Move the ghost image to the desired position
with either the mouse or grey keys. Click the mouse or press [ENTER] to freeze
the window position. You may then re-size the window if desired and terminate
the operation by either clicking again with the mouse or using the [ENTER] key.
If you wish to cancel this process at any time, hit [ESC]. Window moving and
resizing can also be performed on the pull-down menus.

Apart from the date format switch-box object that allows you to change the way
in which date entry is handled, none of the object processes perform any
configuration tasks. They are simply presented to show some of the possible
combinations in which objects may be used and the intuitive manner in which they
operate.

Dialogue objects, for example, provide both insert and over type modes, along
with re-positioning the cursor via [HOME], [END], [CTRL]+[LEFT], [CTRL]+[RIGHT],
etc..

The date dialogue will also insert the required system date portion when a lone
separator is input. (AUTOSCREEN recognizes a '.', '/', '-' or space as valid
separators from the user).



                                       6





                                                                  Using The Demo


The thread processes may be terminated by pressing [ESC]. These routines have
been designed not to allow window changing, moving and resizing; or granting
access to the menu title bar.

To terminate the demo select the Quit option in the normal way.




















































                                       7





                                                                    Getting Help


                                  Getting Help



The supplied .HLP file, AUTOSCRN.HLP, is a Microsoft compatible help database
file that may be used from within the Quick C editor or the Programmers' Work
Bench. If you are using the PWB, simply copy the file to your help directory.
Quick C users will need to append AUTOSCRN.HLP to the end of their existing help
file by using the operating system's copy command as follows:-

     copy qc.hlp /b + autoscrn.hlp /b

Requesting help on AUTOSCREEN in the normal way will then give access to the
supplied help file's index.

The help database is loosely arranged into three different sections: the
Contents that provides access to all AUTOSCREEN functions in alphabetical order,
an Overview section that groups functions in module order, and Guide-Lines. The
last section provides information on both coding AUTOSCREEN based products and
porting the system code to other environments. Full source code of the low-level
functions used to implement the system on the IBM PC is included.




































                                       8





                                                                        Concepts


                                    Concepts



Windows


As outlined in the introduction, AUTOSCREEN is based around the concept of a
window. In fact, as far as the system is concerned, all objects are simply
different types of screen windows. Furthermore, windows may contain other
windows which may in turn contain other window types...

Fully understanding AUTOSCREEN's recursive nature is not, fortunately, a
requirement in using the system. It is only mentioned here to explain how the
system can do so much with such a small code overhead. It also explains the
reasoning behind providing so few different data structures. While it is true
that some data fields are superfluous to certain actions; designing the
libraries in this way ensures that only a minimum amount of system RAM is
devoted to the interface requirements. The few extra bytes taken up by the
unused portion of a datum's structure is more than compensated for by not having
to supply additional routines for other data objects.

As a programmer, you need only be concerned with two different types of windows:
screen windows (SCREEN_W) and menu bar windows (MENU_BAR_W).

The MENU_BAR_W, as its name implies, is reserved for a window structure
containing details of the main menu title bar. If you limit your use to just
using the NewMenuBar() function to create such objects, then you can safely
ignore this window type. The SCREEN_W can be used for all other windows you
require.

AUTOSCREEN maintains a stack for each of these window types in order to
determine which window in each is currently active. It is therefore important to
specify the correct type for your purpose.

Events


Using normal programming methods, the programmer is responsible for determining
the keys pressed by the end-user and converting this information into a specific
action. In such circumstances it is usual to work with individual characters as
the smallest data component being monitored. AUTOSCREEN's smallest component is
the system event.

The Event_t structure records not only information of the actual key pressed
(when appropriate) but also the type of event that took place. This enables the
programmer to react to a specific event type, rather than being concerned unduly
with how the request was made. For example, if a CLOSE_WINDOW event results, the
programmer is unlikely to be concerned whether this happened as the result of
the Close Window Icon having been chosen with the mouse, the user hitting [ESC],
a Continue or Cancel button having been chosen with the mouse or either of the
latter two being selected with the keyboard or an accelerator key combination.





                                       9





                                                               The Event Manager


The Event Manager


Unlike other libraries that just provide the programmer with routines to create
screen object types, AUTOSCREEN provides its own programmer friendly event
manager, GetEvent(). This high-level routine can be configured to operate in the
precise way that you require by setting individual bits of its mode parameter.
It can be told to prevent the user from using the menu bar, allow the user to
move or size the active window, report extended key presses - its exact
configuration is entirely up to you.

GetEvent() is the function used by all high-level processes. It provides direct
access to all keyboard characters available on the target machine, polls the
mouse if it is present while at the same time monitoring the keyboard and
translating any user input into a system event.

GetEvent() can be viewed as AUTOSCREEN's high-level counterpart of C's standard
library function, getch().

To complement high-level input support, AUTOSCREEN provides the routine
DoObjects(). Just as scanf(), in the standard C library, calls its low-level
counterpart getch(); so DoObjects() uses GetEvent(). Unlike scanf() however,
DoObjects() takes a window pointer as a parameter - a pointer to a window that
can contain any number of object types that this version of AUTOSCREEN supports.
Put simply: DoObjects() manages all interaction between the user and the objects
contained in the window; automatically and (as you have now come to expect)
quite transparently. DoObjects() returns the event that terminated its
execution.

Configuring AUTOSCREEN


AUTOSCREEN declares a number of public variables to enable its use with other
modules that a programmer might already have coded. The global HELP_FUNCTION
pointer can, for instance, be set to a programmer's own help module and HELP_KEY
assigned to the desired function key. AUTOSCREEN's event manager will then
launch the custom help module whenever the HELP_KEY is pressed and HELP_ON is
set to TRUE.

In a similar manner, default function key settings for window altering and
closing can also be re-assigned.

Full details of all the public variables provided by the system can be found in
the Global Variable section of this manual or by consulting the supplied help
data base.












                                       10





                                                     Creating AUTOSCREEN Objects


                          Creating AUTOSCREEN Objects



Windows


System windows are created by making a call to NewWindow() which returns a
pointer of Window_t to the window created. The function returns NULL if the
process fails through lack of memory.

The parameters passed to this function describe the window to be instantiated by
specifying a window type, title, its required coordinates, the screen attribute
and type of border to be used. When passing a window title, place an '@'
character before the character to be used as a hot-key; for example "My
@Window". AUTOSCREEN interprets a SHIFT+ALT+letter combination as a
CHANGE_WINDOW request.

SCREEN_W types are pushed onto the screen stack when opened while MENU_BAR_W
types are pushed onto the title bar stack.

Both types of windows are opened by a call to OpenWindow() with the window's
pointer as a parameter. This is the same method used to call the CloseWindow()
routine.

KillWindow() frees any memory taken up by window objects and closes the window
indicated by the supplied pointer parameter. This function returns the window
pointer passed, so freeing memory allocated to a now empty window structure can
be accomplished using:-

     free(KillWindow(mywindow));

The PopWindow() function shuffles the given window to the top of the screen
stack. This is provided as a standard means of ensuring the process window is
made active again after a Yield() is performed.

The Menu Title Bar


Menu title bars are created via a call to NewMenuBar() which takes a Menu_t
pointer and the required attribute as parameters. It returns a pointer of
Window_t to the instantiated structures, or NULL if insufficient memory exists.

NewMenuBar() automatically assigns the required coordinates for the main window
since this is always located at the top of the host screen. When instantiating
other windows, you should therefore take care not to overlap this screen area.
AUTOSCREEN does not check for programming errors such as this.

In the event that a SCREEN_W is programmed to overlap a MENU_BAR_W, then users
will be able to activate a hidden menu title using its ALT+letter combination
(provided that the same combination is not being used for an active SCREEN_W
object). They will not, however, be able to choose it with the mouse.





                                       11





                                                     Creating AUTOSCREEN Objects


AUTOSCREEN first examines the active SCREEN_W for an accelerator key match and
then, if it is not found, searches the active MENU_BAR_W.

Menus


The AUTOSCREEN system reserves menus for choosing code to be executed. Just what
type of code is linked to a menu option, how large it is or how many subordinate
function calls it may contain is irrelevant. The only stipulation is that the
code pointer should be of void (*func)(void) type and that you also specify
sufficient stack space for the routine's use.

At its lowest level, a menu is described by declaring an Option_t array and
assigning values to each of its relevant fields. Thus a file menu might consist
of the following options:-

     Open File...
     Close File
     Merge File...
     DOS Shell

For each option in this menu there will be a specific routine that has been
coded by the programmer to perform the task. The "Open File..." option, for
example, would probably obtain the path and name of the required file via a
dialogue box, locate the file, open a window with the file's name as its title
and then allow the user to perform tasks upon it. The other options will also
have related code to perform.

Given that the high-level routines have been named according to the tasks they
perform, we might make the following declarations:-

     #define ON     1
     #define OFF    0
     void MyQuit(void);

     Option_t Files[] = {
          {"@Open File...", ON, OpenFile, 800},
          {"@Close File", OFF, CloseFile, 800},
          {"@Merge File...", OFF, MergeFile, 800},
          {"E@xit Program", ON, MyQuit, 256},
          {"."},
          {"DOS @Shell", ON, DosShell, 2048},
          {NULL}};

     Option_t Edit[] = {
          {"C@ut    F5", OFF, Cut, 600},
          {"Co@py   F4", OFF, Copy, 600},
          {"Pas@te  F6", OFF, Paste, 600},
          {NULL}};

     Menu_t MainMenu[] = {
          {" @Files ", Files},
          {" @Edit ", Edit},
          {NULL}};



                                       12





                                                     Creating AUTOSCREEN Objects


     void MyQuit(void)
     {
     QUIT_PROGRAM = TRUE;
     }

Note that the last element in each array has NULL assigned to its first field.
This design has been chosen in preference to having to specify the number of
elements when passing the array to an appropriate routine. It also allows the
programmer to easily modify the arrays as coding progresses without having to
alter any other code. The small increase in code size and time taken by the
system to calculate the required details internally at run time is considered a
small price to pay for such programming convenience.

AUTOSCREEN uses the '@' character to mark the following letter as being the
second half of the ALT+letter accelerator key combination. In a similar manner,
the single '.' character indicates a dividing line between menu options.

The defined ON and OFF items are initial values assigned to the Option_t's State
field. AUTOSCREEN shows the accelerator key in bright foreground attribute if
State > 0 and allows the option to be chosen.

You should declare menu items as public in your source code if you want their
associated functions to be able to access and change the initial States
assigned. In the above example, once a file has been opened, it would be logical
for the OpenFile() routine to increment the CloseFile, MergeFile, Cut, Copy and
Paste states to allow their use; and then decrement them when it terminates.

If you are not going to take advantage of AUTOSCREEN's multithreaded
capabilities, then you can have a routine decrement its option's State field as
part of its initialization process. This will ensure that the user cannot launch
a further copy. In such cases, of course, the function should increment its
state field before terminating.

Switches


Switches provide the user with a fast friendly way of choosing the particular
value that a variable should be set to. They also enable the programmer to hide
the actual values being used from the user. This can be particularly important
when requesting values for items like printer font control codes or colour
values.

Consider the following example:-

     #define BLACK  0
     #define WHITE  1

     unsigned COLOUR = BLACK;
     unsigned tempCOL = BLACK;

     static Switch_t Switches[] = {
          {"@Black", ON, &tempCOL, &COLOUR, BLACK},
          {"@White", ON, &tempCOL, &COLOUR, WHITE},
          {NULL}};



                                       13





                                                     Creating AUTOSCREEN Objects


Here we have two variables and two possible colour values that they can contain.
Both are initialized to the same value at start up.

When the user selects a particular value, either by using the mouse, accelerator
combination or a sequence of grey keys, AUTOSCREEN assigns the appropriate value
to tempCOL and updates the display. This is all the switch box does - it does
not assign anything to the COLOUR variable because the user has not yet
confirmed a selection.

User settings are confirmed or cancelled by selecting an appropriate code
button.

Use the AddSwitch() macro to add a switch box to an existing window. Like the
AddCBox() macro detailed in the next section, AddSwitch() calls the AddSBox()
function.

Check Boxes


Check boxes are similar to Switches, but unlike the latter can be used to set a
number of values to a temporary variable. Switch actions can be visualized as
the statement: variable = value; whereas Check Boxes assign a value by the
instruction: variable |= value. The statement sets one or more bits in the
target variable. Such assignments are useful in having the user easily set a
number of internal flags for the program's use.

The declaration is exactly the same as for the Switch_t examined earlier, except
that this time we use a Check_Box_t to help distinguish between them when
examining code. The structures are, in fact, identical.

Check Boxes are added to a window via a call to AddCBox() which is a macro using
the AddSBox() function.

Code Buttons


Code buttons are simply another form of menu option with one important
difference - they are not treated as separate threads. Once again, there is no
limit on the type or length of code they can launch though this time they can
return an int value. When DoObjects() launches a button routine, it returns a
BUTTON_VALUE event and the RetValue field of the Event_t structure contains the
button's code return value.

AUTOSCREEN provides two default code button routines for your use: CANCELfunc()
and CONTINUEfunc(). CANCELfunc is responsible for resetting all temporary
variables used by objects in the active window to their current counterparts. In
our Switch example, tempCOL would be assigned the value of COLOUR. CONTINUEfunc
does the opposite: it updates any current values to that held in their temporary
counterparts. CANCELfunc returns a value of 0 while CONTINUEfunc returns -1.

Code objects are added to a window by a call to AddButton() after describing the
button using an Option_t variable. In this case the StackSize field is
redundant.




                                       14





                                                     Creating AUTOSCREEN Objects


Dialogue Boxes


AUTOSCREEN's dialogue support is based around a powerful generic input routine
that is capable of parsing strings, numbers and dates in real time. Furthermore,
programmers may customize this function's operation to their own particular
requirements.

Adding a dialogue box to a window is achieved in the same manner as adding other
objects: the item is first described to the system by passing parameters to
NewDialogue() and obtaining a pointer to the dialogue created. The new object is
then added to an existing window by a call to AddDBox(). Thereafter, a call to
DoObjects() with the window as its parameter will have the system manage all its
objects automatically.

In addition to describing the type of dialogue required, NewDialogue() requires
a code pointer to a custom acceptance routine. When the user presses [Enter] to
terminate an input entry, AUTOSCREEN takes two specific actions:-

     1)   The input is validated as being the type required.

     2)   The input is verified by a call to the associated custom routine.

If the custom routine returns a value of -1, then AUTOSCREEN accepts the input.
A non negative return value is interpreted as the position of an invalid
character in the input buffer. In the latter case, AUTOSCREEN re-positions the
cursor at this point and awaits further input.

In the majority of situations the custom verification function need only return
-1 to have AUTOSCREEN accept the gathered input type. There may, however, be
occasions when perhaps only numbers in a specific range may be acceptable. In
such cases the verification routine can check the value represented by the input
buffer and return a non negative value accordingly.

You can use the STRING_D type to create further types of your own. Since the
STRING_D type can consist of any printable characters you can utilize
AUTOSCREEN's friendly input facilities to gather a string and then parse it
yourself in the customized function.

AUTOSCREEN also supports scalar and non scalar dialogues. These types allow the
programmer to specify a list of items that the user can chose from by using the
grey keys. Specifying a scalar type tells AUTOSCREEN that the user can only
choose a list member. A non scalar type allows the user to either choose a list
member or enter an item as normal.

If the dialogue object contains a non scalar list of available entries, the
custom routine can add the verified input to the current list by making a copy
and then passing it to AppendItem(). This technique is usefully employed where,
for example, the dialogue obtains details of an object that must exist before
processing can continue. The need to create a new Nominal Account of the given
name while inputting a long Journal Entry is one example of just such a
situation.





                                       15





                                                     Creating AUTOSCREEN Objects


Date input and validation is fully supported by AUTOSCREEN as are all three
national formats (USA, British and Japanese). The system recognizes a space,
'/', '.', or '-' as a valid input separator though the actual character
displayed can be set by the programmer. The default is for a '-'. A lone
separator is interpreted as a request to insert the current field from the
system setting (Typing '.', three times for example, will then insert the
current system date).

Internally, AUTOSCREEN uses a colon as a date field separator to support its
author's combined number and date expression evaluator.















































                                       16





                                                                     Guide-Lines


                                  Guide-Lines



The main() Function


Coding the main() function is simplicity itself. In fact, since the vast
majority of programs will be using a menu title bar, the following skeleton can
be used as a template in most applications.

     void    main(void)
     {
     Window_t *menubar;
     Event_t *event;
     
     InitUI(-1); /* configure system for the best video mode */
     
     // DO_HELP_FUNCTION =     /* ? your help function */;
     // HELP_ON = TRUE;
     
     /* create the menu bar */
     menubar = NewMenuBar(/* global Menu_t */, /* attrib */));
     /* create a window based thread */
     MAINTHREAD = NewThread(WINDOW);
     /* open the menu bar */
     OpenWindow(menubar);

     /* now we set up a continuous loop */
     for(;;)
          {
          do
               event = GetEvent(ALLOW_MENU_BAR);
          while(event->Event != NEW_PROCESS);
          /* add the resulting process to the MAINTHREAD */
          NewProcess(MAINTHREAD,
               event->TgtProcess, event->StackSize);
          /* and launch the thread */
          LaunchThread(MAINTHREAD);
          /* control only returns here when all processes
          have terminated */
          if(QUIT_PROGRAM)
               break;
          /* otherwise we simply continue */
          } // end for loop
     /* clear up */
     free(MAINTHREAD->PList);
     free(MAINTHREAD);
     LeaveUI();
     }

This template declares menubar as a Window_t pointer to hold the main menu bar
and an Event_t pointer (event) to hold the return value from GetEvent().




                                       17





                                                                     Guide-Lines


We initialize the user interface with a call to InitUI() with a parameter of -1.
InitUI() then selects the best text mode available and executes the required set
up code. Had we wished to set a known video mode directly we could have used the
mode number as the required parameter.

The commented-out code can be used to assign a custom help function.

The template next instantiates the main menu bar via a call to NewMenuBar(), and
then the MAINTHREAD via NewThread() requesting a WINDOW type. The user is then
presented with the main menu title bar by opening it with a call to
OpenWindow().

In the for loop we instruct GetEvent() to allow the user to choose an option
from the main menu bar and continually poll its return value until the user has
chosen a process. This process is then attached to MAINTHREAD and the thread
launched.

When control finally returns to our main function we check the value of
QUIT_PROGRAM to see if it has been set. If it is still zero then we simply
continue, otherwise we break out of the for loop and leave AUTOSCREEN via a call
to LeaveUI(). This function performs all necessary cleaning-up operations.

Process Modules


All processes associated with a menu Option_t are given their own private stack
and launched as separate threads by the AUTOSCREEN system. Whether the process
should terminate when it has completed its task or whether it should remain in
existence for the whole of the user session is up to the programmer. Similarly,
whether only one copy of the process may exist at any time; or whether the user
might run limited or unlimited copies of the same process, is entirely at the
programmer's discretion.

The State field in the relevant Option_t structure is examined by AUTOSCREEN to
determine if an option is on or off. On is defined as having a State value > 0.
Given that the initial state is one for a process, it is therefore a simple
matter for the function to check the current state value in its initialization
code and decrement it to ensure another copy is not launched. In a similar
manner the State field can be incremented to enable the process to determine
what copy number it is.

If the process should not be launched when a particular colleague is active, or
vice versa, the new process can check the State field of the offender to decide
whether to become active, to inform the user that an existing task must first be
completed, or to turn off a sister process to ensure it cannot be launched. You
can also set individual bits of the extern QUIT_PROGRAM variable to communicate
between processes.

If QUIT_PROGRAM is not zero, any process calls to GetEvent() will obtain an
EXIT_PROGRAM event and the RetValue field will contain the value of this
variable. Depending on a particular bit setting, an individual process can
decide whether to terminate or to take some other form of action - perhaps
resetting QUIT_PROGRAM to zero or yielding to another process window that might
require the information that this bit represents.



                                       18





                                                                     Guide-Lines


When coding interactive processes you should adhere to the following six
principals:-

     1)   Check and/or update the function's State field in its Option_t
          structure along with those of any other relevant processes.

     2)   Create a window in which to work. As you add objects to a new
          window its MinBounds field is adjusted so that its final setting
          incorporates all objects. To ensure a snug fit, the initial size
          parameters passed to NewWindow() can therefore be reassigned to
          MinBounds by:
          
          mywindow->Bounds = mywindow->MinBounds
          
          The ALTER_WINDOW event will not allow the user to render the
          window smaller than the MinBounds field - though re-positioning
          is always available where possible.
          
          Background text is not supported by this version of AUTOSCREEN.
          If you need to add this enhancement to an object window then
          increase the MinBounds field as appropriate to ensure enough
          space is provided. The wprintf() function breaks lines at the
          right window border automatically so you need only ensure that
          enough lines are provided to stop the text flowing over the
          window's objects. This will allow the user to alter the window's
          width where background text is not of primary importance.

     3)   Assign MAINTHREAD->CurProc to your window's Process field.

     4)   Open the window.

     5)   Act appropriately on the events returned by GetEvent() or
          DoObjects(). You will find that the majority of event handling
          requirements are fully illustrated in the DEMO.C file.

     6)   Before exiting; reset any Option_t State fields that were altered
          on entry.

The PData field in the Window_t structure is reserved specifically for the
programmer's use. This is not used by the AUTOSCREEN system at any time. You can
use this field to attach your own variables or data structures to an existing
window; perhaps a system of process IDs, a customized structure for adding
further objects or scroll bars that this shareware version of AUTOSCREEN does
not support - in fact anything that might prove useful in the particular system
you are developing.












                                       19





                                                 Extended Process Thread Support


                        Extended Process Thread Support



While the WINDOW thread type is reserved for use by the AUTOSCREEN system, total
freedom is given to the programmer to utilize further threads as required.

Such freedom, however, requires some discipline in the area of data processing
when the same information may be updated or altered by one or more currently
active threads. Programmers should therefore pay particular attention to the
design and incorporation of SSADM type "Entity Life History States" in their
final program's data structures.

The WINDOW type thread can be viewed as being "user scheduled". The user decides
which thread should be executed by either launching it from the main menu bar or
resuming it from the point where it was last suspended by changing to the
process' window.

The NEXT and PREV type threads are scheduled by the thread module's Yield()
routine. This function can be supplied a target process to be resumed, or made
to select automatically the next or previous thread in the current thread list -
depending upon the active thread type.

There is no restriction on the number of threads that can be in existence at any
one time (other than available memory).

It should be born in mind that the stack size required will differ with the
memory model being used. As a general rule of thumb, practise has shown that a
maximum stack size of 1024 bytes is normally sufficient for small memory models
and 2048 for large and huge applications. Medium and compact configurations
logically demand a stack size of 1536 bytes. In most situations, however,
AUTOSCREEN's author has found that these stack allocations can be safely reduced
by around 40%.

If the concept of process threads is new to you, then you might like to take a
look at the two thread demos incorporated in the WINDRV.C source code. In the
first, five different functions are declared that are each responsible for
printing a character string to the window. Once a character has been output the
function yields to await control being returned to it. The parent routine
assigns a separate thread to each of these processes and then launches them.
Control is then returned to the parent when all the processes have terminated.

In the second example the parent routine just launches a single process; but
this function adds another copy of itself to the active thread whenever the user
presses a key. This results in up to 26 copies of the same code being run in the
window, creating the illusion of 26 different programs running at the same time.
This will be a familiar technique to most games programmers and highlights the
extra demands being placed on the processor as more and more threads are added.

The action is frozen in this last example by calling GetEvent() without
specifying our interest in extended key presses. This ensures GetEvent() polls
both the mouse and keyboard until an ASCII key is hit (or a CLOSE_WINDOW event
occurs). The function's continuous polling serves to pause the program until




                                       20





                                                 Extended Process Thread Support

another key is pressed.

























































                                       21





                                                                Global Variables


                                Global Variables


ACTIVE_MASK:       Active Mask

Declaration:       unsigned ACTIVE_MASK = 0x0800; /* default */

Comments:          A window is made to appear non active by ANDing each
                   character/attribute pair contained in its Border area with
                   the value of SCREEN_MASK and then XORing with the value of
                   ACTIVE_MASK. It is contained in the ibmpc module.


ACTWINDOW:         The Active Window

Declaration:       Window_t *ACTWINDOW = NULL; /* default */

Comments:          Contains the location of the active window structure. When a
                   window is first opened, it is placed on the top of the
                   SCREENSTACK and made active. ACTWINDOW is contained in the
                   screen module.


ALTER_WINDOW_KEY:  Alter Window Key

Declaration:       unsigned char ALTER_WINDOW_KEY = F9;  /* default */

Comments:          The VIRGIN function key that is assigned to an ALTER_WINDOW
                   event. It is contained in the input module.


CHANGE_WINDOW_KEY: Change Window Key

Declaration:       unsigned char CHANGE_WINDOW_KEY = F6; /* default */

Comments:          The VIRGIN function key that is assigned to a CHANGE_WINDOW
                   event. It is contained in the input module.


CLOSE_WINDOW_KEY:  Close Window Key

Declaration:       unsigned char CLOSE_WINDOW_KEY = F10;  /* default */

Comments:          The VIRGIN function key that is assigned to a CLOSE_WINDOW
                   event. It is contained in the input module.


CURWINDOW:         The Current Window

Declaration:       Window_t *CURWINDOW = NULL; /* default */

Comments:          The CURWINDOW setting is used by all screen output and cursor
                   control routines. It is contained in the screen module.




                                       22





                                                                Global Variables


CW_ICON:           Close Window Icon

Declaration:       unsigned char CW_ICON = '\011'; /* default */

Comments:          The character to be used for displaying a close window icon
                   in the top left border area. It is contained in the ibmpc
                   module.


D_BORDER:          Double Border Structure

Declaration:       Border_t D_BORDER = /* default values */ { 0xc9, 0xbb, 0xc8,
                   0xbc, 0xcd, 0xba, 0xcc, 0xb9, NORMAL };

Comments:          D_BORDER contains the IBM extended character codes to
                   construct a double window border along with the attribute to
                   be used. It is contained in the ibmpc module.


DATE_SEPARATOR:    Date Separator

Declaration:       char DATE_SEPARATOR = '-'; /* default */

Comments:          The character to be output as a date separator. (The DATE_D
                   routine allows a space, '/', ':', '.', and '-' to be
                   interpreted as a valid separator for the user's convenience).
                   DATE_SEPARATOR is contained in the screen module.


DATETYPE:          Date Type

Declaration:       DateType_s DATETYPE = ENG; /* default */

Comments:          The current date type setting for use with DATE_D types. It
                   is contained in the dialogue module.


daysin:            Days In Month

Declaration:       int daysin[12] = { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31,
                   30, 31 };

Comments:          The standard number of days in each month in a non leap year.
                   It is contained in the dialogue module.


DO_HELP_FUNCTION:  Do Help Function

Declaration:       void (*DO_HELP_FUNCTION)(void) = NULL; /* default */

Comments:          The address of the custom help function that is to be
                   launched when the HELP_KEY is pressed and HELP_ON is set. It
                   is contained in the input module.




					23





                                                                Global Variables


EVENT:             System Event

Declaration:       Event_t  EVENT;

Comments:          The variable containing details of the last event that took
                   place in the system. It is contained in the screen module.


HELP_KEY:          Help Key

Declaration:       unsigned char HELP_KEY = F1; /* default */

Comments:          The VIRGIN function key that is assigned to launching the
                   DO_HELP_FUNCTION if HELP_ON is set. It is contained in the
                   input module.


HELP_ON:           Help On

Declaration:       BOOLEAN  HELP_ON = FALSE; /* default */

Comments:          The current state of the customised DO_HELP_FUNCTION. It is
                   contained in the input module.


HELP_STACK_SIZE:   Help Stack Size

Declaration:       unsigned HELP_STACK_SIZE = 1024; /* default */

Comments:          The required stack size for use by the DO_HELP_FUNCTION. It
                   is contained in the input module.


HOST_SCREEN:       Host Screen Variable

Declaration:       Screen_t HOST_SCREEN;

Comments:          HOST_SCREEN contains the maximum coordinates that are
                   available on the host VDU. It is initialized by the InitUI()
                   function and contained in the ibmpc module.


MAINTHREAD:        The Main Process Thread

Declaration:       Thread_t *MAINTHREAD;

Comments:          The address of the structure to which all new processes
                   ordered by the event manager are added. It is contained in
                   the input module and instantiated in the main() function by a
                   call to NewThread().


MOUSE_SUPPORTED:   Mouse Supported Variable




                                       24





                                                                Global Variables


Declaration:       int MOUSE_SUPPORTED = 0;

Comments:          MOUSE_SUPPORTED contains the number of buttons supported by
                   the mouse, or 0 if no mouse exists. It is initialized by the
                   InitUI() function and contained in the ibmpc module.


QUIT_PROGRAM:      Quit Program

Declaration:       int QUIT_PROGRAM = 0; /* default */

Comments:          The event manager checks the setting of this variable on
                   entry, and if it is not equal to zero, initiates an
                   EXIT_PROGRAM event. It is contained in the input module.


S_BORDER:          Single Border Structure

Declaration:       Border_t S_BORDER = /* default values */ { 0xda, 0xbf, 0xc0,
                   0xd9, 0xc4, 0xb3, 0xc3, 0xb4, NORMAL};

Comments:          S_BORDER contains the IBM extended character codes to
                   construct a window border along with the attribute to be
                   used. It is contained in the ibmpc module.


SCREEN_MASK:       Screen Mask

Declaration:       unsigned SCREEN_MASK = 0xFFFF; /* default */

Comments:          A window is made to appear non active by ANDing each
                   character/attribute pair contained in its Border area with
                   the value of SCREEN_MASK and then XORing with the value of
                   ACTIVE_MASK. It is contained in the ibmpc module.


SW_BUTTON:         Switch Button

Declaration:       unsigned char SW_BUTTON = 0x07; /* default */

Comments:          The character to be used for switch buttons. It is contained
                   in the ibmpc module.


TABSTOPS:          Tab Stops

Declaration:       int TABSTOPS = 4; /* default */

Comments:          The number of spaces between one tab position and the next
                   for use by wprintf. It is contained in the screen module.







                                       25





                                                                 Data Structures


                                Data Structures


Border_t:          Border Type

Include:           screen.h

Declaration:       typedef struct{unsigned char TL, TR, BL, BR, HZ, VT, LB, RB,
                   Attrib;}Border_t;

Comments:          Used to record the characters to be used in drawing a
                   window's border and its default attribute.


Curs_t:            Cursor Type

Include:           screen.h

Declaration:       typedef struct {
                   unsigned char Row, Col;
                   } Curs_t;

Comments:          Used in recording the hardware cursor location and type.


DateType_s:        Date Type Set

Include:           dialogue.h

Declaration:       typedef enum {ENG, USA, JAP} DateType_s;

Comments:          The set of date types supported by the system. The default
                   setting is for ENG of the global variable DATETYPE contained
                   in the dialogue module.


Dialogue_t:        Dialogue Type

Include:           dialogue.h


















                                       26





                                                                 Data Structures


Declaration:       typedef struct dilog {
                   char *Buffer; /* to hold input */
                   int BufLen; /*  The length of the buffer. This will be at
                   least the length of the visual display area, if it is more,
                   then the field is scrolled horizontally to extend the input
                   area. */
                   int (*Accept)(struct dilog *); /* the address of the required
                   acceptance routine that is to be called when the user presses
                   '\r'. A return value of > -1 indicates that the input is not
                   acceptable and the DoDialogue() routine will continue at the
                   point in the buffer indicated by the return value. */
                   BOOLEAN Scalar; /* TRUE if no input allowed, else FALSE */
                   int Count; /* used internally by the routine */
                   int BufPosn;   /* ditto */
                   int Offset;  /* ditto */
                   int Last;    /* ditto */
                   int State;   /* ditto */
                   llist_t *List; /* a list of strings from which the user may
                   choose using either the space bar or grey keys. If Scalar is
                   TRUE only a list member may be chosen */ llnode_t *LPosn; /*
                   the current list position. This can be modified by the
                   acceptance routine to begin the next input by displaying the
                   given node for acceptance */ BOOLEAN Signed; /* true if a
                   signed INT_D or NUMBER_D is required. Allows unary operator.
                   */
                   int Decimals;  /* the number of decimals to be displayed in
                   the justified string when the input has been accepted */
                   }Dialogue_t;

Comments:          The storage required to describe the manner in which
                   DoDialogue behaves.


Event_s:           Event Set

Include:           screen.h

Declaration:       typedef enum { CHANGE_WINDOW = 1, DO_MENU_BAR, DO_SWITCH,
                   DO_CHECK_BOX, DO_BUTTON, EXT_KEY_EVENT, CLOSE_WINDOW,
                   ALTER_WINDOW, DO_LINE, ASCII_KEY, NEW_PROCESS, EXIT_PROGRAM,
		   BUTTON_VALUE, DO_DIALOGUE
                   }Event_s;

Comments:          The set of events that this version of AUTOSCREEN supports.
                   This set is liable to be extended in future versions.


Event_t:           Event Type

Include:           screen.h







                                       27





                                                                 Data Structures


Declaration:       struct ext_key {
                   int Class;
                   unsigned char Key;
                   };
                   struct cde {
                   int (*TgtProcess)(void);
                   unsigned StackSize;
                   };
                   typedef struct {
                   Event_s Event;
                   Window_t *Window;
                   llnode_t *Node;
                   union
                   {
                   int RetValue;
                   int LineNo;
                   struct cde;
                   struct ext_key;
                   unsigned char Input;
                   };
                   }Event_t;

Comments:          Storage used to describe the event that just took place.
                   Future versions of AUTOSCREEN may modify the unnamed union
                   but it is unlikely that the overall size of the structure
                   will be changed.


ExtClass_s:        Extended Character Class Set

Include:           input.h

Declaration:       typedef enum { VIRGIN, SHIFT_EXT, CTRL_EXT, CTRL_SHIFT_EXT,
                   ALT_EXT, ALT_SHIFT_EXT, ALT_CTRL_EXT, ALT_CTRL_SHIFT_EXT,
                   GREY_KEY, FAULT } ExtClass_s;

Comments:          Key references in terms of a standard IBM PC/AT keyboard.
                   This provides a standard term of reference for the system.


FKey_s:            Function Key Set

Include:           input.h

Declaration:       typedef enum { F1 = 17, F2, F3, F4, F5, F6, F7, F8, F9, F10,
                   F11, F12 }FKey_s;

Comments:          Key references in terms of a standard IBM PC/AT keyboard.
                   This provides a standard term of reference for the system.


GreyKey_s:         Grey Key Set

Include:           input.h



                                       28





                                                                 Data Structures


Declaration:       typedef enum { SHIFT_TAB, HOME, UP, PGUP, LEFT, RIGHT, END,
                   DOWN, PGDN, INSERT, DEL, CTRL_PRTSCRN, CTRL_LEFT, CTRL_RIGHT,
                   CTRL_END, CTRL_PGDN, CTRL_HOME, CTRL_PGUP } GreyKey_s;

Comments:          Key references in terms of a standard IBM PC/AT keyboard.
                   This provides a standard term of reference for the system. If
                   you are rewriting primitives for porting to another system,
                   simply map return values accordingly. For example: NEXT and
                   PREV keys to PGDN and PGUP.


LLDATA:            Linked List Data Type

Include:           llist.h

Declaration:       typedef char LLDATA;

Comments:          The generic form for data linked to system based data
                   structures.


llist_t:           Linked List Type

Include:           llist.h

Declaration:       typedef struct {
                   size_t length;
                   llnode_t  *first, *last;
                   }llist_t;

Comments:          Storage required for maintaining control over a linked list
                   data structure.


llnode_t:          Linked List Node Type

Include:           llist.h

Declaration:       typedef struct llnode { LLDATA *item; struct llnode *next,
                   *prev; }llnode_t;

Comments:          Primitive node data storage structure.


llstack_t:         Linked List Stack Type

Include:           llist.h

Declaration:       typedef struct {
                   size_t length;
                   llnode_t *top;
                   }llstack_t;





                                       29





                                                                 Data Structures


Comments:          Storage required for maintaining control over a linked list
                   stack type structure.


Menu_t:            Menu Type

Include:           screen.h

Declaration:       typedef struct {
                   char *Title; /* the menu title */
                   Option_t *Options; /* pointer to option array */
                   char HKey; /* the menu hot key */
                   }Menu_t;

Comments:          Storage used in describing a menu bar to the system.


Option_t:          Option Type

Include:           screen.h

Declaration:       typedef struct {
                   char *Title; /* the option title */
                   int State; /* hot key state - ON or OFF */
                   int (*Code)(void); /* function pointer */
                   unsigned StackSize; /* stack to be allocated */
                   char HKey; /* the title hot key */
                   }Option_t;

                   typedef Option_t Button_t;

Comments:          Storage used in describing both option and button type
                   objects to the system.


Register_t:        Register Type

Include:           thread.h

Declaration:       typedef unsigned int Register_t[REGSIZE];

Comments:          The type of array to be passed to the SUSPEND and RESUME
                   functions contained in the register module.


REGSIZE:           Register Size

Include:           thread.h









                                       30





                                                                 Data Structures


Declaration:       #if defined (__MEDIUM) /* medium model */
                   #define REGSIZE 11
                   #elif defined (__COMPACT) /* Compact model */
                   #define REGSIZE 11
                   #elif defined (__SMALL) /* Small Model */
                   #define REGSIZE 10
                   #elif defined (__TINY)  /* Tiny model */
                   #define REGSIZE 10
                   #else    /* Large or Huge model */
                   #define REGSIZE 12
                   #endif

Comments:          The size of the Register_t array for storing register values
                   by the SUSPEND and RESUME functions contained in the register
                   module.


Screen_t:          Screen Type

Include:           screen.h

Declaration:       typedef struct { unsigned char TRow, TCol, BRow, BCol; }
                   Screen_t;

Comments:          Used to record screen area boundaries.


Switch_t:          Switch Type

Include:           screen.h

Declaration:       typedef struct {
                   char *Title; /* the switch title */
                   int State; /* hot key state */
                   int *TempVar; /* the address to hold temporary settings */
                   int *Var; /* the address of the variable to be changed on a
                   continue event */
                   int Mask; /* the mask to be applied */
                   char HKey; /* the title hot key */
                   }Switch_t; /* switch is on when Var == mask */
                   
                   typedef Switch_t CheckBox_t;
                   /* check is on when (Var & mask) == TRUE */

Comments:          Storage used in describing both switch and check box objects
                   to the system.


Thread_s:          Thread Set

Include:           thread.h

Declaration:       typedef enum { NEXT, PREV, WINDOW } Thread_s;




                                       31





                                                                 Data Structures


Comments:          The thread type used on a call to NewThread(). The type of
                   thread governs the action taken to resume another process
                   when the current process terminates or no target process is
                   supplied to the Yield() function. NEXT and PREV types
                   indicate the position of the target process in the current
                   Thread_t's PList. WINDOW indicates that the process on top of
                   the SCREENSTACK should be resumed.


Thread_t:          Thread Type

Include:           thread.h

Declaration:       typedef struct {
                   Register_t Regs;
                   llist_t *PList;
                   llnode_t *CurProc;
                   Thread_s Type;
                   }Thread_t;

Comments:          The storage required for maintaining system thread details.


Wind_s:            Window Set

Include:           screen.h

Declaration:       typedef enum{ SCREEN_W, OBJECT_W, MENU_BAR_W, POP_UP_W
                   }Wind_s;

Comments:          The set of window types supported by this version of
                   AUTOSCREEN. This set is liable to future modification.


Window_t:          Window Type

Include:           screen.h




















                                       32





                                                                 Data Structures


Declaration:       typedef struct wndw {
                   char *Title; /* window title */
                   unsigned char TOffset, TLength; /* title col and length */
                   Screen_t Bounds; /* window boundaries for writing */
                   Screen_t MinBounds; /* minimum window boundaries in order to
                   contain attached objects - except POP_UP */
                   unsigned char Attrib; /* window attribute */
                   Border_t *Border; /* Border details */
                   unsigned *Area; /* saved old screen area */
                   unsigned *Pane; /* saved window screen contents */
                   void *Contents; /* window contents */
                   char HKey; /* Hot key for this window */
                   llist_t *ObjList; /* linked object list */
                   Wind_s Type; /* the type of window */
                   llnode_t *SNode; /* its stack pointer if a main window */
                   struct wndw *Parent; /* its parent window */
                   llnode_t *Posn; /* its node in the parent list */
                   WObj_s CType;  /* its contents type */
                   llnode_t *Process; /* set by user routine to the current
                   process once the window is established */
                   BOOLEAN Changed; /* set to true if contents has changed since
                   the last time pane was saved */
                   Curs_t CursPosn; /* the current cursor position within the
                   window */
                   void *PData; /* private data field for programmer's use */
                   } Window_t;

Comments:          Used to store all required information relating to a window
                   and its associated process and objects.


WObj_s:            Window Object Set

Include:           screen.h

Declaration:       typedef enum{ EMPTY = 1, MENU_TITLE, POP_UP_LIST,
		   CODE_BUTTON, SWITCH, CHECK_BOX,
		   STRING_D, INT_D, NUMBER_D, DATE_D}WObj_s;

Comments:          The set of object types supported by this version of
                   AUTOSCREEN. This set is liable to future modification.
















                                       33





                                                             Function Prototypes


                              Function Prototypes


AddButton:         Add Button

Include:           screen.h

Description:       Adds a Button to the given window at the supplied starting
                   coordinate

Prototype:         unsigned char AddButton(Window_t *window, Option_t *data,
                   unsigned char TRow, unsigned char TCol);

Returns:           The width of the resulting button if successful, else 0 as
                   unsigned char


AddDBox:           Add Dialogue Box

Include:           screen.h

Description:       Adds a dialogue box to the given window as a further object
                   to be managed. The width parameter specifies the width of the
                   entry box required.

Prototype:         unsigned char AddDBox(Window_t *window, char *label, WObj_s
                   type, void *data, unsigned char trow, unsigned char tcol,
                   unsigned char width);

Returns:           The width of the box and title if successful as an unsigned
                   char, else 0.


AddSBox:           Add Switches or Check Boxes

Include:           screen.h

Description:       Adds a number of switches or check boxes to the given window
                   depending upon supplied type parameter.

Prototype:         BOOLEAN AddSBox(WObj_s type, Window_t *window, Switch_t
                   *switches, unsigned char TRow, unsigned char TCol);

Returns:           TRUE if successful else FALSE


AdjBounds:         Adjust Boundaries

Include:           ibmpc.h

Description:       Adjusts the supplied boundaries to a new location based on
                   the supplied horizontal and vertical movements to take place

Prototype:         void AdjBounds(Screen_t *bounds, int hmove, int vmove);



                                       34





                                                             Function Prototypes


Returns:           NOTHING


AppendItem:        Append Item.

Include:           llist.h

Description:       Appends an item to the end of a linked list.

Prototype:         llist_t *AppendItem(llist_t *list, LLDATA *item);

Returns:           A llist_t pointer to the list added to else NULL.


B1inB2:            Bounds1 Contained In Bounds2

Include:           screen.h

Description:       Checks to see that the diagonal lines contained in first
                   parameter are all contained in the second

Prototype:         BOOLEAN B1inB2(Screen_t *bounds1, Screen_t *bounds2);

Returns:           TRUE if all points lie inside bounds2, else FALSE


BegLine:           Begin Line

Include:           screen.h

Description:       Moves cursor to beginning of line

Prototype:         void BegLine(void);

Returns:           NOTHING


BestSizingPosn:    Best Sizing Position

Include:           ibmpc.h

Description:       Locates the best position for undertaking window sizing.

Prototype:         int BestSizingPosn(Window_t *window, int *row, int *col);

Returns:           An int representing a location number, where: 1 == top left,
                   2 == top right, 3 == bottom left and 4 == bottom right. The
                   top left is chosen as default if no other location betters
                   it.


CANCELfunc:        Cancel Function

Include:           input.h



                                       35





                                                             Function Prototypes


Description:       Button function responsible for re-setting all temporary
                   variables to their current values.

Prototype:         int CANCELfunc(void);

Returns:           0


ClearLine:         Clear Line

Include:           screen.h

Description:       Clears the current window line

Prototype:         void ClearLine(void);

Returns:           NOTHING


ClearWindow:       Clear Window.

Include:           screen.h

Description:       Clears the CURWINDOW and positions the cursor at the top left
                   position. Saves the CursPosn field and sets Changed to TRUE.

Prototype:         void ClearWindow(void);

Returns:           NOTHING.


ClipCode:          ClipCode

Include:           screen.h

Description:       Assigns a clip code based on the position of the given points
                   in relation to the passed boundaries
                   
                   1001 | 1000 | 1010
                   -----+------+------
                   0001 | 0000 | 0010
                   -----+------+------
                   0101 | 0100 | 0110
                   

Prototype:         int ClipCode(unsigned char row, unsigned char col, Screen_t
                   *bounds);

Returns:           The assigned clip code as an int


CloseWindow:       Close Window

Include:           screen.h



                                       36





                                                             Function Prototypes


Description:       Closes the given window

Prototype:         Window_t *CloseWindow(Window_t *target);

Returns:           A pointer to the closed window.


CONTINUEfunc:      Continue function

Include:           input.h

Description:       Button routine which is responsible for updating program
                   variables from their existing temporary settings

Prototype:         int CONTINUEfunc(void);

Returns:           -1


CursDn:            Cursor Down.

Include:           screen.h

Description:       Moves cursor down one line.

Prototype:         BOOLEAN CursDn(void);

Returns:           TRUE is successful, else FALSE.


CursHome:          Cursor Home

Include:           screen.h

Description:       Positions the cursor in the top left corner of the CURWINDOW

Prototype:         BOOLEAN CursHome(void);

Returns:           TRUE, or FALSE if no CURWINDOW


CursL:             Cursor Left.

Include:           screen.h

Description:       Moves cursor left one column.

Prototype:         BOOLEAN CursL(void);

Returns:           TRUE if successful, else FALSE.


CursOff:           Cursor Off.




                                       37





                                                             Function Prototypes


Include:           ibmpc.h

Description:       Turns the text cursor off.

Prototype:         void CursOff(void);

Returns:           NOTHING.


CursorType:        Get Cursor Type.

Include:           ibmpc.h

Description:       Sets the start and end parameters to the current cursor scan
                   values.

Prototype:         void CursorType(unsigned char *start, unsigned char *end);

Returns:           NOTHING.


CursR:             Cursor Right.

Include:           screen.h

Description:       Moves cursor right by one column.

Prototype:         BOOLEAN CursR(void);

Returns:           TRUE if successful, else FALSE.


CursRet:           Cursor Return

Include:           screen.h

Description:       Puts the cursor at the beginning of the next line

Prototype:         BOOLEAN CursRet(void);

Returns:           TRUE if successful else FALSE


CursUp:            Cursor Up.

Include:           screen.h

Description:       Moves cursor up one line.

Prototype:         BOOLEAN CursUp(void);

Returns:           TRUE if successful, else FALSE.





                                       38





                                                             Function Prototypes


DecBounds:         Decrement Bounds

Include:           screen.h

Description:       Reduces the boundary area by a value of one

Prototype:         void DecBounds(Screen_t *bounds);

Returns:           NOTHING


DecDBounds:        Decrement Dialogue Boundaries

Include:           screen.h

Description:       Decrements the given dialogue boundaries in preparation for
                   input.

Prototype:         void DecDBounds(Window_t *window);

Returns:           NOTHING


DeleteNode:        Delete Node.

Include:           llist.h

Description:       Deletes a node from a linked list and frees the space
                   allocated to it. If the kill parameter is TRUE, then the data
                   item is also freed.

Prototype:         llnode_t *DeleteNode(llist_t *list, llnode_t *node, BOOLEAN
                   kill);

Returns:           A llnode_t pointer to the last element in the list.


DoDialogue:        Do Dialogue

Include:           dialogue.h

Description:       Gathers a string of the required type into the given window

Prototype:         Event_t *DoDialogue(Window_t *window);

Returns:           A pointer to the terminating event


DoObjects:         Do Objects

Include:           input.h






                                       39





                                                             Function Prototypes


Description:       Handles user interaction with an object window starting with
                   the given node of the windows ObjList. The function assumes
                   at least two buttons being present and corresponding to the
                   CONTINUEfunc and CANCELfunc supplied. If the user selects
                   either of these buttons the procedure terminates. A start
                   value of NULL indicates "as they come". The mode parameter
                   can be one, or a combination of: ALLOW_MENU_BAR and
                   ALLOW_ALTER_WINDOW.

Prototype:         Event_t *DoObjects(Window_t *window, llnode_t *start,
                   insigned int mode);

Returns:           A pointer to the terminating event or NULL if start state was
                   off or all objects were off.


DoPopUp:           Do Pop Up

Include:           input.h

Description:       Handles user interaction with the Pop-Up-Menu by opening the
                   window and highlighting the first option. If the side_exit
                   parameter is FALSE then horizontal movements are ignored. If
                   side_exit is TRUE, then a horizontal movement key results in
                   the closing of the Pop-Up-Menu and the function returns with
                   the given event. A value of side_exit == TRUE implies a
                   return to a DoMenuBar() type handler.

Prototype:         Event_t *DoPopUp(BOOLEAN side_exit, Window_t *window);

Returns:           A pointer to the terminating Event_t structure


EndLine:           End Line

Include:           screen.h

Description:       Moves cursor to the end of the line

Prototype:         void EndLine(void);

Returns:           NOTHING


ExpBounds:         Expand Boundaries

Include:           ibmpc.h

Description:       Expands the supplied boundaries to include the supplied
                   movements from the given location provided minimum boundaries
                   are not reduced. The location code is one of: 1 (top left), 2
                   (top right), 3 (bottom left) or 4 (bottom right).





                                       40





                                                             Function Prototypes


Prototype:         void ExpBounds(Screen_t *bounds, Screen_t *minbounds, int
                   hmove, int vmove, int location);

Returns:           NOTHING


ExtCharClass:      Extended Character Class

Include:           ibmpc.h

Description:       Returns the character's class and adjusts the supplied char
                   to its ASCII component or function key number.

Prototype:         unsigned int ExtCharClass(unsigned char *scan);

Returns:           The character's class from the ExtClass_s as an unsigned int.


FlipArea:          Flip Area

Include:           ibmpc.h

Description:       Flips the area attributes to make it appear inactive if
                   active, and active if inactive using global SCREEN_MASK (AND)
                   and ACTIVE_MASK (XOR).

Prototype:         void FlipTitle(Screen_t *area);

Returns:           NOTHING


GetCurs:           Get Cursor.

Include:           ibmpc.h

Description:       Obtains the current cursor position setting the row and col
                   parameters as appropriate.

Prototype:         void GetCurs(unsigned char *row, unsigned char *col);

Returns:           NOTHING.


GetEvent:          Get Event

Include:           input.h











                                       41





                                                             Function Prototypes


Description:       Gets a system event for use by the calling routine. ALT_EXT
                   keys are interpreted as an Object's selection from within the
                   current window or the Menu bar. SHIFT_ALT_EXT keys request a
                   change of window. The mode parameter determines the degree to
                   which the event manager is responsible for automating the
                   interface. Bits have the following meanings:
                   
                   .......x ALLOW_MENU_BAR
                   ......x. ALLOW_ALTER_WINDOW
                   .....x.. REPORT_EXT_KEY
                   ....x... NO_FLUSH_KEYBD
                   ...x.... REPORT_NULL_EVENT

Prototype:         Event_t *GetEvent(unsigned char mode);

Returns:           A pointer to the Event_t structure.


GetMObj:           Get Mouse Object

Include:           screen.h

Description:       Ascertains whether the mouse has been used to select an
                   object

Prototype:         Event_t *GetMObj(unsigned row, unsigned col);

Returns:           A pointer to the Event_t containing the appropriate details,
                   or NULL if the click took place on the desktop.


GetMPosn:          Get Mouse Position

Include:           ibmpc.h

Description:       Gets the mouse position and button status

Prototype:         int GetMPosn(unsigned *row, unsigned *col);

Returns:           The result of the bx reg: 1 == LEFT, 2 == RIGHT, 4 == MIDDLE
                   (and combinations).


GetMPress:         Get Mouse Press

Include:           ibmpc.h

Description:       Obtains mouse press information for the supplied button.

Prototype:         GetMPress(int button, unsigned *row, unsigned *col, unsigned
                   *status);

Returns:           The number of Button presses as an int




                                       42





                                                             Function Prototypes


GetObject:         Get Object

Include:           screen.h

Description:       Searches the ACTWINDOW and, if necessary, the MENUSTACK.top
                   window to locate the object associated with the given hot
                   key.

Prototype:         Event_t *GetObject(char hkey);

Returns:           A pointer to an Event_t structure if found else NULL


GetVidMode:        Get Video Mode

Include:           ibmpc.h

Description:       Gets the current video mode setting

Prototype:         unsigned char GetVidMode(void);

Returns:           The mode as an unsigned char


GetWindow:         Get Window

Include:           screen.h

Description:       Locates the window whose title hot key corresponds to the
                   char passed. Searching takes place on the SCREENSTACK.

Prototype:         Window_t *GetWindow(char key);

Returns:           A Window_t pointer to the located window if successful, else
                   NULL


HideMouse:         Hide Mouse Cursor

Include:           ibmpc.h

Description:       Hides the mouse cursor

Prototype:         void HideMouse(void);

Returns:           NOTHING


IncBounds:         Increment Bounds

Include:           screen.h

Description:       Increases the circumference by a value of one




                                       43





                                                             Function Prototypes


Prototype:         void IncBounds(Screen_t *bounds);

Returns:           NOTHING


IncDBounds:        Increment Dialogue Boundaries

Include:           screen.h

Description:       Increments the supplied dialogue boundaries to include the
                   label and border areas

Prototype:         void IncDBounds(Window_t *window);

Returns:           NOTHING


InitMouse:         Initialize Mouse

Include:           ibmpc.h

Description:       Checks that a mouse is installed and resets it if present.
                   Sets cursor visible in centre of screen.

Prototype:         int InitMouse(void);

Returns:           0 if mouse not present, else number of buttons supported as
                   an int


InitUI:            Initialize User Interface

Include:           ibmpc.h

Description:       Determines the type of video monitor in use, sets the
                   HOST_SCREEN values for use by other modules and sets the
                   required video mode. If the vdu_mode parameter is given as -
                   1, then the routine selects the best mode available.
                   Ascertains if mouse is supported, initializes it if present,
                   and sets MOUSE_SUPPORTED accordingly.

Prototype:         int InitUI(int vdu_mode);

Returns:           The actual mode set as an int.


InsertOn:          Insert On

Include:           ibmpc.h

Description:       Tests the current keyboard insert status

Prototype:         BOOLEAN InsertOn(void);




                                       44





                                                             Function Prototypes


Returns:           TRUE if insert is on, else FALSE


IsAbove:           Is Above

Include:           screen.h

Description:       Checks to see if the window contained in the target node is
                   above that contained in the location node.

Prototype:         BOOLEAN IsAbove(llnode_t *location, llnode_t *target);

Returns:           TRUE if target window is above location window, else FALSE


IsBelow:           Is Below

Include:           screen.h

Description:       Checks to see if the window contained in the target node is
                   below that contained in the location node.

Prototype:         BOOLEAN IsBelow(llnode_t *location, llnode_t *target);

Returns:           TRUE if target window is below location window, else FALSE


KBStatus:          Key Board Status

Include:           ibmpc.h

Description:       Obtains details of the current keyboard status using int 16H
                   service 02H. Bit Meanings are as follows:-
                   
                   7 6 5 4 3 2 1 0
                   x . . . . . . .  Insert State
                   . x . . . . . .  Caps Lock State
                   . . x . . . . .  Number Lock State
                   . . . x . . . .  Scroll Lock State
                   . . . . x . . .  Alt pressed
                   . . . . . x . .  Ctrl pressed
                   . . . . . . x .  Left Shift Pressed
                   . . . . . . . x  Right Shift Pressed

Prototype:         unsigned int KBStatus(void);

Returns:           The resulting AL register byte for evaluation as an unsigned
                   int.


KillAllWindows:    Kill All Windows

Include:           screen.h




                                       45





                                                             Function Prototypes


Description:       Frees all memory used by window structures.

Prototype:         void KillAllWindows(void);

Returns:           NOTHING


KillWindow:        Kill Window

Include:           screen.h

Description:       Closes and then frees the memory used by a Window structure

Prototype:         Window_t *KillWindow(Window_t *window);

Returns:           A Window_t pointer to the empty structure.


LabelWindow:       Label Window

Include:           screen.h

Description:       Calculates the length of the title string and sets its
                   offset, length and hkey fields as required for a Dialogue
                   object (.._D in WObj_s);

Prototype:         size_t LabelWindow(Window_t *window, char *title);

Returns:           The length of the title string, not including any '@'
                   character as size_t


LargeCurs:         Large Cursor.

Include:           ibmpc.h

Description:       Sets blinking cursor to highlight all of the char area.

Prototype:         void LargeCurs(void);

Returns:           NOTHING.


LaunchThread:      Launch Thread

Include:           thread.h

Description:       Launches the given thread by pushing it onto the
                   THREAD_STACK, saving the Regs, plugging the current return
                   address into the structure and resuming the first process
                   required by the Type field.

Prototype:         void _pascal LaunchThread(Thread_t *thread);




                                       46





                                                             Function Prototypes


Returns:           NOTHING


LeaveUI:           Leave User Interface

Include:           ibmpc.h

Description:       Kills all remaining windows and hides the mouse if it was
                   present. Resets video mode to default.

Prototype:         void LeaveUI(void);

Returns:           NOTHING


MakeCirc:          Make Circular

Include:           llist.h

Description:       Makes a linear list circular.

Prototype:         llist_t *MakeCirc(llist_t *list);

Returns:           A llist_t pointer to the list converted, or NULL if the list
                   is empty.


MakeLinear:        Make Linear

Include:           llist.h

Description:       Forces a given list to linear format

Prototype:         llist_t *MakeLinear(llist_t *list);

Returns:           A pointer of llist_t to the list converted, else NULL if the
                   list is empty.


NameWindow:        Name Window

Include:           screen.h

Description:       Calculates the position that the title will occupy within the
                   window's boundaries and assigns these values to the window's
                   fields. If NULL is passed as a pointer to the title string
                   then the fields are just initialized.

Prototype:         size_t NameWindow(Window_t *window, char *title);

Returns:           The title length, not including any '@' character as size_t.


NewDialogue:       New Dialogue



                                       47





                                                             Function Prototypes


Include:           dialogue.h

Description:       Creates a Dialogue_t description structure from the
                   information supplied. Set type to the required ..._D type,
                   and length to the buffer length required (including the
                   terminating '\0' character). The accept parameter is the
                   address of your own acceptance routine that is passed a
                   pointer to the Dialogue_t structure when the user hits
                   return. This routine should return a value of -1 if the input
                   is acceptable. A non negative value is taken as being the
                   position in the buffer where an external parse failed. In
                   this case, the buffer is re-displayed for the user's
                   attention with the cursor placed on the supplied position.
                   Numbers and dates are parsed in real time and do not require
                   verifying, so the routine can just return -1 unless you want
                   to check for a specific range. The signed and decimal
                   parameters are required for number types. You can supply a
                   list of character strings for the user to choose from via the
                   list parameter. If scalar is set to TRUE, then only a list
                   member may be selected. Otherwise a list member, or user
                   input is gathered for passing to your accept routine.

Prototype:         void *NewDialogue(WObj_s type, int length, int
                   (*accept)(Dialogue_t *), BOOLEAN signed, int decimals,
                   llist_t *list, BOOLEAN scalar);

Returns:           A void pointer to the new structure if successful, else NULL


NewList:           New List.

Include:           llist.h

Description:       Creates a llist_t record for a new linked list.

Prototype:         llist_t *NewList(void);

Returns:           A pointer of llist_t to the new header record if successful,
                   else NULL.


NewMenuBar:        New Menu Bar

Include:           screen.h

Description:       Creates a new Window_t structure and fills it with the
                   required menu bar titles.

Prototype:         Window_t *NewMenuBar(Menu_t *menu, unsigned char attrib);

Returns:           A pointer to the new Window_t structure if successful, else
                   NULL





                                       48





                                                             Function Prototypes


NewNode:           New Node.

Include:           llist.h

Description:       Creates a new node for linking in a list and assigns initial
                   values as passed.

Prototype:         llnode_t *NewNode(LLDATA *item, llnode_t *next, llnode_t
                   *prev);

Returns:           A pointer to the new node if successful, else NULL.


NewPopUp:          New Pop Up Window

Include:           screen.h

Description:       Creates a new Pop Up Window

Prototype:         Window_t *NewPopUp(char *Title, Option_t *Options, unsigned
                   char TRow, unsigned char TCol, unsigned char Attrib, Border_t
                   *Border);

Returns:           A Window_t pointer to the new window if successful else NULL


NewProcess:        New Process

Include:           thread.h

Description:       Creates a new Process_t structure along with the requested
                   stack space to be allocated. If thread is NULL then the
                   process is added to the thread on the top of the
                   THREAD_STACK.

Prototype:         llnode_t *NewProcess(Thread_t *thread, void(*process)(void),
                   size_t stacksize);

Returns:           A pointer to the node in the thread's PList if successful,
                   else NULL.


NewThread:         New Thread

Include:           thread.h

Description:       Creates a new Thread_t structure and assigns initial field
                   values.

Prototype:         Thread_t *NewThread(Thread_s type);

Returns:           A pointer to the Thread_t structure created or NULL if
                   insufficient memory




                                       49





                                                             Function Prototypes


NewWindow:         New Window

Include:           screen.h

Description:       Creates a new Window_t structure.

Prototype:         Window_t *NewWindow(Wind_s Type, char *Title, unsigned char
                   TLine, unsigned char TCol, unsigned char BLine, unsigned char
                   BCol, unsigned char Attrib, Border_t *Border);

Returns:           A pointer to the new Window_t structure or NULL if an error.


OpenWindow:        Open Window

Include:           screen.h

Description:       Opens a window. Draws the window border, clears the text area
                   and makes it active. A SCREEN_W type is pushed onto the
                   SCREENSTACK, MENU_BAR_W type to the MENUSTACK

Prototype:         Window_t *OpenWindow(Window_t *window);

Returns:           The window pointer if successful, NULL indicates insufficient
                   RAM.


PCKey:             PC Key

Include:           ibmpc.h

Description:       Reads a character from the AT/normal PC keyboard setting the
                   supplied ascii and scan code parameters.

Prototype:         BOOLEAN PCKey(unsigned char *scan, unsigned char *ascii);

Returns:           TRUE if character is extended, else FALSE.


PopStack:          Pop Stack.

Include:           llist.h

Description:       Pops the top item off the stack.

Prototype:         LLDATA *PopStack(llstack_t *stack);

Returns:           A LLDATA pointer to the data item popped.


PopWindow:         Pop Window

Include:           screen.h




                                       50





                                                             Function Prototypes


Description:       Pops the given window to the top of the stack.

Prototype:         size_t PopWindow(Window_t *target);

Returns:           The length of the temporary stack used as size_t. (Should be
                   0 if no error occurred);


PosnCurs:          Position Cursor.

Include:           ibmpc.h

Description:       Positions text cursor at the specified row, col coordinates
                   using the current page.

Prototype:         void PosnCurs(unsigned char row, unsigned char col);

Returns:           NOTHING.


PullStack:         Pull Stack

Include:           llist.h

Description:       Pulls an item from anywhere off of the stack and frees the
                   associated node structure

Prototype:         llnode_t *PullStack(llstack_t *stack, llnode_t *node);

Returns:           An llnode_t pointer to the top of the stack, NULL if the
                   stack is empty.


PushStack:         Push Stack.

Include:           llist.h

Description:       Pushes an item onto the stack.

Prototype:         llnode_t *PushStack(llstack_t *stack, LLDATA *item);

Returns:           llnode_t pointer to the new node created, else NULL.


PutArea:           Put Area

Include:           ibmpc.h

Description:       Puts a previously saved screen window area to the specified
                   window coordinates.

Prototype:         unsigned int *PutArea(unsigned char TRow, unsigned char TCol,
                   unsigned char BRow, unsigned char BCol, unsigned int *store);




                                       51





                                                             Function Prototypes


Returns:           The store parameter as an unsigned int pointer.


PutAttrib:         Put Attribute

Include:           ibmpc.h

Description:       Changes the screen attributes in the specified block by
                   ANDing with mask1 and XORing with mask2. A further call to
                   this function with the same parameters therefore restores the
                   original attributes.

Prototype:         void PutAttrib(unsigned char TRow, unsigned char TCol,
                   unsigned char BRow, unsigned char BCol, unsigned mask1,
                   unsigned mask2);

Returns:           NOTHING


PutChar:           Put Character

Include:           ibmpc.h

Description:       Writes a character and its specified attribute at the current
                   cursor position.

Prototype:         void PutChar(unsigned char ch, unsigned char attrib);

Returns:           NOTHING.


PutMouse:          Put Mouse Cursor

Include:           ibmpc.h

Description:       Puts the mouse cursor at position given

Prototype:         void PutMouse(unsigned row, unsigned col);

Returns:           NOTHING


PutString:         Put String

Include:           screen.h

Description:       Puts the given string to the given window starting at the
                   window's present cursor location. If restore is TRUE then the
                   cursor is re-positioned at its original location, otherwise
                   the window's CursPosn is updated. If a date string is being
                   output then set date to TRUE in order to convert internal
                   colon separator to global character.





                                       52





                                                             Function Prototypes


Prototype:         int PutString(Window_t *window, char *buffer, BOOLEAN
                   restore, BOOLEAN date);

Returns:           The number of characters output as an int


ResCurs:           Restore Cursor.

Include:           screen.h

Description:       Restores the previously saved cursor position.

Prototype:         void ResCurs(Curs_t *cursposn);

Returns:           NOTHING.


ResVidMode:        Restore Video Mode

Include:           ibmpc.h

Description:       Restores the original video mode setting

Prototype:         void ResVidMode(void);

Returns:           NOTHING


RevScrBlock:       Reverse Screen Block

Include:           ibmpc.h

Description:       Reverses the attributes of the given screen area.

Prototype:         void RevScrBlock(unsigned char TRow, unsigned char TCol,
                   unsigned char BRow, unsigned char BCol);

Returns:           NOTHING


SaveCurs:          Save Cursor.

Include:           screen.h

Description:       Saves the cursor position in the supplied Curs_t structure.

Prototype:         void SaveCurs(Curs_t *cursposn);

Returns:           NOTHING.


SaveScreen:        Save Screen

Include:           ibmpc.h



                                       53





                                                             Function Prototypes


Description:       Saves the given screen area to memory.

Prototype:         unsigned int *SaveScreen(unsigned char TRow, unsigned char
                   TCol, unsigned char BRow, unsigned char BCol);

Returns:           An unsigned int pointer to the beginning of the allocated
                   array.


ScrollDn:          Scroll Down

Include:           screen.h

Description:       Scrolls the window down by 1 line

Prototype:         void ScrollDn(void);

Returns:           NOTHING


ScrollScreen:      Scroll Screen.

Include:           ibmpc.h

Description:       Used by Scr... and ClearScreen macros. Calls the supplied
                   interrupt number, passing the required number of lines,
                   attribute and coordinates.

Prototype:         void ScrollScreen(unsigned char interrupt, unsigned char
                   lines, unsigned char TLine, unsigned char TCol, unsigned char
                   BLine, unsigned char BCol, unsigned char Attrib);

Returns:           NOTHING.


ScrollUp:          Scroll Up

Include:           screen.h

Description:       Scrolls the window up by 1 line

Prototype:         void ScrollUp(void);

Returns:           NOTHING


SetCurs:           Set Cursor.

Include:           ibmpc.h

Description:       Sets the starting and ending lines for the blinking hardware
                   cursor in text displays.

Prototype:         SetCurs(unsigned char SLine, unsigned char ELine);



                                       54





                                                             Function Prototypes


Returns:           NOTHING.


SetMouseTCurs:     Set Mouse Text Cursor

Include:           ibmpc.h

Description:       Sets the required mouse cursor type in text mode. Two types
                   of cursor are supported, the normal hardware cursor via the
                   video controller and a software cursor. If the hardware
                   option is selected then the first and last scan lines of the
                   cursor need to be defined. This is hardware dependant. The
                   software cursor is controlled by two 16 bit values: the
                   screen mask determining which of the current attributes are
                   retained (AND function) and the cursor mask which determines
                   which characteristics are to be modified (XOR function). The
                   format for both is as follows:-
                   
                   x....... ........  Blink Bit
                   .xxx.... ........  Background Colour
                   ....x... ........  Intensity
                   .....xxx ........  Foreground Colour
                   ........ xxxxxxxx  ASCII Character Code
                   
                   The CX parameter details the screen mask or starting scan
                   line; the DX parameter the cursor mask or ending scan line.
                   Use type == 0 for a software cursor, 1 for a hardware cursor.

Prototype:         void SetMouseTCurs(int type, unsigned CX, unsigned DX);

Returns:           NOTHING


SetVidMode:        Set Video Mode

Include:           ibmpc.h

Description:       Sets the IBMPC video mode.

Prototype:         void SetVidMode(unsigned char mode);

Returns:           NOTHING


ShowDNumber:       Show Dialogue Number

Include:           dialogue.h

Description:       Shows the number as represented by the buffer in its final
                   format using the CURWINDOW and casting CURWINDOW->Contents to
                   Dialogue_t *.

Prototype:         void ShowNumber(void);




                                       55





                                                             Function Prototypes


Returns:           NOTHING


ShowGhostW:        Show Ghost Window

Include:           ibmpc.h

Description:       Puts the supplied area into video reverse.

Prototype:         void ShowGhostW(Screen_t *bounds);

Returns:           NOTHING


ShowLine:          Show Line

Include:           ibmpc.h

Description:       Reverses the video attributes in the supplied window line
                   number (0..n).

Prototype:         void ShowLine(Window_t *window, int line)

Returns:           NOTHING


ShowMouse:         Show Mouse Cursor

Include:           ibmpc.h

Description:       Displays the mouse cursor

Prototype:         void ShowMouse(void);

Returns:           NOTHING


ShowSBChar:        Show Switch Box Character

Include:           ibmpc.h

Description:       Changes the character within the switch brackets or check box
                   square brackets to the character given

Prototype:         void ShowSBChar(Window_t *window, int line, char ch);

Returns:           NOTHING


SmallCurs:         Small Cursor.

Include:           ibmpc.h

Description:       Sets blinking cursor to bottom of character area.



                                       56





                                                             Function Prototypes


Prototype:         void SmallCurs(void);

Returns:           NOTHING.


SysDay:            System Day.

Include:           ibmpc.h

Description:       Gets the system day as held by DOS.

Prototype:         int SysDay(void);

Returns:           The day number in the form of an int.


SysMonth:          System Month.

Include:           ibmpc.h

Description:       Gets the system month as held by DOS.

Prototype:         int SysMonth(void);

Returns:           The system month in the form of an integer.


SysYear:           System Year.

Include:           ibmpc.h

Description:       Gets the current system year held by DOS.

Prototype:         int SysYear(void);

Returns:           The year in the form of an int.


TransFMickeys:     Translate From Mickeys

Include:           ibmpc.h

Description:       Translates mouse mickey coordinates into screen coordinates
                   depending on the current video mode setting

Prototype:         void TransFMickeys(unsigned *dx_reg, unsigned *cx_reg);

Returns:           NOTHING


TransTMickeys:     Translate To Mickeys

Include:           ibmpc.h




                                       57





                                                             Function Prototypes


Description:       Translates the supplied screen coordinates to Mickeys.

Prototype:         void TransTMickeys(unsigned *row, unsigned *col);

Returns:           NOTHING


TStringWidth:      Title String Width

Include:           screen.h

Description:       Calculates the char length of a clean title string and sets
                   the supplied char parameter to the found hot key

Prototype:         unsigned char TStringWidth(char *string, char *hkey);

Returns:           The clean length of the supplied string as an unsigned char


ValidAttrib:       Validate Attribute

Include:           ibmpc.h

Description:       Validates the passed attribute for consistency with the
                   VIDEO_DISPLAY_ADAPTOR in use

Prototype:         unsigned char ValidAttrib(unsigned char attrib);

Returns:           The valid attrib setting as unsigned char


wprintf:           Window printf

Include:           screen.h

Description:       Window counterpart of standard library printf function. If
                   restore is TRUE then the window's cursor position is restored
                   to the original value on returning.

Prototype:         int wprintf(Window_t *window, BOOLEAN restore, char *format,
                   ...);

Returns:           The number of characters printed or -1 to indicate an error


Yield:             Yield

Include:           thread.h

Description:       Suspends the current process and passes control to the given
                   thread or (if parameter is NULL) to the next process in the
                   present thread's PList for given thread type.

Prototype:         void _pascal Yield(llnode_t *target);



                                       58





                                                             Function Prototypes


Returns:           NOTHING
























































                                       59





                                                                           Index


                                     Index


_nfree(), 2                               CursR, 38
_nmalloc(), 2                             CursRet, 38
ACKNOWLEDGEMENTS, i                       CursUp, 38
ACTIVE_MASK, 22                           CURWINDOW, 22
ACTWINDOW, 22                             CW_ICON, 23
AddButton, 15, 34                         D_BORDER, 23
AddCBox, 14                               Data Structure Packing, 3
AddDBox, 15, 34                           Date Support, 16
AddSBox, 14, 34                           DATE_SEPARATOR, 23
AddSwitch, 14                             DATETYPE, 23
AdjBounds, 34                             DateType_s, 26
Allocating Process Stacks, 3              daysin, 23
ALLOW_MENU_BAR, 17                        DecBounds, 38
ALT+letter, 13                            DecDBounds, 39
ALTER_WINDOW, 19                          DEFINITION OF SHAREWARE, i
ALTER_WINDOW_KEY, 22                      DeleteNode, 39
AppendItem, 16, 35                        DEMO.C, 19
atof(), 2                                 Dialogue Support, 15
atoi(), 2                                 Dialogue_t, 26
AUTOSCREEN REGISTRATION, iii              DISCLAIMER - AGREEMENT, i
AUTOSCREEN SUPPORT, ii                    DO_HELP_FUNCTION, 17, 23
autoscrn.hlp, 8                           DoDialogue, 39
B1inB2, 35                                DoObjects, 1, 10, 14, 39
BASIC, 2                                  DoPopUp, 40
BegLine, 35                               EndLine, 40
BestSizingPosn, 35                        Entity Life History States, 20
Border_t, 26                              EVENT, 24
Bounds, 19                                Event_s, 27
Button_t, 30                              Event_t, 9, 14, 17, 27
BUTTON_VALUE, 14                          EXIT_PROGRAM, 18
BYTEREGS, 2                               ExpBounds, 40
CANCELfunc, 14, 35                        ExtCharClass, 41
CHANGE_WINDOW, 11                         ExtClass_s, 28
CHANGE_WINDOW_KEY, 22                     fflush(), 2
Check_Box_t, 14                           FKey_s, 28
ClearLine, 36                             FlipArea, 41
ClearWindow, 36                           FORTRAN, 2, 3
ClipCode, 36                              free(), 2
CLOSE_WINDOW, 9                           getch(), 10
CLOSE_WINDOW_KEY, 22                      GetCurs, 41
CloseWindow, 11, 36                       GetEvent, 10, 17, 41
Code Buttons, 14                          GetMObj, 42
Code Pointers, 12                         GetMPosn, 42
CONTINUEfunc, 14, 37                      GetMPress, 42
Conventions, 3                            GetObject, 43
Curs_t, 26                                GetVidMode, 43
CursDn, 37                                GetWindow, 43
CursHome, 37                              GreyKey_s, 29
CursL, 37                                 HELP_FUNCTION, 10
CursOff, 37                               HELP_KEY, 10, 24
CursorType, 38                            HELP_ON, 10, 17, 24



                                       60





                                                                           Index


HELP_STACK_SIZE, 24                       PData, 19
HideMouse, 43                             PopStack, 50
HOST_SCREEN, 24                           PopWindow, 11, 50
IncBounds, 43                             PosnCurs, 51
IncDBounds, 44                            PullStack, 51
InitMouse, 44                             PushStack, 51
InitUI, 17, 44                            PutArea, 51
InsertOn, 44                              PutAttrib, 52
int86(), 2                                PutChar, 52
IsAbove, 44                               PutMouse, 52
IsBelow, 45                               PutString, 52
kbhit(), 2                                QUIT_PROGRAM, 17, 18, 25
KBStatus, 45                              Register_t, 30
KillAllWindows, 45                        REGS, 2
KillWindow, 11, 46                        REGSIZE, 30
LabelWindow, 46                           ResCurs, 53
LargeCurs, 46                             ResVidMode, 53
LaunchThread, 17, 46                      RetValue, 14, 18
LeaveUI, 17, 46                           RevScrBlock, 53
LLDATA, 29                                S_BORDER, 25
llist_t, 29                               SaveCurs, 53
llnode_t, 29                              SaveScreen, 53
llstack_t, 29                             scanf(), 10
MAINTHREAD, 17, 24                        SCREEN_MASK, 25
MAINTHREAD->CurProc, 19                   Screen_t, 31
MakeCirc, 47                              SCREEN_W, 9, 11
MakeLinear, 47                            ScrollDn, 54
malloc(), 2                               ScrollScreen, 54
Memory Model - Defining The, 4            ScrollUp, 54
Menu Options, 1                           Segment Set Up, 2
MENU_BAR_W, 9, 11                         SetCurs, 54
Menu_t, 11, 13, 30                        SetMouseTCurs, 55
Menus, 12                                 SetVidMode, 55
MinBounds, 19                             SHIFT+ALT+letter, 11
MOUSE_SUPPORTED, 24                       ShowDNumber, 55
NameWindow, 47                            ShowGhostW, 56
NEW_PROCESS, 17                           ShowLine, 56
NewDialogue, 15, 47                       ShowMouse, 56
NewList, 48                               ShowSBChar, 56
NewMenuBar, 9, 11, 17, 48                 SmallCurs, 56
NewNode, 49                               Stack Sizes, 20
NewPopUp, 49                              StackSize, 17
NewProcess, 17, 49                        Standard Library Calls, 2
NewThread, 17, 49                         STRING_D, 15
NewWindow, 11, 50                         strlen(), 2
NULL, 13                                  SW_BUTTON, 25
OFF, 13                                   Switch_t, 14, 31
OMBUDSMAN STATEMENT, ii                   Switches, 13
ON, 13                                    SysDay, 57
OpenWindow, 11, 17, 50                    SysMonth, 57
Option_t, 12, 18, 30                      System Events, 9
OTHER MEMORY MODELS, iii                  SysYear, 57
Pascal, 2, 3                              Table Of Contents, iv
PCKey, 50                                 TABSTOPS, 25



                                       61





                                                                           Index


TgtProcess, 17
The `@' And `.' Characters, 13
Thread demos, 20
Thread_s, 31
Thread_t, 32
Threads, 3
TransFMickeys, 57
TransTMickeys, 57
TStringWidth, 58
Unnamed Types, 3
ValidAttrib, 58
vsprintf(), 2
Wind_s, 32
Window, 9
Window_t, 11, 17, 32
WObj_s, 33
WORDREGS, 2
wprintf, 19, 58
Yield, 11, 20, 58






































                                       62
