Appendix C: GUI Library Functions

C.1 Overview

Graphical user interfaces (GUIs) may be developed in Python using the GUI library.* Unlike many other GUI libraries, this library keeps simple things simple and makes complicated things possible.

C.2 GUI Display

To build a GUI, you have to create at least one display (window).

• Display objects are application windows. They contain other GUI objects (widgets and graphics objects). A program may have several displays open. Displays may contain any number of GUI objects, but they cannot contain another display.

Once a display has been created, you populate it by placing various GUI widgets and graphics objects on it. The library provides various GUI widgets and graphics objects.

The origin (0, 0) of a display is at the top-left corner.

The following function creates a new Display, so you need to save it in a variable (in order to add GUI objects to it later).

For example, a display may be created as follows:

d = Display("Simple GUI", 120, 60)

Once a display has been created, you can add GUI widgets and other graphical objects, using the following function:

d.add(object, x, y)

where object is a GUI widget or graphical object (presented below). The coordinates x, y are optional and specify where in the display to place the object. If omitted, e.g.,

d.add(object)

the object is placed using its own coordinates (e.g., a line or a circle) specified when it was created (more below).

Once a display has been created, the following functions are available:

C.2.1 Drawing on Display

Display objects support drawing of various graphics objects. This is done with the following functions.

For convenience, each of the above functions returns the corresponding graphics object (e.g., drawLabel() returns a Label), which can be ignored or saved for further interaction, such as animation.

C.3 GUI Widgets

Widgets are used to present information and receive user input. The following widgets are available:

• Label objects present textual information.
• Button objects can be pressed by the user to perform an action.
• Checkbox objects can be selected (or deselected) by the user.
• Slider objects can be adjusted by the user to input a value.
• DropDownList objects contain items which can be selected by the user.
• TextBox objects allow the user to enter a single line of text.
• TextArea objects allow the user to enter multiple lines of text.
• Icon objects allow displaying of external images (.jpg or .png).
• Menu objects contain items which can be selected by the user. Menu objects are fixed at the menu bar (top), whereas DropDownList objects are placed anywhere on a display.

Below we present each of these objects in more detail.

C.3.1 Label

Label objects are used to present labels and other permanent text on displays.

The following function creates a new Label, so you need to save it in a variable (so you can use it later).

For example, a label may be created as follows:

label1 = Label("Hello World!")

Once a label has been created, it cannot be resized. So you should create it with the widest (possibly blank) string necessary, e.g.,

label1 = Label("		") # up to 16 characters

Once a label has been created, it may be added to a Display, specifying where to place its top-left corner.

d.add(label1, 50, 50)

Also, the following functions are available:

C.3.2 Button

Button objects can be pressed by the user.

Pressing a Button calls a function. Which function to call is specified when the button is created.

The following function creates a new Button, so you need to save it in a variable (so you can use it later).

For example, a button may be created as follows:

button1 = Button("Play music", playMusic)

where playMusic is a function with zero parameters. This function will be called automatically when the user presses this button.

Once a Button has been created, it may be added to a Display, specifying where to place its top-left corner.

d.add(button1, 50, 50)

C.3.3 Checkbox

Checkbox objects can clicked (i.e., selected or deselected) by the user.

The following function creates a new Checkbox, so you need to save each in a unique variable (so you can use them later).

For example, a checkbox may be created as follows:

checkbox1 = Checkbox()

Once a Checkbox has been created, it may be added to a Display, specifying where to place its top-left corner.

d.add(checkbox1, 50, 50)

If you create a Checkbox without using a callback function, then it is a passive GUI element. In other words, a different part of your program needs to check the state (selected, deselected) of the Checkbox. This can be done using the following functions:

If you create a Checkbox with a callback function, then that function will be called any time the changes state (checked, unchecked) by the user. The function should accept one parameter.

C.3.4 Slider

Slider objects contain an indicator which can be moved by the user to set a value.

The function below creates a new Slider, so you need to save it in a variable (so you can use it later).

For example, a slider may be created as follows:

slider1 = Slider(VERTICAL, 0, 127, 50, changeVolume)

where changeVolume is a function which expects one parameter, the new value of the slider. When the function is called, it may use this value to update the volume of some musical material, for instance.

Once a Slider has been created, it may be added to a Display, specifying where to place its top-left corner.

d.add(slider1, 50, 50)

Additionally, you may use the following functions to get its current value:

C.3.5 DropDownList

DropDownList objects contain items which can be selected by the user.†

The following function creates a DropDownList, so you need to save it in a variable (so you can use it later).

For example, a drop-down list may be created as follows:

