Supplemental Documentation: The EzWindows library

To continue developing our use of interesting objects, we will experiment a bit with a graphics library provided by the authors of our textbook. This library is known as EzWindows and has been installed on our department machines. Please note that this is not part of the standard C++ libraries but instead has been designed by the authors for instructional purposes. Programming Note: If you are trying to do any of your programming without use of your department account, you will not be able to use EzWindows (unless you install it yourself).

The EzWindows library is initially discussed, in part, in Chapter 3.9 of the text, and discussed in a variety of places later in the text as well. Appendix E of the text (starting at page 891) gives more complete and organized documentation of the entire package. Be warned that that documentation is more complete than we need; we will only be discussing a subset of the library functionality. But still it gives a nice overview if scanned.

Preliminaries

The graphical system is based on the use of a coordinate system for which the origin is at the top-left corner. The positive x-axis is to the right, and the positive y-axis is downward (note the difference in orientation between this common computer science convention and the common mathematics conventions).

The unit of measure is centimeters (or fractions thereof). Of course, this may be only approximate depending on the system.

A color type has been defined to include a palette of common colors, identified with the names: Black, White, Red, Green, Blue, Yellow, Cyan, Magenta

Relevant Classes

• Position
• SimpleWindow
• WindowObject
• Label
• RaySegment
• Shape
  • RectangleShape
  • CircleShape
  • TriangleShape
  • SquareShape

class Position

This class is really defined as a convenience for the rest of the package. The graphics package deals with a two-dimenensional coordinate system. This means when describing the position of graphical objects, we might wish to specify two distinct numeric objects, one of which for the "x-coordinate" and another for the "y-coordinate".

Alternatively, it may be more convenient to have a single object which reprsents such a two-dimensional positional data. This is how the Position class is defined.

attributes (i.e. data members)

• float XDistance
  measured in centimeters.

• float YDistance
  measured in centimeters.

constructor(s)

• Position();
  The default construtor creates a position representing (0.0,0.0)

• Position(float x, float y);
  This constructor creates a position representing (x,y) for the given parameter values.

actions (i.e. member functions, methods)

• float GetXDistance()
  returns the current setting

• float GetYDistance()
  returns the current setting

• float SetXDistance(float x)
  alters the current setting to equal the given parameter value

• float SetYDistance(float y)
  alters the current setting to equal the given parameter value

• The class also supports the use of operators +, -, ==, != to perform basic arithmetic or comparison for positions.

class SimpleWindow

A SimpleWindow object represents a window which can be placed on the screen. All of the other graphical primitives must be associated with such a window in order to be created or displayed.

attributes (i.e. data members)

• string Title
  title which appears at the top of the displayed window.

• float Width
  the width of the window, measured in centimeters

• float Height
  the height of the window, measured in centimeters

constructors

• SimpleWindow();
  This creates a "default" window. Such a window has a title "Untitled", has 8cm x 8cm size, and is initially with the top-left corner of the window at a position 3cm from the top of the screen and 3cm from the left of the screen.

• SimpleWindow(string title)
  Creates a window similar to the default, but with the specified title.

• SimpleWindow(string title, float width, float height)
  Creates a window similar to the default, but with the specified title, width and height.

• SimpleWindow(string title, float width, float height, Position initialPos)
  Creates a window with all of the specified characteristic, where initialPos is the initial position of the top-left corner of the window relative to the screen.

actions (i.e. member functions, methods)

• WindowStatus Open()
  Makes the window appear on the display. The return value represents the resulting state of the window.

• WindowStatus Close()
  Removes the window from the display.

• float GetWidth() const
  Returns the current width of the window

• float GetHeight() const
  Returns the current height of the window

class WindowObject

Though we will generally not try to create objects from this class directly, it is worth discussing this because all of the other graphical primitives we will see are variants of this base class.

attributes (i.e. data members)

What all such objects have in common is that they have a "center" position and an associated window

• Position Center
  the (x,y) coordinates of the center of the object

• SimpleWindow& window
  a reference to the associated window for this object

actions (i.e. member functions, methods)

All such objects will support the following actions:

• Position GetPosition()
  Returns the current value of the center position.

• void GetPosition(float& x, float& y)
  An alternative form of the above. Rather than return a position object, this has the effect of resetting the parameters' values to equal that of the current object center.

• void SetPosition(Position p)
  Changes the "center" position of this object to equal that of the given parameter value.

• void SetPosition(float x, float y)
  An alternative form of the above, with the center position set based upon the given parameters.

class Label

A Label is one particular kind of WindowObject. For this reason, it includes all of the attributes and actions supported by the more general class WindowObject. In addition, a Label object supports the following:

attributes (i.e. data members)

• color TextColor;
  the foreground color of the label, that is, the color used to draw the text itself.

• color BackgroundColor;
  the background color of the label.

• string Text
  the actual text of the label.

constructors

• Label(SimpleWindow& W, Position center, string text);
  When creating a Label object, at bare minimum you must specify the associted SimpleWindow object, the position of the center of the label relative to that window, and the actual text. The default color settings will be that of black text on a white background.

