gobjects.h

This interface exports a hierarchy of graphical shapes based on the model developed for the ACM Java Graphics. These subclasses form a hierarchy that looks like this:

GObjectHierarchy
GObject GArc GImage GLabel GLine GOval GRect GPolygon GCompound G3DRect GRoundRect
Types
GObject This type represents an abstract type that unifies the set of all graphics objects.
GRect This type represents a graphical object whose appearance consists of a rectangular box.
GRoundRect This type represents a rectangular box with rounded corners.
G3DRect This type represents a rectangular box that can appear raised or lowered.
GOval This type represents an oval inscribed in a rectangular box.
GLine This type represents a line segment.
GArc This type represents an elliptical arc.
GLabel This subtype represents a text string.
GImage This subtype represents an image from a file.
GPolygon This subtype represents a polygon bounded by line segments.
GCompound This subtype consists of a collection of other graphical objects.
Functions
freeGObject(gobj) Frees the memory associated with the object.
getX(gobj) Returns the x-coordinate of the object.
getY(gobj) Returns the y-coordinate of the object.
getLocation(gobj) Returns the location of this object as a GPoint.
setLocation(gobj, x, y) Sets the location of this object to the specified coordinates.
move(gobj, dx, dy) Moves the object on the screen using the displacements dx and dy.
getWidth(gobj) Returns the width of this object, which is defined to be the width of the bounding box.
getHeight(gobj) Returns the height of this object, which is defined to be the height of the bounding box.
getSize(gobj) Returns the size of the object as a GDimension.
getBounds(gobj) Returns the bounding box of this object, which is defined to be the smallest rectangle that covers everything drawn by the figure.
setColor(gobj, color) Sets the color used to display this object.
getColor(gobj) Returns the color used to display this object.
setVisible(gobj, flag) Sets whether this object is visible.
isVisible(gobj) Returns true if this object is visible.
sendForward(gobj) Moves this object one step toward the front in the z dimension.
sendToFront(gobj) Moves this object to the front of the display in the z dimension.
sendBackward(gobj) Moves this object one step toward the back in the z dimension.
sendToBack(gobj) Moves this object to the back of the display in the z dimension.
contains(gobj, x, y) Returns true if the specified point is inside the object.
getType(gobj) Returns the subtype of the object as a string, as in "GOval" or "GRect".
getParent(gobj) Returns a pointer to the GCompound that contains this object.
setSize(gobj, width, height) Changes the size of this object to the specified width and height.
setBounds(gobj, x, y, width, height) Changes the bounds of this object to the specified values.
setFilled(gobj, flag) Sets the fill status for gobj, where false is outlined and true is filled.
isFilled(gobj) Returns true if gobj is filled.
setFillColor(gobj, color) Sets the color used to display the filled region of this rectangle.
getFillColor(gobj) Returns the color used to display the filled region of gobj.
newGRect(x, y, width, height) Creates a new GRect with the specified bounds.
newGRoundRect(x, y, width, height, corner) Creates a new GRoundRect with the specified dimensions.
newG3DRect(x, y, width, height, raised) Creates a new G3DRect with the specified dimensions.
setRaised(rect, raised) Indicates whether this object appears raised.
isRaised(rect) Returns true if this object appears raised.
newGOval(x, y, width, height) Creates a new GOval with the specified bounds.
newGLine(x0, y0, x1, y1) Creates a new graphical line connecting the points (x0y0) and (x1y1).
setStartPoint(gline, x, y) Sets the start point for the line to (xy), leaving the end point unchanged.
setEndPoint(line, x, y) Sets the end point for the line to (xy), leaving the start point unchanged.
getStartPoint(gobj) Returns the point at which a GLine or GArc starts.
getEndPoint(gobj) Returns the point at which a GLine or GArc ends.
newGArc(x, y, width, height, start, sweep) Creates a new GArc consisting of an elliptical arc.
setStartAngle(arc, start) Sets the starting angle for this GArc object.
getStartAngle(arc) Returns the starting angle for this GArc object.
setSweepAngle(arc, start) Sets the sweep angle for this GArc object.
getSweepAngle(arc) Returns the sweep angle for this GArc object.
setFrameRectangle(arc, x, y, width, height) Changes the boundaries of the rectangle used to frame the arc.
getFrameRectangle(arc) Returns the boundaries of the rectangle used to frame the arc.
newGLabel(str) Creates a GLabel object containing the specified string, positioned with an origin of (0, 0).
setFont(label, font) Changes the font used to display the GLabel as specified by the string font, which has the following format:
    family-style-size 
