Designer Documentation for Students

Creating DesignerObjects

image(path)
image(path, x, y)

Function to create an image from the given path. The path given can be a local file or a URL to a remote image. Keep in mind that loading large URLs can take a little while.

from designer import *
# A random corgi picture from a website
image("http://placecorgi.com/260/180")

We recommend always storing images as local files in adjacent folders, to simplify problems with paths. Never use absolute file locations like C:/Users/acbart... or /usr/acbart/, but instead use relative paths.

Most popular image formats are supported: png, gif, bmp, jpeg.

Animated gifs are partially supported, although many suffer from corruption.

Parameters

  • path (str) – local file path or url of image to use

  • x (int) – horizontal location to draw the image

  • y (int) – vertical location to draw the image

Returns

Image object created

Return type

DesignerObject

emoji(name)
emoji(name, x, y)

Function to create an emoji of the given name. You can also provide the actual unicode character. Not every unicode emoji is supported. You can find a searchable emoji list here. Copy paste the emoji as a string literal as the name argument.

from designer import *
# Either of these will create a picture of a dog on your screen
emoji("dog")
emoji("🐕")
Parameters

  • name (str) – The unicode name of the emoji, or the unicode character of the emoji.

  • x (int) – horizontal location to draw the emoji

  • y (int) – vertical location to draw the emoji

Returns

Emoji image object created

Return type

DesignerObject

text(color, text)
text(color, text, size)
text(color, text, size, x, y)
text(color, text, size, x, y, font_name='Arial')

Function to create text on the screen with the given color. Not all unicode characters are supported!

from designer import *
# Black text that reads "Hello world!"
text("black", "Hello world!")
Parameters

  • color (str) – The color of the text

  • message (str) – text to appear on window

  • size (int) – Font size of the text

  • x (int) – left most x-coordinate of text

  • y (int) – top most y-coordinate of text

  • font_name (str) – The name of the font to use. Defaults to ‘Arial’.

Returns

Text object created

Return type

DesignerObject

rectangle(color, width, height)
rectangle(color, width, height, x, y)
rectangle(color, width, height, x, y, border=None, anchor='center')

Function to create a rectangle object. You must specify the color, width, and height of the rectangle. Optionally, you can also position it at a specific x/y coordinate, although it will default to the center of the Window.

from designer import *
# Black rectangle of size 100x100
rectangle("black", 100, 100)

# Red rectangle of size 50x50 in topleft corner
# Part of the rectangle will be caught off since its drawn from the center
red_box = rectangle("red", 50, 50, 0, 0)

# Once created, you can manipulate the border and other properties
red_box.color = 'purple'
red_box.x = 100

You can also control the border of the rectangle in order to make the shape not be filled, but instead just a bordered rectangle.

# Blue rectangle of size 75x100, not filled
empty = rectangle("blue", 75, 100, border=1)
empty.border = 7

And like any other shape, you can specify an anchor to adjust the “pin” of the object relative to its position.

# Blue 50x50 rectangle drawn from the topleft corner, at position 0,0
rectangle("blue", 50, 50, 0, 0, anchor='topleft')
Parameters

  • color (str) – The color of the rectangle

  • width (int) – The horizontal width of the rectangle

  • height (int) – The vertical height of the rectangle

  • x (int) – The horizontal position in the Window. If not specified, defaults to the center of the window.

  • y (int) – The vertical position in the Window. If not specified, defaults to the center of the window.

  • border (int) – If given, the rectangle is not filled; instead, the center of the rectangle is empty and only a border is shown. The thickness of the border is given by this value.

  • anchor (str) – An anchor indicating where the “pin” (or “center”) of the object should be relative to its position.

Returns

Rectangle designer object created

Return type

DesignerObject

circle(color, radius)
circle(color, radius, x, y)
circle(color, radius, x, y, border=None, anchor='center')

Function to create a circle with the given radius. Defaults to being drawn at the center of the screen, from the center of the circle.