• Label(SimpleWindow& W, float centerX, float centerY, string text);
  Similar result to above constructor, yet with center position specified as two separate float parameters, rather than one Position object.

• Label(SimpleWindow& W, Position center, string text, color textColor, color backgroundColor);
  Similar to the first form, but with the foreground and background colors explicitly specified.

• Label(SimpleWindow& W, float centerX, float centerY, string text, color textColor, color backgroundColor);
  Similar to the second form, but with the foreground and background colors explicitly specified.

actions (i.e. member functions, methods)

• color GetColor()
  returns the current foreground color.

• void SetColor(color c)
  sets the current foreground color.

class RaySegment

A RaySegment object represents a "ray" which is either a line stroke from a start point to an end point and which optionally may include an arrow-head at the end point. Note carefully that the "center" position which is inherited from the WindowObject class is actually treated as the start point of a RaySegment.

A RaySegment is one particular kind of WindowObject. For this reason, it includes all of the attributes and actions supported by the more general class WindowObject. In addition, a RaySegment object supports the following:

attributes (i.e. data members)

• Position EndPoint;
  The end point of the ray.

• float Thickness;
  the thickness of the ray. The line stroke is formed by taking a circle with the given radius and tracing from the start point to the end point.

• bool Arrow
  should an arrow be drawn at the end Point?

constructors

• RaySegment(SimpleWindow& W, Position startPoint, Position endoint);
  When creating a RaySegment object, at bare minimum you must specify the associted SimpleWindow object, and the position of the start and end points. The default color will be black, the thickness 0.1cm, and without an arrow.

• RaySegment(SimpleWindow& W, float startX, float startY, float endX, float endY);
  Similar result to above constructor, yet with each position specified as two separate float parameters, rather than one Position object.

• RaySegment(SimpleWindow& W, Position startPoint, Position endoint, color c, float thickness, bool arrowhead);
  Similar to the first form, but with all parameters explicitly specified.

• RaySegment(SimpleWindow& W, float startX, float startY, float endX, float endY, color c, float thickness, bool arrowhead);
  Similar to the second form, but with all parameters explicitly specified.

actions (i.e. member functions, methods)

• void GetStartPoint(float& x, float& y)
  This has the effect of resetting the parameters' values to equal that of the current start point.

• void GetEndPoint(float& x, float& y)
  This has the effect of resetting the parameters' values to equal that of the current end point.

• void GetPoints(Position& start, Position& end)
  A way to query both end points at once. This has the effect of resetting the parameters' values to equal that of the current start and end point, respectively

• void SetStartPoint(Position p)
  Changes the start position of the ray to equal that of the given parameter value.

• void SetStartPoint(float x, float y)
  An alternative form of the above, with the start point specified by two float paraemters.

• void SetEndPoint(Position p)
  Changes the end position of the ray to equal that of the given parameter value.

• void SetEndPoint(float x, float y)
  An alternative form of the above, with the end point specified by two float paraemters.

• void SetPoints(Position start, Position end)
  A way to set both end points at once. This has the effect of setting the ray's start and end points to equal the values of the respective parameters.

• float GetLength()
  returns the current length of the ray.

• color GetColor()
  returns the current ray color.

• void SetColor(color c)
  sets the current ray color.

• float GetThickness()
  returns the current thickness.

• void SetThickness(float t)
  sets the current thickness

• void SetArrowHead()
  Sets the arrow attribute of the ray object to true.

• void ClearArrowHead()
  Sets the arrow attribute of the ray object to false.

• bool HasArrow()
  Returns the current setting of the ray object's arrow attribute.

class Shape

The remaining window object types share some additional commonalities, in that each represents an object with "area." The class Shape is a general class which identifies those commonalities. So in addition to all of the attributes and actions associated with te more general class WindowObject, all Shape objects offer the following additional support:

attributes (i.e. data members)

• color Color
  the color of the shape, chosen from the available "color" type

• bool Border
  a true/false value which is true if the border is on, and false if the border is off. Note: By default, the border will be set to true.

actions (i.e. member functions, methods)

• void Draw()
  Draws the shape on the associated window based on its current settings. Please note, this does not explicitly remove any previous rendering of the shape.

• void Erase()
  Erases the image of the shape from the associated window based on its current settings. Please note, this does not reconstruct any image which may have been "under" the shape. Instead, it sets the area of the shape back to the background color for the window.

• void SetColor(c)
  sets the color attribute of the shape to the desired color.

• color GetColor()
  returns the current setting of the shape's color attribute

• void SetBorder()
  Sets the border attribute of the shape object to true.

• void ClearBorder()
  Sets the border attribute of the shape object to false.

• bool HasBorder()
  Returns the current setting of the shape object's border attribute.

class RectangleShape

A RectangleShape is one particular kind of Shape. For this reason, it includes all of the attributes and actions supported by the more general class WindowObject and class Shape. In addition, a RectangleShape object supports the following:

attributes (i.e. data members)

• float Width
  the width of the rectangle, measured in centimeters.

• float Height
  the height of the rectangle, measured in centimeters.

constructors