where both style and size are optional.
getFont(label) Returns the current font for the GLabel.
setLabel(label, str) Changes the string stored within the GLabel object, so that a new text string appears on the display.
getLabel(label) Returns the string displayed by this object.
getFontAscent(label) Returns the maximum distance strings in this font extend above the baseline.
getFontDescent(label) Returns the maximum distance strings in this font descend below the baseline.
newGImage(filename) Constructs a new image by loading the image from the specified file, which is either in the current directory or a subdirectory named images.
newGPolygon() Constructs a new empty polygon.
addVertex(poly, x, y) Adds a vertex at (x, y) relative to the polygon origin.
addEdge(poly, dx, dy) Adds an edge to the polygon whose components are given by the displacements dx and dy from the last vertex.
addPolarEdge(poly, r, theta) Adds an edge to the polygon specified in polar coordinates.
getVertices(poly) Returns a vector whose elements are pointers to the GPoint values that represent the vertices.
newGCompound() Creates a new graphical compound with no internal components.
add(compound, gobj) Adds the object to the compound.
add(compound, gobj) Removes the object from the compound.

Type detail


typedef struct GObjectCDT *GObject;
This type represents an abstract type that unifies the set of all graphics objects. As with an abstract class in an object-oriented language, it is not legal to create a GObject directly. Graphical objects are created instead by calling the constructor for one of the concrete subclasses, as follows:

Even though C has no object-oriented hierarchies, this interface defines the types GArc, GCompound, GImage, GLabel, GLine, GOval, GPolygon, GRect, GRoundRect, and G3DRect as synonyms for GObject. Doing so helps to clarify what types are expected by each function and simplifies the process of converting code from languages that implement full hierarchies.


typedef GObject GRect;
This type represents a graphical object whose appearance consists of a rectangular box. For example, the following code adds a filled, red, 200x100 rectangle at the upper left corner of the graphics window:
   main() {
      GWindow gw = newGWindow(500, 300);
      printf("This program draws a red rectangle at (0, 0).\n")
      GRect rect = newGRect(0, 0, 200, 100);
      setFilled(rect, true);
      setColor(rect, "RED");
      add(gw, rect);
   }

Usage:

color = getFillColor(gobj);

typedef GRect GRoundRect;
This type represents a rectangular box with rounded corners.

Usage:

rect = newGRect(x, y, width, height);

typedef GRect G3DRect;
This type represents a rectangular box that can appear raised or lowered.

Usage:

GRoundRect rect = newGRoundRect(x, y, width, height, corner);

typedef GObject GOval;
This type represents an oval inscribed in a rectangular box. For example, the following code displays a filled green oval inscribed in the graphics window:
   main() {
      GWindow gw = newGWindow(500, 300);
      printf("This program draws a green oval filling the window.\n");
      GOval oval = newGOval(getWidth(gw), getHeight(gw));
      setFilled(oval, true);
      setColor(oval, "GREEN");
      add(gw, oval);
   }

Usage:

if (isRaised(rect)) ...

typedef GObject GLine;
This type represents a line segment. For example, the following code adds lines that mark the diagonals of the graphics window:
   main() {
      GWindow gw = newGWindow(500, 300);
      printf("This program draws the diagonals on the window.\n");
      add(gw, newGLine(0, 0, getWidth(gw), getHeight(gw)));
      add(gw, newGLine(0, getHeight(gw), getWidth(gw), 0));
   }

Usage:

oval = newGOval(x, y, width, height);

typedef GObject GArc;
This type represents an elliptical arc. The arc is specified by the following parameters:

All angles in a GArc description are measured in degrees moving counterclockwise from the +x axis. Negative values for either start or sweep indicate motion in a clockwise direction.

The following diagram illustrates the interpretation of these parameters for the arc shown in red:

GArcGeometry

Usage:

pt = getEndPoint(gobj);

typedef GObject GLabel;
This subtype represents a text string. For example, the following code adds a GLabel containing "hello, world" to the center of the window:
   main() {
      GWindow gw;
      GLabel label;
      double x, y;

      printf("This program draws the 'hello, world' message.\n");
      gw = newGWindow(600, 400);
      label = newGLabel("hello, world");
      setFont(label, "SansSerif-18");
      x = (getWidth(gw) - getWidth(label)) / 2;
      y = (getHeight(gw) + getFontAscent(label)) / 2;
      setLocation(label, x, y);
      add(gw, label);
   }
