TextTools Reference Manual

## TextTools 2.0

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

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.

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.

Note: C++ support is not fully implemented in this version of TextTools

### The Common Package

#### Housekeeping

    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.

#### Global variables

    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.

#### Error Codes

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.

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

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

##### General Errors

Ada Name | C++ Name | Explaination
TT_NotYetImplemented | TT_not_yet_implemented | routine doesn't exist
TT_OK | TT_ok | success (value of 0)
TT_MemoryLeak | TT_memory_leak | memory leak detected
TT_LowMemory | TT_low_memory | low / out of memory
TT_TestData | TT_test_data | test data in operation

##### Operating System Errors

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

##### Window Errors

Ada Name | C++ Name | Explaination
TT_WindowExistance | TT_window_existance | window found/not found
TT_NoControls | TT_no_controls | no controls in the window
TT_ControlExistance | TT_control_existance | control found/not found
TT_NoDialogTaskCB | TT_no_dialog_task_cb | no manual handler installed

#### Using the Error Functions

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

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

### Standard String Functions

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.

#### String Lists

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.

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

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

    str255list_list sl = str255list_null;

#### Memory Leak Detection

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.

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.

    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

#### List Operations

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

    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

#### Working with String List Items

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

    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

#### Search and Replace Operations

    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

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

    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

#### Standard Math Functions

These are mostly obsolete.

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

#### Working with Rectangles

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

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

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.

Rectangles have their own record structure.

In C++, a rectangle is

    struct a_rect {
       int left;
       int top;
       int right;
       int bottom;
    }

In Ada, a rectangle is

    type aRect is record
       left, top, right, bottom : integer;
    end record;

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

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.

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

    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++]

#### Rectangle Lists

[to be finished]

### The O/S Package

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.

#### HouseKeeping

    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

#### Session Logs

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.

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.

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

    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

#### Pathname Aliases

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

The O/S package defines the following aliases on startup:

- $tmp - the temp directory (the value of TMPDIR or "/tmp/")
- $home - the user's home directory
- $sys - the working directory for TextTools (the same directory that contains the session long)

There are 6 predefined file systems:

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

Pathnames are 255 character bounded strings.

    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

#### Working with Files

All O/S package file functions accept pathname aliases.

    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

#### Working with Directories

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)

#### Working with Volumes/Devices

    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

#### Working with Memory

    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

#### Working with Processes

    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

#### Working with Distributed Clusters

    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)

#### Working with Dates and Times

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

Ada | C++ | Description
seconds | seconds | number of seconds since Epoch
microseconds | microseconds | number of additional microseconds

    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

#### Loading and Saving Text Files

-- to be filled in

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

### The User IO Package

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

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.

#### Housekeeping

    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

#### Getting Information about the I/O Hardware

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

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

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

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

Ada | C++ | Description | VT-100 Example
Fields | fields | fiends in this record | 4
HasKeyboard | has_keyboard | true if has a keyboard | true (or 1)
HasDirection | has_direction | true if has a game pad | false (or 0)
HasVelocity | has_velocity | true if has a joystick | false (or 0)
HasLocator | has_locator | true if has a mouse | false (or 0)

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

    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

#### The Pen

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

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

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

    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

#### The Pen Colours

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

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

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

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.

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

    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++: ?

#### Palette Colours

This feature is for future expansion.

#### Pen Size

This feature is for future expansion.

#### Line Drawing

    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

#### Rectangle Drawing

    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

#### Turtle Graphics

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

    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

#### Drawing Text

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.

The text is displayed according to the current text style:

Ada | C++ | Description
Normal | normal | Default pen style
Bold | bold | boldface
Underline | underline | underlined text
Italic | italic | italic text
BoldUnderline | bold_underline | bold and underline
BoldItalic | bold_italic | bold and italic
ItalicUnderline | italic_underline | italic and underline
boldUnderlineItalic | bold_underline_italic | bold, underline & italic

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

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

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

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

    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

#### Drawing Emergency Messages

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

    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

#### Text Fonts and Sizes

TextTools font and font list capabilities are for future expansion.

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.

    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

#### Regions

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

#### Pictures

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

    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.

#### Output Spooling

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.

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

    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

#### Playing Sounds

The music sound features of UserIO are for future expansion.

The beep command will play a beep through the system speaker.

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.

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

    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)

#### The Event Queue

There are several kinds of events

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

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

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

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

    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

#### The Keyboard

####

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

    The Mouse

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

#### The Joystick

Joystick support is for future expansion.

### The O/S Package

#### The Controls Package

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

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

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

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

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

       sb1 : aliased aSimpleButton;
    ...
       Init( sb1, 1, 1, 10, 1, 'o' );

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

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.

All controls share certain common properties:

1. 1. Frames - each control has a bounding rectangle.
2. Hot Keys - each control has a hot key.
3. 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).
4. Tool Tips - messages that can appear in a window's info bar when a control is selected.
5. Scrolling - whether or not the control moves when the window contents are scrolled (like a virtual window).
6. Stickyness - whether or not a particular side of a control's frame stretches when the window is resized (not fully implemented).
7. Validity - whether or not a control should be (re)drawn

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

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.

    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

#### Window Control Categories

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

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.

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

Ada | C++ | Type | Description
link | link | str255 | the location being linked to
closeBeforeFollow | close_before_follow | boolean | close window first (if true)

A regular window control has no special fields.

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

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

##### Controls: Themometers

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.

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

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

Here are the specific thermometer control methods:

    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

##### Controls: Scroll Bars

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.

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.

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

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

Here are the specific scroll bar control methods:

    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

##### Controls: Static Lines

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

    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

##### Controls: Edit Lines

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.

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

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

Advance Mode: 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.

    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

##### Controls: Specialized Edit Lines

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

- Integer Edit Lines: support integers instead of strings
- Long Integer Edit Lines: support long integers instead of strings.
- Float Edit Lines: support floating-point values instead of strings.

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

##### Controls: Check Boxes

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.

      [ ] 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

##### Controls: Radio Buttons

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.

      (*) Draft quality (checked)
      ( ) Average quality
      ( ) Best quality
      (-) Unselectable

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

    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

##### Controls: Simple Buttons

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

      < > OK               <-> Unselectable

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.

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

##### Controls: Window Buttons

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.

To change the URL, use the link iconic control subprograms.

    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

##### Controls: Rectangles

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.

        +--------------------+
        |                    |
        |                    |
        +--------------------+

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.

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.

    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

##### Controls: Lines

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.

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

         #
          #
           #
            #

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

    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

##### Controls: Horizontal and Vertical Separators

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

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

##### Controls: Static Lists

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.

         +----------------------------+
         | Status log:                |
         |                            |
         | First item                 |
         +----------------------------+

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

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

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.

#### Basic List Subprograms

    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

#### Movement and Editing

    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)

##### Controls: Check Lists

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.

         +----------------------------+
         |[#] Red                     |
         |[#] Orange                  |
         |[ ] Blue                    |
         +----------------------------+

The subprograms are the same as static lists except:

    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

##### Controls: Radio Lists

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.

         +----------------------------+
         |( ) Surface Mail            |
         |(*) FedEx                   |
         |( ) UPS                     |
         +----------------------------+

The subprograms are the same as static lists except:

    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

##### Controls: Edit Lists

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

The subprograms are the same as static lists except:

    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

##### Controls: Source Edit List

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.

    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

### Unfinished Controls

These controls are not complete:

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

### Window Manager

This section to be written

End of Document