from designer import *
# Black circle of radius 100
circle("black", 100)

# Red circle of radius 50 in topleft corner
# Part of the circle will be caught off since its drawn from the center
red_circle = circle("red", 50, 0, 0)

# Once created, you can manipulate the border and other properties
red_circle.color = 'purple'
red_circle.x = 100

You can also control the border of the circle in order to make the shape not be filled, but instead just a bordered circle.

# Blue circle of size 75, not filled
empty = circle("blue", 75, border=1)
empty.border = 7

And like any other shape, you can specify an anchor to adjust the “pin” of the object relative to its position.

# Blue 50-radius circle drawn from the topleft corner, at position 0,0
circle("blue", 50, 0, 0, anchor='topleft')
Parameters

  • color (str) – The color of the circle

  • radius (int) – radius of circle in pixels

  • x (int) – The horizontal position in the Window. If not specified, defaults to the center of the window.

  • y (int) – The vertical position in the Window. If not specified, defaults to the center of the window.

  • border (int) – If given, the circle is not filled; instead, the center of the circle is empty and only a border is shown. The thickness of the border is given by this value.

  • anchor (str) – An anchor indicating where the “pin” (or “center”) of the object should be relative to its position.

Returns

Circle object created

Return type

DesignerObject

ellipse(color, width, height)
ellipse(color, width, height, x, y)
ellipse(color, width, height, x, y, border=None, anchor='center')

Function to create an ellipse object. You must specify the color, width, and height of the ellipse. Optionally, you can also position it at a specific x/y coordinate, although it will default to the center of the Window.

from designer import *
# Black ellipse of size 100x100
ellipse("black", 100, 100)

# Red ellipse of size 50x50 in topleft corner
# Part of the rectangle will be caught off since its drawn from the center
red_ellipse = ellipse("red", 50, 50, 0, 0)

# Once created, you can manipulate the border and other properties
red_ellipse.color = 'purple'
red_ellipse.x = 100

You can also control the border of the ellipse in order to make the shape not be filled, but instead just a bordered ellipse.

# Blue ellipse of size 75x100, not filled
empty = ellipse("blue", 75, 100, border=1)
empty.border = 7

And like any other shape, you can specify an anchor to adjust the “pin” of the object relative to its position.

# Blue 50x50 ellipse drawn from the topleft corner, at position 0,0
ellipse("blue", 50, 50, 0, 0, anchor='topleft')
Parameters

  • color (str) – The color of the ellipse

  • width (int) – The horizontal width of the ellipse

  • height (int) – The vertical height of the ellipse

  • x (int) – The horizontal position in the Window. If not specified, defaults to the center of the window.

  • y (int) – The vertical position in the Window. If not specified, defaults to the center of the window.

  • border (int) – If given, the ellipse is not filled; instead, the center of the ellipse is empty and only a border is shown. The thickness of the border is given by this value.

  • anchor (str) – An anchor indicating where the “pin” (or “center”) of the object should be relative to its position.

Returns

Ellipse designer object created

Return type

DesignerObject

line(color, start_x, start_y, end_x, end_y)
line(color, start_x, start_y, end_x, end_y, thickness=1)

Function to create a line, beginning at the coordinates given by (start_x, start_y) and ending at the coordinates given by (end_x, end_y). These coordinates are given as absolute values, and must be provided.

# Blue line stretching from 0,0, to 50, 100
line("blue", 0, 0, 50, 100)

# Thick Red line stretching from the middle to the bottom right
line("red", 400, 300, 800, 600, thickness=6)
Parameters

  • color (str) – The color of the line

  • start_x (int) – x-coordinate at which to start line

  • start_y (int) – y-coordinate at which to start line

  • end_x (int) – x-coordinate at which to end line

  • end_y (int) – y-coordinate at which to end line

  • thickness (int) – thickness of line in pixels

Returns

Line designer object created

Return type

DesignerObject

