/usr/share/doc/libtexttools-doc/usermanual.html

<html>
<head>
<title>TextTools User Manual</title>
</head>
<body bgcolor="#FFF0F0">
<h2>TextTools 2.0</h2>

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

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

<p>TextTools is written in Ada 95 and C.  You'll need to download the
Gnat compiler to use TextTools.


<h3>RECENT CHANGES</h3>

<p>The change logs are now online at the PegaSoft Linux Cafe
http://www.pegasoft.ca/docs/discus/index.html.

<p>Partial C++ support added.


<p>If you're looking to contribute to the Texttools project, here are
some outstanding jobs that need to be done:

<ol>
<li>A GUI Window Editor should be written.  Texttools is designed to
load windows saved as a file.</li>

<li>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.</li>

<li>Regions and clipping need to be implemented to allow writing to
windows other than the top window.</li>

<li>Support for AU sounds should be added.</li>

<li>Support for modification keys (control, alt, etc) on mouse clicks
should be added.</li>

<li>Resizing by SIGWINCH isn't finished, primarily because of the
tasking problems in the ALT version of Gnat.</li>

<li>Multiline text pasting sometimes crashes on small files (or is
it because of pasting at the end of the text?) in EditList's.</li>
</ol>

<h3>INSTALLATION</h3>

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

<p>The cpp directory contains C++ examples.
<p>The examples directory contains Ada examples.


<h3>USING TEXTTOOLS IN YOUR OWN PROJECTS</h3>

<ol>
<li>If TextTools are installed in a different
directory than your project, you will need to use the
gnatmake -I switch.</li>

<li>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.</li>
</ol>


<h3>INTRODUCTION</h3>


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

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

<p>The following program opens a simple window.

<hr>

<pre>
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;
</pre>
<hr>

<h3>PACKAGE OVERVIEW</h3>

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

<ul>
<li><b>Common</b> - 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:

         <ul>
         <li>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.</li>

         <li>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.</li>

         <li>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.</li>
         </ul>
</li><li>
<b>OS</b> - this package contains subprograms for working with the Linux
         operating system: that is, for reading the current
         time, deleting files, and the like.

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

         <pre>Erase( To255( "$HOME/temp.txt" ) );</pre>

         <p>$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.
</li><li>

<b>UserIO</b> - 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.
</li><li>

<b>Controls</b> - this package contains all the window controls and
         related subprograms.  Currently defined controls are:

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

<b>Windows</b> - 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.
</li>
</ul>

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.


<h3>WINDOW OVERVIEW</h3>

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

<p>OpenWindow - this procedure creates a new window.  Each window has
   a title, coordinates on the screen, a "style", and an optional
   info bar.

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

<p>CloseWindow - closes the last window you created

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


<h4>Other Useful Window Manager Subprograms</h4>

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

<p><b>ShellOut</b> will close the windows, run a shell command, and reopen
the windows.

<p><b>RefreshDesktop</b> will redraw all the windows on the screen.

<p><b>SetWindowTimeout</b> will set a default control to be selected if there
is no response after a certain amount of time.


<h4>Alerts</h4>

<p>Alerts are small windows that show a short message.

<p>NoteAlert - displays a message with an "OK" button.  The status sound
  is played, if installed.
<p>CautionAlert - displays a message with an "OK" button.  The text is drawn
  to emphasize the message.  The warning sound is played, if installed.
<p>StopAlert - displays a message with an "OK" button.  The text is drawn
  to emphasize the message.  The warning sound is played, if installed.
<p>YesAlert - display a message with "yes" (default) and "no" buttons.
  Plays an optional sound.
<p>NoAlert - display a message with "yes" and "no" (default) buttons.
  Plays an optional sound.
<p>CancelAlert - display a message with cancel button and a customized
  button (default).  Plays an optional sound.
<p>YesCancelAlert - display a message with "yes", "no", and "cancel"
  buttons and returns the number of the button selected.  Plays an
  optional sound.

<p>Example:

   <pre>NoteAlert( "The database has been updated" );</pre>


<h4>Other Predefined Windows</h4>

<p>SelectOpenFile - displays a dialog for opening files.  It has
  one parameter, ASelectOpenFileRec.  You have to fill in certain
  details before displaying this window.
