
                                 AUTOSCREEN
				Version 1.20



The AUTOSCREEN system is a portable C based Library that provides a powerful
  multithreaded user interface to application programs transparently. The
  product is supplied on two separate 360K DS/DD floppy disks in a sealed
                     packet at the end of this manual.
                                      
                                 ATTENTION!
                                      
By opening the product's packet you signify that you have read and accepted
 the terms contained in the License Agreement on page (i) of this document.
      Please do not open the envelope until you have read these terms.
                                      
  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 and pull-down menus; accelerator keys, check boxes, switches and
 code buttons. 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).

  This software product is copyrighted and all rights are reserved by its
  author Edward James Pugh. The distribution of the small C memory model
  shareware product is intended for demonstration and testing purposes
  only and to be run on an IBM PC, XT/AT or 100% compatible. A license to
  use the product in program production may be obtained by registering
  with the author for a fee of just 15.00. In return, the enduser will
  receive the C medium, compact and large memory models; the low-level
  source code for the IBM PC plus the Pascal and BASIC medium and
  large memory model libraries. Unregistered users are hereby granted a
  period of four weeks from the date of receiving the product in which to
  test its functionality and decide whether it meets their requirements.
  At the end of that time the software must be registered with the author,
  passed to another interested party or completely destroyed along with
  any accompanying documentation. Bona fide shareware distributors
  obtaining this product may undertake its distribution provided the
  following conditions are met:-
  
  1. That the complete product only is distributed, unaltered and
  unmodified in any way.
  
  2. That any fee charged to the enduser does not exceed 5.00 Sterling.
  This fee to include all costs incurred by the distributor and VAT or
  sales tax where appropriate.
  
  A distributor's license may be obtained free of charge from the author
  by writing to the following address and enclosing a stamped addressed
  envelope:-
  
  Trident Software, 337 Church Road, Thundersley, Benfleet, Essex SS7 3HJ,
  England.
  
  Copying, duplicating, selling or otherwise distributing this product, in
  whole or in part, is hereby expressly forbidden.
  
  Copyright (C) 1989-92, Edward James Pugh. All Rights Reserved.
  
  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.















                                     i

                           AUTOSCREEN Version 1.2


                             Table Of Contents


Introduction...............................................2
    Compiler Support.......................................2
    Conventions............................................4
    Points To Note.........................................4

Installing The Libraries...................................6

Using The Demo.............................................7

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..........................................21

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

Function Prototypes.......................................35

Index.....................................................62












                                     ii

                                                                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.







                                     2

                                                            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 fields in the correct order. AUTOSCREEN assumes system




                                     3

                                                            Compiler Support


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.




                                     4

                                                              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.
















































                                     5

                                                    Installing The Libraries


                          Installing The Libraries


     The product is supplied on one 360K DS/DD floppy disk which contains
the system header files, small memory model library and Microsoft compatible
.HLP file. The disk also contains a test stub for the user's assistance in
reviewing the product along with its compiled code in the form of DEMO.EXE.
     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.












































                                     6

                                                              Using The Demo


                               Using The Demo


     With DEMO.EXE in your default directory, type: demo 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).
     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. Whilst 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 whilst
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.
     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.




                                     11

                                                 Creating AUTOSCREEN Objects


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}};

     void MyQuit(void)
     {
     QUIT_PROGRAM = TRUE;
     }



                                     12

                                                 Creating AUTOSCREEN Objects


     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}};

     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




                                     13

                                                 Creating AUTOSCREEN Objects


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
whilst 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.


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.




                                     14

                                                 Creating AUTOSCREEN Objects


     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 whilst inputting a long Journal Entry is one
example of just such a situation.
     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.







                                     15

                                                                 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();
     }






                                     16

                                                                 Guide-Lines


     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().
     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.
     When coding interactive processes you should adhere to the following
six principals:-



                                     17

                                                                 Guide-Lines


     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 version of AUTOSCREEN does
not yet support - in fact anything that might prove useful in the particular
system you are developing.

                      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



                                     18

                                             Extended Process Thread Support


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 DEMO.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 another key is pressed.


















                                     19

                                                            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.











                                     20

                                                            Global Variables


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.


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 };






                                     21

                                                            Global Variables


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.


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;







                                     22

                                                            Global Variables


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.






















































                                     23

                                                            Global Variables


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

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.









                                     24

                                                            Global Variables


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.























                                     26

                                                             Data Structures


Dialogue_t:        Dialogue Type

Include:           dialogue.h

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
                   #if !defined(SHAREWARE)
                   , DO_DIALOGUE
                   #endif
                   }Event_s;





                                     27

                                                             Data Structures


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

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.









                                     28

                                                             Data Structures


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

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.








                                     29

                                                             Data Structures


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;

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.





                                     30

                                                             Data Structures


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

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.


















                                     31

                                                             Data Structures


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;

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.







                                     32

                                                             Data Structures


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

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.











                                     33

                                                         Function Prototypes