ddl1 = DropDownList(["item1", "item2", "item3"], itemSelected)

where itemSelected is a function which expects one parameter, the selected item (a string).

Once a DropDownList has been created, it may be added to a Display, specifying where to place its top-left corner.

d.add(ddl1, 50, 50)

C.3.6 TextField

TextField objects are used for entering text on a user interface.

The following function creates a TextField object, so you need to store it in a variable (or other memory location) to be able to use it later.

If you create a TextField with a callback function, then that function will be called any time the enter key is typed inside the box. (Presumably, the user will change the text and then press enter.)

For example, a text field may be created as follows:

text = TextField("type and hit <ENTER> ", 18, process-Entry)

where processEntry is a function which expects one parameter, the updated text (a string).

Once a TextField has been created, it may be added to a Display, specifying where to place its top-left corner.

d.add(textfield1, 50, 50)

If you create a TextField without using a callback function, then it is a passive GUI element. In other words, a different part of your program needs to manage (e.g., check for change in) the text content. This can be done using the following functions:

C.3.7 TextArea

TextArea objects are used for entering text that may span several lines.

Once a TextArea has been created, it may be added to a Display, specifying where to place its top-left corner.

d.add(textarea1, 50, 50)

A TextArea is a passive GUI element. You can access its contents with the following functions:

C.3.8 Icon

Icon objects contain external images (.jpg or .png). They are created using the following functions.

Once an Icon has been created, it may be added to a Display, specifying where to place its top-left corner point.

d.add(icon1, 50, 50)

Additionally, you may use the following functions:

C.3.9 Menu

The GUI library simplifies creation of Menu objects. A display has a menu bar at the top. This is initially empty. Menu items may be added to it (e.g., “File”, “Edit”, etc.). Menus can also be added to a display (or any other graphical object, for that matter), as pop-up menus (i.e., menus that come up when you press the right mouse button).

Menu objects are created using the following function:

Once a menu has been created, it can be populated with items using the following functions:

Once a menu has been created, it can be added to a display as follows:

Again, the second function is also available for every GUI object (e.g., a circle). This opens the door for many interesting GUI applications.

The following outlines the process of creating menu objects:

C.3.9.1 Drop-down Menus

Every display has its own menu bar. To add menus to it, follow these steps:

1. Create a Menu, as follows:

   menu = Menu(name)

   where name is a string.

2. Add menu items to a menu, as follows‡:

   menu.addItem(name, function)

   where name is a string, and function is a function to be called when the user selects this menu item. This function should expect no parameters.

3. Finally, add the menu to a Display’s menu bar:

   display.addMenu(menu)

C.3.9.2 Pop-Up Menus

Pop-up menus are menus displayed when the user right-clicks on a display or other GUI object.

Pop-up menus are created the same way as drop-down menus. The only difference is that pop-up menus are added to a GUI object using the object’s addPopupMenu() function, as follows:

object.addPopupMenu(menu)

C.4 Graphics Objects

Graphics objects are used to draw various geometric shapes on a display. The following graphics objects are available:

• Line objects are used for drawing solid lines with a specified color and thickness.
• Circle objects are used for drawing circles with a specified color and thickness. The circles may be filled or not.
• Point objects are used for drawing points with a specified color.
• Oval objects are used for drawing ovals with a specified color and thickness. The ovals may be filled or not.
• Rectangle objects are used for drawing rectangles with a specified color and thickness. The rectangles may be filled or not.
• Polygon objects are used for drawing polygons with a specified color and thickness. The polygons may be filled or not.
• Below we present each of these objects in more detail. Notice that Display has shortcut functions which create and add such objects in one step (see section “Drawing on Display” above).

C.4.1 Line

Line objects are created using the following functions. Lines are drawn between a starting point (x1, y1) and an ending point (x2, y2).

Once a Line has been created, it may be added to a Display, specifying where to place its leftmost point.

line1 = Line(100, 100, 200, 200)

display1.add(line1)

C.4.2 Circle

Circle objects are created using the following functions. Circles are drawn specifying their center point (x, y), and their radius.

Once a Circle has been created, it may be added to a Display, specifying where to place its center point.

circle1 = Circle(50, 50, 5)

d.add(circle1)

C.4.3 Point

Point objects are created using the following functions. Points are drawn specifying their center point (x, y).

Once a Point has been created, it may be added to a Display, specifying where to place its center point.

point1 = Point(50, 50)

d.add(point1)

C.4.4 Oval

Oval objects are created using the following functions. Ovals are drawn by specifying the top-left corner point (x1, y1) and the bottom-right corner point (x2, y2) of the box that encloses them.

