Big Online Book of Linux Ada Programming

15 Free Ada Bindings

15.1 Using Florist, the POSIX binding

Florist (Florida Statue University/Forest) is a GPL binding of the POSIX (IEEE Standard 1003.5b-1996) standard operating system functions. These include file operations, date and time functions, and multitasking—the same kinds of function provided by the standard C libraries and the Linux kernel.

If you are writing an application that will run on several different operating systems, Florist provides a level of operating system independence. Once you install gnat and Florist on your new platform, you should be able to recompile a Florist application without having to worry about variations in system calls.

Florist is designed for gnat and runs on Linux as well as Solaris, OFS1, AIX, IRIX and HP-UNIX. Florist works closely with the gnat run-time system: you must compile Florist against a particular gnat installation. If you change your gnat installation, you will need to recompile Florist.

Older versions of Florist for Gnat 3.11 work best with a version of Gnat compiled for FSU threads. Native threads require some patching to work, and not all Florist features are supported--see the Florist documentation for details. For more information on FSU threads, read the multitasking section above.

Newer versions of Florist, such as the ALT RPM, works with the normal (native threads) version of Gnat.

Commercial support for Florist is available form ACT.

Because the Linux kernel largely adheres to the POSIX standard, many of Florist functions have the same parameters as their Linux counterparts.

Florist divides the POSIX functions into a set of 73 Ada packages, all prefixed with the name "posix". The main package is called "posix.ads" and contains the definition of data types and many of the basic POSIX functions.

To write Florist applications, you'll need to link in the Florist library with "-lposix" (check?) and, if necessary, use "-I" to indicate where you've installed the package specifications.

15.2 Using Texttools

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.

This is the same package used to implement TIA.

[to be rewritten—KB]

15.2.1 Installation

1. In the C_code directory, type "gcc -O -c *.c" to compile the C files.

2. The Ada files should compile when you build your project with Gnatmake. If TextTools are installed in a different directory than your project, you will need to use the gnatmake -I switch.

When linking, you'll need to include the "-lm" and "-lcurses" switches as well as the object files from C_code. TextTools uses the C math library and ncurses 4.0. For example,

gnatlink -lm -lncurses C_code/*.o ...

15.2.2 Introduction

Although there are over 600 procedures and functions in TextTools, to open window is fairly uncomplicated.

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

-------------------------------------------------------------------

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

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

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

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

15.2.7 Other Predefined Windows

SelectOpenFile - displays a dialog for opening files. It has parameter, ASelectOpenFileRec. You have to fill in certain 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.

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

15.2.11 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

15.3 Using NCurses

Ncurses is a free toolset for drawing on text screens, such as the Linux console.

[not finished]

15.4 Using GTK+ Widgets

GTK+, the Gimp ToolKit, is a widget set (or sometimes called a control set). These are the same widgets used by the Gimp drawing program. Unlike Motif and QT widgets, GTK+ uses an LGPL license, making it very popular for new Linux software, include the GNOME desktop project.

GTK+ also contains 2D drawing operations.

GTK+ is available for download from the GTK web site at http://www.gtk.org.

GtkAda can be downloaded from the ALT web site, or from its home page at http://ada.eu.org/gtkada/.

GtkAda is an Ada95 binding of Gtk+ version 1.2.0. It allows you to develop graphical applications in Ada95 using Gtk+. General GTK+ documentation and a tutorial written with examples in C are available from the GTK web site.

[not finished]

15.5 Using Motif Widgets

Motif (pronounced "Moe-Teef") is an X Windows widget standard created by the Open Software Foundation (OSF), a group of several UNIX companies. Motif is built for the stanadard X Windows library Xt. With Motif, you can create windows and dialog boxes menus, buttons, scrolling lists and the like. Motif is a registered trademark of OSF.

LessTif (pronounced "Less-Teef") is an open source compatible version of Motif 1.2 with some extensions, licenced under LGPL. It is available for download from the LessTif web site at http://www.lesstif.org. This site also includes documentation on compiling and installing LessTif.

There are no Ada bindings for LessTif, but there are Ada bindings for Motif which should work equally well for Lesstif. The bindings are available from the Home for Brave Ada Programmers, http://www.adahome.com.

Motif (and LessTif) have not proven to be very popular. Motif programs tend to be very large, with widgets layouts that are difficult to design, and have a heavy reliance on Motif's cumbersome resource files. Even small Motif programs typically require contain several hundred lines of source code to set up their initial window. Toolsets such as Qt (used in KDE) and GTK+ (used in GNOME) have larger followings, and Motif support is primarily for older applications being ported to Linux.

However, Motif, as a standard, is continuing to evolve.

15.6 Using the TCL Binding

TASH (Tcl Ada SHell) is a binding to TCL/TK. It includes both a thin binding to the basic TCL/TK functions (as found in the C header file tcl.h), as well as versions of the functions made for easier calling from Ada. The binding supports TCL 8.0

http://tash.calspan.com/

TASH also comes with its own TCL shell interpreter which functions like tclsh but is written in Ada.

You can use Mesa under GTK+ by using a GTK+ "GL Area" widget and draw graphics inside using Mesa.

15 Free Ada Bindings

15.1 Using Florist, the POSIX binding

15.2 Using Texttools

15.2.1 Installation

15.2.2 Introduction

15.2.4 Window Overview

5.2.5 Other Useful Window Manager Subprograms

15.2.6 Alerts

15.2.7 Other Predefined Windows

15.2.10 UserIO Overview

15.2.11 Appearance and Keys

15.3 Using NCurses

15.4 Using GTK+ Widgets

15.5 Using Motif Widgets

15.6 Using the TCL Binding

15.7 Using the OpenGL/Mesa Binding

15.8 Engine_3D