Text Mode User Interface Toolkit


Getting started Guide


Release 1.07

Copyright (c) 1991-93 Trumphurst Ltd.



Trumphurst Ltd.
The Willows
St. Martins Moor
Oswestry
Shropshire
SY10 7BH
England
Tel: (+44) 0691-670318
Fax: (+44) 0691-670316
Mail: [email protected]

Installation

The toolkit is provided as ZIPped archives, as follows ...

DOSUITnn.ZIP Library source and makefiles for Zortech C++ (3.0r4)
UITBORnn.ZIP Extra Borland C++ files


Getting started

Four makefiles are supplied ...

makefile Runs the other makefiles in the correct order.
makeuit Makes the documentation program, and the test program.
makelib Makes the libraries.
makeexam Makes the example programs.

Note that the ZTC flags used are -g -mli -bx. You may well have trouble
compiling the examples with a non DOS-extended version of the compiler,
particularly if you retain the -g switch. Feedback from beta testers will
be incorporated here as it is correlated.

The default make will create libraries with assertion, debugging, and
inspecting turned ON. To turn off the inspector, include "-DNINSPECT" in
CFLAGS in the makelib file. To turn off debugging and assertions, include
"-DNDEBUG" in CFLAGS.

For those studying the source, and the makelib file, I should explain
that much effort has been expended in making library modules small, so
that unwanted code is not linked into the executable. To achieve this,
#defines are used to split up each source file into separately compiled
sections, and these are defined in the compiler command line, to give
multiple .OBJ files for each source file. The sources can be compiled
conventionally (e.g. for testing and debugging) by giving the switch "-
DALL" in the compiler command line.

Library documentation

All the library documentation is included in the header files. A new tool,
DocClass, is provided to extract the documentation into a useful, cross-
referenced form. DocClass is a standalone program, which may be compiled
with any C++ compiler. It should be run on all the header files at once
"docclass *.hpp >dosuit.doc".

Inspecting and debugging

The toolkit has a built-in Inspect function. Just place the mouse cursor
anywhere in an object on the screen in a running application, and hold
the Alt key down while clicking on the left mouse button. An inspector
dialog will appear, detailing the values of the internal variables in the
object. This inspect function is easily extended to new types of object
by overriding the inspectinfo virtual method for the object. The
inspector will also allow viewing of the state of the container of the
current VObject, and its container, right up through the hierarchy to the
Application object.

The toolkit also has a built-in debugging function - a static FILE
variable in the VObject class contains a file handle. If VObject::debug
is set to the handle of an fopened file, debugging information will be
output to the file whenever internal state changes occur within VObjects.
This file can be useful in determining what processing is going on as
objects are moved and resized by the automatic layout facilities in the
toolkit, and as input events occur.

Notes for Borland C++ users

Libraries should be installed in your Borland C++ directory. Separate
makefiles are provided for Borland C++. These have the extension "BCC" (i.
e. MAKEFILE.BCC, and MAKELIB.BCC). Version 2.0 of BC++ has a bug which
prevents parts of the toolkit working correctly. You should have at least
BC++ V3.00 (the compiler I used to test the port) to proceed. Obviously,
you should extract the Borland versions of the libraries (UITBB?nn.ZIP),
rather than the Zortech ones.

Notes for users of earlier versions of the toolkit.

In line with my expanding knowledge and understanding of C++, the toolkit
is gradually becoming more object oriented, as well as being extended to
provide additional functionality. The changes below are shown most recent
first.

Release 1.07

Some minor modifications made to enable the toolkit to compile and run
without error under Borland C++ 3.1.

Also the .SRC files (which were missing) are now included in the
distribution.

Release 1.06

The automatic documentation utility, DocClass, is now included. This
generates the full library documentation from the header files.

Release 1.05

There have been many minor bug fixes. The ListElement class is no longer
derived from VObject, thus saving lots of memory. A new type of generic
Collection, LCollection, is therefore available to hold ListElements.

Standard Command and Option function calls now take a const char *
parameter (the name of the invoking VObject), rather than a pointer to a
VObject.

TextEdit objects now have an optional const char * parameter representing
a list of valid characters which may be accepted into the edit. This
makes it easy to create specialised TextEdits without having to derive a
new class for each one. The CRestore return value from the complete
function has been removed. togg toggled on and off by selecting the
option.

The memory protection class Protected now has facilities for dumping a
stack trace as well as a list of all Protected objects allocated.

Release 1.04

Most variable argument lists have been removed, as they are not type safe.
Wherever a constructor or method expected a variable argument list, a new
one has been provided which takes a Collection. Together with the new
addition operators for Collections, this provides type- safe argument
list passing.

EditControl classes have been modified to provide a cleaner class
hierarchy - all EditControls now have a virtual method which returns a
pointer to the VObject which inherits from that particular EditControl.
Thus Collections of EditControls can be copied into Collections of
VObjects. This has enabled EditControlList to be defined as inheriting
from EditControl and GCollection(EditControl). EditCluster has been
redefined with this in mind, and it can now lay out any kind of
EditControl (not just TextEdits). Two similar layout classes
(EditHCluster and EditVCluster) provide layout for EditControls which
don't need separate prompts.

New classes ControlledButton and ButtonController provide a much improved
method of deriving such things as RadioButtons. Most of the behaviour of
groups of RadioButtons is now implemented in OneButtonController (derived
from ButtonController). This makes this area of the toolkit much easier
to extend with your own classes.

Release 1.03

New Command class introduced, providing type-safe function call despatch
to arbitrary classes. This enabled the UserEvent class to be eliminated
entirely.

Release 1.02

The Event handling has been extensively re-written to remove switch
statements, and make Event despatch more extensible.