arc(color, start_angle, stop_angle, width, height)
arc(color, start_angle, stop_angle, width, height, x, y)
arc(color, start_angle, stop_angle, width, height, x, y, thickness=1, anchor='center')

Function to make an arc, as if it were part of an ellipse. Think of the arc as being part of the border of an ellipse with the given width/height; then the start_angle and stop_angle are the slice (in degrees) of the border that will actually be drawn. This is a line, not a polygon, so there is no option to fill in the arc.

from designer import *
# Black arc of size 100x100, from 0 to 90 degrees (quarter circle)
arc("black", 0, 90, 100, 100)
# Black arc of size 100x100, from 135 to 270 degrees (2/3 circle)
arc("black", 135, 270, 100, 100)

# Red U of size 50x50 in topleft corner
# Part will be cut off unless you change the anchor!
red_U = arc("red", 180, 360, 50, 50, 0, 0)

# Once created, you can manipulate the thickness and other properties
red_U.anchor = 'topleft'
red_U.thickness = 10
Parameters

  • color (str) – The color of the arc

  • start_angle (int) – angle in degrees to start drawing arc at

  • stop_angle (int) – angle in degrees to stop drawing arc at

  • width (int) – The horizontal width of the arc, as if it were a complete ellipse

  • height (int) – The vertical height of the arc, as if it were a complete ellipse

  • x (int) – left most x-coordinate of arc

  • y (int) – top most y-coordinate of arc

  • thickness (int) – thickness of arc in pixels

Returns

Arc object created

Return type

DesignerObject

shape(color, x1, y1, x2, y2, x3, y3, ...)
shape(color, points)

Function to create a shape of at least three points. The points should be relative to each other. The resulting image will be centered in the middle of the window, which can be adjusted by using x and y. If you want to absolutely position the image instead, then use lines.

Parameters

  • color (str) – color of shape.

  • points (List[Tuple] in (x, y), (x, y) format of points to be connected of shape) – coordinates of points of shape

Returns

Shape object created

lines(color, x1, y1, x2, y2, x3, y3, ...)
lines(color, points)

Function to create a shape of at least three points. The points will be absolutely positioned in the window.

Parameters

  • color (str) – color of shape.

  • points (List[Tuple] in (x, y), (x, y) format of points to be connected of shape) – coordinates of points of shape

Returns

Shape object created

group(object1, ...)
group(objects)

Function to group any number of Designer objects together. They will produce one single picture when they are done. The advantage of grouping together a bunch of objects is that they become easier to rotate and scale together.

Parameters

objects (at least one DesignerObject) – collection of objects to be grouped together for collective functionality

Returns

Created Designer Group object

Designer Objects Attributes

DesignerObjects are how images and shapes are positioned and drawn onto the screen. They aggregate together information such as where to be drawn, their size, and their color. Each type of DesignerObject has its own specific kinds of attributes, but all DesignerObjects have certain common attributes.

x: integer

The horizontal position of the object on the screen.

box = rectangle('red', 50, 50)
# Set to be 100 pixels from the left-hand side of the window
box.x = 100
# Move 5 pixels left
box.x -= 5
y: integer

The vertical position of the object on the screen.

box = rectangle('red', 50, 50)
# Set to be 100 pixels from the top of the window
box.y = 100
# Move 5 pixels up
box.y -= 5
width: integer

The horizontal size of the object on the screen.

box = rectangle('red', 50, 50)
# Set to be 100 pixels wide
box.width = 100
# Increase width by 10 pixels
box.width += 10
height: integer

The vertical size of the object on the screen.

box = rectangle('red', 50, 50)
# Set to be 100 pixels tall
box.height = 100
# Increase height by 10 pixels
box.height += 10
scale_x: float

How much to multiply the object’s width by in calculating its final horizontal size on the screen.

box = rectangle('red', 50, 50)
# Will be drawn twice as wide
box.scale_x = 2.0
# Will be drawn half as wide
box.scale_x = .5
scale_y: float

How much to multiply the object’s height by in calculating its final vertical size on the screen.