Controlling the appearance and positioning of a GLabel depends on understanding the following terms:

The following diagram illustrates the interpretation of these terms:

GLabelGeometry

Usage:

rect = getFrameRectangle(arc);

typedef GObject GImage;
This subtype represents an image from a file. For example, the following code adds a GImage containing the Stanford tree at the center of the window, assuming that the image file StanfordTree.png exists, either in the current directory or an images subdirectory:
   main() {
      printf("This program draws the Stanford tree.\n");
      GWindow gw = newGWindow(600, 400);
      GImage tree = newGImage("StanfordTree.png");
      double x = (getWidth(gw) - getWidth(tree)) / 2;
      double y = (getHeight(gw) - getHeight(tree)) / 2;
      add(gw, tree, x, y);
   }

Usage:

descent = getFontDescent(label);

typedef GObject GPolygon;
This subtype represents a polygon bounded by line segments. The newGPolygon function creates an empty polygon. To complete the figure, you need to add vertices to the polygon using the functions addVertex, addEdge, and addPolarEdge. As an example, the following code adds a filled red octagon to the center of the window:
   main() {
      GWindow gw;
      GPolygon stopSign;
      double edge;
      int i;

      printf("This program draws a red octagon.\n");
      gw = newGWindow(600, 400);
      edge = 75;
      stopSign = newGPolygon();
      addVertex(stopSign, -edge / 2, edge / 2 + edge / sqrt(2.0));
      for (i = 0; i < 8; i++) {
         addPolarEdge(stopSign, edge, 45 * i);
      }
      setFilled(stopSign, true);
      setColor(stopSign, "RED");
      add(gw, stopSign, getWidth(gw) / 2, getHeight(gw) / 2);
   }

The program results in the following picture:

StopSign

Usage:

GImage image = newGImage(filename);

typedef GObject GCompound;
This subtype consists of a collection of other graphical objects. Once assembled, the internal objects can be manipulated as a unit. The GCompound keeps track of its own position, and all items within it are drawn relative to that location.

Usage:

vec = getVertices(poly);

Function detail


void freeGObject(GObject gobj);
Frees the memory associated with the object. This operation is not necessary for objects that have been installed in a window. Adding a GObject to a GWindow or a GCompound transfers ownership to the container, which assumes responsibility for freeing the object.

Usage:

freeGObject(gobj);

double getX(GObject gobj);
Returns the x-coordinate of the object.

Usage:

x = getX(gobj);

double getY(GObject gobj);
Returns the y-coordinate of the object.

Usage:

y = getY(gobj);

GPoint getLocation(GObject gobj);
Returns the location of this object as a GPoint.

Usage:

pt = getLocation(gobj);

void setLocation(GObject gobj, double x, double y);
Sets the location of this object to the specified coordinates.

Usage:

setLocation(gobj, x, y);

void move(GObject gobj, double dx, double dy);
Moves the object on the screen using the displacements dx and dy.

Usage:

move(gobj, dx, dy);

double getWidth(GObject gobj);
Returns the width of this object, which is defined to be the width of the bounding box.

Usage:

width = getWidth(gobj);

double getHeight(GObject gobj);
Returns the height of this object, which is defined to be the height of the bounding box.

Usage:

height = getHeight(gobj);

GDimension getSize(GObject gobj);
Returns the size of the object as a GDimension.

Usage:

size = getSize(gobj);

GRectangle getBounds(GObject gobj);
Returns the bounding box of this object, which is defined to be the smallest rectangle that covers everything drawn by the figure. The coordinates of this rectangle do not necessarily match the location returned by getLocation. Given a GLabel object, for example, getLocation returns the coordinates of the point on the baseline at which the string begins; the getBounds method, by contrast, returns a rectangle that covers the entire window area occupied by the string.

Usage:

rect = getBounds(gobj);

void setColor(GObject gobj, string color);
Sets the color used to display this object. The color string is usually one of the predefined color names: BLACK
BLUE
CYAN
DARK_GRAY
GRAY
GREEN
LIGHT_GRAY
MAGENTA
ORANGE
PINK
RED
WHITE
YELLOW

The case of the individual letters in the color name is ignored, as are spaces and underscores, so that the color DARK_GRAY can be written as "Dark Gray".

Usage:

setColor(gobj, color);

