Graphic Objects and Interaction

The IDEAS C++ Tutor uses a pre-defined library of graphic objects
and a few functions for interaction.  The purpose of the graphic 
objects is to give students immediate exposure to programming 
with objects. The interaction functions provide a simple means
for mouse input and timing for animation.  

This document is a brief description of the graphic objects
and interaction function, intended for implementors and lesson
designers, but not for C++ students.

Overview

The purpose of these objects and functions is to allow the
student to write interesting programs without learning a
full-blown graphical interface. Also the graphical objects
provide a simple example of using objects. After using objects 
to learn the basics of programming, object-oriented programming 
concepts of classes and instancing are introduced. The student
will then begin to define new classes.

All graphic objects are subclassed from class gob (for "graphic 
object"). All graphic objects are automatically displayed in a
pre-defined window. Objects are displayed for the lifetime of
their scope. In other words, an object declared as a global 
variable will be displayed always.  A graphic object declared
local to a function will only be displayed for the lifetime of
the function invocation. Objects have a visibility attribute
that can be used to hide them.

All display and redisplay is implicit, which frees the user
from any kind of display management. This is not always an
advantage, e.g. drawing a set of lines requires the programmer
to create a line object for each line to be displayed. In any
case, the programmer can set attributes of objects and query
the state of objects using a set of member functions described
below.

Some Implementation Details

There is a global display list of all graphic objects. Objects
automatically put themselves on the list at creation time, and 
remove themselves when they are destroyed. Objects also make
calls to Windows to invalidate regions of the display when
changes are made. Programmers are expected to use a pre-defined
application framework, which automatically updates the display
before waiting for user input or for a time delay. The graphic
object code is integrated with the application framework to hide
all graphical interface details from novice programmers.

The interactive functions are non-standard, at least for Windows.
The functions provide blocking I/O by running a standard
event processing loop until input of the desired type arrives
or until an indicated time delay has passed.  All events arriving
at the event processing loop are placed in queues for retrieval
by the interactive functions.

Graphic Objects

The graphic objects are described here. Specifications for the
interaction functions will follow.

Class "gob"

The parent class for all graphic objects is "gob".  It defines
several fields used by all graphic objects:
    next - the next object in the display list
    visible - a flag indicating whether to display the object
    changed - a flag indicating whether the object has been 
    	modified
	x1, y1, x2, y2 - screen coordinates. See particular object
		classes for the interpretation of these fields
	fillcolor - the color used to fill the object, if applicable
	linecolor - the color used to outline the object
	linewidth - the width of the outline
These fields can be read, but they should never be written
directly by the programmer.  Use member functions instead.
Here are the member functions inherited by every graphic object:
	void MoveTo(int x, int y) - Move the object to location 
		(x, y).  Coordinates are relative to the upper left of
		the window. Increasing y values move down the screen.
		In general, the object is moved so that its upper left
		corner is at location (x, y).
	void MoveRel(int dx, int dy) - Move the object by the distance
		(dx, dy).
	void BBox(int &left, int &top, int &right, int &bottom) - 
		gets a bounding box for the object.  This is intended 
		for the redisplay system, but may be called by anyone.
	void SetFillColor(int color) - Sets the fillcolor of an
		object. Valid arguments are:   
		CLR_WHITE, CLR_BLACK, CLR_GRAY, CLR_RED, CLR_ORANGE,
		CLR_YELLOW, CLR_GREEN, CLR_BLUE, CLR_PURPLE, CLR_NONE,
		where CLR_NONE means "no fill," i.e. transparent.
	void SetLineColor(int color) - Sets the linecolor of an
		object. Valid arguments are the same as for 
		SetFillColor.
	void SetLineWidth(int width) - Sets the linewidth of an
		object, in pixels.
	void SetVisible(int v) - Sets the visibility of an object.
		Use 1 for visible, 0 for invisible.
In addition, there are Erase, Draw, and other routines for 
internal use.

Class "line"

The line class inherits from gob, and has the following special
properties:

x1, y1 refer to one of the line's endpoints. The other endpoints
are set by calling member function
	void EndAt(int x, int y) - sets the other line endpoint.
Lines are not filled, so the fillcolor is ignored.

Class "rect"

The rect class inherits from gob and draws a rectangle. It has
the following special properties:

x1, y1 refer to the upper left.  x2, y2 refer to the lower
right. x2 and y2 are not directly accessible.  Member functions:
	void SetWidth(int width)
	void SetHeight(int height)
are used to set the width and height of the rectangle. Neither
width nor height can be less than zero.

Class "oval"

The oval class inherits from gob and draws an oval. Except for
appearance, it is exactly like class rect, and the oval is 
always inscribed within the corresponding rectangle.

Class "text"

The text class inherits from gob and draw a text string. It has
the following special properties:

x1, y1 refer to the upper left. x2 and y2 are not directly
accessible. The text uses linecolor for the text color and 
ignores fillcolor and linewidth. The following member function
is used to specify the text:
	void SetText(char *text) - sets the text to be displayed 
Use the BBox member function to determine the width and height.

Interaction Functions

cin and cout work according to the normal iostream semantics,
except that the programmer should include "tutorial.h" rather
than the normal include files, and output appears in a
scrolling window.

There are input functions that block until a value can be 
returned:
	void WaitMouse(int &x, int &y) - waits for a button-down
		event and sets x and y
	int WaitChar() - waits for a character to be typed and
		returns it
	int Pause(long ms) - waits a duration given in milliseconds
	
There are also non-blocking functions for input:
	int GetMouse(int &x, int &y) - returns TRUE if mouse input
		is pending, in which case x and y are set. Otherwise,
		returns false.
	int GetChar(char &c) - returns TRUE if typed input is
		pending, in which case c is set to the character typed.
		Otherwise returns false.
	void EventWait(long timeout) - waits until timeout (an
		absolute time specified in milliseconds), but returns
		early if any input appears before timeout. EventWait
		returns immediately if input is pending. A parameter of
		-1 means to wait forever for input.

To get the current time, call
	long GetTime() - returns time since program started in
		milliseconds.