Lab 7: Introduction to Adagraph

Adagraph is a simple graphics package written by Jerry van Dijk for the GNAT AdaGIDE development environment.  Adagraph permits the creation of a graphics window, the display of simple shapes and interation with the mouse cursor and buttons.  In is original configuration Adagraph is limited to 16 colors however Martin Carlisle of the Air Force Academy has modified Adagraph to support 256 colors.  For now we will be using the original Adagraph for GNAT AdaGIDE v. 3.11.

Before performing Step 1 below, check to see if Adagraph has already been installed on your lab computer.

1. AFTER you have installed GNAT AdaGIDE v 3.11, download the Adagraph installer zip file ag05cgn.zip to your hard drive.  Unzip it into a temporary directory and run Setup.

2. Find the Adagraph folder inside the GNAT directory.  Build and run the demo.adb program. This program will open two windows.  One of the windows will contain the graphics and the other will be a text window displaying user prompts.  Make sure the focus is on the text window as you respond to the messages.  You will probably want to separate the two windows so that you can see the contents of both.

3. Open the Adagraph package specification (adagraph.ads) and review the functions and procedures referenced there.  This code is listed below with comments in violet.

package Adagraph is

   -------------------
   -- Library types --
   -------------------

   type Event_Type is (None, Moved, Left_Up, Left_Down, Right_Up, Right_Down);

Event_Type is an enumerated type used in the Mouse_Type record to indicate mouse cursor and button activity.
   type Mouse_Type is
      record
         Event : Event_Type;
         X_Pos : Integer;
         Y_Pos : Integer;
      end record;
Color_Type defines 16 colors by name  these colors are also numbered 0 through 15 consecutively.  You may be interested in knowing that these colors correspond to a four-bit binary number in which each bit respectively represents (HI/LOW, RED, GREEN, BLUE). The HI/LOW bit turns sets the intensity of all thee colors HI or LOW.  A 1 in a color bit turns on that color. Having the HI/LOW bit set to 1 and all color bits set to 0, still turns on all colors slightly (see Dark_Gray) On the other hand Light_Gray = (0,1,1,1) (i.e. Red Green and Blue all on at a LOW level) is obtained by turning on all color bits and turning off the HI/LOW bit.  By the additive property of light spectra RED and GREEN make yellow so Yellow = (1,1,1,0).  Verify the other color names by comparing the position of the enumerated type color name with its corresponding binary value.
   type Color_Type is (Black, Blue, Green, Cyan, Red, Magenta, Brown,
                       Light_Gray, Dark_Gray, Light_Blue, Light_Green,
                       Light_Cyan, Light_Red, Light_Magenta, Yellow, White);

   type Fill_Type is (No_Fill, Fill);

The enumerated type Fill_Type is used to specifed whether a circle, ellipse or rectangle will be displayed as solid or outlined.


   -----------------------
   -- Library constants --
   -----------------------

   Adagraph_Dll_Version : constant Integer := 5;
 

   ------------------------------
   -- Extended character codes --
   ------------------------------

   Vk_Nul    : constant Character := Character'Val (16#00#);
   Vk_Prior  : constant Character := Character'Val (16#21#);
   Vk_Next   : constant Character := Character'Val (16#22#);
   Vk_End    : constant Character := Character'Val (16#23#);
   Vk_Home   : constant Character := Character'Val (16#24#);
   Vk_Left   : constant Character := Character'Val (16#25#);
   Vk_Up     : constant Character := Character'Val (16#26#);
   Vk_Right  : constant Character := Character'Val (16#27#);
   Vk_Down   : constant Character := Character'Val (16#28#);
   Vk_Insert : constant Character := Character'Val (16#2D#);
   Vk_Delete : constant Character := Character'Val (16#2E#);
 

The arrow keys and some other control keys are declared.
   ----------------------------------
   -- System information functions --
   ----------------------------------

   function Get_Dll_Version return Integer;

Get_Dll_Version is used to determine which version of the AdaGraph Dynamic Link Library is available on the current system.
   procedure Get_Max_Size (X_Size, Y_Size : out Integer);
Get_Max_Size is used to determine the maximum size available for graphics on the current system.
   -----------------------
   -- Window management --
   -----------------------

   procedure Create_Graph_Window (X_Max,  Y_Max  : out Integer;
                                  X_Char, Y_Char : out Integer);