string getColor(GObject gobj);
Returns the color used to display this object. This color is always returned as a string in the form "#rrggbb", where rr, gg, and bb are the red, green, and blue components of the color, expressed as two-digit hexadecimal values.

Usage:

color = getColor(gobj);

void setVisible(GObject gobj, bool flag);
Sets whether this object is visible.

Usage:

setVisible(gobj, flag);

bool isVisible(GObject gobj);
Returns true if this object is visible.

Usage:

if (isVisible(gobj)) . . .

void sendForward(GObject gobj);
Moves this object one step toward the front in the z dimension. If it was already at the front of the stack, nothing happens.

Usage:

sendForward(gobj);

void sendToFront(GObject gobj);
Moves this object to the front of the display in the z dimension. By moving it to the front, this object will appear to be on top of the other graphical objects on the display and may hide any objects that are further back.

Usage:

sendToFront(gobj);

void sendBackward(GObject gobj);
Moves this object one step toward the back in the z dimension. If it was already at the back of the stack, nothing happens.

Usage:

sendBackward(gobj);

void sendToBack(GObject gobj);
Moves this object to the back of the display in the z dimension. By moving it to the back, this object will appear to be behind the other graphical objects on the display and may be obscured by other objects in front.

Usage:

sendToBack(gobj);

bool contains(GObject gobj, double x, double y);
Returns true if the specified point is inside the object.

Usage:

if (contains(gobj, x, y)) . . .

string getType(GObject gobj);
Returns the subtype of the object as a string, as in "GOval" or "GRect".

Usage:

type = getType(gobj);

GObject getParent(GObject gobj);
Returns a pointer to the GCompound that contains this object. Every GWindow is initialized to contain a single GCompound that is aligned with the window. Adding objects to the window adds them to that GCompound, which means that every object you add to the window has a parent. Calling getParent on the top-level GCompound returns NULL.

Usage:

parent = getParent(gobj);

void setSize(GObject gobj, double width, double height);
Changes the size of this object to the specified width and height. This method applies to the types GOval, GImage, and GRect (and its subclasses).

Usage:

setSize(gobj, width, height);

void setBounds(GObject gobj, double x, double y, double width, double height);
Changes the bounds of this object to the specified values. This method applies to the types GOval, GImage, and GRect (and its subclasses).

Usage:

setBounds(gobj, x, y, width, height);

void setFilled(GObject gobj, bool flag);
Sets the fill status for gobj, where false is outlined and true is filled.

Usage:

setFilled(gobj, flag);

bool isFilled(GObject gobj);
Returns true if gobj is filled.

Usage:

if (isFilled(gobj)) . . .

void setFillColor(GObject gobj, string color);
Sets the color used to display the filled region of this rectangle.

Usage:

setFillColor(gobj, color);

string getFillColor(GObject gobj);
Returns the color used to display the filled region of gobj. rectangle. If none has been set, getFillColor returns the empty string.

Usage:

color = getFillColor(gobj);

GRect newGRect(double x, double y, double width, double height);
Creates a new GRect with the specified bounds. By default, the rectangle is unfilled.

Usage:

rect = newGRect(x, y, width, height);

GRoundRect newGRoundRect(double x, double y, double width, double height, double corner);
Creates a new GRoundRect with the specified dimensions. The corner parameter specifies the diameter of the arc forming the corner.

Usage:

GRoundRect rect = newGRoundRect(x, y, width, height, corner);

G3DRect newG3DRect(double x, double y, double width, double height, bool raised);
Creates a new G3DRect with the specified dimensions. The corner parameter specifies whether this rectangle should appear raised.

Usage:

G3DRect rect = newG3DRect(x, y, width, height, raised);

void setRaised(G3DRect rect, bool raised);
Indicates whether this object appears raised.

Usage:

setRaised(rect, raised);

bool isRaised(G3DRect rect);
Returns true if this object appears raised.

Usage:

if (isRaised(rect)) ...

GObject newGOval(double x, double y, double width, double height);
Creates a new GOval with the specified bounds. By default, the oval is unfilled.

Usage:

oval = newGOval(x, y, width, height);

GObject newGLine(double x0, double y0, double x1, double y1);
Creates a new graphical line connecting the points (x0y0) and (x1y1).

Usage:

line = newGLine(x0, y0, x1, y1);

void setStartPoint(GLine line, double x, double y);
Sets the start point for the line to (xy), leaving the end point unchanged. This method is therefore different from setLocation, which moves both components of the line segment.

