TextTools 2.0

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

Operating System Errors

Window Errors

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

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

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

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

• 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