Creates a default graphics window of a predetermined size which will display graphics characters of a specified height and width.
   procedure Ext_Create_Graph_Window (X_Max,  Y_Max  : out Integer;
                                      X_Char, Y_Char : out Integer);
Creates the largest possible graphics window
   procedure Create_Sized_Graph_Window (X_Size, Y_Size : in     Integer;
                                        X_Max,  Y_Max  :    out Integer;
                                        X_Char, Y_Char :    out Integer);
Creates a graphics window of a size specified by the user.
   procedure Destroy_Graph_Window;
Closes the current graphics window
   function Is_Open return Boolean;
Returns true is a graphics window is open
   procedure Set_Window_Title (Title : in String);
Displays a title on the graphics window (in the blue bar).


   ---------------------
   -- Input functions --
   ---------------------

   function Key_Hit return Boolean;

Returns true if a key has been pressed since the last Get_Key function call.
   function Get_Key return Character;
Gets a key from the keyboard input buffer
   function Mouse_Event return Boolean;
Returns true if a mouse event has occured since the last Get_Mouse function call.
   function Get_Mouse return Mouse_Type;
Gets a mouse_event


   -----------------------
   -- Graphic functions --
   -----------------------

   procedure Clear_Window (Hue : in Color_Type := Black);

Clears the graphics window to black or some user specified color
   function Get_Pixel (X, Y : in Integer) return Color_Type;
Returns the color of a pixel at the specified location in the graphics window
   procedure Put_Pixel (X, Y : in Integer; Hue : in Color_Type := White);
Places a pixel of a specified color at a specified location in the graphics window
   procedure Draw_Line (X1, Y1, X2, Y2 : in Integer;
                        Hue            : in Color_Type := White);
Draws a line of a specified color from the point X1, Y1 to the point X2, Y2 in the graphics window
   procedure Draw_Box (X1, Y1, X2, Y2 : in Integer;
                       Hue            : in Color_Type := White;
                       Filled         : in Fill_Type  := No_Fill);
Draws a rectangle of a specified color (filled or outline) with its upper-left corner at X1,Y1 and its lower-right corner at X2,Y2
   procedure Draw_Circle (X, Y, Radius : in Integer;
                          Hue          : in Color_Type := White;
                          Filled       : in Fill_Type  := No_Fill);
Draws a circle of a specified color (filled or outline) with is center at X,Y with a radius of Radius pixels
   procedure Draw_Ellipse (X1, Y1, X2, Y2 : in Integer;
                           Hue            : in Color_Type := White;
                           Filled         : in Fill_Type  := No_Fill);
