Graphical user interfaces

All of the programs we have seen so far have been text-based. However, in practice it is common for programs to interact with the user via graphical user interfaces or GUIs.
There are a variety of toolkits available for creating GUIs with Python. We'll use a popular one called Tkinter, which is the Python version of the cross-platform toolkit Tk. Tkinter comes with the Python distribution. For help learning Tkinter, see the Resources page.
The basic building blocks of a GUI are called widgets. Tkinter provides a number of built-in classes that define widgets. Each widget is a graphical element that displays something and/or allows the user to interact with the program. Some kinds of widgets include frames (containers, often invisible, that contain other widgets), canvases (places where things can be painted), buttons, menus, and text boxes.
Each widget type is a class. For example, Tkinter has built-in Frame, Canvas, and Button classes. As with other Python classes, to create an instance of a class, you call its constructor (see the next page).
Here is how we can create a simple "Hello world!" GUI using Tkinter.
- Import the Tkinter module and create a Tk root widget. A single root widget should be created for each program, and it must be created before any other widgets.
```
>>> from tkinter import *
>>> root = Tk()
```
- Give root a title. Then run the event loop, which renders the GUI and waits for the user to perform some action. This is an infinite loop; it runs until the user closes the window or does something else that causes the program to quit.
```
>>> root.title("Hello world!")
>>> root.mainloop()
```

Widgets

All widget constructors (except for the root widget) have the same general form.
- ```
widgetclass(master, option=value, ...)
```
  The constructor creates an instance of the widget class as a child to the given master window (an instance of some widget class), and using the given options. All options have default values, so in the simplest case you only need to specify the master.
To display any widget, the widget needs to call its grid() method.
- grid() tells the widget where to appear within its master window unless this is obvious.
- Most programs will have a Frame, which is just a top-level container to hold other widgets. In the following example the root widget (an instance of the Tk class) is the master window for the frame.
- The call to the grid() method doesn't take any arguments because it doesn't need to specify a special location within its master window. As we'll see later, grid() has various optional arguments to specify particular locations.
```
>>> root = Tk()
>>> root.title("Just a frame")
''
>>> frame = Frame(root)
>>> frame.grid()
>>> root.mainloop()
```

You can view the options available for any widget using its keys() method. To change the settings for one or more options, use either the configure() or config() method (which are equivalent). To see the current setting for an option, use the method cget().

>>> frame.keys()
['bd', 'borderwidth', 'class', 'relief', 'background', 'bg', 'colormap', 
 'container', 'cursor', 'height', 'highlightbackground', 'highlightcolor',
'highlightthickness', 'padx', 'pady', 'takefocus', 'visual', 'width']
>>> frame.config(width=500, height=500, bg='pink')
>>> frame.cget("width")
500
>>> frame.cget("bg")
'pink'

Widgets: Canvases

A canvas is a widget that provides a space for painting figures and text. The Canvas class has a number of methods for painting figures within it. Each of these returns an int which serves as an id for the graphical object that is created. Note that a graphical object is not an actual Python object, that is, an instance of some widget class.

Graphical objects on the canvas can be modified using the itemconfig() method.

>>> canvas = Canvas(frame, width = 400, height = 200, bg='yellow')
>>> canvas.grid()
>>> oval = canvas.create_oval(10, 30, 50, 50)
>>> canvas.itemconfig(oval, fill='red')

Graphical objects can be moved using the coords method, which takes the graphical object id and the new coordinates as arguments.
Practice
- Write a program that draws something pretty. Define a class that is a subclass of Canvas. In the __init__() method, be sure to also call the __init__() method for Canvas.
- Write a program, again using a subclass of Canvas, that draws a given number of small rectangles in random positions on a canvas of given width and height.
Answers to problems

Widgets: Buttons

A common way for programs to interact with the user is with the Button widget. Here is a simple example that creates a button and a Label (a widget for displaying text or images).
```
>>> label = Label(frame, text="Press the button.")
>>> label.grid()
>>> button = Button(frame, text="Press me.")
>>> button.grid()
```
However, you will notice when running the program that clicking the button doesn't do anything. That's because we haven't told it what to do! To give the button more interesting behavior, we can specify a value for the command option.
```
>>> def print_hello():
>>>	    print("hello!")
>>> button.config(command = print_hello)
```
- Notice that the value of the command option is a function object. This is an example of a callback, because when the user presses the button the flow of execution "calls back" to that function.
Practice
- Write a program that creates a GUI with a single button. When that button is pressed, it should create a label that says "Thank you!".
- Write a program that creates a GUI with a single button. When that button is pressed, it should create a second button. When that button is pressed, it should create a label that says, "Nice job!". What happens if you press the buttons more than once?
- Write a program that creates a canvas and a button. When the user presses the button, it should draw a circle on the canvas.
- Write a program with multiple rectangles in a canvas like the one you wrote on the last page, but the GUI also has a button. When the user presses the button, each of the rectangles moves to a random new position.
Answers to problems

