campy.graphics.gobjects module

Provide a hierarchy of graphical shapes based on the ACM Graphics model.

This module exports the superclass GObject, as well as derived classes:

• GRect
• GRoundRect
• G3DRect
• GOval
• GArc
• GLine
• GImage
• GLabel
• GPolygon

There is also a GCompound class to facilitate nested object structures.

For more information on how to use each of these objects, see the comments on each class.

class campy.graphics.gobjects.G3DRect(width, height, *, x=None, y=None, raised=False)

Bases: campy.graphics.gobjects.GRect

Graphical representation of a rectangular box that can be raised or lowered.

The 3D effect of this rectangle is purely aesthetic and does not affect the rectangle’s z-positioning on the parent GCompound.

raised

Get or set whether this object appears raised.

True represents a rectangle with highlights to appear raised above the background. False represents a rectangle with highlights to appear lowered above the background.

class campy.graphics.gobjects.GArc(width, height, start, sweep, x=0, y=0)

Bases: campy.graphics.gobjects.GFillableObject

Graphical representation of an elliptical arc.

An elliptical arc is uniquely determined by the following three parameters:

• The coordinates of the ellipse’s bounding rectangle (width, height) and (x, y)
• The angle at which the arc starts (start)
• The number of degrees that the arc covers (sweep)

All angles in the GArc class are measured in degrees counterclockwise from the positive x-axis. Negative angles refer to degrees clockwise.

To create an semicircle arc starting 45 degrees counterclockwise of the positive x-axis with diameter 50:

window = GWindow()
arc = GArc(50, 50, 45, 180, x=0, y=0)
window.add(arc)

If a GArc is unfilled, the figure consists only of the arc itself.

If a GArc is filled, the figure consists of the pie-shaped wedge formed by connecting the endpoints of the arc to the center.

For example, the following program draws a 270-degree arc starting at 45 degrees filled in yellow, similar to the PacMan video game:

window = GWindow()
center = GPoint(window.width / 2, window.height / 2)
radius = 25
pacman = GArc(2 * radius, 2 * radius, 45, 270
    x=center.x - radius, y=center.y - radius)
pacman.filled = True
pacman.fill_color = "YELLOW"
window.add(pacman)

bounds

Get the bounding rectangle for this arc.

@rtype: GRectangle

containsAngle(theta)

Internal method

end_point

Get the GPoint at which the arc ends.

start

Get or set the starting angle (in degrees) of this GArc.

The starting angle is measured in degrees counterclockwise from the positive x-axis.

start_point

Get the GPoint at which the arc starts.

sweep

Get or set the sweep angle (in degrees) of this GArc.

The sweep angle is measured in degrees and represents the number of degrees carved out by this GArc. For example, a semi-elliptical arc has a sweep of 180 degrees.

class campy.graphics.gobjects.GCompound

Bases: campy.graphics.gobjects.GObject, collections.abc.MutableSequence

A graphics object that is a collection of other graphics objects.

Once assembled, the contained :class:`GObject`s can be manipulated as a unit.

The GCompound has its own position, and items within in are drawn relative to that position.

Internally, the GCompound just holds a stack of its :class:`GObject`s.

add(gobj, x=None, y=None)

Add a new GObject to this GCompound.

If two additional arguments x and y are both supplied, move the object to (x, y) first. It is an error to specify just one of x and y.

Parameters:

• gobj – The object to add to this compound.
• x – (optional) The x-coordinate of the location to which to move this object.
• y – (optional) The y-coordinate of the location to which to move this object.

bounds

Get the bounding box for this GCompound.

The bounding box of a GCompound is the smallest rectangle that covers all of its components bounding boxes.

Returns:A bounding box that covers all of this compounds components. Return type:GRectangle

clear()

Remove all graphical objects from the GCompound.

insert(index, value)

S.insert(index, value) – insert value before index

location

Get or set the location of this object as a GPoint.

You can supply either a GPoint or a 2-element tuple to this property. Accessing this property will return a GPoint which can be unpacked as a tuple.

remove(gobj)

Remove a GObject from this GCompound.

Return whether or not the GCompound contained the GObject.

Parameters:gobj – The object to remove. Returns:Whether this compound contained the object.