Draws an ellipse of a specified color (filled or outline) which would be inscribed in a rectangle located at X1,Y1 and X2,Y2 (see definition of location of the rectangle in Draw_Box( ).
   procedure Flood_Fill (X, Y : in Integer; Hue : in Color_Type := White);
Fills a region of the graphics window with a specified color.  The limits of the region to be filled contains the point X,Y and is of a constant color.
   procedure Display_Text (X, Y : in Integer;
                           Text : in String;
                           Hue  : in Color_Type := White);
Displays graphical text of a specified color.  Each character is X_Char in width and Y_Char in height (see description of window creation procedures).  The lower-left corner of the first character is located at X,Y.


   ----------------------
   -- Polydraw support --
   ----------------------

   function Where_X return Integer;

Returns the horizonal (X) position of the current drawing point in the graphics window
   function Where_Y return Integer;
Returns the vertical (Y) position of the current drawing point in the graphics window
   procedure Goto_XY (X, Y : in Integer);
Moves the current drawing point to the specified location (X,Y) without drawing a line
   procedure Draw_To (X, Y : in Integer; Hue : in Color_Type := White);
Draws a line of a specified color from the current drawing point location to the specified location.

The following are named exceptions that can be used to control the program operation and prevent a run-time error when an error occurs in a graphic program (see exception handling).

   ----------------
   -- Exceptions --
   ----------------

   Close_Handle_Failed     : exception;
   Create_Event_Failed     : exception;
   Create_Thread_Failed    : exception;
   Dll_Version_Error       : exception;
   Ellipse_Error           : exception;
   Error_Copying_Cmdline   : exception;
   Error_Copying_Title     : exception;
   Error_Reading_Font      : exception;
   Error_Reading_Size      : exception;
   Fill_Rect_Error         : exception;
   Flood_Fill_Error        : exception;
   Get_Pixel_Error         : exception;
   Get_Position_Error      : exception;
   Invalid_Color_Value     : exception;
   Invalid_Coordinate      : exception;
   Invalid_Window_Size     : exception;
   Invalidate_Rect_Error   : exception;
   Line_To_Error           : exception;
   Move_To_Error           : exception;
   Mouse_Event_Error       : exception;
   Rectangle_Error         : exception;
   Select_Brush_Error      : exception;
   Select_Pen_Error        : exception;
   Set_Pixel_Error         : exception;
   Set_Textcolor_Error     : exception;
   Set_Title_Error         : exception;
   Text_Out_Error          : exception;
   Thread_Status_Error     : exception;
   Unknown_Adagraph_Error  : exception;
   Update_Window_Error     : exception;
   Wait_Failed_Error       : exception;
   Window_Already_Closed   : exception;
   Window_Already_Open     : exception;
   Window_Not_Open         : exception;

end Adagraph;


4. Copy the sample graph program simple_graph_demo.adb to the Adagraph directory.  Build and run this program. Press the spacebar to see the next demo until the program is finished.
 

with adagraph;
use  adagraph;
procedure simple_graph_demo is

  xmax,ymax,xchar,ychar : integer;
  px,py : integer;
  col   : color_type;

  -- this procedure is used to pause the program until a key is pressed
  procedure wait_for_keypress is
    key : character;
  begin
    if key_hit then
      key:=get_key;
    end if;
    while not(key_hit) loop
      null;
    end loop;
    key:=get_key;
  end wait_for_keypress;

begin
  ext_create_graph_window(xmax,ymax,xchar,ychar);
  set_window_title("Simple Graphics Demo");

  clear_window(black);

  draw_line(10,20,400,300,light_red);
  draw_line(400,20,10,300,light_green);

  wait_for_keypress;

  draw_box(50,30,80,60,magenta,no_fill);
  draw_box(250,250,290,290,yellow,fill);

  wait_for_keypress;

  draw_ellipse(30,120,60,150,light_blue,no_fill);
  draw_ellipse(35,125,55,145,brown,fill);

  wait_for_keypress;

  display_text(300,380,"This is a test....",white);

  wait_for_keypress;

  put_pixel(250,200,white);

  wait_for_keypress;

  for i in 1..1000 loop
    px:=10*(i mod 48 +1);
    py:=14*(i/38+1);
    col:=color_type'val(i mod 16);
    put_pixel(px,py,col);
  end loop;

  wait_for_keypress;

  destroy_graph_window;

end simple_graph_demo;


5. Review this program for understanding.  If there is any part of this program that you do not understand, ask the instructor or lab assistant.

6. As a demonstration of your understanding of Adagraph, write an Ada program that draws the following figure.

7.  Please include your name in a comment block at the top of your source code and give a hard copy to the instructor before you leave the lab or email a copy of your source code to the instructor by the end of the day.

Optional Exercises

For fun :-) you might want to download and run some of the sample graphics programs below:
 


treesort_graphics.adb - This program is based on our recursive treesort program.  It traverses the sort tree to determine depth and width of the tree in order to properly scale the graphics display.
screen_savers.adb - this is a shell for a menu-driven program.  You can use this source as a starting point for building a graphics demonstration program.
orbit.adb - This is an interactive demo program.  You can use the arrow keys as "thrusters" for the orbiting satellite.  The C key clears the trace and Q quits the program.
rectree.adb - This program demonstrates the power of recursive programs.  You enter the initial stem length, amount of decrement (decrease in stem length per recursive level) and the angle between the branches (in radians).  Start with 50 5 and 0.3. Be careful, if your tree size exceeds the boundary of the graphics window, the program will crash.
color_box.adb - This is an interactive program that redraws color boxes selected by pressing the arrow keys. The color is selected by pressing the keys 0 through 9 and the program is terminated by pressing Q.


This course material has been converted to electronic format for use at
Murray State University, and the
Dept. of Computer Science and Information Systems

Use of this material for educational purposes only is governed by
the definition of Fair Use (Section 107) of the U.S. Copyright Act.
Course material is the property of  R. A. Pilgrim
All Rights Reserved