box = rectangle('red', 50, 50)
# Will be drawn twice as tall
box.scale_y = 2.0
# Will be drawn half as tall
box.scale_y = .5
angle: float

An amount to rotate the image, in degrees (0-360). You can provide negative values and amounts greater than 360.

box = rectangle('red', 50, 50)
# Will be drawn at a 45 degree angle
box.angle = 45
# Rotates it 180 degrees around
box.angle += 180
flip_x: boolean

Whether or not to horizontally mirror this shape to the other direction. Note that symmetric shapes have no effect when they are mirrored, even if they are rotated. The order of transformations is flipping, scaling, and then rotating.

ada = image('ada.png', 50, 50)
# Will be flipped horizontally
ada.flip_x = True
# Will not be flipped horizontally
ada.flip_x = False
flip_y: boolean

Whether or not to vertically mirror this shape to the other direction. Note that symmetric shapes have no effect when they are mirrored, even if they are rotated. The order of transformations is flipping, scaling, and then rotating.

ada = image('ada.png', 50, 50)
# Will be flipped vertically
ada.flip_y = True
# Will not be flipped vertically
ada.flip_y = False
visible: boolean

Whether or not this object should actually be drawn on screen, or whether it will be hidden. Objects that are invisible still get “update” events.

box = rectangle('red', 50, 50)
# Will not be drawn
ada.visible = False
# Will be drawn
ada.visible = True
alpha: float

A value from 0..1 indicating the amount of transparency (or “opacity”) that this object should have when it is being drawn on the screen.

box = rectangle('red', 50, 50)
# Partially transparent
ada.alpha = .5
# Fully invisible
ada.alpha = 0.0
# Fully visible
ada.alpha = 1.0
layer: string

A string indicating the layer that this object should be drawn on. Objects with the same layer will be drawn on top of each other in the order that they were created. The order of the layers should be set using set_window_layers() function, providing a list of the layer names (strings) in order from bottom to top.

Alternatively, you can force a specific object to be drawn on top of all other layers using the "top" layer or below everything using the "bottom" layers, which are built in.

There are also layer modifiers, which can be used to relatively position objects within layers:

  • "layer_name:top"

  • "layer_name:above"

  • "layer_name"

  • "layer_name:below"

  • "layer_name:bottom"

Swap out the name of the layer for the layer you want to modify. For example, if you have a layer called "background" and you want to draw an object on top of everything else in that layer, you would use "background:top". Note that you cannot use these modifiers with the "top" and "bottom" layers, but they can be used without a layer name to modify the default layer.

box = rectangle('red', 20, 50)
box2 = rectangle('blue', 50, 20)
# box on top
box.layer = 'top'
# box on bottom
box.layer = 'bottom'

# box2 above box
box.layer = 'below
box2.layer = 'above'

# Can only call set_window_layer once, but makes things explicit
set_window_layers(['background', 'foreground'])
box.layer = 'background'
box2.layer = 'foreground'
# Make circle in background layer appear behind everything else
green_circle = circle('green', 200, 200)
green_circle.layer = 'background:bottom'
scale: [scale_x, scale_y]

The combined horizontal and vertical scale of the object on the screen, as a list of two values. You can also set a single value in order to control both properties at the same time.

size: [width, height]

The combined width and height of the object on the screen, as a list of two values.

pos: [x, y]

The position of the object on the screen, as a list of two values.

Designer Object Functions

move_forward(object, amount)
move_forward(object, amount, angle)

Move the given object forward by amount, either in its current rotation angle attribute or the given angle. This changes the x and y attribute of the Designer Object, in addition to returning the value.

from designer import *
# Black rectangle of size 100x100
# Defaults to angle=0 (pointing to the right)
box = rectangle("black", 100, 100)

# Move the box to the right 50 pixels
move_forward(box, 50)

# Move the box upwards 20 pixels
move_forward(box, 20, 90)

