TextTools User 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 use TextTools.

### RECENT CHANGES

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:

1. A GUI Window Editor should be written. Texttools is designed to load windows saved as a file.
2. The Window Manager should be rewritten to use tagged record features when working with controls. The enumerated control type should be discarded so users can create their own controls using child packages.
3. Regions and clipping need to be implemented to allow writing to windows other than the top window.
4. Support for AU sounds should be added.
5. Support for modification keys (control, alt, etc) on mouse clicks should be added.
6. Resizing by SIGWINCH isn't finished, primarily because of the tasking problems in the ALT version of Gnat.
7. Multiline text pasting sometimes crashes on small files (or is it because of pasting at the end of the text?) in EditList's.

### INSTALLATION

1. Install the GNAT compiler (or in GCC 3.1 or newer, make sure Ada is enabled).
2. Edit C_code/curses.c If you are using NCURSES3, uncomment the NCURSES3 define. If using NCURSES4, comment out the NCURSES5 define.
3. Type "make" in the topmost Texttools directory.
4. Test the examples by running them. (Note: Red Hat's console is not fully VT-102 compatible. Use xterm instead.)

The cpp directory contains C++ examples.

The examples directory contains Ada examples.

### USING TEXTTOOLS IN YOUR OWN PROJECTS

1. If TextTools are installed in a different directory than your project, you will need to use the gnatmake -I switch.
2. When linking, you'll need to include the "-lm" and "-lcurses" switches. TextTools uses the C math library and ncurses 3.x, 4.x or 5.x.

### INTRODUCTION

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;

### PACKAGE OVERVIEW

TextTools is broken into 5 main packages, based on what they do.

- Common - this package contains all the basic data types used by TextTools, plus subprograms that work with those types. In particular, two important types are defined:
  - Str255 - most TextTools subprograms use this bounded, 255 character string type instead of the standard Ada fixed strings. The function To255 converts an Ada string to a Str255. ToString converts in the other direction.
  - Str255List - some list controls display a block of text. These controls use the Str255List.List type, a linked list of Str255 strings. The subprograms for this type are defined the generic package gen_list.
  - Most TextTools calls do not return errors. There are some exceptions, such in the OS package. Error numbers are returned in the LastError variable. LastError is 0 if there is no error.
- OS - this package contains subprograms for working with the Linux operating system: that is, for reading the current time, deleting files, and the like.

  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.

- UserIO - this package contains all the input/output routines for TextTools: it handles mouse clicks, draws text, and so forth. Normally, only people writing controls will need access to this package. However, the pen colours, beep sounds and text styles, are also defined here.
- Controls - this package contains all the window controls and related subprograms. Currently defined controls are:

  Thermometer
  ScrollBar
  StaticLine
  EditLine (and family)
  CheckBox
  RadioButton
  WindowButton
  Rectangle
  Line
  HorizontalSep
  VerticalSep
  StaticList
  CheckList
  RadioList
  EditList
  SourceCodeList (used by PegaSoft's TIA)

- Windows - this is the window manager. It creates and draws windows, and DoDialog procedure lets a user interact with the window. It also handles the "Accessories" window that appears when ESC is pressed.

Each package is started with a "Startup" procedure, and shutdown with a "Shutdown" procedure. The only procedure to take parameters is StartupCommon: you need to specify a program name and a short name to use for temporary files.

### WINDOW OVERVIEW

The Window Manager draws all the windows on the screen. For simple programs, you will need to use only four Window Manager procedures.

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.

#### Other Useful Window Manager Subprograms

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

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

#### Other Predefined Windows

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;

### CONTROL OVERVIEW

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.

- AdvanceMode - if set, the cursor will move to the next control when the edit field is full. This is useful in business applications where fixed-length product numbers are typed in.
- BlindMode - if set, hides the characters typed. This is useful for typing in passwords.

SimpleButton - This is a button that, when selected, terminates the dialog.

- Instant - if set, the button acts like a menu item. Pressing the hot key will immediately select the button and terminate the dialog. Otherwise, pressing the hot key only moves the cursor to the button.

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.

### OS Package

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.

### UserIO Overview

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

#### Keyboard Macros

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

#### Appearance and Keys

Most of the objects on the screen should be easily understood, the majority designed after their GUI counterparts. Here is a list:

- `< > Text` - A button. Press Return to activate. Type the hilighted letter to go immediately to this button.
- `| > Text` - An menu button. Enter Return to activate. Type the hilighted letter to immediately activate.
- `( ) Text` - A radio button. Press Return to select this item and deselect the previous item in the group.
- `[ ] Text` - A check box. Press Return to switch on or off.
- `-----#-------` - A scroll bar.
- `-----50%-----` - A thermometer graph.

Buttons with hyphens in them are not selectable.

#### Basic Keyboard Shortcuts:

##### Movement Keys

- Up/Down Arrow - move up or down to the next menu item
  - in lists - move up or down one line in the list
  - in scroll bars - adjust up or down by 10%
- Left/Right Arrows - move left or right to the next menu item
  - in lists - move up or down one line in the list
  - in scroll bars - adjust up or down by 1
- Page Up (or Control-P) - move up one page in a list
  - in scroll bars - same as up and down arrows
- Page Down (or Control-N) - move down one page in a list
  - in scroll bars - same as up and down arrows
- Home Key (or Control-Y) - move to the top of a list
  - in scroll bars - go to the top
- End Key (or Control-E) - move to the bottom of a list
  - in scroll bars - go to the bottom
- Tab Key - move to the next item in the window
- Control-T - move to the previous item in the window
- Return Key (or Spacebar) - activate a button

When inside of a list box, the movement keys move you around the list. If you are on the Linux console, pressing alt and the hilighted letter will always jump to the appropriate object, even if you're inside a list box or the notepad.

##### Editing Keys

- Control-6 - mark text * only works in edit lists
- Control-X - clear text * in lists, clear the current line (or lines, if control-6 used)
- Control-B - copy text * in lists, copy the current line (or lines, if control-6 used)
- Control-V - paste text * in notepad, paste the last line copied

##### Misc. Keys

- ESC Key (or F1) - bring up the accessories menu
- Control-L - redraw the screen
- Control-A (or F2) - execute a keyboard macro

For more detailed information, consult the TextTools reference manual.

End of Document