Events and bindings

The exercises from the previous slide provide examples of event-driven programming, which is typical of GUI applications.
- An event is something that happens to your application. For example, the user presses a key or clicks or drags the mouse.
- An event handler is a function that gets called when an event occurs.
- A binding is an association between a widget, an event, and an event handler: when an event happens on the widget, the event handler is called.
Some widgets have default bindings. For example, by default a button invokes the callback specified by its command option when the mouse button is released. To affect the behavior of the button when it is clicked, we just need to assign the appropriate function to the command option.
However, we can also create our own bindings by using the bind() method and creating new event handlers.
- An event handler is a function designed to handle a particular kind of event. Each handler must take an "event" argument. The handler may be a method, in which case it also takes the usual initial "self" argument.
- When the handler is called, it is passed an Event object that is bound to the event argument. This contains information about the type of event that occurred and details like the coordinates (the x and y attributes) of the event.
- Here is a possible event handler that is not a method.
```
def print_coords(event):
    la = Label(frame, text = "Clicked: " + str(event.x) + " " + str(event.y))
    la.grid()
```
- bind() is a widget method. The first argument to bind() is a string describing the type of event, and the second is the appropriate event handler. The following code creates a binding for a click of the first mouse button in a canvas.
```
canvas = Canvas(frame)
canvas.bind("<Button-1>", print_coords)
```
Event handlers can deal with a variety of different events, including:
- <ButtonRelease-1>: the first mouse button was released
- <Motion>: the mouse was moved
- <B1-Motion>: the mouse was moved with the first button pressed
- <Key>: the user pressed any key
- <KeyPress-x>: the user pressed the 'x' key
- <Enter>: the mouse entered the widget
A relatively complete list is here.
To bind a handler to a graphical "object" within a Canvas, use the Canvas method tag_bind(), which takes the object id, the event type string, and the handler.
Practice
- Write a program with a canvas. When the user clicks the mouse inside the canvas, a small orange circle is drawn at the location of the mouse click.
- Write a program with a canvas and a label. When the user moves the mouse around inside the canvas the label should display the current mouse coordinates.
- Write a program with a canvas that contains a circle. When the user clicks in the circle, its color changes to green if it's currently red, to red if it's currently green.
- Write a program with a canvas in which the user can draw a rectangle by pressing the mouse button down for the upper left corner, dragging down and to the right, and then releasing the button for the lower right corner.
Answers to problems

Widgets: Text entry

Tkinter provides two widgets that allow users to type text: an Entry widget, which is a single line, and a Text widget, which has multiple lines.

The insert() method allows you to put text into an entry or text box. The get() method returns the contents of the entry (which the user may have changed).

>>> root = Tk()
>>> entry = Entry(root, width=100)
>>> entry.grid()
>>> entry.insert(END, "A line of text.")
>>> print(entry.get())
A line of text.
>>> entry.insert(1, "nother")
>>> print(entry.get())
Another line of text.

For Text widgets, locations are specified using a dotted index, like 1.1, which has the line number before the dot and the column number after. The get() method takes a start and end index as arguments.

>>> text = Text(root, width=100, height=5)
>>> text.insert(END, "A line of text.")
>>> print(text.get(0.0, END))
A line of text.

>>> text.insert(1.1, 'nother')
>>> print(text.get(1.5, END))
er line of text.

Practice: Create a program with a canvas and a text entry box. Draw some shape on the canvas and allow the user to change the color of the shape by typing a color name in the entry box and pressing return. For the event type, use '<Return>'.
Answer

Working with Canvas objects

You draw things inside a canvas with Canvas methods like create_line, create_rectangle, and create_text
The result, however, is not a widget, so you can't use widget methods to manipulate the canvas objects or to bind event handlers to them; instead you have to use one of the canvas methods that operates on canvas objects.
There are two ways to refer to canvas objects, using their id or a tag.
A canvas object's id is what is returned by the canvas method that creates the object.
An object is assigned a tag with the option tags. A tag must be a string. Any number of objects can have the same tag, and an object may have more than one.
Many canvas methods take as a first argument an object id or tag.
- To move an object by some x and y distance, you use move.
- To change or return the coords of an object, you use coords.
- To bind an event handler to an object, you use tag_bind.
- To change the value of some option for the object, you use itemconfigure.
- To get the value of some option for the object, you use itemcget.
A canvas method with a tag as its first argument applies to all objects with that tag.

