RAPID Users' Guide

RAPID is the Rapid Ada Portable Interface Design Tool.  It was originally implemented by  Dr. Martin C. Carlisle of the  United States Air Force Academy  Department of Computer Science. Since its initial release in November 1998, several people have contributed to the design and implementation of the tool.  In particular, RAPID 2.0 was made possible by significant contributions of W. Blair Watkinson II.  Look under Help/About in RAPID for a list of contributors.

This page is intended to provide some basic information about using RAPID.  It is often hard as the implementer to know what things will be unclear to users.  If you have suggestions on how to improve this page, send them to the current maintainer.

A good start is to look at the Original RAPID paper (postscript) presented at SIGAda '98.  This contains some basic information on how to use RAPID as well as more detailed information on the implementation.

Follow these links to:
Starting RAPID
Using the widgets
Editing the window
Working with menus
Main program information
New features in RAPID 3.3

RAPID Tutorial:  Click here for a step-by-step description of how to make a small RAPID application.

Starting RAPID
When you first open RAPID, you will see a window that looks like the following:

At this point, the user should either open an existing .gui file (using the open file button or menu choice) or create a new one (using the new button or menu choice).

Alternatively, you can specify the name of a .gui file on the command line (or even set it so that RAPID opens when you double-click on a .GUI file in some windowing systems, including Win 95/98/NT). This feature is NOT implemented in the JVM version.

For each application developed using RAPID, the user should name exactly one window "main".  The main window is the controlling window for the application, and when this window is closed, the application will exit. The name of a window is changed using the Modify Window choice from the Edit menu. When you create a new window, the dialog will ask for a window name.  Note that your application may contain multiple windows.  Each window is designed using a separate session of RAPID.  Make sure that you name one window "main"-- you may use any name you wish for the other windows of your application.

Using the widgets

All of the following widgets are selectable on the toolbar.  Push a button to select which kind of widget to create. (Note on the JVM version the button does not seem to stay depressed, but instead the button that is drawn without a border indicates which type of widget is currently selected). Then in the window below, while holding down the left mouse button, draw a rectangle where you want the widget to appear. The size and location of this rectangle will be the size and location of the new widget.   Following this, a dialog will appear asking you to fill in properties for the widget.  You must fill in all of the properties. If you do not, and press ok or apply, you will hear a beep and the cursor will move to an invalid property. Each widget must have a name.  To pick a name, follow the rules for Ada identifiers.  Most widgets have helpful procedures/functions in the Mcc.Tki packages.

After a widget has been drawn, you can click and drag it to move it.  Also, if you click it, resizing buttons will appear.  Finally, right-clicking the widget reopens the properties dialog for that widget.  Some widgets also have the ability to select a font.  In this case, there will be a change font button that brings up a dialog like the following.  You may either select a font, or choose "select default" and allow the GUI to use the standard font for that widget.

Following are the widgets currently supported in RAPID:

Text label.  This has text, justification (left, right or center), foreground color and background color.  For colors, you may enter the name of a common color (e.g. "red").  These are found in Mcc.Tki.Colors.  It should be relatively straight-forward to add other colors to the enumeration type (this requires recompiling RAPID).  You may also type "default", which yields default behavior.
Text button.  This has text and an action.  An action is any Ada code that would be valid inside a begin/end block.  If it begins with an identifier, an appropriate "with" clause will be generated for the first identifier if it is fully qualified (i.e., if you specify "File_Menu.New_Choice" as an action, a "with" clause for File_Menu will be generated automatically).  You must then write a package called File_Menu (both spec and body), containing a procedure called "New_Choice".  The spec for New_Choice must be as follows:

