Renderable Quick Reference

01

Creating shapes

Create a concrete shape rather than Renderable itself. The standard shapes share the same position, size, color, border, fill, rotation, and visibility options.

Rectangle(screen, x, y, width, height, color=Color("black"), border=None, fill=True, rotation=0, visible=True)

Create a rectangular shape.

RoundedRectangle(screen, x, y, width, height, ..., radius=10)

Create a rectangle with a configurable corner radius.

Oval(screen, x, y, width, height, ...)

Create an oval or circle.

Triangle(screen, x, y, width, height, ...)

Create a three-sided shape.

Polygon(screen, num_sides, x, y, width, height, ...)

Create a regular polygon with at least three sides.

CustomPolygon(screen, vertices, color=Color("black"), border=None, fill=True, rotation=0, visible=True)

Create an irregular polygon from at least three coordinate points.

Example

box = Rectangle(screen, 40, 50, 100, 70, Color("blue"))
button = RoundedRectangle(
    screen, 180, 50, 120, 60,
    Color("orange"), radius=14
)
ball = Oval(screen, 340, 50, 70, 70, Color("red"))

Regular & custom polygons

hexagon = Polygon(screen, 6, 60, 180, 90, 90, Color("green"))
arrow = CustomPolygon(
    screen,
    [(210, 180), (300, 225), (210, 270), (230, 225)],
    Color("purple")
)

02

Position, size & center

A shape's location is its unrotated top-left anchor. Move that anchor, resize from it, or position the shape by its center when that is easier to reason about.

POSITION MODELOne anchor, one rotation pivot

The location anchors the shape's unrotated box. Rotation changes its vertices around the center without changing x or y.

shape.x(value=None) · shape.y(value=None)

Read an anchor coordinate, or pass a number to replace it.

shape.location()

Return the shape's anchor as a Location.

shape.move(dx, dy) · shape.move((dx, dy))

Move by a relative offset.

shape.moveto(x, y) · shape.moveto(location)

Move the anchor to an absolute position.

shape.width(value=None) · shape.height(value=None)

Read or change the shape's dimensions.

shape.center() · shape.center(x, y)

Read the center or move it to a new position.

shape.center(move_to=location, x=value, y=value, centroid=False)

Position all or part of the center with named options.

Example

player.move(8, 0)
player.moveto(Location(120, 90))
player.width(80)
player.height(50)

Centering

player.center(screen.center())
player.center(x=screen.width() / 2)

03

Rotation & directional movement

A rotation of 0 degrees points upward. Positive rotation turns clockwise on the Screen, and directional movement follows the shape's current heading.

shape.rotation(angle=None)

Read the current angle, or set an absolute angle in degrees.

shape.rotate(angle_difference)

Turn relative to the current rotation.

shape.angleto(object_or_location)

Return the angle from the current heading to a target.

shape.lookat(object_or_location)

Rotate until the shape faces a target.

shape.forward(distance) · shape.backward(distance)

Move along the current heading.

Example

ship.rotate(4)
ship.forward(6)

Face a target

ship.lookat(screen.mouse())
turn_needed = ship.angleto(target)

04

Appearance, ordering & lifecycle

Change style without recreating a shape, control its place in the drawing order, or temporarily remove it from the Screen.

shape.color(value=None)

Read or change the fill Color.

shape.border(color=None, width=None, fill=None)

Read the border Color or update border, thickness, and fill together.

shape.border_width(value=None)

Read or change border thickness.

shape.fill(value=None)

Read or change whether the interior is filled.

shape.visible(value=None)

Read or change visibility without removing the shape.

shape.front() · shape.back()

Move the shape to the front or back of the Screen's drawing order.

shape.remove()

Detach the shape from its Screen.

Example

button.color(Color("gold"))
button.border(Color("navy"), width=3)
button.fill(True)

Visibility & ordering

menu.visible(False)
player.front()
background.back()

05

Geometry & collision

Inspect the rendered geometry, test pointer positions, and detect contact between shapes without writing separate collision code for each shape type.

shape.vertices()

Return the current perimeter as a list of Locations.

shape.bounds()

Return (top_left_location, width, height) for the rotated shape's axis-aligned bounds.

shape.contains(x, y) · shape.contains(location)

Test whether a point lies inside the shape.

shape.overlaps(other_shape)

Test whether two Renderables intersect or contain one another.

shape.distance(other_shape_or_location)

Return center-to-center distance, or center-to-point distance.

Example

def mousedown(location):
    if button.contains(location):
        button.color(Color("green"))

Collision loop

if player.overlaps(obstacle):
    player.moveto(start)

distance = player.distance(goal)

06

Transforms & copies

Treat width, height, and rotation as one reusable transform, or clone a shape before modifying a variation.

shape.transform()

Return (width, height, rotation).

shape.transform((width, height, rotation))

Apply all three transform values together.

shape.clone()

Create another shape of the same type on the same Screen.

Example

saved_transform = player.transform()
shadow.transform(saved_transform)

Clone

copy = original.clone()
copy.move(30, 30)
copy.color(Color("light gray"))

07

Shape-specific controls

Most behavior is shared, but rounded rectangles and ovals expose a few geometry controls of their own.

rounded.radius(value=None)

Read or change the non-negative corner radius of a RoundedRectangle.

oval.wedges(value=None)

Read or set the number of perimeter wedges; custom values must be at least 20.

oval.slices()

Create and return one triangular CustomPolygon for each oval wedge.

Example

panel.radius(18)
planet.wedges(40)

Oval slices

slices = wheel.slices()
for index, piece in enumerate(slices):
    piece.color(colors[index % len(colors)])

08

Attaching a Pen

Attach a Pen to a moving shape to leave a polyline behind its anchor. The Pen starts drawing immediately and follows later move and moveto calls; the Line & Pen reference covers direct Pen construction and full path control.

shape.pen(color=Color("black"), width=2, top=False)

Start a trail and return its Pen.

shape.pen_stop() · shape.pen_clear()

Stop drawing or clear all trail history.

shape.pen_width(value=None) · shape.pen_top(value=None)

Read or change trail thickness and whether it renders above objects.

pen.color(value=None) · pen.drawing(value=None)

Read or change the returned Pen's color and active state.

pen.coordinates(*points)

Read the current path or replace it with Locations and coordinate tuples.

Example

trail = player.pen(Color("blue"), width=4)
player.move(40, 0)
player.move(0, 40)
player.pen_stop()

Resume & clear

trail.drawing(True)
player.move(-40, 0)
player.pen_clear()

09

Grouping objects

CompoundObject groups existing Screen objects so they can move, rotate, recolor, order, and collision-test together.

CompoundObject(*objects, **named_objects)

Create a group from one or more existing pyDraw Objects.

group.objects() · group.object(name) · group.add(...) · group.remove(...)

Inspect or change the objects managed by the group.

group.center(centroid=True) · group.width() · group.height()

Read the group's center and dimensions; compound dimensions cannot be set directly.

group.rotate(angle, pivot=None) · group.rotation(angle=None)

Rotate all children around the group center or a supplied pivot.

group.contains(point) · group.overlaps(renderable)

Test against the Renderable children in the group.

ALSO SUPPORTS

x()y()move()moveto()color()front()back()

Example

ship = CompoundObject(
    hull=hull,
    cockpit=cockpit,
    left_fin=left_fin,
    right_fin=right_fin,
)

ship.rotate(4)
ship.move(3, 0)

Named children

ship.object("cockpit").color(Color("cyan"))
for part in ship.objects():
    part.visible(True)