WObj_s:            Window Object Set

Include:           screen.h

Declaration:       typedef enum{ EMPTY = 1, MENU_TITLE, POP_UP_LIST,
                   CODE_BUTTON, SWITCH, CHECK_BOX #if !defined(SHAREWARE) ,
                   STRING_D, INT_D, NUMBER_D, DATE_D, #endif }WObj_s;

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















































                                     34

                                                         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













                                     35

                                                         Function Prototypes


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);

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












                                     36

                                                         Function Prototypes


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

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.









                                     37

                                                         Function Prototypes


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

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.





                                     38

                                                         Function Prototypes


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.

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);



                                     39

                                                         Function Prototypes


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.


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











                                     40

                                                         Function Prototypes


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

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.













                                     41

                                                         Function Prototypes


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).

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);




                                     42

                                                         Function Prototypes


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

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.







                                     43

                                                         Function Prototypes


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


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









                                     44

                                                         Function Prototypes


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

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);



                                     45

                                                         Function Prototypes


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);

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);






                                     46

                                                         Function Prototypes


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

Description:       Frees all memory used by window structures.

Prototype:         void KillAllWindows(void);

Returns:           NOTHING








                                     47

                                                         Function Prototypes


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);

Returns:           NOTHING








                                     48

                                                         Function Prototypes


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.








                                     49

                                                         Function Prototypes


NewDialogue:       New Dialogue

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.














                                     50

                                                         Function Prototypes


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


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);






                                     51

                                                         Function Prototypes


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


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);



                                     52

                                                         Function Prototypes


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

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



                                     53

                                                         Function Prototypes


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);

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



                                     54

                                                         Function Prototypes


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.

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);





                                     55

                                                         Function Prototypes


Returns:           NOTHING
























































                                     56

                                                         Function Prototypes


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

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.








                                     57

                                                         Function Prototypes


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);

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




                                     58

                                                         Function Prototypes


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);

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












                                     59

                                                         Function Prototypes


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.

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);





                                     60

                                                         Function Prototypes


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

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









                                     61

                                                         Function Prototypes


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);

Returns:           NOTHING


















                                     62

                                                                       Index


                                   Index


_nfree(), 3                             CONTINUEfunc(), 14
_nmalloc(), 3                           conventions, 4
ACTIVE_MASK, 21                         current system date, 16
ACTWINDOW, 21                           Curs_t, 26
AddButton, 35                           CursDn, 38
AddButton(), 14                         CursHome, 39
AddCBox(), 14                           CursL, 39
AddDBox, 35                             CursOff, 39
AddDBox(), 15                           CursorType, 39
AddSBox, 35                             CursR, 39
AddSBox(), 14                           CursRet, 40
AddSwitch() macro, 14                   CursUp, 40
AdjBounds, 36                           CURWINDOW, 22
allocating process stacks, 4            custom acceptance routine, 15
ALLOW_MENU_BAR, 17                      CW_ICON, 22
ALT+letter, 13                          D_BORDER, 22
ALTER_WINDOW, 19                        data structure packing, 4
ALTER_WINDOW_KEY, 21                    Date input, 15
AppendItem, 36                          DATE_SEPARATOR, 22
AppendItem(), 15                        DATETYPE, 22
atof(), 3                               DateType_s, 26
atoi(), 3                               daysin, 22
autoscrn.hlp, 8                         DecBounds, 40
B1inB2, 36                              DecDBounds, 40
Background text, 19                     DeleteNode, 41
BASIC, 2                                DEMO.C, 19
BegLine, 36                             dialogue support, 15
BestSizingPosn, 37                      Dialogue_t, 27
Border_t, 26                            DO_HELP_FUNCTION, 17, 23
Bounds, 19                              DoDialogue, 41
Button_t, 30                            DoObjects, 41
BUTTON_VALUE, 14                        DoObjects(), 2, 10, 14
BYTEREGS, 3                             DoPopUp, 42
CANCELfunc, 37                          EndLine, 42
CANCELfunc(), 14                        Entity Life History States, 20
CHANGE_WINDOW, 11                       EVENT, 23
CHANGE_WINDOW_KEY, 21                   Event_s, 27
Check boxes, 14                         Event_t, 9, 14, 17, 28
Check_Box_t, 14                         EXIT_PROGRAM, 18
ClearLine, 37                           ExpBounds, 42
ClearWindow, 37                         ExtCharClass, 42
ClipCode, 38                            ExtClass_s, 28
CLOSE_WINDOW, 9                         fflush(), 3
CLOSE_WINDOW_KEY, 21                    FKey_s, 29
CloseWindow, 38                         FlipArea, 43
CloseWindow(), 11                       FORTRAN, 2, 4
code button, 14                         free(), 3
Code buttons, 14                        getch(), 10
code pointer, 12                        GetCurs, 43
coding interactive processes, 19        GetEvent, 17, 43
CONTINUEfunc, 38                        GetEvent(), 10



                                     63

                                                                       Index


