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 use TextTools.
The change logs are now online at the PegaSoft Linux Cafe http://www.pegasoft.ca/docs/discus/index.html.
Partial C++ support added.
If you're looking to contribute to the Texttools project, here are some outstanding jobs that need to be done:
The cpp directory contains C++ examples.
The examples directory contains Ada examples.
Although there are over 600 procedures and functions in TextTools, to open window is fairly uncomplicated. Detailed explanations of all TextTools procedures and functions are located in texttools.txt.
Everything in TextTools is drawn in a window. Everything in a window is a control (sometimes called a "widget"). To display a window, you must create a window, fill in the window with controls to display, and run the window manager's DoDialog command.
The following program opens a simple window.
with common, os, userio, controls, windows;
use common, os, userio, controls, windows;
procedure demo is
-- Define Window Controls
OKButton : aliased ASimpleButton;
MessageLine : aliased AStaticLine;
-- The Dialog Record
DT : ADialogTaskRecord;
begin
-- Start TextTools
StartupCommon( "demo", "demo" );
StartupOS;
StartupUserIO;
StartupControls;
StartupWindows;
-- Create a new window. The window will not appear until the
-- DoDialog procedure is used.
OpenWindow( To255( "Demo Window" ), -- title at top of window
0, 0, 78, 23, -- the coordinates of the window
Style => normal, -- type of window, usually "normal"
HasInfoBar => true ); -- true if control information is
-- displayed at the bottom of the
-- window
-- Setup the controls in the window
-- OK Button located near bottom of window
Init( OKButton,
36, 20, 44, 20, -- coordinates in window
'o' ); -- hot key for OK button
SetText( OKButton, "OK" ); -- button will have "OK"
SetInfo( OKButton, To255( "Select me to quit" ) );
AddControl( SimpleButton, OKButton'unchecked_access, IsGlobal => false );
-- Message at top of window in bright red
Init( MessageLine,
1, 1, 78, 1 );
SetText( MessageLine, "Welcome to TextTools" );
SetStyle( MessageLine, Bold );
SetColour( MessageLine, Red );
AddControl( SimpleButton, MessageLine'unchecked_access, IsGlobal => false );
-- Display the window and handle any input events. When dialog
-- is finished, return control which completed the dialog.
loop
DoDialog( DT );
exit when DT.Control = 1; -- first control is the OK button
end loop;
-- close the window
CloseWindow;
-- Shutdown TextTools
ShutdownWindows;
ShutdownControls;
ShutdownUserIO;
ShutdownOS;
ShutdownCommon;
end demo;
TextTools is broken into 5 main packages, based on what they do.
Texttools pathnames are defined in this package. A path is a Str255 string. The OS package can define path prefixes, beginning with a "$". For example, "$HOME" is predefined as the user's home directory. To delete a file called "temp.txt" from the user's home directory, you can use the OS erase command:
Erase( To255( "$HOME/temp.txt" ) );
$SYS is another predefined prefix. This refers to a directory in the user's home directory named with the "short name" you specify in the StartupCommon procedure. Sounds, keyboard macros and the session_log file are located here.
Thermometer
ScrollBar
StaticLine
EditLine (and family)
CheckBox
RadioButton
WindowButton
Rectangle
Line
HorizontalSep
VerticalSep
StaticList
CheckList
RadioList
EditList
SourceCodeList (used by PegaSoft's TIA)
OpenWindow - this procedure creates a new window. Each window has a title, coordinates on the screen, a "style", and an optional info bar.
AddControl - adds a control to the current window. If IsGlobal is false, the coordinates you specified in the control's Init call will be treated as relative to the top-left corner of the window, as opposed to the top left corner of the screen.
CloseWindow - closes the last window you created
DoDialog - this procedure displays the window and handles all interaction between the user and the window. It has one parameter, ADialogTaskRecord, which lets you set up callbacks (if necessary) and returns the number of the control which terminated the dialog.
Windows can be saved using the SaveWindow command, and loaded again using LoadWindow. When a window is loaded with LoadWindow, you don't need to open the window or set up the controls--the Window Manager does this automatically for you.
ShellOut will close the windows, run a shell command, and reopen the windows.
RefreshDesktop will redraw all the windows on the screen.
SetWindowTimeout will set a default control to be selected if there is no response after a certain amount of time.
Alerts are small windows that show a short message.
NoteAlert - displays a message with an "OK" button. The status sound is played, if installed.
CautionAlert - displays a message with an "OK" button. The text is drawn to emphasize the message. The warning sound is played, if installed.
StopAlert - displays a message with an "OK" button. The text is drawn to emphasize the message. The warning sound is played, if installed.
YesAlert - display a message with "yes" (default) and "no" buttons. Plays an optional sound.
NoAlert - display a message with "yes" and "no" (default) buttons. Plays an optional sound.
CancelAlert - display a message with cancel button and a customized button (default). Plays an optional sound.
YesCancelAlert - display a message with "yes", "no", and "cancel" buttons and returns the number of the button selected. Plays an optional sound.
Example:
NoteAlert( "The database has been updated" );
SelectOpenFile - displays a dialog for opening files. It has one parameter, ASelectOpenFileRec. You have to fill in certain details before displaying this window.
SelectSaveFile - displays a dialog for saving files. It has one parameter, ASelectSaveFileRec. You have to fill in certain details before displaying this window.
ShowListInfo - displays a Str255List list in a window
EditListInfo - displays a Str255List list in a window and let's the user edit the list.
Example:
sof : ASelectOpenFileRec;
...
sof.prompt := To255( "Select a file to open" );
sof.direct := false; -- can't select directories
SelectOpenFile( sof );
if sof.replied then
FilePath := sof.path & "/" & sof.fname;
else
-- user cancelled
end if;
Every control must be initialized with the Init procedure. Init positions the control in the window and assigns a "hot key", a short cut key for moving to the control.
You can turn a control off (make it unselectable) using SetStatus. Setting the control's status to Standby will make it selectable. Some controls are automatically turned off, such as the static line control.
The following controls can be used in a TextTools window:
Thermometer - This is a thermometer bar graph. It shows the percentage between the maximum value and the current value, and is filled based on the percentage.
ScrollBar - This is a scroll bar. A thumb is drawn at the relative location of the thumb value to the maximum value of the bar. The bar will be horizontal or vertical depending on the shape specified in the Init procedure.
StaticLine - This is an unchanging line of text.
EditLine (and family) - This is an editable line of text.
SimpleButton - This is a button that, when selected, terminates the dialog.
CheckBox - A check box is an option which may be turned on or off.
RadioButton - A radio button is one of a set of options which may be turned on or off. Every radio button has a family number defined in the Init procedure. When a radio button is turned on, all other buttons in the family are turned off.
WindowButton - Loads a window from disk and displays it. The window must have been saved with the Window Manager's SaveWindow procedure.
Rectangle - A box which can be drawn around controls.
Line - A line--what else would it be--drawn between two corners of the enclosing rectangle defined by the Init procedure.
HorizontalSep - A horizontal line, often used to separate controls into groups.
VerticalSep - A vertical line, often used to separate controls into groups.
StaticList - A scrollable box of unchanging text.
CheckList - A scrollable box of check boxes.
RadioList - A scrollable box of radio buttons.
EditList - A scrollable box of editable text.
SourceCodeList (used by PegaSoft's TIA) - A scrollable box containing source code.
This package contains various calls for working with the operating system. All calls support path prefixes as described above. Here are some of the subprograms:
UNIX - run a UNIX shell command. The function variations return the result of the command.
RunIt - runs a UNIX program.
ValidateFilename - check for a syntactically correct filename.
NotEmpty - true if a file is not empty
IsDirectory - true if file is a directory
IsFile - true if file is a "regular" file
MakeTempFileName - creates a random file name for a temporary file
Erase - deletes a file
LoadList - load a Str255List list from a file
SaveList - save a Str255List list to a file
MyID - return the PID for your program
SessionLog - write to the session log. If a $SYS directory exists, SessionLog creates a file called "session_log" in that directory. All SessionLog calls write to this file.
The UserIO package handles all the input and output for TextTools. Unless you are writing a game or new controls, you'll probably won't need to use UserIO at all. However, there are a few useful subprograms to be aware of:
Beep - play a .wav file. Requires Warren Gay's wavplay program. These files must be saved in the $SYS directory, with the name of the beep sound in upper case.
Keypress - get a keypress
DrawErr - draw an error message. DrawErr draws the text on the left-side screen in white. Use only for emergencies.
GetDisplayInfo - retrieve information about the current screen, such as whether it supports colour, and it's dimensions. Use this information to resize your windows for different screens.
Example:
Beep( Startup ); -- play startup sound
UserIO will load a set of keyboard macros at startup. These must be saved in the $SYS directory, in a file called macro_file. The first letter of each line is the key for the macro, and the rest of the line is the expanded macro. For example, if a line in macro_file contained
pPegaSoft
then typing control-A followed by "p" would put the word "PegaSoft" in the input queue as if the person had typed "PegaSoft".
Most of the objects on the screen should be easily understood, the majority designed after their GUI counterparts. Here is a list:
Buttons with hyphens in them are not selectable.
For more detailed information, consult the TextTools reference manual.
End of Document