File: refmanual.html

package info (click to toggle)
libtexttools 2.1.0-30
links: PTS, VCS
area: main
in suites: sid, trixie
size: 932 kB
sloc: ada: 11,394; ansic: 529; makefile: 106; sed: 78; sh: 12
file content (2676 lines) | stat: -rw-r--r-- 92,281 bytes
parent folder | download | duplicates (10)
<html>
<head>
<title>TextTools Reference Manual</title>
</head>
<body bgcolor="#FFF0F0">
<h2>TextTools 2.0</h2>

Copyright (c) 1999-2003 PegaSoft Canada.<br>
Designed and Programmed by Ken O. Burtch<br>
Home Page: http://www.pegasoft.ca/tt.html<br>

<p>The Texttools packages are a GPL, ncurses-based library for the Linux
console.  Texttools contain more than 600 procedures and functions to
create windows, draw scroll bars, handle the mouse and keyboard events,
play sounds, and much more.  The Texttools package also provides a
thick binding to Linux kernel calls.  You can create a wide
variety of application programs using Texttools alone.

<p>TextTools is written in Ada 95 and C.  You'll need to download the
Gnat compiler to build TextTools.  You can write programs in Ada or C++
when you use TextTools.

<p><i>Note: C++ support is not fully implemented in this version of TextTools</i>
<h3>The Common Package</h3>

<h4>Housekeeping</h4>

<pre>
StartupCommon (startup_common)
  Initialize the common package.  The names are strings with a maximum of
  255 characters.
  Ada: StartupCommon( long_name, short_name );
  C++: startup_common( long_name, short_name );

IdleCommon (idle_commom)
  Perform idle-time tasks (if any).

ShutdownCommon (shutdown_common)
  Shut down the common package.
</pre>

<h4>Global variables</h4>

<pre>
IsFinder (is_finder)
  Reserved for future use.  False if this is a Texttools server.  Currently
  always true.

ProgramName (Ada only)
  The program name specified in StartupCommon.

ShortProgramName (Ada only)
  The short program name specified in StartupCommon.
</pre>

<h4>Error Codes</h4>

<p>There is a global LastError (or last_error in C++) variable which is
set to a non-zero value if an error occurred during the last TextTools
function.  These error codes are the same no matter what operating
system you are using.

<p>The exception is the common package functions.  These are considered
so primitive that they never return an error.

<p>If you have a directory in your home directory with the same name as
the "short name" in StartupCommon, errors will be saved in a file
called "session_log".

<h5>General Errors</h5>

<table border="1">
<tr><td><b>Ada Name</b></td><td><b>C++ Name</b></td><td><b>Explaination</b></td></tr>

<tr><td>TT_NotYetImplemented</td><td>TT_not_yet_implemented   </td><td>routine doesn't exist</td></tr>
<tr><td>TT_OK                </td><td>TT_ok                    </td><td>success (value of 0)</td></tr>
<tr><td>TT_MemoryLeak        </td><td>TT_memory_leak           </td><td>memory leak detected</td></tr>
<tr><td>TT_LowMemory         </td><td>TT_low_memory            </td><td>low / out of memory</td></tr>
<tr><td>TT_TestData          </td><td>TT_test_data             </td><td>test data in operation</td></tr>
</table>

<h5>Operating System Errors</h5>

<table border="1">
<tr><td><b>Ada Name</b>             </td><td><b>C++ Name</b>                 </td><td><b>Explaination</b></td></tr>
</td></tr>
<tr><td>   TT_SystemError       </td><td>TT_system_error          </td><td>O/S command failed</td></tr>
<tr><td>   TT_ParamError        </td><td>TT_param_error           </td><td>param too long</td></tr>
<tr><td>   TT_FileExistance     </td><td>TT_file_existance        </td><td>file found/not found</td></tr>
<tr><td>   TT_PathExistance     </td><td>TT_path_existance        </td><td>path found/not found</td></tr>
<tr><td>   TT_VolExistance      </td><td>TT_vol_existance         </td><td>disk volume found/not found</td></tr>
<tr><td>   TT_DevExistance      </td><td>TT_dev_existance         </td><td>device found/not found</td></tr>
<tr><td>   TT_FileStatus        </td><td>TT_file_status           </td><td>file open/not open</td></tr>
<tr><td>   TT_FileLocking       </td><td>TT_file_locking          </td><td>file locked/unlocked</td></tr>
<tr><td>   TT_FileAccess        </td><td>TT_file_access           </td><td>file is un/accessible</td></tr>
<tr><td>   TT_VolLocking        </td><td>TT_vol_locking           </td><td>disk volume is (not) readonly</td></tr>
<tr><td>   TT_VolAccess         </td><td>TT_vol_access            </td><td>disk volume is un/accessible</td></tr>
<tr><td>   TT_VolFull           </td><td>TT_vol_full              </td><td>disk volume is full</td></tr>
<tr><td>   TT_DevSequential     </td><td>TT_dev_sequential        </td><td>tape device (un)expected</td></tr>
<tr><td>   TT_IOError           </td><td>TT_io_error              </td><td>hardware or media error</td></tr>
<tr><td>   TT_PathError         </td><td>TT_path_error            </td><td>bad path or file sys</td></tr>
<tr><td>   TT_FileBounds        </td><td>TT_file_bounds           </td><td>file position out of bounds</td></tr>
<tr><td>   TT_OSOld             </td><td>TT_os_old                </td><td>O/S too old to support</td></tr>
<tr><td>  TT_OSService         </td><td>TT_os_service            </td><td>O/S service missing</td></tr>
<tr><td>   TT_Integrity         </td><td>TT_integrity             </td><td>O/S integrity is bad</td></tr>
</table>

<h5>Window Errors</h5>

<table border="1">
<tr><td><b>Ada Name</b>             </td><td><b>C++ Name</b>                 </td><td><b>Explaination</b></td></tr>

<tr><td>   TT_WindowExistance   </td><td>TT_window_existance      </td><td>window found/not found</td></tr>
<tr><td>   TT_NoControls        </td><td>TT_no_controls           </td><td>no controls in the window</td></tr>
<tr><td>   TT_ControlExistance  </td><td>TT_control_existance     </td><td>control found/not found</td></tr>
<tr><td>   TT_NoDialogTaskCB    </td><td>TT_no_dialog_task_cb     </td><td>no manual handler installed</td></tr>
</table>

<h4>Using the Error Functions</h4>

<p>You can use error handling functions in the common package for your
own applications.