<p>SelectSaveFile - displays a dialog for saving files.  It has
  one parameter, ASelectSaveFileRec.  You have to fill in certain
  details before displaying this window.
<p>ShowListInfo - displays a Str255List list in a window
<p>EditListInfo - displays a Str255List list in a window and let's
  the user edit the list.

<p>Example:

<pre>
   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;
</pre>

<h3>CONTROL OVERVIEW</h3>

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

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

<p>The following controls can be used in a TextTools window:

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

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

<p>StaticLine - This is an unchanging line of text.

<p>EditLine (and family) - This is an editable line of text.

   <ul>
   <li>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.</li>

   <li>BlindMode - if set, hides the characters typed.  This is
   useful for typing in passwords.</li>
   </ul>

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

   <ul>
   <li>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.</li>
   </ul>

<p>CheckBox - A check box is an option which may be turned on or off.

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

<p>WindowButton - Loads a window from disk and displays it.  The window must
   have been saved with the Window Manager's SaveWindow procedure.

<p>Rectangle - A box which can be drawn around controls.

<p>Line - A line--what else would it be--drawn between two corners of the
   enclosing rectangle defined by the Init procedure.

<p>HorizontalSep - A horizontal line, often used to separate controls into groups.

<p>VerticalSep - A vertical line, often used to separate controls into groups.

<p>StaticList - A scrollable box of unchanging text.

<p>CheckList - A scrollable box of check boxes.

<p>RadioList - A scrollable box of radio buttons.

<p>EditList - A scrollable box of editable text.

<p>SourceCodeList (used by PegaSoft's TIA) - A scrollable box containing source code.


<h3>OS Package</h3>

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


<p>UNIX - run a UNIX shell command.  The function variations return
  the result of the command.
<p>RunIt - runs a UNIX program.
<p>ValidateFilename - check for a syntactically correct filename.
<p>NotEmpty - true if a file is not empty
<p>IsDirectory - true if file is a directory
<p>IsFile - true if file is a "regular" file
<p>MakeTempFileName - creates a random file name for a temporary file
<p>Erase - deletes a file
<p>LoadList - load a Str255List list from a file
<p>SaveList - save a Str255List list to a file
<p>MyID - return the PID for your program
<p>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.


<h3>UserIO Overview</h3>
<p>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:

<p>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.
<p>Keypress - get a keypress
<p>DrawErr - draw an error message.  DrawErr draws the text on the left-side
screen in white.  Use only for emergencies.
<p>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.

<p>Example:
  <Pre>Beep( Startup ); -- play startup sound</pre>

<h4>Keyboard Macros</h4>

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

  <pre>pPegaSoft</pre>

<p>then typing control-A followed by "p" would put the word "PegaSoft"
in the input queue as if the person had typed "PegaSoft".


<h4>Appearance and Keys</h4>

<p>Most of the objects on the screen should be easily understood, the
   majority designed after their GUI counterparts. Here is a list:
  
   <ul> 
   <li><tt>&lt; &gt; Text</tt> - A button. Press Return to activate. Type the hilighted
   letter to go immediately to this button.</li>
   <li><tt>| &gt; Text</tt> - An menu button. Enter Return to activate. Type the
   hilighted letter to immediately activate.</li>
   <li><tt>( ) Text</tt> - A radio button. Press Return to select this item and
   deselect the previous item in the group.</li>
   <li><tt>[ ] Text</tt> - A check box. Press Return to switch on or off.</li>
   <li><tt>-----#-------</tt> - A scroll bar.</li>
   <li><tt>-----50%-----</tt> - A thermometer graph.</li>
   </ul>
   
   <p>Buttons with hyphens in them are not selectable.
   
<h4>Basic Keyboard Shortcuts:</h4>
   
<h5>Movement Keys</h5>

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

   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.
   
<h5>Editing Keys</h5>

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

<h5>Misc. Keys</h5>
  
<ul> 
<li>ESC Key (or F1) - bring up the accessories menu</li>
   
<li>Control-L - redraw the screen</li>
   
<li>Control-A (or F2) - execute a keyboard macro</li>
</ul>

<p>For more detailed information, consult the TextTools reference manual.

<p>End of Document
</body>
</html>
libtexttools-doc 2.1.0-10 / usr / share / doc / libtexttools-doc / usermanual.html