# Move the box down and left, both 10 pixels, by chaining
move_forward(move_forward(box, 10, 270), 10, 180)
Parameters

  • object (DesignerObject) – A Designer Object

  • amount (int) – The number of pixels to move

  • angle (int) – The direction (in degrees) to move in; defaults to the object’s current angle attribute (which defaults to 0).

Returns

The Designer Object that was passed in.

Return type

DesignerObject

Animation

linear_animation(obj, property, start, end, duration, absolute=True, shift=None, loop=False)

Animates an object’s property, interpolating linearly between start and end. For example, if you want the object to glide from the left to the right of the screen, you can animate the object’s x property from 0 to get_width(). Or you could animate the object’s angle property from 0 to 360 to make it spin in place.

Parameters

  • obj (DesignerObject) – The designerobject to animate

  • property (str) – The name of the property to animate (e.g., ‘x’, ‘y’, ‘angle’)

  • start (int or float) – The starting value of the property

  • end (int or float) – The ending value of the property

  • duration (float) – The duration of the animation in seconds

  • absolute – (TODO) This parameter is not implemented yet

  • shift – (TODO) this parameter is not implemented yet

  • loop (bool) – Whether to loop the animation

Returns

This DesignerObject

sequence_animation(obj, property, items, duration, times=1, absolute=True, shift=None, loop=False)

Animates an object’s property in sequence. For example, if you have a list of images, you can animate the object’s filename property to change the image repeatedly. This is useful for creating animations.

Parameters

  • obj (DesignerObject) – The designerobject to animate

  • property (str) – The name of the property to animate (e.g., ‘x’, ‘y’, ‘angle’, ‘filename’, ‘name’)

  • items (list) – The items to iterate through with the animation

  • duration (float) – The duration of the animation in seconds

  • times (int) – The number of times to iterate through the items

  • absolute – (TODO) This parameter is not implemented yet

  • shift – (TODO) this parameter is not implemented yet

  • loop (bool) – Whether to loop the animation

Returns

This DesignerObject

Settings

get_width()

Returns the horizontal size of the Window.

Return type

int

get_height()

Returns the vertical size of the Window.

Return type

int

set_window_height(message)
set_window_height(None)

Changes the caption displayed at the top of the window. If you set the message to be None instead, then it will render internal debug information about the number of static and non-static objects being drawn on the screen.

Parameters

  • message – The text to render in the screen.

  • type – str

set_window_color(color)

Changes the background color of the window to whatever color you specify. Defaults to 'white'.

from designer import *
# Black text that reads "Hello world!"
set_window_color('blue')
Parameters

  • color – The color to set the background to.

  • type – str

background_image(path)
Parameters

path (str) – local file path or url of image to use

Changes the background of the window to the image. The path given can be a local file or a URL to a remote image. Keep in mind that loading large URLs can take a little while.

set_window_layers(layer_names)
Parameters

layer_names (list[str]) – List of layer names in order from bottom to top

Sets the order of the layers in the window. The first layer in the list will be drawn first, and the last layer in the list will be drawn last. The order of the layers is important, because objects in the same layer will be drawn on top of each other in the order that they were created. You can use layer modifiers to relatively position objects within layers. See the documentation on the layer attribute for more information.

Events

when(event_name, event_handler)
when(predicate_function, event_handler)
when('starting', event_handler)
when('updating', event_handler)
when('typing', event_handler)
when('clicking', event_handler)

Binds the function given by event_handler to the event_name.

Collisions

colliding(object, x, y) → bool
colliding(object, other_object) → bool

Tests if the object is colliding with either the point or the other object.

Parameters

  • object (DesignerObject) – A DesignerObject

  • x (int) – The horizontal position to check.

  • y (int) – The vertical position to check.

  • other_object (DesignerObject) – Another DesignerObject to check against.

Return type

bool

Game Control

stop()

Stops the game completely, closing the window.

pause()

Pauses the game, keeping the window open and whatever the last thing to draw was. However, no further events will be processed (besides the 'quitting' event).