JEWL.IO User Manual

This document is part of the JEWL library, copyright © John English 2000. The JEWL library is released for public use under the terms of the GNU General Public License, and may be freely copied, distributed, used and modified under the terms of that license. Suggestions, comments, bug reports and modifications should be reported to the author <je@brighton.ac.uk>.

Contents

1. Introduction
2. Non-GUI input and output facilities
3. String input
4. Input of standard types
5. Generic input facilities
6. Message boxes
7. File dialogs

1. Introduction

JEWL (John English's Window Library) is a collection of Ada packages aimed at novices which enables reasonably sophisticated GUI applications to be built with a minimum of effort. The packages are designed to be platform-independent, but at present the only implementation is for Microsoft Windows. The examples in this document are all based on the Windows implementation.

JEWL.IO is a package which is a more-or-less direct replacement for the standard package Ada.Text_IO and its relations Ada.Integer_Text_IO and Ada.Float_Text_IO, which means that traditional text-based programs can be converted to GUI-based programs with a minimum of effort. JEWL.IO uses GUI dialogs for input, and all input is also echoed to the standard output. This means that the input part of any program can be made to use GUI dialogs, while output will still be written to the text-based standard output. The fact that all input is echoed to the standard output means that the output log will exactly mirror an equivalent program whose input is completely text-based.

JEWL.IO also contains some additional facilities: for example, facilities for generating error messages and other user alerts as message boxes (which are also echoed to the standard output); functions to convert data to strings and to concatenate strings to simplify data output; and generalisations such as the provision of Put_Line procedures for types other than strings.

JEWL.IO provides similar facilities to Ada.Text_IO together with some new features:

• Input and output of standard types: String, Character, Integer, Float and Boolean
• Input and output of new types and subtypes: enumeration types, integral types and floating point types
• Type conversions from the above types to strings
• Standard user alerts: error messages, information messages and queries
• File operations: opening and creating files using standard dialogs to identify the files to be opened or created.

In all the dialogs except the user alerts there is a Cancel button which allows input to be aborted. Pressing the Cancel button (or the close button in the dialog's title bar) will in all cases close the dialog and raise an Input_Cancelled exception.

The following sections describe each of these in more detail. In all cases, the names used to describe the parameters are the actual names used in the declarations, so a procedure described as Get(Prompt,Default) can be called like this:

    Get ("My prompt", "My default");

or like this:

    Get (Prompt => "My prompt", Default => "My default");

or like this:

    Get (Default => "My default", Prompt => "My prompt");

Also, the name of each operation in its description is hyperlinked to its declaration in the HTML version of the corresponding package specification, so that you can view the formal specification of any operation by clicking on the link in its description.

2. Non-GUI input and output facilities

Output facilities are dealt with first, as they have the greatest similarity to those provided by Ada.Text_IO. They are common to all the data types handled by JEWL.IO (String, Integer, Float and Boolean; any enumerated type, integral type or floating-point type) as well as the standard type Character. The output operations available are as follows:

Put (Item)

Write the value of Item to the standard output.

 

Put (File, Item)

Write the value of Item to the file specified by File.

 

Put_Line (Item)

Write Item and a newline to the standard output.

 

Put_Line (File, Item)

Write Item and a newline to the file specified by File.

 

New_Line (Spacing)

Start a new line on the standard output as many times as specified by Spacing. Spacing is optional, and if it is omitted it is assumed to be 1.

 

New_Line (File, Spacing)

Start a new line on the file specified by File as many times as specified by Spacing. Spacing is optional, and if it is omitted it is assumed to be 1.

There are also some standard type conversion operations:

S := To_String(Item)

Convert a (non-string) value Item to a String.

T := S & X

Concatenate a String S and the value X into a single String.

T := X & S

Concatenate the value X and a String S into a single String.

The length of the result of To_String(Item) will depend on the value of the Item parameter; similarly, the length of S & X will depend on the values of S and X. Such unconstrained strings can be passed to a subprogram which expects an unconstrained string as its parameter (e.g. Put) but can only be assigned to a String variable (or a slice of a string variable) if it is exactly the correct size. For example, this will generate a Constraint_Error exception if the result of To_String(Item) is not exactly 20 characters long:

    S : String(1..20) := To_String(Item);

It is often simpler to declare a String variable of the correct size and initialise it using a declaration like this:

    declare
      S : String := To_String(Item);
    begin
      -- use the value of S here
    end;

The bounds of S do not need to be specified; the result of To_String(Item) will be used to determine them.

Some extra input facilities for use with files are provided:

Skip_Line (File, Spacing)

Skip as many lines of input as specified by Spacing. Spacing is optional, and if it is omitted it is assumed to be 1.

 

End_Of_Line (File)

A function which returns True if the input position in the file specified by File is at the end of a line in the file.

 

End_Of_File (File)

A function which returns True if the input position in the file specified by File is at the end of the file.

3. String input

Strings are handled slightly differently to other types, since String is an unconstrained type whose length is variable. The operations available reflect this. They are as follows:

Get (Prompt, Default)

This is a function which displays a dialog box which allows the user to enter a string of indefinite size (up to a very large system-dependent maximum). The dialog box has the title "Input required" and contains the specified prompt, an edit box for entering the required string value, and OK and Cancel buttons. The edit box is initialised to the value given by Default. Pressing the OK button closes the dialog, and returns the string as the result of the function. The prompt and the user's input are copied to the standard output for logging purposes.

Since the string's length is unknown, the only places where this function can be used is in contexts where an unconstrained string is acceptable. These are as the parameter to another procedure or function:

    Put(Get(Prompt,Default));

or in a declaration:

    S : String := Get(Prompt,Default);

Both the Prompt and Default parameters are optional, so that the simplest form of using Get is like this:

    S : String := Get;

By default, Prompt is "Enter your text:" and Default is the empty string ("", zero characters in length).

Get (Item, Length, Prompt, Default)

This is a procedure which reads a string into a fixed-length string variable. The Prompt and Default parameters are used as described above. Item is a string variable and Length is a Natural (or Integer) variable. The text entered in the dialog's edit box is copied into Item if Item is big enough. If Item is not large enough to hold all the text entered in the dialog box, as much of it as will fit will be copied. Length will be set to the actual number of characters copied into Item.

 

Get (File, Item, Length)

As above, except that the input comes from the file specified by File, and no dialog is used (so there is no prompt or default value).

For the sake of compatibility with the names of operations in Ada.Text_IO, the last two are both available under different names:

Get_Line (Item, Length, Prompt, Default)

This is the same as Get (Item, Length, Prompt, Default).

 

Get_Line (File, Item, Length)

This is the same as Get (File, Item, Length).

There is also a version of Get which will read a single character from a file:

Get (File, Item)

This procedure reads a single character from the specified file into the Character variable Item.

4. Input of standard types

The standard types handled by JEWL.IO (apart from String, which was dealt with above) are Integer, Float and Boolean. There are no input facilities provided for single characters, as a String or enumerated type would usually be a more suitable choice of input type. If necessary, the input facilities for enumerated types described below can be used with type Character.

For Integer, Float and Boolean, the following input operations are available:

Get (Item, Default, Prompt)

Use a GUI dialog to read a value of the appropriate type into Item, displaying Prompt as a prompt, with an initial value Default as the initial value of the dialog box. Both Prompt and Default can be omitted. If Prompt is omitted, a standard prompt will be displayed in the dialog box (e.g. "Enter an integer:" for type Integer); if Default is omitted, no default value will be provided when the dialog box is displayed.

 

Get (File, Item)

Read a value into Item from the file specified by File.

Integer and Float dialogs use the same dialog box as for String, except that the input is checked to make sure it is valid when the OK button is pressed. If it is not valid, an error message will be displayed as a message box (see Error, below) and the dialog will be redisplayed if the "OK" button is pressed in response.

Boolean dialogs have different forms depending on whether a default value is specified. If there is no default, the dialog box contains the specified prompt and three buttons labelled "Yes", "No" and "Cancel". Pressing the "Yes" button returns the value True, "No" returns False, and "Cancel" raises an Input_Cancelled exception as usual.

If there is a default, a checkbox is displayed (labelled with the specified prompt) together with "OK" and "Cancel" buttons. The checkbox is checked initially if the default value is True.

5. Generic input facilities

JEWL.IO provides generic subpackages for input and output of enumeration types, integral types and floating-point types. To use these, they must be instantiated with the appropriate type:

    package My_Enumerated_IO is new JEWL.IO.Enumeration_IO (My_Enum);
    package My_Integral_IO   is new JEWL_IO.Integer_IO (My_Int);
    package My_Float_IO      is new JEWL_IO.Float_IO (My_Float);

The operations available in these packages are the standard output operations and the following input operations (the same as described for the input of standard types, above):

Get (Item, Default, Prompt)

Use a GUI dialog to read a value of the appropriate type into Item, displaying Prompt as a prompt, with an initial value Default as the initial value of the dialog box. Both Prompt and Default can be omitted. If Prompt is omitted, a standard prompt will be displayed in the dialog box (e.g. "Enter an integer:" for type Integer); if Default is omitted, no default value will be provided when the dialog box is displayed.

 

Get (File, Item)

Read a value into Item from the file specified by File.

The dialogs for integral and floating-point types use the same dialog box as for String, except that the input is checked to make sure it is valid when the OK button is pressed. If it is not valid, an error message which specifies the allowed range of values will be displayed as a message box (see Error , below) and the dialog will be redisplayed if the "OK" button is pressed in response.

Note that you should avoid providing a use clause for subtypes of Integer or Float, as this will produce an ambiguity between the existing operations for Integer and Float and those provided in the new package. For example, consider what will happen if Integer_IO is instantiated for Natural (a subtype of Integer):

    package Natural_IO is new JEWL.IO.Integer_IO(Natural);
    use Natural_IO;

If Get is called for an Integer or Natural variable, the compiler will be unable to distinguish between the two versions of Get available:

    Get(Item);  -- is this Get(Item:Integer) or Get(Item:Natural)?

To resolve the ambiguity, you would need to specify the package name in both cases:

    JEWL.IO.Get(Item);      -- Get(Item:Integer)
    Natural_IO.Get(Item);   -- Get(Item:Natural)

If there is no use clause for Natural_IO, the version of Get for type Natural will still need to be qualified as Natural_IO.Get as in the second case above but Get(Item) without any extra qualification will now be interpreted unambiguously as a reference to the version of Get for type Integer (the first case above).

The dialog for enumeration types has a combobox instead of an edit box, and if a default value has been supplied this will be the value initially displayed in the combobox.. Pressing the button at the right of the combobox will display a pull-down list of the possible values of the enumerated type. Only values displayed in this list can be selected; the value in the combobox cannot be edited directly.

6. Message boxes

A message box is a dialog which can be used to notify the user of an error or other information, or to ask a yes/no question. There are three operations which display message boxes:

Message (Text) Show an information message with an "OK" button and an information icon. Text is the text of the message which appears inside the dialog window. The message is also echoed to the standard output.
Error (Text) Show an error message with an "OK" button and an error icon. Text is the text of the message which appears inside the dialog window. The error message is also echoed to the standard output.
Query (Text, Title) Show a query message with a "Yes" button, a "No" button and an error icon. Text is the text of the message which appears inside the dialog window. This is a function which returns a Boolean result, which will be True if the "Yes" button is pressed and False if the "No" button is pressed. The query and the user's response is also echoed to the standard output.

7. File dialogs

A selection of standard dialogs are provided to open and create files. These display a directory tree and allow you to select or manually type in a filename to be opened or created. In each case a parameter File identifies the file being opened or created, and must be a variable of type File_Type. The procedures which use these dialogs are as follows:

Open (File, Title)

Open an existing file for input. Title is the caption to be displayed in the title bar of the dialog box, and is optional; if it is omitted, the title "Select input file" will be used.

 

Create (File, Title)

Create a new file for output. If a file of the specified name already exists, a message box will be displayed asking you to confirm that you want to overwrite it. Title is the caption to be displayed in the title bar of the dialog box, and is optional; if it is omitted, the title "Select output file" will be used.

 

Append (File, Title)

Open a file for appending output to. If a file of the specified name does not already exist, a message box will be displayed asking you to confirm that you want to create it. Title is the caption to be displayed in the title bar of the dialog box, and is optional; if it is omitted, the title "Select output file" will be used.

The dialogs will look like this:

Files should be closed when they are no longer needed, as follows:

Close (File)

Close the specified file when it is no longer needed.