• RectangleShape(SimpleWindow& W, Position center);
  When creating a RectangleShape object, at bare minimum you must specify the associted SimpleWindow object, as well as the position of the center of the rectangle relative to that window. The remaining attributes will be set according the the default of a color of Red, a width of 1cm and a height of 2cm.

• RectangleShape(SimpleWindow& W, float centerX, float centerY);
  Similar result to above constructor, yet with center position specified as two separate float parameters, rather than one Position object.

• RectangleShape(SimpleWindow& W, float centerX, float centerY, color c, float width, float height);
  This constructs a rectangle with all attributes specified based upon the given parameter values.

actions (i.e. member functions, methods)

• float GetWidth()
  returns the current width of the rectangle.

• float GetHeight()
  returns the current height of the rectangle.

• void GetSize(float &w, float &h)
  Calling this method has the effect of resetting the values of parameters w and h to equal the current rectangle size. This does not change the rectangle itself.

• void SetSize(float w, float h)
  Calling this method changes the current width and height of the rectangle based upon the values of the given parameters.

class CircleShape

A CircleShape is one particular kind of Shape. For this reason, it includes all of the attributes and actions supported by the more general class WindowObject and class Shape. In addition, a CircleShape object supports the following:

attributes (i.e. data members)

• float Diameter
  the diameter of the circle, measured in centimeters.

constructors

• CircleShape(SimpleWindow& W, Position center);
  When creating a CircleShape object, at bare minimum you must specify the associted SimpleWindow object, as well as the position of the center of the circle relative to that window. The remaining attributes will be set according the the default of a color of Red and diameter of 1cm.

• CircleShape(SimpleWindow& W, Position center, color c, float diameter);
  This constructs a circle with all attributes specified based upon the given parameter values.

actions (i.e. member functions, methods)

• float GetDiamter()
  Returns the current diameter of the circle.

• void SetSize(float d)
  Calling this method changes the current diameter of the circle based upon the value of the given parameter.

class TriangleShape

As defined by this library, a triangle represents only equilateral triangles with a horizontal bottom edge. A TriangleShape is one particular kind of Shape. For this reason, it includes all of the attributes and actions supported by the more general class WindowObject and class Shape. In addition, a TriangleShape object supports the following:

attributes (i.e. data members)

• float SideLength
  the length of each side of the triangle, measured in centimeters.

constructors

• TriangleShape(SimpleWindow& W, Position center);
  When creating a TriangleShape object, at bare minimum you must specify the associted SimpleWindow object, as well as the position of the center of the triangle relative to that window. The remaining attributes will be set according the the default of a color of Red and side length of 1cm.

• TriangleShape(SimpleWindow& W, Position center, color c, float sidelength);
  This constructs a triangle with all attributes specified based upon the given parameter values.

actions (i.e. member functions, methods)

• float GetSideLength()
  Returns the current side length of the triangle.

• void SetSize(float sl)
  Calling this method changes the current side length of the triangle based upon the value of the given parameter.

class SquareShape

A SquareShape is one particular kind of Shape. For this reason, it includes all of the attributes and actions supported by the more general class WindowObject and class Shape. In addition, a SquareShape object supports the following:

attributes (i.e. data members)

• float SideLength
  the length of each side of the square, measured in centimeters.

constructors

• SquareShape(SimpleWindow& W, Position center);
  When creating a SquareShape object, at bare minimum you must specify the associted SimpleWindow object, as well as the position of the center of the square relative to that window. The remaining attributes will be set according the the default of a color of Red and side length of 1cm.

• SquareShape(SimpleWindow& W, Position center, color c, float sidelength);
  This constructs a square with all attributes specified based upon the given parameter values.

actions (i.e. member functions, methods)

• float GetSideLength()
  Returns the current side length of the square.

• void SetSize(float sl)
  Calling this method changes the current side length of the square based upon the value of the given parameter.

class EllipseShape

A EllipseShape is one particular kind of Shape, representing an axis-aligned ellipse. For this reason, it includes all of the attributes and actions supported by the more general class WindowObject and class Shape. In addition, a EllipseShape object supports the following:

attributes (i.e. data members)

• float Width
  the width of the ellipse, measured in centimeters.

• float Height
  the height of the ellipse, measured in centimeters.

constructors

• EllipseShape(SimpleWindow& W, Position center);
  When creating a EllipseShape object, at bare minimum you must specify the associted SimpleWindow object, as well as the position of the center of the ellipse relative to that window. The remaining attributes will be set according the the default of a color of Red, a width of 1cm and a height of 2cm.

• EllipseShape(SimpleWindow& W, Position center, color c, float width, float height);
  This constructs a ellipse with all attributes specified based upon the given parameter values.

actions (i.e. member functions, methods)

• float GetWidth()
  returns the current width of the ellipse.

• float GetHeight()
  returns the current height of the ellipse.

• void GetSize(float &w, float &h)
  Calling this method has the effect of resetting the values of parameters w and h to equal the current ellipse size. This does not change the ellipse itself.

• void SetSize(float w, float h)
  Calling this method changes the current width and height of the ellipse based upon the values of the given parameters.