GUI layout management

As we've seen, you use the widget method grid to display the widget.

from tkinter import *
root = Tk()
frame = Frame(root)
Button(frame, text="A useless button").grid()
frame.grid()
root.mainloop()

Often we'd like to control where widgets appear inside their container widgets. This is called layout management. We can do this using some of the options that are possible with grid.
- The options row and column specify cells within the container where the widget should go.
- The options rowspan and columnspan cause the widget to take up multiple cells.

Layout management: examples

Using row, column, and columnspan: layout1.py

from tkinter import *
root = Tk()
frame = Frame(root)
label1 = Label(frame, text='Name')
label1.grid(row=0, column=0)
entry1 = Entry(frame)
entry1.grid(row=0, column=1)
label2 = Label(frame, text='PIN')
label2.grid(row=1, column=0)
entry2 = Entry(frame)
entry2.grid(row=1, column=1)
button = Button(frame, text='OK')
button.grid(row=2, columnspan=2)
frame.grid()
root.mainloop()

For more elaborate displays, you can group widgets together inside instances of the Canvas class: layout2.py

from tkinter import *
root = Tk()
frame = Frame(root)
leftcanvas = Canvas(frame)
label1 = Label(leftcanvas, text='Name')
label1.grid(row=0, column=0)
entry1 = Entry(leftcanvas)
entry1.grid(row=0, column=1)
label2 = Label(leftcanvas, text='PIN')
label2.grid(row=1, column=0)
entry2 = Entry(leftcanvas)
entry2.grid(row=1, column=1)
button = Button(leftcanvas, text='OK')
button.grid(row=2, columnspan=2)
leftcanvas.grid(row=0, column=0)
rightcanvas = Canvas(frame)
ur_canvas = Canvas(rightcanvas, width=50, height=50, bg='green')
ur_canvas.grid(row=0)
lr_canvas = Canvas(rightcanvas, width=75, height=75, bg='yellow')
lr_canvas.grid(row=1)
rightcanvas.grid(row=0, column=1)
frame.grid()
root.mainloop()

grid() has other options to control where the widget is positioned within its cell; see this help page.

Summary

All programs should begin by creating a root window. The root window is the main window that pops up when the program runs, and it is the window to which all widgets will be added (directly or indirectly).
```
>>> from tkinter import *
>>> root = Tk()
```
All widget constructors have the same general form: widgetclass(master, option=value, ...)
- For basic GUIs, you can simply add all widgets directly to the root window, meaning that every widget will have the root as its "master".
```
>>> canvas = Canvas(root, width=500, height=500)
>>> canvas.grid()
>>> button = Button(root, text="Press me.")
>>> button.grid()
```
- Alternatively, you can also group widgets together in a hierarchy using Frame widgets.
To make a widget visible, you must call its grid() method. A simple way to handle this is to always call widget.grid() immediately after the widget is created.

For any widget, you can:

view its available options with the keys() method
change its available options with the config() method

view its current setting for an option with the cget() method

>>> frame.keys()
['bd', 'borderwidth', 'class', 'relief', 'background', 'bg', 'colormap', 
 'container', 'cursor', 'height', 'highlightbackground', 'highlightcolor',
'highlightthickness', 'padx', 'pady', 'takefocus', 'visual', 'width']
>>> frame.config(width=500, height=500, bg='pink')
>>> frame.cget("width")
500

To make your widgets respond to events, you will need to define event bindings. This will always involve the following two steps:
- Define an event handler, which is a function that takes an event object as its argument and specifies the actions to be taken when an event occurs.
```
>>> def print_coords(event):
>>>     print("Clicked: ", event.x, event.y)
```
- Bind the event handler to a particular widget using its bind() method. This creates an association between the widget, a particular event, and the event handler.
```
>>> canvas.bind("<Button-1>", print_coords)
```
- Note that the command option available for some widgets (e.g. Buttons) is simply a shortcut for creating event bindings.
To control where widgets appear inside their master container widget, use options to the grid() method.
The last line of your program should always be a call to the mainloop() method of your root window, which will create your GUI and start the event loop.
```
>>> root.mainloop()
```