send_backward(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.

send_forward(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.

send_to_back(gobj)

Move 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 that are further forward.

send_to_front(gobj)

Move 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.

class campy.graphics.gobjects.GFillableObject(filled=False, fill_color=None)

Bases: campy.graphics.gobjects.GObject

Representation of a GObject that can be filled.

Subclasses of GFillableObject have a boolean property filled and a GColor-valued property fill_color.

fill_color

Return the color used to fill this object.

If none has been set, return the empty string.

filled

Get or set whether this object is filled.

A value of True corresponds to filled and a value of False corresponds to outlined.

class campy.graphics.gobjects.GLabel(label, x=0, y=0)

Bases: campy.graphics.gobjects.GObject

Graphical representation of a text string.

For example, to add a GLabel with the message “Hello, world!” to the center of a GWindow:

window = GWindow()
label = GLabel("Hello, world!")
label.font = "SansSerif-18"
x = (window.width - label.width) / 2
y = (window.height + label.ascent) / 2
window.add(label, x, y)

In order to control the appearance and positioning of a GLabel, it’s important to understand the following terms:

• The baseline is the horizontal line on which the characters rest.
• The origin is the point on the baseline at which the label begins.
• The height is the distance (in pixels) that would separate two successive lines such that characters would not overlap.
• The ascent is the maximum distance that any character in this font extends above the baseline.
• The descent is the maximum distance that any character in this font extends below the baseline.

ascent

Return the maximum distance strings in this font ascend above the baseline.

bounds

Get the bounding box for this GLabel.

The bounding box of a GLabel is the smallest rectangle that completely covers the displayed message.

Returns:A bounding box that covers this GLabel’s message. Return type:GRectangle

descent

Return the maximum distance strings in this font descend below the baseline.

font

Get or set this GLabel’s font.

text

Get or set this GLabel’s label.

Setting the label changes the internal state of the GLabel, so a existing drawn labels will redisplay.

class campy.graphics.gobjects.GLine(x0, y0, x1, y1)

Bases: campy.graphics.gobjects.GObject

Graphical representation of a line segment defined by two endpoints.

To create a line from (14, 41) to (601, 106):

line = GLine(14, 41, 601, 106)

To draw two diagonal lines crossing a GWindow:

window = GWindow()
window.add(GLine(0, 0, window.width, window.height))
window.add(GLine(0, window.height, window.width, 0))

Note that creating a GLine will not automatically add it to any displays. Rather, you must explicitly call the .add method on an appropriate GWindow.

end

Get or set this GLine’s ending point.

Changing the end point modifies the line segment even if it has already been added to a GWindow.

Usage:

window = GWindow()
line = GLine(0, 0, 41, 41)
window.add(line)
print(line.end)  # => GPoint(41, 41)
line.end = 4, 1
print(line.end)  # => GPoint(4, 1)

You can supply either a GPoint or a 2-element tuple to this property. Accessing this property will return a GPoint which can be unpacked as a tuple:

window = GWindow()
line = GLine(0, 0, 41, 41)
window.add(line)
line.end = GPoint(106, 106)  # Supply a GPoint to the setter.
endx, endy = line.start  # Unpack the end point immediately.

Setting the end point does not modify the start point. Thus, this is different from setting this GLine’s location, which translates the entire line segment.

start

Get or set this GLine’s starting point.

Changing the start point modifies the line segment even if it has already been added to a GWindow.

Usage:

window = GWindow()
line = GLine(0, 0, 41, 41)
window.add(line)
print(line.start)  # => GPoint(0, 0)
line.start = 4, 1
print(line.start)  # => GPoint(4, 1)

You can supply either a GPoint or a 2-element tuple to this property. Accessing this property will return a GPoint which can be unpacked as a tuple:

window = GWindow()
line = GLine(0, 0, 41, 41)
window.add(line)
line.start = GPoint(16, 25)  # Supply a GPoint to the setter.
startx, starty = line.start  # Unpack the start point immediately.

Setting the start point does not modify the end point. Thus, this is different from setting this GLine’s location, which translates the entire line segment.

class campy.graphics.gobjects.GObject

Bases: object

The common superclass of all graphical objects that can be displayed on a graphical window.

For examples illustrating the use of the GObject class, see the descriptions of the individual subclasses.

bounds

Get the bounding box for this object.

The bounding box of an object is the smallest rectangle that covers everything drawn by the figure. The coordinates of this rectangle will usually, but not always, match the object’s location. For example, the location of a GLabel gives the coordinates of the point on the baseline where the string begins. However, the bounds of the GLabel represent a rectangle that entirely covers the window area occupied by the GLabel.

Subclasses must override this property (and optionally declare a setter) to indicate their bounding box.

Returns:The bounding box of this GObject. Return type:GRectangle

color

Get or set the color used to draw this object.

The supplied color can be any object acceptable to GColor, so check that class’s documentation for complete details on arguments.

Usually, the supplied color will be one of the predefined colors:

• BLACK
• BLUE
• CYAN
• DARK_GRAY
• GRAY
• GREEN
• LIGHT_GRAY
• MAGENTA
• ORANGE
• PINK
• RED
• WHITE
• YELLOW

TODO(sredmond): Add more detail to the possible colors with examples.

Accessing this property will return a GColor which can be used anywhere that expects a color.

height

Get the height of this GObject.

The height of an object is the same as the height of its bounding box.

Returns:The height (in pixels) of this GObject.

line_width

Get or set the line width used to draw this GObject.

location

Get or set the location of this object as a GPoint.

You can supply either a GPoint or a 2-element tuple to this property. Accessing this property will return a GPoint which can be unpacked as a tuple.

move(dx, dy)

Move this object on the screen using the supplied displacements.

Parameters:

• dx – The displacement in the x-direction.
• dy – The displacement in the y-direction.

parent

Return the GCompound that contains this object, if it exists.

Each GWindow has a single GCompound that is aligned with the window. Adding objects to the window adds them to the window’s top GCompound. So, a GObject does not have a parent until it is added to a GCompound, either directly or by way of adding the GObject to a GWindow:

window = GWindow()
oval = GOval(0, 0, 41, 41)
print(oval.parent is None)  # => True
window.add(oval)
print(oval.parent is None)  # => False

Returns:This object’s parent GCompound, if it exists. Return type:GCompound

rotate(theta)

Rotate this object some degrees counterclockwise about its origin.

Param:The angle (in degrees) about which to rotate this object about its origin.

scale(*scales)

Scale this object by the given scale factor(s).

Most clients use the one-argument form, which scales an object in both dimensions. To double the size of a GOval:

oval = GOval(0, 0, 41, 41)
oval.scale(2)
print(oval.width, oval.height)  # => 82, 82

There is also a two-argument form which applies separate scale factors to the x- and y-dimensions:

oval = GOval(0, 0, 41, 41)
oval.scale(3, 5)
print(oval.width, oval.height)  # => 123, 205

It is an error to call this function with no arguments, or with three or more arguments.

Parameters:scales – The scale factors by which to scale this object.

send_backward()

Moves this object one step toward the back in the z dimension.

If it was already at the back of the stack, nothing happens.

send_forward()

Moves this object one step toward the front in the z dimension.

If it was already at the front of the stack, nothing happens.

send_to_back()

Move 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 that are further forward.

send_to_front()

Move 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.

size

Get the size of this GObject as a GDimension.

Returns:The size of this GObject in pixels. Return type:GDimension

visible

Get or set whether this GObject is visible.

A GObject that is visible will still exist on a GWindow once added.

Usage:

window = GWindow()
oval = GOval(0, 0, 41, 41)
window.add(oval)
print(oval.visible)  # => True
oval.visible = False  # Hides the oval on the window.
print(oval.visible)  # => False

width

Get the width of this GObject.

The width of an object is the same as the width of its bounding box.

Returns:The width (in pixels) of this GObject.

x

Get or set the x-coordinate of this GObject.

y

Get or set the y-coordinate of this GObject.

class campy.graphics.gobjects.GOval(width, height, *, x=0, y=0)

Bases: campy.graphics.gobjects.GFillableObject

Graphical representation of an oval inscribed in a rectangular box.

To display a filled green oval:

window = GWindow()
oval = gobjects.GOval(window.width, window.height)
oval.filled = True
oval.color = "GREEN"
window.add(oval)

bounds

Get the bounding box for this GOval.

The bounding box of a GOval is simply the bounding rectangle.

Returns:A bounding box that covers this GOval. Return type:GRectangle

class campy.graphics.gobjects.GPolygon

Bases: campy.graphics.gobjects.GFillableObject

Graphical representation of a polygon.

Polygons are bounded by line segments. A GPolygon is initialized to an empty polygon with no vertices. To complete the figure, you need to add vertices to the polygon using the methods add_vertex(), add_edge(), or add_polar_edge().

To add a filled red octagon to the center of the window:

window = GWindow()
edge_length = 75
stop_sign = GPolygon()
start = GPoint(-edge_length / 2, edge_length / 2 + edge_length / math.sqrt(2.0))
stop_sign.add_vertex(start)
for edge in range(8):
    stop_sign.add_polar_edge(edge_length, 45*edge)
stop_sign.filled = True
stop_sign.color = "RED"
window.add(stop_sign, window.width / 2, window.height / 2)

add_edge(dx, dy)

Adds an edge to the polygon whose components are given by the displacements dx and dy from the last vertex.

add_polar_edge(r, 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.

@type r: float @type theta: float @param theta: degrees @rtype: void

add_vertex(point)

Add a vertex at a given GPoint relative to the polygon origin.

bounds

Get the bounding box for this GPolygon.

Returns:The bounding box of this GPolygon. Return type:GRectangle

class campy.graphics.gobjects.GRect(width, height, *, x=0, y=0)

Bases: campy.graphics.gobjects.GFillableObject

Graphical representation of a rectangular box.

To add a filled red rectangle with width 200 and height 100 to a GWindow:

window = GWindow()
rect = GRect(200, 100)
rect.filled = True
rect.color = "RED"
window.add(rect, 0, 0)

bounds

Get the bounding box for this GRect.

The bounding box of a GRect is simply the rectangle’s bounds itself.

Returns:A bounding box that covers this GRect. Return type:GRectangle

class campy.graphics.gobjects.GRoundRect(width, height, *, x=None, y=None, corner=10)

Bases: campy.graphics.gobjects.GRect

Graphical representation of a rectangular box with rounded corners.

The rounded corners are quarter-circle arcs of a fixed diameter.

CORNER_ROUNDING = 10