Interactive Programs Reference

---

One of the most common libraries to create interactive graphics in Python is called Tk (short for "tkinter"). Tk is a powerful graphics library that should be automatically installed for Windows and Mac along with Python when you installed it. But some of the functions are hard to use. For this reason, we provide our own small graphics library that is built on top of Tk and makes it easier to use. However, it's not a replacement for Tk - it just adds new functions to make certain things like drawing text easier. You can always explore the full Tk library if you're interested in seeing what else you can do!

The Mouse

You can get the location of the mouse at any time using get_mouse_x() and get_mouse_y() on the canvas:

rect = canvas.create_rectangle(0, 0, 100, 100)
...
canvas.moveto(rect, canvas.get_mouse_x(), canvas.get_mouse_y())

Most times, we will get the mouse location inside a loop so that we can update something many times as the mouse moves (such as the position of a shape).

To check for mouse clicks, use get_new_mouse_clicks in a loop:

while ...:
    clicks = canvas.get_new_mouse_clicks()
    for click in clicks:
        canvas.create_rectangle(click.x, click.y, click.x + 10, click.y + 10)

Each element of the list given to you by the canvas has an x and y coordinate that you can use to know where that click occurred.

To check for mouse drag events (when the user moves the mouse while it is being held down), use get_new_mouse_drag_events in a loop:

while ...:
    mouse_drag_events = canvas.get_new_mouse_drag_events()
    for event in mouse_drag_events:
        canvas.create_rectangle(event.x, event.y, event.x + 10, event.y + 10)

Each element of the list given to you by the canvas has an x and y coordinate that you can use to know where that mouse drag event occurred.

Finally, you can wait for the user to click using wait_for_click:

canvas.wait_for_click() # This line will wait for the user to click
print("You clicked!") # This code will not run until the user clicks

Unlike the previous examples, wait_for_click doesn't need to be called in a loop - the function itself will not finish until the user clicks.

The Keyboard

To check for keyboard key presses, use get_new_key_presses in a loop:

while ...:
    presses = canvas.get_new_key_presses()
    for press in presses:
        if press == "Up":
            character.move(0, -5)

Each element of the list given to you by the canvas is the text name of the key that was pressed. E.g. "a" will be for the lowercase "a" key, "A" will be if Shift+a is pressed, etc. If you are unsure what the key name is, try writing a program that prints out the key name, like this:

while True:
    presses = canvas.get_new_key_presses()
    for press in presses:
        print(press)

More Events

The Canvas is a Tkinter frame, and you can call bind() on it to listen for additional events. See this link for a more in-depth list of the kinds of events that you can respond to.

Interactors (Buttons / Text Fields)

You can add interactors (buttons and text fields) around the edges of the canvas to allow users to interact with them. These aren't put on the canvas, these are put around the edges of the canvas, so you don't specify coordinates like you usually do for graphical objects, you specify which area (top, bottom, left, right) you want the interactor.

Buttons

Create a button using the create_button function:

my_button = canvas.create_button("Click me", Canvas.TOP)

create_button exposes the customization options of the standard tk.Button, so you can specify additional options if you'd like via keyword arguments. Keyword arguments are parameters you specify in a comma-separated list with the form name=value. Many Tkinter options will work with the way the canvas lays out buttons. You can see a list of all options here. For instance, to make a button that has blue text and Courier font, you can use fg and font:

button = canvas.create_button("Click me", Canvas.TOP, fg="blue", font="Courier")

To delete the button you have created, use destroy() on the button variable:

my_button.destroy()

To check for button clicks, use get_new_button_clicks in a loop:

while ...:
    clicks = canvas.get_new_button_clicks()
    for click in clicks:
        if click == "Click me":
            ...

Each element of the list given to you by the canvas is the text name of the button that was clicked.

Text Fields

Create a text field using the create_text field function:

canvas.create_text_field("Enter name", Canvas.TOP)

create_text_field exposes the customization options of the standard tk.Entry, so you can specify additional options if you'd like via keyword arguments. Keyword arguments are parameters you specify in a comma-separated list with the form name=value. Many Tkinter options will work with the way the canvas lays out buttons. You can see a list of all options here. For instance, to make a text field that has red text and obscures what the user enters like a password field, you can use fg and show:

canvas.create_text_field("Enter name", Canvas.TOP, fg="red", show="*")

To delete the text field you have created, use delete_text_field() and specify the description you used when you created it:

canvas.delete_text_field("Enter name")

To get the text currently entered into the text field, use canvas.get_text_field_text and specify the description you used when you created it:

entered_text = canvas.get_text_field_text("Enter name")

You will usually use this in combination with a button to know when the user is ready to do something - e.g. have them enter their name and click "Ok" to begin:

while ...:
    clicks = canvas.get_new_button_clicks()
    for click in clicks:
        if click == "Click me":
            entered_text = canvas.get_text_field_text("Enter name")

---