Win_IO

Version 5.0

A set of packages for simple graphical input and output

http://www.istr.unican.es/win_io/

Universidad de Cantabria, SPAIN

Author: Michael Gonzalez  mgh@unican.es

Win_IO is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation. It is based on GtkAda, and thus is portable within Unix, Linux and Windows platforms.

The current version 5.0 is designed for GtkAda 3.4.0. The introduction of GtkAda 3 (and gtk 3) has introduced various incompatibilities with version 2 software. Thus, if you are still using Gtkada 2.X please use Win_IO 4.0. 

  1. Introduction
  2. Input Windows
  3. Output Windows
  4. Message Windows
  5. Menu Windows
  6. Graphics Windows
  7. Plot Windows
  8. Tasking
  9. Changes from Previous Versions
  10. Downloading, Installation and Compilation

1. Introduction

Win_IO is a set of packages for graphical input and output. It is designed specially for students or Ada users who do not want to spend their time learning a complex graphical user interface, but who are "tired" of the old-fashioned text-oriented input and output. Win_IO has the same goals as JEWL (John English Windows Library, http://www.it.bton.ac.uk/staff/je/jewl/), but is simpler (and less powerful) and is portable within Unix, Linux and Windows platforms. JEWL is currently only provided for Windows.

Win_IO is composed of the following modules:
 
Input_Windows Provides a simple window with I/O capabilities for data of the types Integer, Float, and String

Several data can be displayed and/or retrieved on the same window.
Output_Windows Provides a simple window with Output capabilities for data of the types Integer, Float, and String.

Several data can be displayed on the same window.
Message_Windows Provides a simple window for displaying a short message. It provides an OK button for closing the window.
Menu_Windows Provides a simple window with several buttons that enable the user to select from a number of options. 

It is a generic package that must be instantiated with an enumeration type. One button will be created for each value in this type.
Graphics_Windows Provides a simple window with drawing capabilities.
Plot_Windows Provides a simple window for drawing two-dimensional graphs from sets of points.

 

2. Input_Windows

An Input_Window is a window that provides the following items: The spec can be found in: input_windows.ads

An example using this package can be found in: Example with Input_Windows

Input_Window operations:
 
   function Input_Window
     (Title : String)
     return Input_Window_Type;		 Create the window, with the specified title.
   procedure Put_Line
     (IW : in out Input_Window_Type;
      Str : String);		 Put the Str String on the results area of the IW window.
 procedure Create_Entry
     (IW : in out Input_Window_Type;
      Label : String;
      Initial_Value : String);		 Create an entry box on the IW window with the specified label and initial value (String). May raise Repeated_Label.
  procedure Create_Entry
     (IW : in out Input_Window_Type;
      Label : String;
      Initial_Value : Integer);		 Create an entry box on the IW window with the specified label and initial value (Integer). May raise Repeated_Label.
   procedure Create_Entry
     (IW : in out Input_Window_Type;
      Label : String;
      Initial_Value : Float);		 Create an entry box on the IW window with the specified label and initial value (Float). May raise Repeated_Label.
   procedure Wait
     (IW : in out Input_Window_Type;
      Message : String);		 Display Message on the results area of the IW window, and wait for the OK button to be pressed. This will be an indication that the data on the entry boxes has been edited. May raise Canceled if the Cancel button is pressed. Before returning, it hides the window.
  procedure Get
     (IW : in out Input_Window_Type;
      Label : String;
      Item : out Integer);		 Read an Integer from the entry box matching Label in the IW window. Value is returned in Item. May raise Label_Not_Found. May raise Data_Error if text on the entry box is not an integer.
   procedure Get
     (IW : in out Input_Window_Type;
      Label : String;
      Item : out Float);		 Read a Float from the entry box matching Label in the IW window. Value is returned in Item. May raise Label_Not_Found. May raise Data_Error if text on the entry box is not a float.
   procedure Get
     (IW : in out Input_Window_Type;
      Label : String;
      Item : out String);		 Read a String from the entry box matching Label in the IW window. Value is returned in Item. If the Item parameter is longer than the text in the box it is padded with spaces if the Item parameter is shorter, then the input text is truncated. May raise Label_Not_Found. 
   procedure Get_Line
     (IW : in out Input_Window_Type;
      Label : String;
      Item  : out String;
      Num   : out Natural);		 Read a String from the entry box matching Label in the IW window Works similar to Ada.Text_IO.Get_Line, returning the input text in the first characters of Item, and the number of read characters in Num. May raise Label_Not_Found

3. Output_Windows

An Output_Window is a window that provides the following items: The spec can be found in: output_windows.ads

An example using this package can be found in: Example with Output_Windows

An example using this package to continuously update the data on the window is shown in: Example with Continuous Update Output_Windows

The operations of Output_Windows are:
 
   function Output_Window
     (Title : String)
     return Output_Window_Type;		 Create the window, with the specified title
   procedure Create_Box
     (OW : in out Output_Window_Type;
      Label : String;
      Initial_Value : String);		 Create a display box on the OW window, with the specified label and value (String). May raise Repeated_Label.
   procedure Create_Box
     (OW : in out Output_Window_Type;
      Label : String;
      Initial_Value : Integer);		 Create a display box on the OW window, with the specified label and value (Integer). May raise Repeated_Label.
  procedure Create_Box
     (OW : in out Output_Window_Type;
      Label : String;
      Initial_Value : Float);		 Create a display box on the OW window, with the specified label and value (Float). May raise Repeated_Label.
  procedure Update_Box
     (OW : in out Output_Window_Type;
      Label : String;
      New_Value : String);		 Update the display box on the OW window corresponding to the specified label using the new_value (String). May raise Label_Not_Found.
   procedure Update_Box
     (OW : in out Output_Window_Type;
      Label : String;
      New_Value : Integer);		 Update the display box on the OW window corresponding to the specified label using the new_value (Integer). May raise Label_Not_Found.
   procedure Update_Box
     (OW : in out Output_Window_Type;
      Label : String;
      New_Value : Float);		 Update the display box on the OW window corresponding to the specified label using the new_value (Float). May raise Label_Not_Found.
   procedure Draw
     (OW : in out Output_Window_Type);		 Draws the window, and returns immediately
   procedure Wait
     (OW : in out Output_Window_Type);		 Draws the window and then waits for the OK button to be pressed. This will an indication that the data on the entry boxes has been viewed. Before returning, it hides the window
   procedure Close
     (OW : in out Output_Window_Type);		 Destroys the window, which now becomes unavailable

 

4. Message_Windows

A Message_Window is a window that provides the following items:


The spec can be found in: message_windows.ads

An example using this package can be found in: Example with Message_Windows

The operations of Message_Windows are:
 
   function Message_Window
     (Message : String)
     return Message_Window_Type;		 Create the window, with the specified message.
   procedure Wait
     (MW : in out Message_Window_Type);		 Wait for the OK button to be pressed. This will an indication that message has been viewed. Before returning, it hides the window

5. Menu_Windows

A MENU_Window is a window that provides the capability of choosing among a set of options.

It provides a button for each value of the generic enumeration type parameter.

It provides a Wait operation that waits until the user presses one of those buttons. The operation returns the chosen option.

An example using this package can be found in: Example with Menu_Windows

The spec can be found in: menu_windows.ads

The operations of Menu_Windows are:
 
   function Menu_Window
     (Title : String)
     return Menu_Window_Type;		 Create the window, with the specified title.
   procedure Wait
     (MW : in out Menu_Window_Type;
      Selection : out Enum);		 Wait for a button to be pressed. This will an indication that the option has been chosen. The chosen option is returned in Selection. Before returning, it hides the window

6. Graphics_Windows

Graphics_Windows provides a canvas type, which represents a window that provides a blank rectangle for drawing.

It also provides an OK button for which a Wait operation is provided.

A canvas has an associated font size, a pen colour, a pen size for drawing lines (initially black, one pixel wide) and a fill colour used to colour closed shapes (initially white).

The spec can be found in: graphics_windows.ads

An example using this package can be found in: Example with Graphics_Windows

Another example using this package to show an animated graphic can be found in: Example of Animation with Graphics_Windows

The description of the Graphics_Windows package appears in the following subsections:

6.1 Support types

The Graphics_Windows package provides a set of support types, which are described in the following table with their respective operations:
 
   subtype Colour_Range is Cairo.Color_Range;
   subtype Color_Range is Colour_Range;

   type Colour_Type  is record
      Red    : Colour_Range;
      Green  : Colour_Range;
      Blue   : Colour_Range;
   end record;
   subtype Color_Type  is Colour_Type;

   function Light
      (Colour : Colour_Type)    return Colour_Type;
   function Dark
      (Colour : Colour_Type)   return Colour_Type;

   Black    : constant Colour_Type :=   (  0,  0,  0);
   White    : constant Colour_Type :=  (1.0,1.0,1.0);
   Red       : constant Colour_Type :=   (1.0,  0,  0);
   Green    : constant Colour_Type :=  (  0,1.0,  0);
   Blue      : constant Colour_Type :=   (  0,  0,1.0);
   Gray      : constant Colour_Type :=   (0.5,0.5,0.5);
   Yellow  : constant Colour_Type :=  (1.0,1.0,  0);
   Cyan     : constant Colour_Type :=  (0,1.0,1.0);
   Magenta: constant Colour_Type :=  (1.0,  0,1.0);

 A colour specified as an RGB value. Several common colors are specified as constants. Operations Light and Dark provided for convenience.

Color_Type is a renaming of the above, with American spelling
 
   type Point_Type is record
      X,Y : Integer;
   end record;

   function "+"
       (P1,P2 : Point_Type)   return Point_Type;
   function "-"
      (P1,P2 : Point_Type)   return Point_Type;

 (X,Y) coordinates of a point on the window

Origin is at the top left corner. "+" and "-" operators defined
 
   type    Point_List   is array (Positive range <>) 
      of Point_Type;		 An array of points, used by some operations
   type Image_Type is private;

   function Image 
      (Canvas : Canvas_Type;
        Name   : String) -- filename in jpg, gif, ... formats
       return Image_Type;

 Refers to an image, obtained through the Image operation. A variety of file formats are supported, including JPG, GIF and XPM

6.2 Canvas creation and properties

The operations of Graphics_Windows for canvas creation and properties are:
 
   function Canvas
      (Width    : Integer;
        Height   : Integer;
        Title    : String:="Graphics Window")
       return Canvas_Type;		 Creates a new Canvas with the specified width, height and title.
   procedure Set_Colour
       (Canvas : in out Canvas_Type;
        Colour : in Colour_Type := Black);

   procedure Set_Color
       (Canvas : in out Canvas_Type;
         Color  : in Color_Type := Black) 
      renames Set_Colour;

 Set the pen colour for a canvas
   procedure Erase (Canvas   : in Canvas_Type); Erase the drawing in a canvas
   procedure Set_Font_Size
     (Canvas   : in out Canvas_Type;
      size     : in Integer);		 Set a new font size for all subsequent text drawn on the canvas.
   procedure Set_Pen  
       (Canvas   : in out Canvas_Type;
        Colour   : in Colour_Type := Black;
        Width    : in Natural     := 1);		 Set the pen used to draw lines on the canvas to this colour and thickness.
   procedure Set_Fill  
      (Canvas   : in out Canvas_Type;
       Colour   : in Colour_Type);		 Set the colour used to fill subsequent closed shapes drawn on the canvas.
   procedure Set_Fill 
       (Canvas   : in out Canvas_Type);		 Clear the fill property for subsequent closed shapes drawn on the canvas.
   procedure Set_Fill 
       (Canvas   : in out Canvas_Type;
         Filled   : in Boolean);		 Set (or clear) the fill property for subsequent closed shapes drawn on the canvas.

6.3 Drawing operations

The drawing operations defined in Graphics_Windows are:
 
   procedure Draw_Point 
      (Canvas   : in Canvas_Type;
        Point    : in Point_Type);		 Draw a point on the canvas
   procedure Draw_Text 
      (Canvas   : in Canvas_Type;
        From     : in Point_Type;
        Text     : in String);		 Draw a text string on the canvas from the top-left point specified by From.
   procedure Draw_Line 
      (Canvas   : in Canvas_Type;
        From     : in Point_Type;
        To       : in Point_Type);		 Draw a line on the canvas starting at point From and finishing at point To.
   procedure Draw_Line_List
     (Canvas   : in Canvas_Type;
      Points   : in Point_List);		 Draw lines on the canvas connecting the points in the list.
   procedure Draw_Rectangle
     (Canvas   : in Canvas_Type;
      From     : in Point_Type;
      To       : in Point_Type);		 Draw a rectangle on the canvas from the From corner point to the To diagonally-opposite point.
  procedure Draw_Rectangle
     (Canvas   : in Canvas_Type;
      From     : in Point_Type;
      Width    : in Positive;
      Height   : in Positive);		 Draw a rectangle on the canvas from the From corner point with the specified Width and Height.
   procedure Draw_Ellipse
     (Canvas   : in Canvas_Type;
      From     : in Point_Type;
      To       : in Point_Type);		 Draw an ellipse on the canvas bounded by a rectangle from the From corner point to the To diagonally-opposite point.
   procedure Draw_Ellipse
     (Canvas   : in Canvas_Type;
      From     : in Point_Type;
      Width    : in Positive;
      Height   : in Positive);		 Draw an ellipse on the canvas bounded by a rectangle from the From corner point with the specified Width and Height.
   procedure Draw_Circle
     (Canvas   : in Canvas_Type;
      Centre   : in Point_Type;
      Radius   : in Positive);		 Draw a circle on the canvas with the specified centre point and radius.
   procedure Draw_Arc
     (Canvas   : in Canvas_Type;
      From     : in Point_Type;
      Width    : in Positive;
      Height   : in Positive;
      Angle1   : in Natural;
      Angle2   : in Natural);		 Draw an arc on the canvas; it is part of an ellipse bounded by a rectangle from the From point, with the specified width and height; Angle 1 is the the initial angle of the arc (in degrees) and Angle2 is the final angle of the arc (in degrees).
   procedure Draw_Polygon
     (Canvas   : in Canvas_Type;
      Points   : in Point_List);		 Draw a polygon on the canvas with vertices at these points.
   procedure Draw_Image 
     (Canvas   : in Canvas_Type;
       From     : in Point_Type;
       Image    : in Image_Type);		 Draw an image on the canvas from the From point using the Image object.
   procedure Draw
     (Canvas : in out Canvas_Type);		 Draws the canvas and returns immediately
   procedure Wait
     (Canvas : in out Canvas_Type);		 Draw the canvas and wait until the OK button is pressed: then, the Canvas is hid.
   procedure Close
     (Canvas : in out Canvas_Type);		 Destroys the canvas, which now becomes unavailable

7. Plot_Windows

A Plot Window provides an area for displaying several graphs each derived from a set of points. It also provides an OK button for which a Wait operation is provided.

A Plot Window has an associated title, X Axis title and Y Axis title

Each Graph has a set of points and the following attributes:

Operations are provided to add points to the set and to change each of the attributes.

Another operation, New_Graph, is used to switch to a new graph once the previous one has been built.

An example using this package can be found in: Example with Plot_Windows

The spec can be found in: plot_windows.ads

The operations of Plot_Windows are:
 
   function Plot_Window
     (Plot_Title, 
      X_Axis_Title, Y_Axis_Title : String)
     return Plot_Window_Type;		 Creates a new Plot window with the specified title and axes titles. The first graph in this plot will be ready to accept points and attribute changes
   procedure Add_Point 
      (Plot : in out Plot_Window_Type; 
       X,Y : in Float);		 Adds a point to the current graph; (X,Y) are the coordinates
   type Colour_Type is
           (Black, White, Red, 
            Green, Blue, Gray, Yellow,
            Cyan, Magenta);
   subtype Color_Type is Colour_Type;

   procedure Set_Colour 
      (Plot : in out Plot_Window_Type; 
       Colour : Color_Type);

   procedure Set_Color 
      (Plot : in out Plot_Window_Type; 
       Color : Color_Type) 
      renames Set_Colour;

 Sets the color of the current graph to this value. The type and operation are provided with both American and British spellings.
   type Symbol_Type is
         (No_Symbol, Square, Circle,
          Up_Triangle, Down_Triangle);

   procedure Set_Symbol 
      (Plot : in out Plot_Window_Type;
        Symbol : Symbol_Type);

 Sets the symbol of the current graph to this value
   procedure Set_Lines 
      (Plot : in out Plot_Window_Type;
       With_Lines : Boolean);		 Sets the lines attribute of the current graph. If true, lines will be drawn between points.
   procedure Set_Graph_Title 
      (Plot : in out Plot_Window_Type;
       Graph_Title : String);		 Sets the title of the current graph to this value.
procedure New_Graph 
      (Plot : in out Plot_Window_Type);		 Switches to a new graph. All subsequent operations to add points or set graph attributes will refer to the new graph. May raise Too_Many_Graphs if Max_Graphs is exceeded.
  procedure Wait 
      (Plot : in out Plot_Window_Type);		 Draws the graphs in the Plot_Window and then waits for the OK button to be pressed. Then, it hides the window

8. Tasking

The Windows version of GtkAda does not currently work with tasks. Therefore, we have made tasking support configurable since Win_IO 3.0, and as a default tasking support is disabled. To enable it you need to set the Tasking_Supported constant in the Task_Support package specification to the value True.

If tasking support is enabled, a limited support for tasking is included since gtk does not support calls that handle events (like Gtk.Main.Main) to be made from different tasks. In Win_IO a substantial number of procedures are of this kind, and cannot be called from different tasks:
 
Package
Operation
All Wait
All Close
Output_Windows Draw
Graphics_Windows Draw

Consequently, a tasking application architecture using Win_IO must put any call in the table above in a single task (or the main program). Other calls may be made from different tasks.

An example can be found in test_tasking_graphics_window. In this example, two concurrent tasks draw rectangles in a Graphics_Window object. The main program periodically refreshes the window by invoking the Draw operation.

 

9. Changes from Previous Versions

Changes from Version 4.0

Introduced support for GtkAda 3.X. Various calls were fixed to the new requirements of GtkAda 3.X. Package Graphics_Windows was fully rewritten to use the new Cairo graphic capabilities. Package Plot_Windows was completely rewritten because the support packages used for plotting were no longer available in GtkAda 3.X.

Changes from Version 3.0

The Plot_Canvas object used by Plot_Windows changed in gtkada and made previous versions of Win_IO to fail compilation. Version 4.0 corrects this problem and can be used with GtkAda version 2.14.0 and later.

Changes from Version 2.0.1

For more comfortable use, we have changed the position of the new windows to the "none" policy in which the system chooses the position, instead of the previous "mouse" policy in which the window was created at the current position of the mouse.

Win_IO was no longer usable under Windows with the newest GtkAda versions. To solve this problem we have made tasking support configurable, and as a default tasking support is disabled. See section on Tasking, above.

Changes from Version 2.0

Fixed a bug by which the name of an Image was ignored, and a hardcoded name was used instead.

Changes from Version 1.3.1

Changed to GtkAda 2.2.x

Added support for JPEG and GIF image formats

The window "Delete" event is now handled.

Fixed a bug in Input_Windows, which prevented proper use of the Canceled exception that is raised when the "Cancel" button is pressed.

Changes from Version 1.3

Fixed a bug in Graphics_Windows, which failed when text was drawn without having defined its size.

Fixed a bug in Plot_Windows, which failed if no title was given to a graph.

Changes from Version 1.2

Fixed a bug in Graphics_Windows.Draw_Circle, which drew the circle with half the requested radius.

Fixed the Graphics_Windows.Erase procedure.

Added some limited support for tasking. See "8. Tasking" for more details

Changes from Version 1.1

The floating point unit is reset before some float point calculations to prevent a bug in Windows 2000 drivers that leaves the floating point unit in an incorrect state.

The Graphics_Windows implementation is changed because of a non-portability issue between the Windows and Linux implementations affecting the animated graphics display.

Changes from Version 1.0

The Output_Windows package has been changed to add operations to be able to update the data displayed on a window, and draw the window without having to wait for the OK button. This allows continuous updates.

The Graphics_Windows package has been changed to add a new Draw operation, that does not wait for the OK button to be pressed. This allows animated graphics to be displayed.

10. Downloading, Installation and Compilation

Win_IO 5.0 Requires GtkAda version 3.4.0 or higher. It has been tested under Windows 7, Windows 10, Linux Ubuntu 13.10 32 bits and Linux Ubuntu 16.04 64 bits, using the gnat compiler, versions GNAT-GPL-2013 with GtkAda 3.4.2 and GNAT-GPL-2016 with GtkAda-GPL-2016. The GNAT compiler can be found at http://libre.adacore.com/.  Both the Gnat compiler and GtkAda are free software.

To download Win_IO click on one of the following links:

Windows 

Installation

To install Win_IO just copy the file with the sources in a directory of your choice and decompress it there.

Compiling from the command line

To compile a program that uses one ore more of the Win_IO packages from the command line create a project file that: For instance, assuming that GtkAda is installed in C:\GtkAda\, Win_IO is in c:\Win_IO_Dir and the main program is test_win_io.adb, the project file test_win_io.gpr could be something like:

with "c:\GtkAda\lib\gnat\gtkada.gpr";
project Test_Win_Io is
    for Source_Dirs use (".", "c:\Win_IO_Dir");
    for Main use ("test_win_io.adb");
end Test_Win_Io;

 The compilation command would be:
    gnatmake -P test_win_io.gpr

Compiling and executing from GPS

For GPS you should create a dependency between your project and the gtkada project by right-clicking on the  project icon (in the project window at the left hand side, which can be shown with "Tools" => "Views" => "Project") and selecting "Project" and then "Dependencies", and finally adding file lib\gnat\gtkada.gpr from the gtkada installation directory.

Then, you should configure the project to include the sources for Win_IO. You can do this by adding the Win_IO directory to the "Source dirs" part of the "Properties" part of the "Project" menu. Remember also to add the ".exe" suffix as the default suffix for the main file.

Build the application from "Build" => "Project" => "Build All".

When running your application do it from "Build" => "Run" => "Your application" and then remember to tick the "Run in external terminal" option.

Linux 

Installation

To install Win_IO just copy the file with the sources in a directory of your choice and decompress it there.

Compiling from the command line

To compile a program that uses one ore more of the Win_IO packages from the command line create a project file that: For instance, assuming that GtkAda is installed in /usr/local/include/gtkada, Win_IO in /usr/local/win_io and the main program is test_win_io.adb, the project file test_win_io.gpr could be something like:

with "/usr/local/include/gtkada/lib/gnat/gtkada.gpr";
project Test_Win_Io is
    for Source_Dirs use (".", "/usr/local/win_io");
    for Main use ("test_win_io.adb");
end Test_Win_Io;

 The compilation command would be:
    gnatmake -P test_win_io.gpr

Compiling and executing from GPS

For GPS you should create a dependency between your project and the gtkada project by right-clicking on the  project icon (in the project window at the left hand side, which can be shown with "Tools" => "Views" => "Project") and selecting "Project" and then "Dependencies", and finally adding file lib\gnat\gtkada.gpr from the gtkada installation directory.

Then, you should configure the project to include the sources for Win_IO. You can do this by adding the Win_IO directory to the "Source dirs" part of the "Properties" part of the "Project" menu. 

Build the application from "Build" => "Project" => "Build All".

When running your application do it from "Build" => "Run" => "Your application" and then remember to tick the "Run in external terminal" option, or run it directly from an external terminal if you get gtk-related errors.