procedure New_Choice(Obj : in out Mcc.Tki.Widget.Button.Button'Class);

Picture button.  Same as above, but instead of text, has a picture (which should be the name of a GIF file).  Additionally, the user can specify a tooltip, which will appear after the mouse has rested over the button for a brief period of time.
Single line text entry.
Check button.  Allows the user to turn on/off the check button.  Has a text label.
Radio button-- the radio button is unique among widgets as it comes in groups.  Only 1 radio button may be selected at a time.  The user must enter the group name along with the widget name.
Listbox with optional scrollbars.  A list of items.  User can select foreground color and background color.  Also can select whether or not to have a vertical or horizontal scrollbar.  Add and delete entries from the listbox (or query which is selected) using the utilities in Mcc.Tki.Widget.Listbox.  If an invalid color is chosen, you will be prompted to reenter.
Scale widget.  Creates a slider which is used to enter a value from a discrete range.
Progress bar.  Used to mark progress of an operation (between 0.0 and 1.0).  User can select foreground color and background color (see Text label for a discussion of colors).  If an invalid color is chosen, you will be prompted to reenter.
Dropdown list.  Used to select from a list of items when real estate is sparse (list only appears when button is pushed).  User can select foreground color and background color (see Text label for a discussion of colors).  Also can specify how many rows will appear when list is displayed.  Add and delete items from the list (or query which is selected) using utilities in Mcc.Tki.Widget.Dropdown.

Editing the window
With a window open, you can not only create new widgets by clicking and dragging, and can also perform the following actions:

• Select a widget by clicking on it.  Use Ctrl + left mouse to select multiple.
• With a single widget selected, use the 9 handles to resize
• Move a single widget or multiple widgets in lock-step by clicking and dragging it (them)
• Delete all selected widgets using Del, the cut button, or the menu choice
• Resize the window by clicking and dragging the black rectangle in the lower right corner.

Working with menus
If you push the "Menu" button, you will see a screen like the following:

From this screen, you can add submenus (followed by "*") or choices.  In the bottom right corner, we select whether to insert inside the menu as its first entry, or after the menu if a we insert when a menu is highlighted.  Insertions always occur after the highlighted entry.  The MENUBAR entry is a dummy entry that allows you to insert before the first menu.

If we insert, we get a dialog with the properties.  The user must enter the name of the menu (what is displayed), its action (Ada code-- see the discussion of Text buttons in  Using the widgets  above-- the only difference here is that the procedure is required to have no parameters), an underline position (which character is underlined, use 0 for no underline, 1 to underline the first character, 2 for the second, etc.), and a shortcut.  Shortcuts should look like "Ctrl+X", to indicate that Ctrl+X also activates this menu item.

Once finished, push "Done" and you will see the menu above the editing area.

Main program

The compile button generates Ada code to implement the designed GUI.  Note this compiles the GUI to Ada-- it does not compile the Ada. If your window is called "hello_world", then "hello_world_window.ads" and "hello_world_window.adb" will be created. Recall you MUST have one window named "main" (which, when compiled, yields "main_window.ads" and "main_window.adb"). Then, the user must write the rest of the program, including a main program, which should look like the following:

with Main_Window;
with Mcc.Tki.Container.Window;

procedure Demo is

begin
   Main_Window.Generate_Window;
   Mcc.Tki.Container.Window.Event_Loop;
end Demo;

Each window is then opened by calling its Generate_Window procedure.  Callbacks occur when buttons are pushed, menu items selected, etc.  See  Using the widgets above for more information.

The packages in the Mcc.Tki hierarchy contain useful functions for interacting with RAPID generated widgets.  For example, Mcc.Tki.Widget.Text_Entry contains methods for setting and reading the text entry, among others.

News and new features for RAPID 3.3

• This release is only tested in the Tcl/Tk configuration.
• Fixed bug in the GUI file format for ITEM, DROPDOWN, TEXTENTRY, TEXTBOX
• Added support for giving multiple gui file names on the command line when in non-interactive mode (-ni)
• Fixed bug whereby Ada files were generated to the GUI file directory instead of the current working dir in non-interactive mode
• In non-interactive mode, new command line switch -od lets user choose different output directory for code generation
• New WINDOW kind FRAME_CHILD lets window act as child to existing FRAME
• Added support for referencing DROPDOWN and TEXTENTRY Ada types/items from child packages
• An Ada action callback for a MENU button may be declared without reference to another package. In this case, the subprogram is declared separate within the current generated package body
• The Ada type for a TEXTENTRY data item may now be STRING_SUBTYPE. Appropriate filling/truncation is generated for converting to/from the fixed string.
• WINDOW has new attribute ACCESSIBILITY which can be set to READ_ONLY to suppress generation of procedure Read_Window
• Ada type of TEXTENTRY variable can now be any signed or modular type
• Generated procedures Fill_Window, Generate_and_Fill_Window, Close_Window, Read_Window can now be used as button action callbacks
• New window feature Snap to Grid facilitates aligning widgets
• New generated procedure Ok calls Read_Window and if successful then calls Close_Window. This is useful for implementing OK buttons.

• This release is only tested on Linux and it does not contain a Windows exe.
• The jvm_peer, msil_peer, and gwindows_peer backends are not included in this release as they are not maintained at this time (March 2009.) If you wish to study these backends, please refer to the directories in tags/rapid-3.01 of the RAPID Subversion repository.
• tcl_peer is updated for Tcl/Tk versions 8.{4,5,6a} and TASH version 8.6-0
• gtk_peer is updated for gtk+-2.{10,12,14} and GtkAda from the libre svn trunk of Jan 2009
• GUI file format maintains backward compatibility with RAPID 3.01
• New command line switch -ni supports non-interactive Ada code generation for a given .gui file. Example:
  ./rapid -ni myfile.gui
  will produce myfile_window.{ads,adb} without launching the RAPID GUI.
• New widget: FRAME, for creating an empty space with a border around it
• New widget: TEXTBOX, similar to TEXTENTRY but for multi-line text, supports optional user variable of type Ada.Strings.Unbounded.Unbounded_String
• TEXTENTRY now also supports unsigned user types
• CHECKBUTTON optional user variable can now be any two-valued enum type in addition to Boolean. The first value is interpreted as OFF, the seconds as ON.
• The procedures Fill_Window,Generate_and_Fill_Window,Read_Window are not created if they are null operations. In other words, they are only created if there are user variables to read or write.

Rapid 3.0 adds the following new functions and procedures to every generated window (note all RAPID 3.0 changes should be backward compatible with versions 2.0 and higher):

• Is_Open added to Mcc.Gui.Container.Window returns a boolean indicating whether the window is currently open
• Already_Open exception is raised if Generate_Window is called a second time before the window is closed
• Close_Window is equivalent to Mcc.Gui.Container.Window.Destroy, but takes no arguments
• Fill_Window fills in the Check Buttons, Dropdown lists, and Text_Entries using global variables specified in window design.  See next paragraph for more details.
• Generate_and_Fill_Window is equivalent to Generate_Window followed by Fill_Window
• Read_Window reads the Check Buttons, Dropdown lists and Text_Entries into global variables specified in window design.  See next paragraph for more details.

RAPID 3.0 now allows you to specify fully qualified variables (i.e. globals with the package name specified) that will be used to read/write the values of Check buttons, Dropdown lists and Text_Entries as follows:

For Check buttons:  you may specify a boolean variable which when Fill_Window is called will be used to set whether or not it is checked, and when Read_Window is called will be set with whether or not it is checked.  Leaving this blank means the Check button will not be filled in or have its value read out automatically.

For Dropdown lists:  you may specify both an enumeration type and a variable.  If an enumeration type is specified, then the dropdown list is filled in with its values when created.  If a variable is given, this variable will be used by Fill_Window and Read_Window to fill in/read out the value.  Note you may specify a type without specifying a variable.

For Text_Entries:  you may specify a data item (variable), its base type (float_1, float_2, float_3, float_e indicate how many spaces after the decimal point, or exponential notation), and (optionally) a data type (if you wish to add range checking, e.g.).  The data type has no effect if the base type is Unbounded_String.  These are used by Fill_Window and Read_Window to fill in/read out the value.  Note that Read_Window has two additional parameters, beep_on_error and highlight_error.  If beep_on_error is true, a beep will occur on a constraint error (failed range check), and if highlight_on_error is true, the offending entry will be highlighted (only the first error detected).