Once an Oval has been created, it may be added to a Display, specifying where to place its top-left corner point (x1, y1).

oval1 = Oval(50, 30, 100, 150)

d.add(oval1)

C.4.5 Rectangle

Rectangle objects are created using the following functions. Rectangles are drawn by specifying the top-left corner point (x1, y1) and the bottom-right corner point (x2, y2).

Once a Rectangle has been created, it may be added to a Display, specifying where to place its top-left corner point.

rec1 = Rectangle(50, 30, 100, 150)

d.add(rec1)

C.5 Additional Color Functions of Graphics Objects

Once a graphics object has been created, the following functions are available:

C.6 Event Functions

Event functions are used to receive and process user actions at the GUI interface. Every GUI object listens for user actions (e.g., mouse click, mouse drag, typing a key, etc.), and allows you to specify a function to be called if and when a user action occurs.

You do not have to specify a function for every user action on every object on your GUI, only for the ones that you want. For example, you could make a program that draws a circle when the mouse is clicked on a particular location and cleans up all circles when the mouse exits the window.

The following event functions are available for all GUI library objects (i.e., Display, Label, Button, Checkbox, DropDownList, Slider, TextBox, Line, Circle, Rectangle, and Icon) except menus.§

Note: In the case of overlapping objects (e.g., a label and display), user events are handled by the object on top (front-most).

C.6.1 Keyboard Events

Keyboard events are divided into “key typed” and “key pressed/released” events. (For more information, see the Java API documentation on KeyEvents.)

C.6.1.1 Key Typed Events

“Key typed” events are higher-level and generally are independent of platform (and keyboard layout). These are generated when a character is typed on the keyboard (typing means both pressing and releasing the character key(s) on the keyboard).

The following function is provided to handle “key typed” events. It is available for all GUI objects (e.g., Display, Circle, etc.).

C.6.1.2 Key Down/Up Events

“Key down” and “key up” events are lower-level events and are generated whenever a key is pressed or released. As a result, these events may be used for various gaming applications (e.g., when pressing and holding a key does one thing, and when releasing the key does another).

These events are specific to the platform and keyboard layout (i.e., some keys may not work the same on all platforms). So test on all desired platforms to make sure keystroke controls work as intended.

“Key down” and “key up” events are the only way to find out about keys that do not generate character input (e.g., action keys, modifier keys, etc.).

The following functions are provided to handle “key down” and “key up” events. They are available for all GUI objects (e.g., Display, Circle, etc.).

“Key down” and “key up” events use virtual key codes to report which keyboard key has been pressed, rather than a character generated by the combination of one or more keystrokes (such as “A”, which comes from shift and “a”).

For example, pressing the Shift key will cause a “key down” event with a VK_SHIFT key code whereas pressing the “a” key will result in a VK_A key code. After the “a” key is released, a “key up” event will be fired with VK_A.

Here is a list of the most important virtual key codes:

• VK_0 through VK_9 are for keys “0” thru “9”.
• VK_A through VK_Z are for keys “A” thru “Z” (regardless of case - upper/lower).
• VK_LEFT, VK_RIGHT, VK_UP, VK_DOWN are for the arrow keys.
• VK_F1 through VK_F12 are for the function keys.
• other keys, such as VK_AMPERSAND, VK_CAPS_LOCK, VK_COMMA, VK_CONTROL, VK_ENTER, VK_MINUS, VK_PLUS, VK_SPACE, and so on.

For a complete list see the Java API documentation on KeyEvent.

C.6.2 Mouse Events

The following functions handle various mouse events.

The first group handles mouse events which happen inside a specific GUI object (e.g., display, circle, etc.):

The following functions handle movement of a mouse that crosses the borders of a GUI object (i.e., entering or exiting the object boundaries):

C.6.3 Display Events

In addition to all the above, Display objects also have an onClose() event handling function.

C.7 Scheduling Tasks – The Timer Class

The GUI library supports scheduling tasks (e.g., animation) through Timer class. Timer objects are used to schedule how often to perform a certain task (i.e., how often to call a given function).

C.7.1 Creating Timers

Timer objects are used to to schedule functions to be executed after a given time interval, repeatedly or once. The following function creates a new Timer, so you need to save it in a variable (so you can use it later).

For example, the following:

t = Timer(500, Play.noteOn, [A4], True)

creates a Timer t, which will call function Play.noteOn(A4) repeatedly every 500 milliseconds (i.e., half second). In order for a timer to operate, it needs to get started:

t.start()

Once a Timer t has been created, the following functions are available:

---