11.4. The SimpleGUI Module

The SimpleGUI module was created specifically to help students learn and experiment with event-based interactions. It was designed to work in a web version of Python called CodeSkulptr 3. Unfortunately, simpleGUI is not a module that works inside the Runestone textbook, it only works in CodeSkulptr. Here is a screenshot of what CodeSkulptr 3 looks like when you first open it, and press the Run button at the top-left:


This screenshot shows that CodeSkulptr 3 provides a window for entering text and a sample script to get you started. On the left are buttons for you to control the CodeSkultpr web page interface, including running, saving and loading scripts, accessing documentation, and a ‘join’ button that allows you to share access to your script with a classmate, so that you can work on it together.

On the right there is an Output window, which is basically just a console. Any print() output will show up there.

When you run the starter script that is provided, you will also see that a window pops up. This window has a canvas and a button. When this window first appears, it displays the message “Welcome!”. When you click the ‘Click me’ button, the message in the canvas changes to “Good job!”.

Let’s examine the lines of code in this script to understand what is happening.

Go to CodeSkulptr 3 and play with this code: https://py3.codeskulptor.org/. Run the script and then do a few simple edits, testing the program after each:

The window that pops up when you run a CodeSkulptr script with the SimpleGUI module has two labels at the bottom left. These are provided by SimpleGUI as an aid to help novice programmers understand what mouse and keyboard events the SimpleGUI module is recieving.


Play around with clicking the mouse in the canvas and typing keys on the keyboard to see these indicators change. Note that just because the SimpleGUI module sees the events doesn’t mean something will happen in the canvas window in response to clicks and keypresses. It is up to you to write code to tell the SimpleGUI module and the Python interpreter that you want something to happen in response to such events.

11.4.1. Using Toolkit Documentation

There are many different toolkits that you can use for building GUIs (and for other things, too). Every toolkit handles input events slightly differently and offers slightly different sets of interface widgets and ways to customize them. So, one of the most important skills you can develop is learning how to read the documentation for a toolkit to figure out how to use it. No-one memorizes all the functions, methods and objects that a toolkit contains, unless they happen to use that toolkit every day. So, when seasoned programmers need to use a toolkit, they typically have the documentation window for that toolkit open in a separate tab, so they can refer to it as they build their program. Clicking the Docs button in the CodeSkulptr 3 interface will automatically open the documentation for you in a new browser tab. Switch to this tab and then click on Graphics Modules. You should see this:


The CodeSkulptr system has 3 different modules for graphical applications: SimpleGUI, SimpleMap and SimplePlot. We are only going to look at SimpleGUI (but you should feel free to explore the other two modules on your own). There are a number of different documentation sections for the SimpleGUI module. In order to build a GUI interface, what we are most interested in is the Control Objects, so click on that section to open it.


When you open this you will see that you can add various controls and user input handlers to a frame: lables, buttons, text input boxes, and keyboard and mouse event handlers. We’ll talk about the event handlers in the next section. For now let’s look at adding text labels. Click on the Add Text Label section and you will see the following:


There are three sections to the documentation for this function: Syntax, Example, and See also. The Syntax information shows how to use the command, including what parameters you need to specify. This particular documentation shows you that you can use the add_label() method on a window frame object. Assuming you have called your window ‘frame’, you simply type either ‘frame.add_label(“Label Text”) or you can add a width for the size of the label, like this: ‘frame.add_label(“Label Text”, 100)’. When you look at the Example information, it shows how to use this method in a complete code sample. Here you see that it is customary to assign a label to a variable called something like ‘label1’ or ‘label2’. Assigning a label (or other user interface widget) to a variable means you can access that widget to do things with it. The See also section tells you that there are some related methods you might want to know about. In this case, the related methods allow you to get the current text that a label is showing, and also change the text that a label is showing.

You have attempted of activities on this page