GetMObj, 44                             NEW_PROCESS, 17
GetMPosn, 44                            NewDialogue, 50
GetMPress, 44                           NewDialogue(), 15
GetObject, 44                           NewList, 50
GetVidMode, 45                          NewMenuBar, 17, 51
GetWindow, 45                           NewMenuBar(), 9, 11
GreyKey_s, 29                           NewNode, 51
HELP_FUNCTION, 10                       NewPopUp, 51
HELP_KEY, 10, 23                        NewProcess, 17, 51
HELP_ON, 10, 23                         NewThread, 17, 52
HELP_ON = TRUE, 17                      NewWindow, 52
HELP_STACK_SIZE, 23                     NewWindow(), 11
HideMouse, 45                           NEXT type thread, 20
HOST_SCREEN, 23                         NULL, 13
IncBounds, 45                           number and date expression
IncDBounds, 45                              evaluator, 16
InitMouse, 46                           OFF, 13
InitUI, 46                              ON, 13
InitUI(-1), 17                          OpenWindow, 17, 52
InsertOn, 46                            OpenWindow(), 11
int86(), 3                              Option_t, 12, 18, 30
IsAbove, 46                             Pascal, 2, 4
IsBelow, 47                             PCKey, 52
kbhit(), 3                              PData field, 19
KBStatus, 47                            PopStack, 53
KillAllWindows, 47                      PopWindow, 53
KillWindow, 48                          PopWindow(), 11
KillWindow(), 11                        PosnCurs, 53
LabelWindow, 48                         PREV type thread, 20
LargeCurs, 48                           process IDs, 19
LaunchThread, 17, 48                    processes, 18
LeaveUI, 49                             public variables, 10
LeaveUI(), 17                           PullStack, 53
LLDATA, 29                              PushStack, 53
llist_t, 29                             PutArea, 54
llnode_t, 30                            PutAttrib, 54
llstack_t, 30                           PutChar, 54
lone separator, 16                      PutMouse, 54
main() function, 17                     PutString, 55
MAINTHREAD, 17, 24                      QUIT_PROGRAM, 17, 18, 24
MAINTHREAD->CurProc, 19                 Register_t, 31
MakeCirc, 49                            REGS, 3
MakeLinear, 49                          REGSIZE, 31
malloc(), 3                             ResCurs, 55
maximum stack size, 20                  ResVidMode, 55
memory model, defining the, 5           RetValue, 14, 18
menu options, 2                         RevScrBlock, 55
MENU_BAR_W, 9, 11                       S_BORDER, 24
Menu_t, 11, 12, 30                      SaveCurs, 56
menus, 12                               SaveScreen, 56
MinBounds, 19                           scanf(), 10
MOUSE_SUPPORTED, 24                     SCREEN_MASK, 24
NameWindow, 49                          Screen_t, 31
national date formats, 15               SCREEN_W, 9, 11



                                     64

                                                                       Index


ScrollDn, 56                            Yield(), 11, 20
ScrollScreen, 56
ScrollUp, 57
segment set up, 3
SetCurs, 57
SetMouseTCurs, 57
SetVidMode, 58
SHIFT+ALT+letter, 11
ShowDNumber, 58
ShowGhostW, 58
ShowLine, 58
ShowMouse, 59
ShowSBChar, 59
SmallCurs, 59
stack, 18
stack allocations, 20
StackSize, 17
standard library calls, 3
State field, 18
STRING_D type, 15
strlen(), 3
SW_BUTTON, 25
Switch_t, 13, 32
Switches, 13
SysDay, 59
SysMonth, 59
system event, 9
SysYear, 60
Table Of Contents, ii
TABSTOPS, 25
TgtProcess, 17
the '@' character, 13
the single '.' character, 13
Thread demos, 20
Thread_s, 32
Thread_t, 32
threads, 4
TransFMickeys, 60
TransTMickeys, 60
TStringWidth, 60
unnamed struct and union types, 3
ValidAttrib, 61
variable = value, 14
variable |= value, 14
vsprintf(), 3
Wind_s, 33
window, 9
WINDOW thread type, 20
Window_t, 11, 17, 33
WObj_s, 34
WORDREGS, 3
wprintf, 61
wprintf(), 19
Yield, 61



                                     65