Usage:

setStartPoint(gline, x, y);

void setEndPoint(GLine line, double x, double y);
Sets the end point for the line to (xy), leaving the start point unchanged.

Usage:

setEndPoint(line, x, y);

GPoint getStartPoint(GObject gobj);
Returns the point at which a GLine or GArc starts.

Usage:

pt = getStartPoint(gobj);

GPoint getEndPoint(GObject gobj);
Returns the point at which a GLine or GArc ends.

Usage:

pt = getEndPoint(gobj);

GArc newGArc(double x, double y, double width, double height, double start, double sweep);
Creates a new GArc consisting of an elliptical arc.

The following screenshots show several examples of how the GArc constructor interprets the start and sweep parameters:

GArcExamples

In the code fragments underneath each of these diagrams, r is the radius of the circular arc, and cx and cy are the coordinates of the center or the window.

Usage:

arc = newGArc(x, y, width, height, start, sweep);

void setStartAngle(GArc arc, double start);
Sets the starting angle for this GArc object.

Usage:

setStartAngle(arc, start);

double getStartAngle(GArc arc);
Returns the starting angle for this GArc object.

Usage:

angle = getStartAngle(arc);

void setSweepAngle(GArc arc, double start);
Sets the sweep angle for this GArc object.

Usage:

setSweepAngle(arc, start);

double getSweepAngle(GArc arc);
Returns the sweep angle for this GArc object.

Usage:

angle = getSweepAngle(arc);

void setFrameRectangle(GArc garc, double x, double y, double width, double height);
Changes the boundaries of the rectangle used to frame the arc.

Usage:

setFrameRectangle(arc, x, y, width, height);

GRectangle getFrameRectangle(GArc arc);
Returns the boundaries of the rectangle used to frame the arc.

Usage:

rect = getFrameRectangle(arc);

GLabel newGLabel(string str);
Creates a GLabel object containing the specified string, positioned with an origin of (0, 0).

Usage:

label = newGLabel(str);

void setFont(GLabel label, string font);
Changes the font used to display the GLabel as specified by the string font, which has the following format:
   family-style-size
where both style and size are optional. If any of these elements are missing or specified as an asterisk, the existing value is retained.

Usage:

setFont(label, font);

string getFont(GLabel label);
Returns the current font for the GLabel.

Usage:

font = getFont(label);

void setLabel(GLabel label, string str);
Changes the string stored within the GLabel object, so that a new text string appears on the display.

Usage:

setLabel(label, str);

string getLabel(GLabel label);
Returns the string displayed by this object.

Usage:

str = getLabel(label);

double getFontAscent(GLabel label);
Returns the maximum distance strings in this font extend above the baseline.

Usage:

ascent = getFontAscent(label);

double getFontDescent(GLabel label);
Returns the maximum distance strings in this font descend below the baseline.

Usage:

descent = getFontDescent(label);

GImage newGImage(string filename);
Constructs a new image by loading the image from the specified file, which is either in the current directory or a subdirectory named images. The upper left corner of the image is positioned at the origin.

Usage:

GImage image = newGImage(filename);

GPolygon newGPolygon(void);
Constructs a new empty polygon.

Usage:

poly = newGPolygon();

void addVertex(GPolygon poly, double x, double y);
Adds a vertex at (x, y) relative to the polygon origin.

Usage:

addVertex(poly, x, y);

void addEdge(GPolygon poly, double dx, double dy);
Adds an edge to the polygon whose components are given by the displacements dx and dy from the last vertex.

Usage:

addEdge(poly, dx, dy);

void addPolarEdge(GPolygon poly, double r, double theta);
Adds an edge to the polygon specified in polar coordinates. The length of the edge is given by r, and the edge extends in direction theta, measured in degrees counterclockwise from the +x axis.

Usage:

addPolarEdge(poly, r, theta);

Vector getVertices(GPolygon poly);
Returns a vector whose elements are pointers to the GPoint values that represent the vertices. This vector is shared with the internal data structure of the GPolygon and must not be freed by the client.

Usage:

vec = getVertices(poly);

GObject newGCompound(void);
Creates a new graphical compound with no internal components.

Usage:

comp = newGCompound();

void add(GCompound compound, GObject gobj);
Adds the object to the compound.

Usage:

add(compound, gobj);

void add(GCompound compound, GObject gobj);
Removes the object from the compound.

Usage:

add(compound, gobj);