<pre>
NoError (no_error)
   Clear the error variable.  Usually, this is the first call in any
   TextTools function.
   Ada: NoError;
   C++: no_error(); [ Doesn't work ]

Error (error)
   Report an error with one of the TextTools error codes.
   Ada: Error( TT_SomeErrorCode );
   C++: error( TT_some_error_code ); [ Doesn't work ]

RaisingErrors (Ada only)
   Raise a GeneralError exception when an error is reported using Error.
   Ada: RaisingErrors;

TrapErrors (Ada only)
   Don't raise a GeneralError exception when an error is reported using
   Error.
   Ada: TrapErrors;

RaiseErrors (Ada only)
   Return true if an error will raise an GeneralError exception.
   Ada: bool := RaiseErrors;

TrapErrors (Ada only)
   Return true if an error will not raise an GeneralError exception.
   Ada: bool := TrapErrors;

RestoreRaising (Ada only)
   Restore the old value of RaisingErrors/TrapErrors.
   Ada: RestoreRaising ( RaiseErrorsValue );
</pre>
 
<h3>Standard String Functions</h3>

<p>These are an Ada-only feature.  The common package contains an
instantiated version of 255 character bounded strings.  There are also
ToInteger and ToLongInteger functions defined.


<h4>String Lists</h4>

<p>Some TextTools functions use a list of strings.  Strings are declared in
the common/str255list package.  (In C++, the str255list functions are included
in common.h.)  List of strings are used for window controls containing
multiple lines of text, including editable text boxes and lists of check
boxes.

<p>The generic package (template) on which the strings list is based is in the
file gen_list.adb.

<p>If you're using C++, make sure you assign string list variables a null value
before using them.

<pre>str255list_list sl = str255list_null;</pre>


<h4>Memory Leak Detection</h4>

<p>The string lists have simple memory leak detection functions.  GetAllocation
will report the amount of memory allocated by all string lists.  The memory
leak function will check to see if the amount of memory has changed.

<p>For example, use GetAllocation when your program starts and there are no lists.
Use MemoryLeak when your program completes execution and all string lists
should be cleared and empty.  If there are any string lists that contain
items, MemoryLeak will be true.

<pre>
GetAllocation (str255list_get_allocation)
  Return the amount of memory allocated in the list.
  Ada: Str255List.GetAllocation( bytes );
  C++: str255list_get_allocation( &bytes );
  Errors: none

MemoryLeak (str255list_memory_leak)
  True if there is a the difference in memory compared to the amount returned
by GetAllocation.
  Ada: b := Str255List.MemoryLeak( bytes );
  C++: b = str255list_memory_leak( bytes );
  Errors: none
</pre>

<h4>List Operations</h4>

<p>Here are some list operations that affect on or more entire lists, including
clearing, copying and swapping lists.

<pre>
Compact (str255list_compact)
  Deallocate all non-essential memory (for example, by discarding cache items).
This potentially reduces performance but also reduces memory use.
  Ada: Str255List.Compact( list );
  C++: str255list_compact( &list );
  Errors: none

Clear (str255list_clear)
  Discard an entire list.
  Ada: Str255List.Clear( list );
  C++: str255list_clear( &list );
  Errors: none

Copy (str255list_copy/copy2)
  Create one or two duplicate copies of a list.
  Ada: Str255List.Copy( FromList, ToList ); or
       Str255List.Copy( FromList, ToList1, ToList2 );
  C++: str255list_copy( &FromList, &ToList ); or
       str255list_copy2( &FromList, &ToList1, &ToList2 );
  Errors: Ada STORAGE_ERROR exception if out of memory

Move (str255list_move)
  Copy one list to another.
  Ada: Str255List.Move( FromList, ToList );
  C++: str255list_move( &FromList, &ToList );
  Errors: Ada STORAGE_ERROR exception if out of memory

Swap (str255list_swap)
  Swap one list for another.
  Ada: Str255List.Swap( List1, List2 );
  C++: str255list_swap( &List1, &List2 );
  Errors: none

Is_Empty (str255list_is_empty)
  True if the list is empty (has no items).
  Ada: b := Str255List.IsEmpty( TheList );
  C++: b = str255list_is_empty( &TheList );
  Errors: none

Length (str255list_length)
  Returns the number of items in the list.
  Ada: n := Str255List.Length( TheList );
  C++: n = str255list_length( &TheList );
  Errors: none

Concat (str255list_concat)
  Append one list to another returning the new list.
  Ada: Str255List.Concat( List1, List2, NewList );
  C++: str255list_concat( &list1, &list2, &new_list);
  Errors: Ada STORAGE_ERROR exception if out of memory
</pre>  

<h4>Working with String List Items</h4>

<p>This section lists the string list functions for adding or removing
individual items from a string list.

<pre>
Push (str255list_push)
  Add an item to the top of the list as if the list was a stack.
  Ada: Str255List.Push( TheList, str255 );
  C++: str255list_push( &TheList, str255 );
  Errors: Ada STORAGE_ERROR exception if out of memory

Queue (str255list_queue)
  Add an item to the bottom of the list as if the list was a queue.
  Ada: Str255List.Queue( TheList, str255 );
  C++: str255list_queue( &TheList, str255 );
  Errors: Ada STORAGE_ERROR exception if out of memory

Insert (str255list_insert/2)
  Add an item sorted alphabetically to the list, or at a specific position.
  Ada: Str255List.Insert( TheList, str255 ); or
       Str255List.Insert( TheList, index, str255 );
  C++: str255list_insert( &TheList, str255 ); or
       str255list_insert2( &TheList, index, str255 );
  Errors: Ada STORAGE_ERROR exception if out of memory

Pull (str255list_pull/discard)
  Remove a item from the top of the list and return it (if desired).
  Ada: Str255List.Pull; or
       Str255List.Pull( TheList, str255 );
  C++: str255list_discard(); or
       str255list_pull( &TheList, &str255 );
  Errors: none

Cut (str255list_cut)
  Remove an item from an index in the list and return it.
  Ada: Str255List.Cut( TheList, index, str255 );
  C++: str255list_cut( &TheList, index, &str255 );
  Errors: none

Clear (str255list_clear_item)
  Remove an item from a particular list position without returning it.
  Ada: Str255List.Clear( TheList, Index );
  C++: str255list_clear_item( &TheList, index );
  Errors: none
</pre>

<h4>Search and Replace Operations</h4>

<pre>
Find (str255list_find/lookup)
  Locate an item in the list and return the position (or look up a position
and return the item).  The Ada version of position lookup has a default
starting index of 1. If the item is not found, the position will be zero.
  Ada: Str255List.Find( TheList, Index, Item ); or
       Str255List.Find( TheList, Item, StartIndex, Index );
  C++: str255list_find( &TheList, Index, &Item ); or
       str255list_lookup( &TheList, startindex, &item, &index );
  Errors: none

Replace (str255list_replace)
  Replace one item with a new item.
  Ada: Str255List.Replace( TheList, index, item );
  C++: str255list_replace( &TheList, index, &item );
  Errors: none
</pre>

<p>Sublists are new lists created by removing a set of items from another list.  There are two subprograms for creating and working with sublists.

<pre>
Sublist (str255list_sublist)
  Copy a set of items and create a new list.  The items are not removed from
the original list.
  Ada: Str255List.Sublist( TheList, startindex, len, Sublist );
  C++: str255list_sublist( &TheList, startindex, len, &Sublist );
  Errors: Ada STORAGE_ERROR exception if out of memory
</pre>

<h4>Standard Math Functions</h4>

<p>These are mostly obsolete.

<pre>
RND (CRnd)
  Generate a uniformally distributed random number between 1 and a limit.
  Ada: num := RND( limit );
  C++: num = Crnd( limit );

NormalRND (Cnormalrnd)
  Generate a normal (Gaussian) distributed random number between 1 and a limit.
  Ada: num := NormalRND( limit );
  C++: num = Cnormalrnd( limit );

Odds (Coods)
  Randomly true based on the indicated percent.
  Ada: bool := Odds( percent );
  C++: bool = odds( percent );

SetRNDSeed (Csetrndseed)
  Set a random number seed.
  Ada: SetRNDSeed( seed );
  C++: Csetrndseed( seed );
</pre>

<h4>Working with Rectangles</h4>

<p>Texttools uses many rectangles.  Windows are rectangular.  OK buttons are
surrounded by invisible bounding rectangles.

<p>A recntangle is described by the coordinates of its sides: the left side,
the top side, the right side and the bottom side.  The upper-left corner
of a rectangle is (left, top) and the bottom-right corner is (right, bottom).

<p>For example, a rectangle drawn from (5, 10) to (15, 20) has a left side
at 5, a top side at 10, a right side at 15 and a bottom side at 20.

<p>Rectangles have their own record structure.

<p>In C++, a rectangle is

<pre>
struct a_rect {
   int left;
   int top;
   int right;
   int bottom;
}
</pre>

<p>In Ada, a rectangle is

<pre>
type aRect is record
   left, top, right, bottom : integer;
end record;
</pre>

<p>There is one predefined rectangle, nullRect (or null_rect) that
represents an empty rectangle (the sides are 0, 0, -1 and -1).

<p>There is not data structure for a single point.  A 2-D point is
represented by a pair of integers in a function's parameters.

<p>Because rectangles are used so often when drawing to the screen,
TextTools has a set of rectangle subprograms to create, change and
test rectangles.

<pre>
SetRect (set_rect)
  Create a new rectangle from the coordinates of the sides.
  Ada: SetRect( r, 1, 10, 15, 20 );
  C++: set_rect( &r, 1, 10, 15, 20 );

OffsetRect (offset_rect)
  Displace/slide a rectangle by a certain distance.  If returning a value
  in Ada, the new rect is returned (instead of altering the original rect).
  Ada: OffsetRect( r, 10, -1 ); or r2 := OffsetRect( r, 10, -1 );
  C++: r2 = offset_rect( &r, 10, -1 );

InsetRect (inset_rect)
  Move the parallel sides of a rectangle in or out from the center by a
  certain distance.  A negative distance makes the rectangle smaller.
  If returning a value in Ada, the new rect is returned (instead of altering
  the original rectangle).
  Ada: InsetRect( r, -5, -5 ); or r2 := InsetRect( r, -5, -5 );
  C++: r2 = inset_rect( &r, -5, -5 );

InsideRect (inside_rect)
  True if one rectangle is inside of another.
  Ada: bool := InsideRect( inner, outer );
  C++: int = inside_rect( inner, outer );

InRect (in_rect)
  True if a point is inside a rectangle.
  Ada: bool := InRect( 5, 10, r );
  C++: int = in_rect( 5, 10, r );

IsEmptyRect (is_empty_rect)
  True if a rectangle is empty (that is, if the bottom is less than the
  top or the right side is less than the left side).
  Ada: bool := IsEmptyRect( r );
  C++  int = is_empty_rect( r ); [Needs fixing for C++]
</pre>

<h4>Rectangle Lists</h4>

<p>[to be finished]


<h3>The O/S Package</h3>

<p>The O/S package was indended as a thick binding to the operating system.
This would have allowed TextTools to be portable across a variety of
operating systems.  Since the time the O/S package was started, GCC
Ada has included its own O/S library package, making the TextTools O/S
package obsolete.  However, the O/S package is still used by TextTools
and contains useful O/S utilities.

<h4>HouseKeeping</h4>

<pre>
StartupOS (startup_os)
  Initialize the O/S package.  It creates a new session_log file if the
session log directory exists, initializes pathname aliases.  This should
be the first subprogram called in the O/S package.
  Ada: StartupOS;
  C++: startup_os();
  Errors: TT_OSService (no tty device for TextTools)

ShutdownOS (shutdown_os)
  Stop the O/S package.  It discards memory allocated at startup.  This
should be the final subprogram called in the O/S package.
  Ada: ShutdownOS;
  C++ shutdown_os;
  Errors: none

IdleOS (idle_os )
  Performs any idle-time tasks.  This is normally called for the application
by the Window manager.
  Ada: IdleOS( idlePeriod );
  C++: idle_os( idlePeriod );
  Errors: none
</pre>

<h4>Session Logs</h4>

<p>StartupCommon contains both a long name and a short name for the
application.  If the user, in his home directory, has a subdirectory
with the same name as the application short name, the O/S package
will create a file called "session_log" containing information about
the last run of the program.

<p>For example, if the short name for a program is "small_demo", then
the application log will be stored in "~/small_demo/session_log".
If the small_demo directory is missing, there will be no session log.

<p>Many of the TextTools functions record debugging information into a
session log if it exists.  Your program can also write to the session
log.

<pre>
SessionLog (session_log)
  Append a message to the session log.
  Ada: SessionLog( msg ); or
       SessionLog( fixedstring_msg ); or
       SessionLog( msg, errorccode ); or
       SessionLog( fixedstring_msg, errorcode );
  C++: SessionLog( str255_msg );
  Errors: none
</pre>

<h4>Pathname Aliases</h4>

<p>O/S pathnames can contain aliases for common directories.  If the pathname
starts with a "$", the first word (up to a '/') indicates an alias.

<p>The O/S package defines the following aliases on startup:
<ul>
<li>$tmp - the temp directory (the value of TMPDIR or "/tmp/")</li>
<li>$home - the user's home directory</li>
<li>$sys - the working directory for TextTools (the same directory that contains the session long)</li>
</ul>

<p>There are 6 predefined file systems:

<ul>
<li>UNIXFS   - 255 character UNIX names</li>
<li>UNIX14FS - 14 character UNIX names</li>
<li>DOSFS    - DOS 8 character / 2 character suffix names</li>
<li>OS/2     - 255 character O/S names</li>
<li>NONE     - an undefined file system</li>
</ul>

<p>Pathnames are 255 character bounded strings.

<pre>
UNIX
  Call the standard C library system() function.  Start an O/S shell and
run the specified command(s).  If a boolean result, return true on
success.  If a string result, return the first string of the output.
  Ada: UNIX( cmd ); or
       b := UNIX( cmd ); or
       s := UNIX( cmd );
  C++: N/A (use system() directly)
  Errors: TT_ParamError (cmd is over 255 characters)
          TT_SystemError (unable to run command / command failed)

RunIt
  Run ("spawn") a command without invoking a shell.  This is a binding to the
UNIX fork(), dup() and exec() syscalls.  The command takes up to 3 parameters.
The output of the command is returned as a list of str255 strings.
  Ada: RunIt( cmd, parm1 := "", parm2 := "", parm3 := "", results );
  C++: N/A
  Errors: TT_SystemError (unable to run command / command failed )

ValidateFilename (validate_filename)
  Ensure that a filename is syntactically correct for a particular file
system.  If the filename is unacceptable, the reason is outlined in errmsg
and a legal filename (with the problem characters replaced by underscores)
is returned.  If the filename is acceptable, errmsg is empty.
  Ada: ValidateFilename( fs, filename, new_filename, errmsg ); 
  C++: validate_filename( fs, str255_fn, str255_newfn, &errmsg );
  Errors: none

ValidatePathname (validate_pathname)
  Same as ValidateFilename but validates an entire path.
  Ada: ValidatePathname( fs, pathname, new_pathname, errmsg ); 
  C++: validate_pathname( fs, str255_pn, str255_newpn, &errmsg );
  Errors: none

SetPath (set_path)
  Change the default path (the present/current working directory).
  Ada: SetPath( path );
  C++: set_path( str255_path );
  Errors: TT_ParamError (cmd is over 255 characters)
          TT_SystemError (unable to run command / command failed)

GetPath (get_path)
  Return the current default path (the present/current working directory).
  Ada: path := GetPath;
  C++: str255_path := get_path();
  Errors: none;

PathAlias (path_alias)
  Create a new path alias (like $tmp, $home, etc.).
  Ada: PathAlias( alias, path );
  C++: path_alias( str255_alias; str255_path );
  Errors: Ada STOARGE_ERROR exception will occur if memory is low

ExpandPath (expand_path)
  Return a path with the path aliases replaced with actual directories.
  Ada: fullpath := ExpandPath( aliasedpath );
  C++: str255_fullpath = expand_path( str255_aliasedpath );
  Errors: none

SplitPath (split_path)
  Separate a path into the directory name and the filename.
  Ada: SplitPath( path, dirname, filename );
  C++: split_path( path, dirname, filename );
  Errors: none

DecomposePath (decompose_path)
  Separate a pathname or URL into its components.  Not complete.
  Ada: N/A
  C++: N/A
  Errors: N/A
</pre>

<h4>Working with Files</h4>

<p>All O/S package file functions accept pathname aliases.

<pre>
NotEmpty (not_empty)
  Return true if the file exists and has a length greater than zero.
  Ada: b := NotEmpty( path );
  C++: b = not_empty( str255_path );
  Errors: TT_ParamError (the path is too long)

IsDirectory (is_dir)
  Return true if the file is a directory.
  Ada: b := IsDirectory( path );
  C++: b = is_dir( str255_path );
  Errors: none

IsFile (is_file)
  Return true if the pathname specifies a readable, existing file.
  Ada: b := IsFile( path );
  C++: b = is_file( str255_path );
  Errors: none

MakeTempFileName (make_temp_file_name)
  Create a new path for a temporary file.
  Ada: MakeTempFileName( newpath );
  C++: make_temp_file_name( str255_newpath );
  Errors: none

Lock (lock)
  Not completed.
  Ada: N/A
  C++: N/A
  Errors: N/A

Unlock (unlock)
  Not completed.
  Ada: N/A
  C++: N/A

Erase (erase)
  Permanently delete a file.
  Ada: erase( path );
  C++: erase( str255_path );
  Errors: TT_FileAccess    (permission denied)
          TT_FileExistance (no such file)
          TT_PathExistance (no such path)
          TT_VolAccess     (no such volume)
          TT_SystemError   (other error)

Trash (trash)
  Remove a file by moving it to $HOME/.Trash/.  If unable to trash the file,
it will be removed with Erase.
  Ada: Trash( path );
  C++: trash( path );
  Errors: TT_FileAccess    (permission denied)
          TT_FileExistance (no such file)
          TT_PathExistance (no such path)
          TT_VolAccess     (no such volume)
          TT_SystemError   (other error)

EmptyTrash (empty_trash)
  Remove old files from the trash.  Performs a UNIX "find -mtime +3".
  Ada: EmptyTrash;
  C++: empty_trash();
  Errors: TT_SystemError (unable to run command / command failed)

Move (move)
  Rename or move a file.  Runs UNIX "mv" command.
  Ada: Move( oldpath, newpath);
  C++: move( str255_oldpath, str255_newpath );
  Errors: TT_ParamError (cmd is over 255 characters)
          TT_SystemError (unable to run command / command failed)

Shrink (shrink)
  Compresses a file using UNIX "zoo" command.  Returns the pathname
of the compressed file.
  Ada: compressedpath := Shrink( path );
  C++: str255_compressedpath = shrink( str255_path );
  Errors: TT_ParamError (cmd is over 255 characters)
          TT_SystemError (unable to run command / command failed)

Expand (expand)
  Expand a file that was compressed with Shrink. Uses "zoo" command.
  Ada: pathname := Expand( compressedpath );
  C++: str255_pathname = expand( str255_compressedpath );
  Errors: TT_ParamError (cmd is over 255 characters)
          TT_SystemError (unable to run command / command failed)

Archive (archive)
  Compress and add a file to an archive containing several compressed
files.  Uses "zoo" command.
  Ada: Archive( archivepath, filename );
  C++: archive( str255_archivepath, str255_filename );
  Errors: TT_ParamError (cmd is over 255 characters)
          TT_SystemError (unable to run command / command failed)

Extract (extract)
  Extract a file from an Archive archive.  Uses "zoo" command.
  Ada: Extract( archivepath, filename );
  C++: extract( str255_archivepath, str255_filename );
  Errors: TT_ParamError (cmd is over 255 characters)
          TT_SystemError (unable to run command / command failed)

Armour (armour)
  Encrypt binary file as plain text.  Not completed.
  Ada: N/A
  C++: N/A
  Errors: N/A

Disarmour (disarmour)
  Decrypt a binary file encrypted as plain text.  Not completed.
  Ada: N/A
  C++: N/A
  Errors: N/A

Usage (usage)
  Change the access permissions on a file.  Defaults are user=normal,
group=ReadOnly, others=ReadOnly.  Runs "chmod" command.
  Ada: Usage( path, me := normal, us := ReadOnly, everyone = ReadOnly );
  C++: N/A
  Errors: TT_ParamError (cmd is over 255 characters)
          TT_SystemError (unable to run command / command failed)

BeginSession (begin_session)
  Begin a series of optimized O/S calls.  Not complete.
  Ada: N/A
  C++: N/A
  Errors: N/A

EndSession (end_session)
  Complete a series of optimized O/S calls.  Not complete.
  Ada: N/A
  C++: N/A
  Errors: N/A
</pre>

<h4>Working with Directories</h4>

SpaceUsed (space_used)
  Return the number of bytes used in a directory.  Uses "df" command,
  Ada: bytes := SpaceUsed( dir );
  C++: byes = space_used( dir );
  Errors: TT_ParamError (cmd is over 255 characters)
          TT_SystemError (unable to run command / command failed)


<h4>Working with Volumes/Devices</h4>

<pre>
SpaceFree (space_free)
  Return the space free on a volume/device.  Not complete.
  Ada: N/A
  C++: N/A
  Errors: N/A
 
TotalSpace (total_space) 
  Return the total capacity of a volume/device.  Not complete.
  Ada: N/A
  C++: N/A
  Errors: N/A

EntriesFree (entries_space) 
  Return the free directory entries (inodes) of a volume/device.  Not complete.
  Ada: N/A
  C++: N/A
  Errors: N/A

TotalEntries (total_space) 
  Return the total directory entries (inodes) of a volume/device.  Not complete.
  Ada: N/A
  C++: N/A
  Errors: N/A

OnDevice (on_device)
  Return the device path for the device/volume that a file resides on.  Not
complete.
  Ada: N/A
  C++: N/A
  Errors: N/A
</pre>

<h4>Working with Memory</h4>

<pre>
TotalMem (Ctotalmem)
  Return the total memory of the computer (including virtual memory).  Uses
the proc filesystem.
  Ada: bytes := TotalMem;
  C++: bytes = Ctotalmem();
  Errors: none

FreeMem (Cfreemem)
  Return the free memory of the computer (including virtual memory).  Uses the
proc filesystem.
  Ada: bytes := FreeMem;
  C++: bytes = Cfreemem();
  Errors: none

RealTotalMem (Crealtotalmem)
  Return the total memory of the computer (not virtual memory).  Uses the proc
filesystem.
  Ada: bytes := RealTotalMem;
  C++: bytes = Crealtotalmem();
  Errors: none

RealFreeMem (Crealfreemem)
  Return the free memory of the computer (not virtual memory).  Uses the proc
filesystem.
  Ada: bytes := RealFreeMem;
  C++: bytes = Crealfreemem();
  Errors: none
</pre>

<h4>Working with Processes</h4>

<pre>
MyID
  Return your process identification number (PID).
  Ada: pid := MyID;
  C++: N/A (use getpid)
  Errors: none

Nice
  Change the priority of your process.  Same as C nice().
  Ada: Nice ( change );
  C++: N/A (use nice)
  Erros: none

IsLocal (is_local)
  Return true if program is running on a virtual console.
  Ada: b := IsLocal;
  C++: b = is_local();
  Errors: none
</pre>

<h4>Working with Distributed Clusters</h4>

<pre>
GetFreeClusterHost (get_free_cluster_host)
  Return an idle host in a computer cluster.  Not complete, but will return the
name of the current host using "uname" command.
  Ada: N/A
  C++: N/A
  Errors: TT_ParamError (cmd is over 255 characters)
          TT_SystemError (unable to run command / command failed)
</pre>

<h4>Working with Dates and Times</h4>

A time is represented by a ATime record (struct):

<table border="1">
<tr><td><b>Ada</b></td><td><b>C++</b></td><td><b>Description</b></td></tr>
<tr><td>seconds</td><td>seconds</td><td>number of seconds since Epoch</td></tr>
<tr><td>microseconds</td><td>microseconds</td><td>number of additional microseconds</td></tr>
</table>

<pre>
GetDate (get_date)
  Return the date in dd/mm/yy format.
  Ada: s := GetDate;
  C++: str255 = get_date();
  Errors: none

GetTime (get_time)
  Return the time in hh:mm:ss format.
  Ada: s := GetTime;
  C++: str255 = get_time();
  Errors: none

GetClock
  Get the current time and date.  Uses C's gettimeofday().
  Ada: GetClock( time, timezone );
  C++: N/A (use gettimeofday)
  Errors: none

GetLongDate (get_long_date)
  Return the full english date (in the ctime() format).
  Ada: s := GetLongDate;
  C++: str255 = get_long_date();
  Errors: none

GetTimeStamp (get_time_stamp)
  Return the current date and time in a format that can be sorted.  In this
case, the number of microseconds since the Epoch.
  Ada: s := GetTimeStamp;
  C++: str255 = get_time_stamp();
  Errors: none;

Wait (os_wait)
  Wait for at least the specific number of seconds.  Uses C usleep().
  Ada: Wait (float_seconds);
  C++: os_wait (float_seconds);
  Errors: none
</pre>

<h4>Loading and Saving Text Files</h4>
<p>-- to be filled in

<pre>
AddFile (add_file)
  Append a string to a file.  Includes an end-of-line character.
  Ada: AddFile( file, string );
  C++: add_file( str255_file, str255_string );
</pre>

<h3>The User IO Package</h3>

<p>The UserIO package performs all the low-level drawing and reads the keyboard
and mouse.  It is TextTools' interface to the curses/ncurses library.

<p>Normally, a TextTools application doesn't need to use the UserIO package
directly.  The Windows package makes all the necessary TextTools calls
to draw your windows.


<h4>Housekeeping</h4>

<pre>
StartupUserIO (startup_userio)
  Initialize the UserIO package.  It starts curses, resets the drawing
defaults and reads any macro file. The background colour is set to blue.
When it is finished, it clears the window and positions the pen at the
upper-left corner.  This should be the first subprogram called in the
UserIO package.
  Ada: StartupUserIO;
  C++: startup_userio();
  Errors: none

ShutdownUserIO (shutdown_userio )
  Stop the UserIO package.  It stops curses, discards the macro file and
any unprocessed input.  It flushes any unrevealed drawing to the screen.
This should be the last subprogram called in the UserIO package.
  Ada: ShutdownUserIO;
  C++ shutdown_userio;
  Errors: none

IdleUserIO (idle_userio )
  Performs any idle-time tasks.  After 60 seconds of no activity, UserIO
will discard any non-essential allocated memory.  This is normally called
for the application by the Window manager.
  Ada: IdleUserIO( idlePeriod );
  C++: idle_userio( idlePeriod );
  Errors: none

ResetUserIO (reset_userio)
  Reinitializes curses.  Called by the Window manager when refreshing the
entire desktop after the screen has been clobbered by another program.  The
drawing defaults are left unchanged.
  Ada: ResetUserIO;
  C++  reset_userio();
  Errors: none

BlueBackground (blue_background)
  TextTools normally has a blue background.  The call can change the
background colour to black background instead of blue.
  Ada: BlueBackground( bool );
  C++" blue_background( int );
  Errors: none

IsBlueBackground (is_blue_background)
  True if the background is current blue instead of black.
  Ada: bool := IsBlueBackground;
  C++: uchar = is_blue_background();
  Errors: none
</pre>

<h4>Getting Information about the I/O Hardware</h4>

<p>The display is the current screen or window that TextTools is drawing on.
TextTools can return statistics about the current display device.

<p>The information about the display device is returned as a aDisplayInfoRec
(or C++ a_display_info_rec) record.  The record has these fields:

<table border="1">
<tr><td><b>Ada</b>         </td><td><b>C++</b>           </td><td><b>Description</b>                  </td><td><b>VT-100 Example</b></td></tr>
<tr><td>Fields      </td><td>fields        </td><td>fiends in this record         </td><td>8</td></tr>
<tr><td>TextBased   </td><td>text_based    </td><td>true if text-based display   </td><td>true (or 1)</td></tr>
<tr><td>H_Res       </td><td>h_res         </td><td>horizontal columns           </td><td>80</td></tr>
<tr><td>V_Res       </td><td>v_res         </td><td>vertical rows                </td><td>24</td></tr>
<tr><td>C_Res       </td><td>c_res         </td><td>RGB bits (or 0)               </td><td>0</td></tr>
<tr><td>P_Len       </td><td>p_len         </td><td>palette length (or 0)         </td><td>0</td></tr>
<tr><td>D_Buf       </td><td>d_buf         </td><td>number of display buffers     </td><td>1</td></tr>
<tr><td>S_Res       </td><td>s_res         </td><td>sound resolution (or 0)       </td><td>0</td></tr>
<tr><td>Y_Res       </td><td>y_res         </td><td>sound voices/channels (or 0)  </td><td>0</td></tr>
</table>

<p>Likewise, information about the input hardware can be obtained in a
anInputInfoRec (or C++ an_input_info_rec):

<table border="1">
<tr><td><b>Ada</b>          </td><td><b>C++</b>           </td><td><b>Description</b>                  </td><td><b>VT-100 Example</b></td></tr>
<tr><td>Fields       </td><td>fields        </td><td>fiends in this record        </td><td>4</td></tr>
<tr><td>HasKeyboard  </td><td>has_keyboard  </td><td>true if has a keyboard       </td><td>true (or 1)</td></tr>
<tr><td>HasDirection </td><td>has_direction </td><td>true if has a game pad       </td><td>false (or 0)</td></tr>
<tr><td>HasVelocity  </td><td>has_velocity  </td><td>true if has a joystick       </td><td>false (or 0)</td></tr>
<tr><td>HasLocator   </td><td>has_locator   </td><td>true if has a mouse          </td><td>false (or 0)</td></tr>
</table>

<p>TextTools supports ncurses-compatible mice, but there is currently no
game pad or joystick support.

<pre>
GetDisplayInfo (get_display_info)
  Return information about the video display and sound hardware.
  Ada: GetDisplayInfo( dspinforec );
  C++: get_display_info( &dspinforec );
  Errors: none

GetInputInfo (get_input_info)
  Return information about the input devices.
  Ada: GetInputInfo( inpinforec );
  C++: get_input_info( &inpinforec );
  Errors: none
</pre>

<h4>The Pen</h4>

<p>UserIO draws everything on the screen using an imaginary pen.  The pen
has a location, an angle and a default colour.

<p>When the UserIO package is started, the pen is at the top-left corner
of the display and has an angle of 0 degrees (see turtle graphics).  The
colour is "outline".

<p>The pen position is set by moving or drawing with the pen.

<pre>
GetPenPos (get_pen_pos)
  Return the pen position.
  Ada: GetPenPos( x, y );
  C++: get_pen_pos( &x, &y );
  Errors: none

GetPixel (get_pixel)
  Return RGB (0,0,0) or (100,100,100) depending on whether or not a
screen position has a character in it.
  Ada: GetPixel( x, y, R, G, B );
  C++: GetPixel( x, y, &R, &G, &B );
  Errors: none

MoveToGlobal (move_to_global)
  Move the pen to a particular screen position.
  Ada: MoveToGlobal( x, y );
  C++: move_to_global( x, y );
  Errors: none
  Notes: local move to is defined in the window manager.

CLS (Cls)
  Clear the screen to the background colour.  Cls changes the pen colour.
  Ada: CLS;
  C++: Cls();
  Errors: none
</pre>

<h4>The Pen Colours</h4>

On most text-based screens, the pen colour can be one of several predefined
colour names:

<table border="1">
<tr><td><b>Ada</b></td>          <td><b>C++</b></td>           <td><b>Description</b></td></tr>
<tr><td>None         </td><td>none          </td><td>an undefined colour</td></tr>
<tr><td>Outline      </td><td>outline       </td><td>the thin, bright pen for drawing windows</td></tr>
<tr><td>ScrollBack   </td><td>scroll_back   </td><td>the background colour of a scroll bar</td></tr>
<tr><td>ScrollThumb  </td><td>scroll_thumb  </td><td>the colour of a scroll bar thumb</td></tr>
<tr><td>ThermBack    </td><td>therm_back    </td><td>the background colour of a thermometer</td></tr>
<tr><td>ThermFore    </td><td>therm_fore    </td><td>the foreground colour of a thermometer</td></tr>
<tr><td>White        </td><td>white         </td><td>white</td></tr>
<tr><td>Red          </td><td>red           </td><td>red</td></tr>
<tr><td>Purple       </td><td>purple        </td><td>purple</td></tr>
<tr><td>Green        </td><td>green         </td><td>green</td></tr>
<tr><td>Blue         </td><td>blue          </td><td>blue</td></tr>
<tr><td>Yellow       </td><td>yellow        </td><td>yellow</td></tr>
<tr><td>Black        </td><td>black         </td><td>black</td></tr>
</table>

<p>The first few colour names are logical colours: their actual value may
change depending on the TextTools background colour (blue or black).

<p>The pen colour can also be set using RGB (red, green and blue) percentages.
TextTools will attempt to match the RGB value to the nearest pen colour name.

<p>If the text display is monochrome, TextTools attempts to draw with characters
representing different colours.

<pre>
SetPenColour (set_pen_colour):
   Change the pen to a certain colour or colour name.
   Ada: SetPenColour( colour_name ); or
        SetPenColour( R, G, B );
   C++: ?
   Errors: none

GetPenColour (get_pen_colour)
   Return the current pen colour or the closest colour name.
   Ada: colour_name := GetPenColour(); or
        GetPenColour( R, G, B );
   C++: ?
</pre>


<h4>Palette Colours</h4>

<p>This feature is for future expansion.


<h4>Pen Size</h4>

<p>This feature is for future expansion.


<h4>Line Drawing</h4>

<pre>
DrawLine (draw_line)
  Draw a line between a pair of points.  It never uses the terminal's line
drawing characters.
  Ada: DrawLine( x1, y1, x2, y2 );
  C++: draw_line( x1, y1, x2, y2 );
  Errors: none

DrawHorizontalLine (draw_horizontal_line)
  Draw a horizontal line.  It uses the terminal's line drawing characters
if available.
  Ada: DrawHorizontalLine( x1, x2, y );
  C++: draw_horizontal_line( x1, x2, y );
  Errors: none

DrawVerticalLine (draw_vertical_line)
  Draw a vertical line.  It uses the terminal's line drawing characters if
available.
  Ada: DrawVerticalLine( y1, y2, x );
  C++: draw_vertical_line( y1, y2, x );
  Errors: none
</pre>

<h4>Rectangle Drawing</h4>

<Pre>
FrameRect (frame_rect)
  Draw the outline of a rectangle in the current pen colour.
  Ada: FrameRect( r );
  C++: frame_rect( &r );
  Errors: none

FrameRect3D (frame_rect_3d)
  Draw the outline of a rectangle with 3D lighting effects in the current
pen colour.
  Ada: FrameRect3D( r );
  C++: frame_rect_3d( &r );
  Errors: none

PaintRect (paint_rect)
  Fill a rectangle in the current pen colour.
  Ada: PaintRect( r );
  C++: paint_rect( &r );
  Errors: none

FillRect (fill_rect)
  Fill a rectangle with a specific colour.
  Ada: FillRect( r, colour_name );
  C++: fill_rect( &r, colour_name );
  Errors: none

FramedRect (framed_rect)
  Frame and fill a rectangle with specific colours.
  Ada: FramedRect( r, frame, background );
  C++: framed_rect( &r, frame, background );
  Errors: none

EraseRect (erase_rect)
  Erase a rectangle with the background colour.
  Ada: EraseRect( r );
  C++: EraseRect( &r );
  Errors: none
</pre>

<h4>Turtle Graphics</h4>

<p>TextTools can perform Logo-style turtle graphics.  The pen has a drawing
angle and it can draw forward along the angle.

<pre>
SetPenAngle (set_pen_angle)
  Set the current drawing angle (in degrees).
  Ada: SetPenAngle( degrees );
  C++: set_pen_angle( degrees );
  Errors: none (angle is contrained to >=0 and < 360)

ChangePenAngle (change_pen_angle)
  Add to or subtract from the pen angle.
  Ada: ChangePenAngle( change );
  C++: change_pen_angle( change );
  Errors: none (angle is contrained to >=0 and < 360)

GetPenAngle (get_pen_angle)
  Return the current pen angle.
  Ada: float := GetPenAngle;
  C++: float = get_pen_angle();
  Errors: none

MoveForward (move_forward)
  Move forward in the current pen angle direction without drawing.
  Ada: MoveForward( pixels );
  C++: move_forward( pixels );
  Errors: usual things may happen when trying to draw off the screen

DrawForward (draw_forward)
  Draw forward in the current pen angle direction.
  Ada: DrawForward( pixels );
  C++: draw_forward( pixels );
  Errors: usual things may happen when trying to draw off the screen
</pre>

<h4>Drawing Text</h4>

<p>Text is drawn at the current position of the pen and the pen advances
when the text is drawn.  However, the text is not affected by the pen
angle or colour.

<p>The text is displayed according to the current text style:

<table border="1">
<tr><td><b>Ada</b>                 </td><td><b>C++</b>                   </td><td><b>Description</b></td></tr>
<tr><td>Normal              </td><td>normal                </td><td>Default pen style</td></tr>
<tr><td>Bold                </td><td>bold                  </td><td>boldface</td></tr>
<tr><td>Underline           </td><td>underline             </td><td>underlined text</td></tr>
<tr><td>Italic              </td><td>italic                </td><td>italic text</td></tr>
<tr><td>BoldUnderline       </td><td>bold_underline        </td><td>bold and underline</td></tr>
<tr><td>BoldItalic          </td><td>bold_italic           </td><td>bold and italic</td></tr>
<tr><td>ItalicUnderline     </td><td>italic_underline      </td><td>italic and underline</td></tr>
<tr><td>boldUnderlineItalic </td><td>bold_underline_italic </td><td>bold, underline & italic</td></tr>
</table>

<p>The text style is an enumerated type.  Not all displays will support every
one of these modes.

<p>There are also a large set of logical styles.  TextTools tries to use the
most appropriate text colour and attribute for a particular style.

<table border="1">
<tr><td><b>Ada</b></td>                 <td><b>C++</b></td>                   <td><b>Description</b></td></tr>
<tr><td>Success             </td><td>success               </td><td>successful operation</td></tr>
<tr><td>Failure             </td><td>failure               </td><td>failed operation</td></tr>
<tr><td>Warning             </td><td>warning               </td><td>user warning</td></tr>
<tr><td>Status              </td><td>status                </td><td>status information</td></tr>
<tr><td>Citation            </td><td>citation              </td><td>a quote or citation</td></tr>
<tr><td>SectionHeading      </td><td>section_heading       </td><td>a document section heading</td></tr>
<tr><td>SubHeading          </td><td>sub_heading           </td><td>a document subheading</td></tr>
<tr><td>Heading             </td><td>heading               </td><td>a document heading</td></tr>
<tr><td>Title               </td><td>title                 </td><td>a document title</td></tr>
<tr><td>Emphasis            </td><td>emphasis              </td><td>an emphasized word or phrase</td></tr>
<tr><td>Input               </td><td>input                 </td><td>UserIO input field colour</td></tr>
<tr><td>Marquee             </td><td>marquee               </td><td>an impressive announcement</td></tr>
<tr><td>Headline            </td><td>headline              </td><td>newspaper-style headline</td></tr>
<tr><td>FinePrint           </td><td>fine_print            </td><td>legal notices</td></tr>
<tr><td>DefinedTerm         </td><td>defined_term          </td><td>a definition</td></tr>
<tr><td>Footnote            </td><td>footnote              </td><td>a footnote</td></tr>
<tr><td>ToAddress           </td><td>to_address            </td><td>an envelope's destination</td></tr>
<tr><td>FromAddress         </td><td>from_address          </td><td>an envelope's source</td></tr>
<tr><td>SubScript           </td><td>sub_script            </td><td>a subscript</td></tr>
<tr><td>SuperScript         </td><td>super_script          </td><td>a superscript</td></tr>
</table>

<p>A text colour can be any pen colour name.  The text colour is separate from
the pen's drawing colour.

<pre>
SetTextStyle (set_text_style)
  Sets the current text style.  All future text will be drawn in this style.
  Ada: SetTextStyle( style );
  C++: set_text_style( style );
  Errors: none

GetTextStyle (get_text_style)
  Return the current text style.
  Ada: style := GetTextStyle;
  C++: style = get_text_style();
  Errors: none

SetTextColour (set_text_colour)
  Select the current text colour.  All future text will be drawn in this colour.
  Ada: SetTextColour( colour_name );
  C++: set_text_colour( colour_name );
  Errors: none

Draw (draw)
  Draw text on the screen.  The draw command doesn't recognize formatting
characters like tabs or C++ '\n'--it draws the raw ASCII characters.
  Ada: Draw( str255 ); or
       Draw( adastring ); or
       Draw( str255, width, ellipsis ); or
       Draw( ch ); or
       Draw( int ); or
       Draw( long ); or
       Draw( float );
  C++: draw_cstring( c_string *s );
  Errors: none

DrawLn (draw_ln)
  Start a new line, returning to the left side of the screen.
  Ada: DrawLn;
  C++: draw_ln();
  Errors: none

DrawEdit (draw_edit)
  Draw a text edit field.
  Ada: DrawEdit( str255, width, am );
  C++: draw_edit( str255, width, am );
  Errors: none
</pre>

<h4>Drawing Emergency Messages</h4>

<p>These text drawing routines are for emergency situations, displaying
critical system errors.  This are intended for internal use by TextTools.

<pre>
DrawErr (draw_err)
  Draw an emergency message.  Always drawn in white and the normal text style.
  Ada: DrawErr( str255 ); or
       DrawErr( int ); or
       DrawErr( long ); or
       DrawErr( input_rec );
  C++: draw_cerr( c_string *s );
  Errors: none

DrawErrLn (draw_errln)
  Draw a newline, returning to the left side of the screen.
  Ada: DrawErrLn;
  C++: draw_err_ln();
  Errors: none
</pre>

<h4>Text Fonts and Sizes</h4>

<p>TextTools font and font list capabilities are for future expansion.

<p>The height of text (on a text-based screen) is always 1.  The width will be
1 for a single character, or the length of a string for the string.

<pre>
GetTextHeight (get_text_height):
  Return the height of a character or string (always 1).
  Ada: int := GetTextHeight( ch ); or int := GetTextHeight( s255 );
  C++: int := get_text_height( s255 );
  Errors: none

GetTextWidth (get_text_width):
  Return the width of a character (always 1) or a string.
  Ada: int := GetTextWidth( ch ); or int := GetTextWidth( s255 );
  C++: int = get_text_width( s255 );
  Errors: none
</pre>

<h4>Regions</h4>

<p>Regions, arbitrarily shaped objects, are for future expansion.  In
TextTools, they are represented as a linked list of rectangles.


<h4>Pictures</h4>

<p>Pictures are copies of what is on the TextTools screen.  Pictures
are not completely implemented.

<pre>
ScreenDump (screen_dump)
  Save a copy of the display in a file called "ScreenDump".
  Ada: ScreenDump;
  C++: screen_dump();
  Errors: In Ada, STORAGE_ERROR exception if out of memory.
</pre>

<h4>Output Spooling</h4>

<p>Since TextTools is based on curses, TextTools applications can use
curses' delayed drawing features (called output spooling).  TextTools
can delay displaying the screen until several drawing operations have
been done and then it will display the final result.  When erasing and
drawing many items on the screen, this can reduce flicker and make the
display appear faster over slow connections to a video terminal.

<p>Note: Spooling has been disabled because of problems with certain versions
of ncurses.

<pre>
WaitToReveal (wait_to_reveal)
  Begin output spooling.  Don't draw anything.
  Ada: WaitToReveal;
  C++: wait_to_reveal();
  Errors: none

Reveal (reveal)
  Stop output spooling.  Update the display to reflect what has been
secretly drawn.
  Ada: Reveal;
  C++: reveal();
  Errors: none

RevealNow (reveal_now)
  Show what has been drawn so far, but continue to spool.
  Ada: RevealNow;
  C++: reveal_now();
  Errors: none
</pre>

<h4>Playing Sounds</h4>

<p>The music sound features of UserIO are for future expansion.

<p>The beep command will play a beep through the system speaker.

<p>If Warren Gay's wavplay is installed, beep will search for a play sound
samples for particular beep styles.  The sound samples must be in uppercase
(with the Ada name) and stored in the session directory.

<table border="1">
<tr><td><b>Ada</b>            </td><td><b>C++</b>             </td><td><b>Description</b></td></tr>
<tr><td>Normal         </td><td>normal_beep     </td><td>a default beep</td></tr>
<tr><td>Success        </td><td>success_beep    </td><td>successful operation</td></tr>
<tr><td>Failure        </td><td>failure_beep    </td><td>a failed operation</td></tr>
<tr><td>Warning        </td><td>warning_beep    </td><td>a warning to the user</td></tr>
<tr><td>Status         </td><td>status_beep     </td><td>status information</td></tr>
<tr><td>BadInput       </td><td>bad_input       </td><td>bad input into a window edit text field</td></tr>
<tr><td>HourChime      </td><td>hour_chime      </td><td>played by window manager at :00</td></tr>
<tr><td>QuarterChime1  </td><td>quarter_chime1  </td><td>played by window manager at :15</td></tr>
<tr><td>QuarterChime2  </td><td>quarter_chime2  </td><td>played by window manager at :30</td></tr>
<tr><td>QuarterChime3  </td><td>quarter_chime3  </td><td>played by window manager at :45</td></tr>
<tr><td>Alarm          </td><td>alarm           </td><td>timer ring</td></tr>
<tr><td>NewMail        </td><td>new_mail        </td><td>new email sound</td></tr>
<tr><td>LowPower       </td><td>low_power       </td><td>power failure</td></tr>
<tr><td>Startup        </td><td>startup         </td><td>played at UserIO startup</td></tr>
<tr><td>Shutdown       </td><td>shutdown        </td><td>played at UserIO shutdown</td></tr>
</table>

<pre>
Beep (beep)
  Beep the speaker or play a .wav file for a particular sound.
  Ada: Beep( style );
  C++: beep( style );
  Errors: TT_file_existance (the .wav file doesn't exist)

PlaySound (play_sound)
  Play a .wav file using wavplay (if installed).
  Ada: PlaySound( path_str255 );
  C++: play_sound( path_str255 );
  Errors: TT_file_existance (the .wav file doesn't exist)
</pre>

<h4>The Event Queue</h4>

<p>There are several kinds of events

<table border="1">
<tr><td><b>Ada</b>               </td><td><b>C++</b>                 </td><td><b>Description</b></td></tr>
<tr><td>NullInput         </td><td>null_input          </td><td>no input</td></tr>
<tr><td>KeyInput          </td><td>key_input           </td><td>keyboard input</td></tr>
<tr><td>HeldKeyInput      </td><td>held_key_input      </td><td>key held down</td></tr>
<tr><td>DirectionInput    </td><td>direction_input     </td><td>joystick direction</td></tr>
<tr><td>LocationInput     </td><td>location_input      </td><td>specific mouse position</td></tr>
<tr><td>ButtonDownInput   </td><td>button_down_input   </td><td>mouse button pressed</td></tr>
<tr><td>ButtonUpInput     </td><td>button_up_input     </td><td>mouse button released</td></tr>
<tr><td>HeartbeatInput    </td><td>heartbeat_input     </td><td>a "keep alive" event</td></tr>
<tr><td>MoveInput         </td><td>move_input          </td><td>mouse position change</td></tr>
<tr><td>UserInput         </td><td>user_input          </td><td>user-defined input</td></tr>
</table>

<p>An event is a variant record (in C++, a union) called AnInputRecord (or
an_input_record).  The fields depends on the type of input.

<table border="1">
<tr><td><b>Ada</b>               </td><td><b>C++</b></td><td><b>Description</b></td></tr>
<tr><td>-                 </td><td>-                                </td><td>no input</td></tr>
<tr><td>Key               </td><td>key_data.key                     </td><td>keyboard input</td></tr>
<tr><td>HeldKey           </td><td>held_key_data.held_key           </td><td>key held down</td></tr>
<tr><td>Direction         </td><td>direction_data.direction         </td><td>joystick direction</td></tr>
<tr><td>Velocity          </td><td>direction_data.velocity          </td><td>joystick velocity</td></tr>
<tr><td>X                 </td><td>location_data.x                  </td><td>mouse X position</td></tr>
<tr><td>Y                 </td><td>location_data.y                  </td><td>mouse Y position</td></tr>
<tr><td>DownButtion       </td><td>button_down_data.down_button     </td><td>mouse button number</td></tr>
<tr><td>DownLocationX     </td><td>button_down_data.down_location_y </td><td>mouse button down X</td></tr>
<tr><td>DownLocationY     </td><td>button_down_data.down_location_x </td><td>mouse button down Y</td></tr>
<tr><td>UpButtion         </td><td>button_up_data.up_button         </td><td>mouse button number</td></tr>
<tr><td>UpLocationX       </td><td>button_up_data.down_location_x   </td><td>mouse button down X</td></tr>
<tr><td>UpLocationY       </td><td>button_up_data.down_location_y   </td><td>mouse button down Y</td></tr>
<tr><td>-                 </td><td>-                                </td><td>heart beat</td></tr>
<tr><td>MoveLocationX     </td><td>move_data.move_location_x        </td><td>move move X</td></tr>
<tr><td>MoveLocationY     </td><td>move.data.move_location_y        </td><td>move location Y</td></tr>
<tr><td>id                </td><td>user_data.id                     </td><td>user-defined long int</td></tr>
</table>

<p>For better efficiency on multiuser systems, some keyboard functions
have a response time parameter.  This can be set to blocking (wait
indefinitely for a keypress), erratic (wait a fraction of a second),
or instant (return immediately if there is no keypress).

<pre>
GetInput (get_input)
  Return the next event in the input event queue.  Ada doesn't allow a
C++ default for response_time.
  Ada: GetInput( input_rec, response_time := blocking );
  C++: get_input( &input_rec, response_time ); // not working yet
  Errors: In Ada, STORAGE_ERROR exception if out of memory.

SetInput (set_input)
  Add an event to the input event queue.  If usetime is true, use the
time in the record instead of the current time for the time stamp.  Ada
doesn't allow a C++ default for usetime.
  Ada: SetInput( input_rec, usetime := false );
  C++: set_input( &input_rec, usetime );
  Errors: In Ada, STORAGE_ERROR exception if out of memory.

HeartBeat (heart_beat)
  Add a heartbeat event to the input event queue.
  Ada: HeartBeat;
  C++: heart_beat();
  Errors: In Ada, STORAGE_ERROR exception if out of memory.

SetInputString (set_input_string)
  Add a string to the input event queue as if the user had typed it in
from the keyboard.
  Ada: SetInputString( str255 );
  C++: set_input_string( str255 );
  Errors: In Ada, STORAGE_ERROR exception if out of memory.

FlushInput (flush_input)
  Discard all events in the input event queue.
  Ada: FlushInput;
  C++: flush_input;
  Errors: none

GetInputLength (get_input_length)
  Return the length of the input event queue.
  Ada: long := GetInputLength;
  C++: long = get_input_length;
  Errors: none

WaitFor (wait_for)
  Wait for the specific number of ticks (1/60th of a second).  If any input
occurs, add it to the input event queue.  WaitFor will wait for at least
the number of specified ticks, but it may wait for longer--it's not intended
for high precision waiting.
  Ada: WaitFor( ticks );
  C++: wait_for( ticks );
  Errors: none
</pre>

<h4>The Keyboard</h4>

<pre>
FlushKeys (flush_keys)
  Discard all pending keypresses that are not yet in the event queue.
  Ada: FlushKeys;
  C++: flush_keys;
  Errors: none

Keypress (keypress)
  Check for a keypress.  Return ASCII 0 if there is none.  If shortblock
is true, wait for a fraction of second instead of returning immediately
with an ASCII 0.
  Ada: ch := Keypress( shortblock );
  C++: ch = keypress( shortblock );
  Errors: none

GetKey (get_key)
  Wait for a keypress and return the character.
  Ada: GetKey( ch );
  C++: get_key( &ch );

<h4>The Mouse</h4>

GetLocation (get_location)
  Return the current position of the locator device (usually a mouse).
  Ada: Not Yet Implemented
  C++: Not Yet Implemented
  Errors: none
</pre>

<h4>The Joystick</h4>

<p>Joystick support is for future expansion.


<h3>The O/S Package</h3>


<h4>The Controls Package</h4>

<p>Window controls (sometimes called "widgets") are items that appear in windows.
OK buttons, scroll bars, and text entry boxes are all controls.

<p>In TextTools, controls are objects.  Since Ada and C++ have slightly different
object oriented methodologies, the functions are slightly different between
the two languages.

<p>Every control has a constructor and destructor.  To use a control, declare it.
The constructor requires the bounding rectangle around the control and an
associated hot key (the quick select key on the keyboard).

<pre>
   a_simple_button sb1( 1, 1, 10, 1, 'o' );
   // create a button in the window located between (1,1) and (10,1)
   // with a hot key of 'o'.
</pre>

<p>In Ada, there is an additional Init function to set up the rectangle and hot
key.

<pre>
   sb1 : aliased aSimpleButton;
...
   Init( sb1, 1, 1, 10, 1, 'o' );
</pre>

<p>If you don't want a hot key, use an ASCII NUL character for the key.  Some
controls may have additional initialization values.

<p>Once a control is created, it must be added to the window using the Window
Manager's AddControl (C++, add_control) function.  The next time the window
is drawn, the control will appear.

<p>All controls share certain common properties:

<ol>
<li>1.  Frames - each control has a bounding rectangle.</li>
<li>  Hot Keys - each control has a hot key.</li>
<li>  Status - whether the control is selectable or not.  The possible status
      codes are off (unselectable), standby (selectable but not current) or
      on (the control is the active one in use by the user).</li>
<li>  Tool Tips - messages that can appear in a window's info bar when a control
      is selected.</li>
<li>  Scrolling - whether or not the control moves when the window contents
      are scrolled (like a virtual window).</li>
<li>  Stickyness - whether or not a particular side of a control's frame
      stretches when the window is resized (not fully implemented).</li>
<li>  Validity - whether or not a control should be (re)drawn</li>
</ol>

<p>There are a number of elementary functions common to every control.  Most of
these functions are used internally by TextTools.

<p>SetInfo can be used to create "tool tips", messages that appear in a window's
info bar when the control is the current target of a user's actions.  Initially
a control has no tool tip: when the control is selected, the contents of the
tool bar do not change.  When a message is added using SetInfo and the control
is selected, the message appears in the tool bar.  There is no way to turn off
a tool tip once it has been created: an empty string will simply erase the
previous contents of the info bar when the control is selected.

<pre>
Hear (hear)
  Used by Window Manager DoDialog.  Give user to a control.  For example, have
the control "hear" and respond to a keypress.  The control will return a
dialog action if the Window Manager needs to respond to the control changes.
  Ada: Hear( control, inputRec, dialogAction );
  C++: control.hear( input_rec, &dialog_action );
  Errors: none

Move (move)
  Used by Window Manager DoDialog.  Move a control to a new position in a
window.  Indicate the horizontal and vertical change.
  Ada: Move( control, dx, dy );
  C++: control.move( dx, dy );
  Errors: none

Resize (resize)
  Used by Window Manager DoDialog.  Resize the bounding box of a control,
possibly moving the control at the same time.  Indicate the rectangle
coordinate changes.
  Ada: Resize( control, dleft, dtop, dright, dbottom );
  C++: control.resize( dleft, dtop, dright, dbottom );
  Errors: none

Draw (draw)
  Used by Window Manager DoDialog.  Draw (or redraw) the control if it is
not invalid.
  Ada: Draw( control );
  C++: control.draw();
  Errors: none

SetStatus (set_status)
  Used by Window Manager DoDialog.  Change the status of a control (whether it
is active or not, etc.)
  Ada: SetStatus( control, status );
  C++: control.set_status( status );
  Errors: none

GetStatus (get_status)
  Used by Window Manager DoDialog.  Change the status of a control (whether it
is active or not, etc.)
  Ada: status := GetStatus( control );
  C++: status = control.get_status();
  Errors: none

Encode (encode)
  Used by Window Manager SaveWindow.  Encode the control as a string for saving
to a text file.  Note: This function is currently broken.
  Ada: str255 := Encode( control );
  C++: str255 = control.encode();
  Errors: none

Decode (Decode)
  Used by Window Manager LoadWindow.  Create a control from a control saved by Encode.  Note: This function is currently broken.
  Ada: Decode( control, str255 );
  C++: control.decode( str255 );
  Errors: none

Invalid (invalid)
  Used internally by controls or by Window Manager.  Mark a control as needing
to be redrawn.
  Ada: Invalid( control );
  C++: control.invalid();
  Errors: none

NeedsRedrawing (needs_redrawing)
  Used internally by Window Manager.  Check to see if a control needs redrawing
(if it has been marked invalid).
  Ada: b := NeedsRedrawing( control );
  C++: b = control.needs_redrawing();
  Errors: none

GetHotKey (get_hot_key)
  Used internally by Window Manager.  Get the hot key for the control.
  Ada: c := GetHotKey( control );
  C++: c = control.get_hot_key();
  Errors: none

SetInfo (set_info)
  Used internally by Window Manager.  Set the info bar text associated with
the control.  Setting the info message to a blank string creates a blank
message in the info bar.  (This is TextTools' equivalent to a "tool tip".)
  Ada: SetInfo( control, str255 );
  C++: control.set_info( str255 );
  Errors: none

GetInfo (get_info)
  Used internally by Window Manager.  Get the info bar text associated with
the control.
  Ada: str255 := GetInfo( control );
  C++: str255 = control.get_info();
  Errors: none

HasInfo (has_info)
  Used internally by Window Manager.  Determine if a info bar text should be
shown for the control (that is, whether or not SetInfo has ever been used for
this control).
  Ada: b := HasInfo( control );
  C++: b = control.has_info();
  Errors: none

GetStickyness (get_stickyness)
  Used internally by Window Manager.  Return true if a side of a control is
sticky.  Note: Stickyness is not fully implemented.
  Ada: GetStickyness( control, left, top, right, bottom );
  C++: control.get_stickyness( &left, &top, &right, &bottom );
  Errors: none

SetStickyness (set_stickyness)
  Make certain sides of a control's bounding box sticky (that is, the side
stretches when the window is stretched).  Note: Stickyness is not fully
implemented.
  Ada: SetStickyness( control, left, top, right, bottom );
  C++: control.set_stickyness( left, top, right, bottom );
  Errors: none

InControl (in_control)
  Return true if a point is inside of the control's bounding retangle.
  Ada: b := InControl( control, x, y );
  C++: b = control.in_control( control, x, y );
  Errors: none

GetFrame (get_frame)
  Return a control's bounding retangle.
  Ada: r := GetFrame( control );
  C++: r = control.get_frame( control );
  Errors: none

Scrollable (scrollable)
  Mark a control as scrollable (able to be scrolled when a window's contents
are scrolled).
  Ada: Scrollable( boolean );
  C++: control.scrollable( bool );
  Errors: none

Init (C++ N/A)
  Set the bounding box, hot key and radio family for a control.
  Ada: Init( control, left, top, right, bottom, key [, family] );
  C++: N/A (part of the constructor)
  Errors: none
</pre>

<h4>Window Control Categories</h4>

<p>Unless you are creating new types of controls, you don't have to worry about
the control categories.

<p>There are two categories of controls: window controls and iconic controls.
Iconic controls are controls which represent information to the user or that
allow the user to control an application.  A static line of text is an iconic
control.  "Window controls" are controls that affect the window and its
contents.  A check box is a window control.  Any iconic control can be linked
to another TextTools window (they are "hypertext-enabled", like items in a
web browsers window) as opposed to window controls that never lead anywhere
else when clicked.

<p>All controls are either extended from anIconicControl or aWindowControl, two
window tagged types (ie. classes in C++).  Iconic controls have two special
fields:

<table border="1">
<tr><td><b>Ada</b></td><td><b>C++</b></td><td><b>Type</b></td><td><b>Description
<tr><td>   link              </td><td>link                </td><td>str255   </td><td>the location being linked to</td></tr>
<tr><td>   closeBeforeFollow </td><td>close_before_follow </td><td>boolean  </td><td>close window first (if true) </td></tr>
</table>

<p>A regular window control has no special fields.

<p>Iconic control links are in URL format and can be one of the following:

<ul>
<li><tt>window://</tt> - open a window saved in a SaveWindow file</li>
<li><tt>http://</tt>   - shell out to the lynx browser to display web page</li>
<li><tt>file://</tt>   - shell out to the lynx browser to display a text file</li>
<li><tt>unix://</tt>   - shell out and run the specified O/S command</li>
</ul>


<h5>Controls: Themometers</h5>

<p>A thermometer is a bar graph indicating progress information or a percentage
value.  Thermometers can be horizontal or vertical: if the control frame is
narrow, the thermometer will be vertical.

<p>Thermometers have a maximum value and a current value.  The difference
between the two will be displayed as a bar graph.  For example, if the max is
10 and the current value is 5, the thermometer will show 50%.

<p>Values less than zero or larger than the maximum value will be truncated
accordingly.

<p>Here are the specific thermometer control methods:

<pre>
GetMax (get_max)
  Return the maximum value of the thermometer.
  Ada: long := GetMax( control );
  C++: long = control.get_max();
  Errors: none

GetValue (get_value)
  Return the current value of the thermometer.
  Ada: long := GetValue( control );
  C++: long = control.get_value();
  Errors: none

SetMax (set_max)
  Set the maximum value of the thermometer.  The initial value is 0.
  Ada: SetMax( control, long );
  C++: control.set_max( long );
  Errors: none

SetValue (set_value)
  Set the current value of the thermometer.  The initial value is 0.
  Ada: SetValue( control );
  C++: control.set_value();
  Errors: none
</pre>

<h5>Controls: Scroll Bars</h5>

<p>A scroll bar is a bar containing a position marker called a "thumb" used to
represent a relative position or value.  They are commonly used to scroll
through a window's contents.  A scroll bar can be horizontal or vertical: if
the scroll bar frame is narrow, the scroll bar will be vertical.

<p>Scroll bars have a maximum position and a thumb position.  The thumb ranges
between zero and the maximum position.  For example, if the maximum position
is 50 and the thumb position is 25, the thumb shows 50% progress.

<p>Values less than zero or larger than the maximum position will be truncated
accordingly.

<p>When a scroll bar is "owned" by a list control, the scroll bar is automatically updated when the list control is scrolled.

<p>Here are the specific scroll bar control methods:

<pre>
GetMax (get_max)
  Return the maximum position of the scroll bar.
  Ada: long := GetMax( control );
  C++: long = control.get_max();
  Errors: none

GetThumb (get_thumb)
  Return the current position of the thumb.
  Ada: long := GetThumb( control );
  C++: long = control.get_thumb();
  Errors: none

SetMax (set_max)
  Set the maximum position of the thumb for the scroll bar.  The initial value
is 0.
  Ada: SetMax( control, maxval );
  C++: control.set_max( maxval );
  Errors: none

SetThumb (set_thumb)
  Set the position of the thumb, between 0 and the current maximum.  The
initial value is 0.
  Ada: SetThumb( control, thumbval );
  C++: control.set_thumb( thumbval );
  Errors: none

SetOwner (set_owner)
  Assign the number of the control that owns the scroll bar so that, when the
owner is changed, the scroll bar is updated automatically by the Window Mgr.
The initial value is 0 (no owner).
  Ada: SetOwner( control, ownerid );
  C++: control.set_owner( ownerid );
  Errors: none

GetOwner (get_owner)
  Return the previously assigned owner id for the scroll bar.
  Ada: ownerid := GetOwner( control );
  C++: control.get_owner();
  Errors: none
</pre>

<h5>Controls: Static Lines</h5>

<p>A static line is a single line of unchanging text.  The text can be assigned
colours and styles.  The default control status is off (that is, that the
static line cannot be selected by the user).

<pre>
GetText (get_text)
  Return the static text.
  Ada: str255 := GetText( control );
  C++: str255 = control.get_text();
  Errors: none

SetText (set_text)
  Assign the static text to be displayed.
  Ada: SetText( control, str255 ) or SetText( control, fixedstr );
  C++: control.set_text( str255 ) or control.set_text( char *str );
  Errors: none

GetStyle (get_style)
  Return the text style.
  Ada: style := GetStyle( control );
  C++: style = control.get_style();
  Errors: none

SetStyle(set_style)
  Set the text style for the static text.  The initial value is normal.
  Ada: SetStyle( control, style );
  C++: control.set_style( style );
  Errors: none

GetColour (get_colour)
  Return the name of the current text colour.
  Ada: colour_name := GetColour( control );
  C++: colour_name = control.get_colour();
  Errors: none

SetColour (set_colour)
  Assign the name of the colour for the static text.  The initial value is
none.
  Ada: SetColour( control, colour_name );
  C++: control.set_colour( colour_name );
  Errors: none
</pre>

<h5>Controls: Edit Lines</h5>

<p>An edit line is a line of text that, unlike a static line, can be edited by
the user.  Edit lines (currently) do not scroll to allow text larger than
than size of the control--a 10 character edit line can hold a maximum of 10
characters.

<p>The constructor has an additional maximum value parameter.  Use 0 (or omit)
for the default.

<p><b>Blind Mode</b>: use this mode to enter passwords.  The value of the edit line will
not be displayed.

<p><b>Advance Mode</b>: use this mode for entry of fixed length data on forms.  This mode
will automatically advance to the next control when the edit line is full.

<pre>
GetText (get_text)
  Return the current value of the edit line.
  Ada: str255 := GetText( control );
  C++: str255 = control.get_text();
  Errors: none

SetText (set_text)
  Assign text to the edit line.
  Ada: SetText( control, str255 );
  C++: control.set_text( str255 );
  Errors: none

GetAdvanceMode (get_advance_mode)
  Return true if advanced mode is on.
  Ada: bool := GetAdvanceMode( control );
  C++: bool = control.get_advance_mode;
  Errors: none

SetAdvanceMode (set_advance_mode)
  Turn advance mode on or off.  The initial value is off (false).
  Ada: SetAdvanceMode( control, bool );
  C++: control.set_advance_mode( bool );
  Errors: none

GetBlindMode (get_blind_mode)
  Return true if blind mode is on.
  Ada: bool := GetBlindMode( control );
  C++: bool = control.get_blind_mode();
  Errors: none

SetBlindMode (set_blind_mode)
  Turn blind mode on or off.  The initial value is off (false).
  Ada: SetBlindMode( control, bool );
  C++: control.set_blind_mode( bool );
  Errors: none

GetMaxLength (get_max_length)
  Return the maximum length of text the edit line can hold.
  Ada: len := GetMaxLength( control );
  C++: len = control.get_max_length();
  Errors: none

SetMaxLength (set_max_length)
  Assign the maximum length of text the edit line can hold.  The initial value
is the width of the edit control.  Assigning a value larger than the width of
the control will have unpredictable results.
  Ada: len := GetMaxLength( control );
  C++: len = control.get_max_length();
  Errors: none
</pre>

<h5>Controls: Specialized Edit Lines</h5>

<p>There are several edit lines customized for specific kinds of input.

<ul>
<li><b>Integer Edit Lines</b>: support integers instead of strings</li>
<li><b>Long Integer Edit Lines</b>: support long integers instead of strings.</li>
<li><b>Float Edit Lines</b>: support floating-point values instead of strings.</li>
</ul>

<p>They are identical to a standard edit line except that they have GetValue
(get_value) and SetValue (set_value) functions instead of Get/SetText.


<h5>Controls: Check Boxes</h5>

<p>Check boxes are controls that can be checked off like boxes on a form.
A check box can be true (if checked) or false (if unchecked).  If a check
box is turned off (with SetStatus), a hypen indicates that the control
cannot be selected.

<pre>
  [ ] unchecked     [X] checked    [-] unselectable

GetText (get_text)
  Return the text message of the check box.
Ada: s255 := GetText( control );
C++: s255 = control.get_text();
Errors: none

GetCheck (get_check)
  Return true if the check box is checked.
Ada: bool := GetCheck( control );
C++: bool = control.get_check();
Errors: none

SetText (set_text)
  Change the text message of the check box.  The initial value is "Check".
Ada: SetText( control, s255 );
C++: control.set_text( s255 );
Errors: none

SetCheck (set_check)
  Check or uncheck the check box.  The initial value is undefined.
Ada: SetCheck( control, bool );
C++: control.set_check( bool );
Errors: none
</pre>

<h5>Controls: Radio Buttons</h5>

<p>Like a check box, radio buttons can be checked on or off.  Radio buttons are
grouped into families so that turning on one radio button will automatically
turn off all others in the family.  Users can select one option from a list
of options represented by the button family.  When a radio button is turned
off (with SetStatus), a hypen indicates that the control cannot be selected.

<pre>
  (*) Draft quality (checked)
  ( ) Average quality
  ( ) Best quality
  (-) Unselectable
</pre>

<p>Because radio buttons belong to families, the Init procedure (or C++
constructor) has a numeric family id.

<pre>
GetText (get_text)
  Return the text message of the radio button.
Ada: s255 := GetText( control );
C++: s255 = control.get_text();
Errors: none

GetCheck (get_check)
  Return true if this button is checked.
Ada: bool := GetCheck( control );
C++: bool = control.get_check();
Errors: none

GetFamily (get_family)
  Return the numeric family id for this radio button (0 if none).
Ada: id := GetFamily (control );
C++: id = control.get_family();
Errors: none

SetText (set_text)
  Changes the text message for the radio button.  The initial text is "Radio".
Ada: SetText( control, s255 );
C++: control.set_text( s255 );
Errors: none

SetCheck (set_check)
  Check or uncheck the radio button.  The initial value is undefined.
Ada: SetCheck( control, bool );
C++: control.set_check( bool );
Errors: none
</pre>

<h5>Controls: Simple Buttons</h5>

<p>A simple button is a button that can be selected in order to perform an action.
An "OK button" or a "Cancel button" are examples of simple buttons.  When a
simple button is selected, the Window Manager's DoDialog function returns
control to your program.  If a simple button is turned off (with SetStatus),
a hypen indicates that the control cannot be selected

<pre>
  < > OK               <-> Unselectable
</pre>

<p>Normally, a simple button will not activate when selected by the user: after
pressing the button hot key, the user presses the Enter/Return key to
activate the button.  (A mouse click will automatically activate the button.)
When a simple button is set to "instant", it acts like a menu item: if the
user presses the hot key for the button, it will automatically activate the
button.

<pre>
  | > Menu Item        |-> Unselectable

GetText (get_text)
  Return the text message of the simple button.
Ada: s255 := GetText( control );
C++: s255 = control.get_text();
Errors: none

SetText (set_text)
  Change the text message of the simple button.  The initial value is "OK".
Ada: SetText( control, s255 );
C++: control.set_text( s255 );
Errors: none

GetInstant (get_instant)
  Return true if the instant hot key activation feature is on.
Ada: bool := GetInstant( control );
C++: bool = control.get_instant();
Errors: none

SetInstant (set_instant)
  Turn the instant hot key activation on or off.  The initial value is false.
Ada: SetInstant( control, bool );
C++: control.set_instant( bool );
Errors: none

GetColour (get_colour)
  Return the colour name of the message text.
Ada: colname := GetColour( control );
C++: colname = control.get_colour();
Errors: none

SetColour (set_colour)
  Change the colour name of the colour of the message text.
Ada: SetColour( control, colname );
C++: control.set_colour( colname );
Errors: none
</pre>

<h5>Controls: Window Buttons</h5>

<p>A window button is displayed the same as a simple button.  Instead of
returning control to the application when activiated, the window button will
try to follow a TextTools URL (often to a window previously saved to a file
using SaveWindow).  Use Window buttons to display static screens suck as
on-line help without adding extra work for your application.

<p>To change the URL, use the link iconic control subprograms.

<pre>
GetText (get_text)
  Return the text message of the window button.
Ada: s255 := GetText( control );
C++: s255 = control.get_text();
Errors: none

SetText (set_text)
  Change the text message of the window button.  The initial value is "Help".
Ada: SetText( control, s255 );
C++: control.set_text( s255 );
Errors: none

GetInstant (get_instant)
  Return true if the instant hot key activation feature is on.
Ada: bool := GetInstant( control );
C++: bool = control.get_instant();
Errors: none

SetInstant (set_instant)
  Turn the instant hot key activation on or off.  The initial value is false.
Ada: SetInstant( control, bool );
C++: control.set_instant( bool );
Errors: none

GetControlHit (get_control_hit)
  Used by internally window manager.  Restore the control id hit when returning
from a link.
Ada: cid := GetControlHit( control );
C++: cid = control.get_control_hit();
Errors: none

SetColour (set_colour)
  Used by internally window manager.  Save the control id hit when following
a link.
Ada: SetControlHit( control, cid );
C++: control.set_control_hit( cid );
Errors: none
</pre>

<h5>Controls: Rectangles</h5>

<p>A rectangle control draws a rectangle in the window.  Although you could draw
a rectangle "manually" with TextTool's rectangle drawing functions, a
rectangle control will be automatically redrawn by the window manager when
needed.

<pre>
    +--------------------+
    |                    |
    |                    |
    +--------------------+
</pre>

<p>Rectangles are often used surround related controls on the screen.  Declaration
order is important: rectangles declared after the controls they surround will
be drawn after those controls, erasing them.

<p>Rectangles are normally unselectable and have no hot key (but there's no reason
why they can't because they are normal window controls).  The initial status is
off.

<pre>
SetColours (set_colours)
  Set the colour name of the frame and background colour for the rectangle.
The initial values are outline foreground and black background.
Ada: SetColours( control, fore_colname, back_colname );
C++: control.set_colours( fore_colname, back_colname );
Errors: none

GetColours (get_colours)
  Return the colour names of the frame and background colour for the
rectangle.
Ada: GetColours( control, fore_colname, back_colname );
C++: control.get_colours( &fore_colname, &back_colname );
Errors: none
</pre>

<h5>Controls: Lines</h5>

<p>Link controls, like rectangle controls, are User IO lines that are managed by
the window manager, redrawn on command.  Horizontal and vertical lines can be
drawn by controls described below.

<p>The line is drawn either from top-left to bottom-right corner of the control
frame or from the opposite corners.

<pre>
     #
      #
       #
        #
</pre>

<p>The initial status value is off (the line is not selectable).

<pre>
SetColour (set_colour)
  Change the colour name for the colour of the line.
Ada: SetColour( control, colname );
C++: control.set_colour( colname );
Errors: none

GetColour (get_colour)
  Return the colour name of the line colour.
Ada: colname := GetColour( control );
C++: colname = control.get_colour();
Errors: none

SetDrawDir (set_draw_dir);
  Select the drawing direction.  True is down and to the right.  The initial
value is false.
Ada: SetDrawDir( control, bool );
C++: control.set_draw_dir( bool );
Errors: none
</pre>

<h5>Controls: Horizontal and Vertical Separators</h5>

<p>Separators are horizontal or vertical lines.  Horizontal separators can be
used to separate sets of menu items.

<p>The line colour is always outline for separators.  The default status is off
(unselectable).  There are no properties that can be set.


<h5>Controls: Static Lists</h5>

<p>The first kind of list control is a static list.  Static lists are a list of
strings that cannot be edited by the user.  The list appears in a rectangle
and can be scrolled by the user.

<pre>
     +----------------------------+
     | Status log:                |
     |                            |
     | First item                 |
     +----------------------------+
</pre>

If a scroll bar is associated with the list, it will be adjusted when the list
is scrolled and vice versa.

<i>Basic Key assignments:</i>

<ul>
<li>Up Arrow / Control-J - move up one line</li>
<li>Down Arrow / Control-K - move down one line</li>
<li>Home Key / Control-Y - move to top</li>
<li>End Key / Control-E - move to bottom</li>
<li>Control-P - Page Up</li>
<li>Control-N - Page Down</li>
<li>Control-6 - Set Mark</li>
</ul>

<p>Since all other list types are subclasses of static lists, there are many
subprograms defined here including search and replace.  Programs can use
these features on any list even when keys are not defined for the user.

<h4>Basic List Subprograms</h4>

<pre>
SetList (set_list)
  Assign the text to the list, a linked list of 255 character strings.  If
a list already exists, it will be deallocated first.  The initial value is
an empty list.
Ada: SetList( control, str255list );
C++: controls.set_list( str255list );
Errors: none

SetOrigin (set_origin)
  Change the origin point for the list (the index of the text line displayed
in the top line of the list control).
Ada: SetOrigin( control, line );
C++: control.set_origin( line );
Errors: none

GetList (get_list)
  Return a pointer to the linked list being displayed in the control.  It
doesn't make a copy of the list.
Ada: str255list := GetList( control );
C++: str255list = control.get_list();
Errors: none

GetOrigin (get_origin)
  Return the origin point for the list (the index of the text line being
displayed in the top  of the list control).  The first line would be "1".
Ada: linenum := GetOrigin( control );
C++: linenum = control.get_origin( control );
Errors: none

GetCurrent (get_current)
  Return the index of the line the cursor is currently on.  The first line of
the list would be "1".
Ada: linenum := GetCurrent( control );
C++: linenum = control.get_current();
Errors: none

GetLength (get_length)
  Return the number of lines of linked list text in the list control.
Ada: lines := GetLength( control );
C++: lines = control.get_length();
Errors: none

SetScrollBar (set_scroll_bar)
  Record the control id for the scroll bar associated with this list.
Ada: SetScrollBar( control, cid );
C++: control.set_scroll_bar( cid );
Errors: none (if the control is not a scroll bar, there will be errors when
the Window Manager attempts to access the control)

GetScrollBar (get_scroll_bar)
  Return the control id of the scroll bar associated with this list (0 if none).
Ada: cid := GetScrollBar( control );
C++: cid = control.set_scroll_bar();
Errors: none
</pre>

<h4>Movement and Editing</h4>

<pre>
JustifyText (justify_text)
  Attempt to make the text fit into a specific width (usually the width of the
list control) by breaking long lines and concatenating them with following
line.  This is performed recursively until the end of the linked list is
reached.
Ada: JustifyText( control, width, startingline );
C++: control.justify_text( width, startingline );
Errors: none (could raise an Ada STORAGE_ERROR exception)

MoveCursor (move_cursor)
  Move the cursor to a new position in the list.  In static lists, the cursor
is against the left margin no matter what the horizontal value is.
Ada: MoveCursor( control, dx, dy );
C++: control.move_cursor( dx, dy );
Errors: none (the cursor will be constrained to the limits of the list)

CopyLine (copy_line)
  Return a copy of the line at the current cursor position in the list.
Ada: s255 := CopyLine( control );
C++: s255 = control.copy_line();
Errors: none

PasteLine (paste_line)
  Inserts a line at the current cursor position in the list.
Ada: PasteLine( control, s255 );
C++: control.paste_line( s255 );
Errors: none (could raise an Ada STORAGE_ERROR exception)

FindText (find_text)
  Search the linked list from the current position forward looking for a
string.  If the regexp flag is true, the string is treated as a regular
expression.  If backwards is true, the search will be conducted backwards from
the current position.  If found, the search text will be hilighted.  If not
found, there will be a failure beep.
Ada: FindText( control, s255, back_bool, regexp_bool := false );
C++: control.find_text( s255, back_book, regexp_bool = false );
Errors: none

ReplaceText (replace_text)
  Like FindText, except replace the (first) occurrence of the string with a new
string.
Ada: ReplaceText( control, s255, new_s255, back_bool, regexp_bool := false );
C++: control.replace_text( s255, new_s255, back_book, regexp_bool = false );
Errors: none

SetFindPhrase (set_find_phrase)
  Change the list text searched for by FindText.  Changing the text to a null
string will turn off the hilighted search text.
Ada: SetFindPhrase( control, s255 );
C++: control.set_find_phrase( s255 );
Errors: none

SetMark (set_mark)
  Mark (record) a linked list line.  A -1 will remove the last mark.
The marked line will be hilighted.  Only one mark can be placed at a time.
Ada: SetMark( control, linenum );
C++: control.set_mark( linenum );
Errors: none

GetMark (get_mark)
  Return the last line marked (or -1 if none).
Ada: linenum := GetMark( control );
C++: linenum = control.get_mark();
Errors: non

CopyLines (copy_lines)
  Copy a set of linked list lines and return the lines as a new linked list.
The first line to copy must be indicated by SetMark.
Ada: CopyLines( control, last_linenum, str255list );
C++: control.copy_lines( last_linenum, &str255list );
Errors: none (could raise an Ada STORAGE_ERROR exception)
</pre>

<h5>Controls: Check Lists</h5>

<p>A check list is a list of check boxes.  Like a static list, the list cannot
be edited by the user can select individual boxes in the list.  The boxes
are represented as a linked list of booleans.

<pre>
     +----------------------------+
     |[#] Red                     |
     |[#] Orange                  |
     |[ ] Blue                    |
     +----------------------------+
</pre>

<p>The subprograms are the same as static lists except:

<pre>
SetChecks (set_checks)
  Assign a boolean list representing the status of the check boxes.  If the
boolean list is shorter than the list of strings, the remaining check boxes
are unselectable. 
Ada: SetChecks( control, boolist );
C++: control.set_checks( boolist );
Errors: none

GetChecks (get_checks)
  Return a pointer to the boolean list representing the status of the check
boxes.
Ada: boollist := GetChecks( control );
C++: boollist = control.get_checks();
Errors: none
</pre>

<h5>Controls: Radio Lists</h5>

<p>A check list is a list of radio buttons.  Like a static list, the list cannot
be edited by the user can select individual boxes in the list.  The boxes
are represented as a linked list of booleans.  The buttons are implicitly
members of the same family.

<pre>
     +----------------------------+
     |( ) Surface Mail            |
     |(*) FedEx                   |
     |( ) UPS                     |
     +----------------------------+
</pre>

<p>The subprograms are the same as static lists except:

<pre>
SetChecks (set_checks)
  Assign a boolean list representing the status of the check boxes.  If the
boolean list is shorter than the list of strings, the remaining check boxes
are unselectable. 
Ada: SetChecks( control, boolist );
C++: control.set_checks( boolist );
Errors: none

GetChecks (get_checks)
  Return a pointer to the boolean list representing the status of the check
boxes.  Only one boolean will be true.
Ada: boollist := GetChecks( control );
C++: boollist = control.get_checks();
Errors: none

GetCheck (get_check)
  Return the button checked.
Ada: linenum := GetCheck( control );
C++: linenum = control.get_check();
Errors: none
</pre>

<h5>Controls: Edit Lists</h5>

<p>Edit lists contain lists of text that can be edited by the user.  There is
a special edit list for source code editing.

<p>The subprograms are the same as static lists except:

<pre>
GetPosition (get_position)
  Return the position in the list (the line and the character).
Ada: GetPosition( control, x, y );
C++: control.get_postion( &x, &y );
Errors: none

SetCursor (set_cursor)
  Move the cursor to an exact position (MoveCursor uses a relative position).
Ada: SetCursor( control, x, y );
C++: control.set_cursor( x, y );
Errors: none (the cursor is constrained to reasonable positions)

Touch (touch)
  Mark the text as changed (this is done automatically if the user changes
text).
Ada: Touch( control );
C++: control.touch():
Errors: none

ClearTouch (clear_touch)
  Clear the touch flag so that the text doesn't need saving.
Ada: ClearTouch( control );
C++: control.clear_touch();
Errors: none

WasTouched (was_touched)
  True if the text was touched (needs saving because it was changed).
Ada: b := WasTouched( control );
C++: b = control.was_touched();
Errors: none
</pre>

<h5>Controls: Source Edit List</h5>

<p>This is the list control used by PegaSoft's TIA IDE.  It is designed to hold
programmer source code.  It has all the features of an edit list but also
has keyword hilighting.

<pre>
AddKeyword (add_keyword)
  Add a word to the list of keywords to be hilighted.  TextTools will only
hilight the word if it is separated from the rest of the text by spaces or
punctuation symbols.
Ada: AddKeyword( control, s255 );
C++: control.add_keyword( str255 );
Errors: none (could raise an Ada STORAGE_ERROR exception)

ClearKeywords (clear_keywords)
  Remove all keywords.
Ada: ClearKeyword( control );
C++: control.clear_keywords();
Errors: none
</pre>

<h3>Unfinished Controls</h3>

<p>These controls are not complete:

<ul>
<li>SimplePicture: ASCII art "bit-mapped" picture</li>
<li>Picture:       ASCII art "bit-mapped" picture, different "resolutions"</li>
<li>Sketch:        pre-recorded set of User IO drawing operations</li>
<li>Animation:     animated picture or sketch</li>
<li>HTML Box:      a web page</li>
</ul>

<h3>Window Manager</h3>

<p>This section to be written

<p>End of Document

</body>
</html>