Screen Quick Reference

01

Creating a Screen

Every pyDraw program begins with one Screen. Its width and height define the drawable coordinate space, with (0, 0) at the top-left.

Screen(width=800, height=600, title="pydraw")

Create a Screen with an optional window title.

screen.title(value=None)

Read the current title, or set a new one.

Example

screen = Screen(640, 420)

Custom title

screen = Screen(640, 420, "My game")
screen.title("Level one")

02

Size & locations

Use the Screen's measured canvas dimensions and location helpers instead of repeating coordinate calculations throughout a program.

screen.width() · screen.height()

Return the current drawable canvas dimensions.

screen.size()

Return the host window size. In the browser, this matches the drawable Screen size.

screen.center()

Return the Location at the center of the canvas.

screen.top_left() · screen.top_right()

Return either top corner as a Location.

screen.bottom_left() · screen.bottom_right()

Return either bottom corner as a Location.

screen.fullscreen(value=None)

Read or change fullscreen state in the local runtime.

Example

player.moveto(screen.center())
label.moveto(screen.top_left())

03

Background color & image

A Screen starts with a white background. Change its color at any time or place an image behind every object.

screen.color(value=None)

Read the current background Color, or set a new one.

screen.picture(path)

Use an image file as the Screen background.

Example

screen.color(Color("lightblue"))
current = screen.color()

Background image

screen.picture("background.png")

04

Input & mouse state

After defining input functions, call listen() once to register them. The Screen begins tracking mouse state at that point.

screen.listen()

Register supported input functions defined above this call.

screen.mouse()

Return the latest known pointer position as a Location.

Example

def mousemove(location):
    player.moveto(location)

screen.listen()
screen.loop()

05

Keeping a program running

Choose one global loop model. loop() is the simplest option; a custom while loop is useful when the program needs ongoing animation or game logic.

screen.loop()

Keep the program alive and update the Screen automatically.

screen.update()

Process input and present the latest render changes once.

screen.sleep(seconds, delta=False)

Pause a custom loop, optionally compensating for frame work and returning delta time.

screen.exit()

Close the Screen and end the program.

Automatic loop

screen.listen()
screen.loop()

Animated loop

running = True
while running:
    player.move(2, 0)
    screen.update()
    screen.sleep(1 / 60)

Delta-aware movement

dt = 1 / 60
while True:
    player.move(120 * dt, 0)
    screen.update()
    dt = screen.sleep(1 / 60, delta=True)

06

Objects, clearing & resetting

The Screen owns the objects drawn on it. You can inspect that collection, remove individual objects, clear the scene, or reset the entire Screen state.

screen.objects()

Return an immutable tuple of active objects.

screen.contains(object) · object in screen

Check whether an object is currently attached to the Screen.

screen.remove(object) · screen.add(object)

Detach an object or restore a previously removed one.

screen.clear()

Remove the regular objects currently on the Screen.

screen.reset()

Remove objects, grid helpers, timing state, and registered input handlers.

Example

for object in screen.objects():
    object.visible(False)

if player in screen:
    screen.remove(player)
    screen.add(player)

07

Grids & coordinate helpers

Display a temporary coordinate grid while learning, debugging placement, or planning a scene.

screen.grid(rows=None, cols=None, cellsize=(50, 50), helpers=True)

Create grid lines by row count, column count, or cell size.

screen.toggle_grid(value=None)

Show, hide, or toggle the current grid.

screen.gridlines()

Return the grid's Line objects as an immutable tuple.

Example

screen.grid(cellsize=(50, 50), helpers=True)
screen.toggle_grid(False)
screen.toggle_grid(True)

Fixed rows and columns

screen.grid(rows=6, cols=8)

08

Alerts & prompts

Ask the user to confirm an action or enter a short text response without building a custom interface.

screen.alert(text, title="Alert", accept_text="Ok", cancel_text="Cancel")

Show a confirmation dialog and return True or False.

screen.prompt(text, title="Prompt")

Show a text prompt and return the entered string.

Example

restart = screen.alert("Play again?", "Game over", "Yes", "No")
name = screen.prompt("What is your name?", "Player")

09

Screen capture

Capture the current drawable area as a PNG file.

screen.grab(filename=None)

Save a PNG and return its final filename.

Example

filename = screen.grab("my-drawing")
print(filename)  # my-drawing.png