PyUI Widgets

  1. Widget Basics
  2. Labels
  3. Buttons
  4. Edit Boxes
  5. List Boxes
  6. DropDown List Boxes
  7. Check Boxes
  8. Slider Bars
  9. Entry
  10. GridPanel
  11. FormPanel

Widget Basics

PyUI has a basic set of Widgets that can be used when building GUI applications. Widgets are generally not constructed with size and position information. This information is usually supplied by the Layout Manager when the Panel that the Widget is in is "packed".


Labels are extremely simple static text display Widgets. They have no interactivity with the user - all Labels do is display text. Developers should use Labels for text when they want the position of the text to be controlled by a Layout Manager.

newLabel = pyui.widgets.Label("this is a label")


Buttons are Widgets that can be pressed by the user. There are basic Buttons which have text labels and ImageButtons which have images on them. Buttons take a handler argument when they are contructed which is called when the button is pressed.

The handler method is passed the button instance that generated the event, not the event itself. This allows different buttons of the same class to have different behaviour based on their textual label. For example:

import pyui
def onPress(button):
    print "button #%s" % button.text
    if button.text == "button 1":
        print "Got #1 button!"
newFrame = pyui.widgets.Frame(10, 10, 160, 200, "full'o'buttons")
for i in range(0,10):
    newButton = pyui.widgets.Button("button %d" % i, onPress)

This technique lends itself well to data-generated sets of buttons.

Edit Boxes

Edit Boxes are Widgets that allow the entry of text into them. The classes Edit and Password are very similar - the only difference being that Password displays "*" characters instead of the actual text typed into it.

Edit boxes only accept text if they have the current focus. When the return key is pressed, Edit Boxes invoke the handler method that they were constructed with. Below is an example of using an Edit Box to echo out text.

import pyui
def onEnter(edit):
    print "Entered: ", edit.text
newFrame = pyui.widgets.Frame(10, 10, 160, 100, "click on edit box")
newEdit = pyui.widgets.Edit("", 20, onEnter)

This should look something like:


There is also a NumberEdit widget that behaves like a regular Edit box but only accepts numeric characters.

List Boxes

List boxes are Widgets that display a scrolling list of text items. The items in the list box are selectable and callback method is invoked when an item is selected, or double clicked on. Items are added to a list box with the addItem() method which takes as arguments the text for the item, a userData field and an optional color to use to draw that item.

Below is an example of using the ListBox. The example adds a new item to the listbox when the button is pressed, then prints out the text of the list box item when it is selected. The list box takes two arguments which are callback methods - one for when an item is selected, and one for when an item is doubleclicked.

import pyui
from pyui.desktop import getDesktop()

def onDouble(item):
    print "doubled item":,

def onChanged(item):
    print "got item: ",

def onPress(button):
    newList.addItem("new item!", None)
    return 1
newFrame = pyui.widgets.Frame(10, 10, 250, 200, "Show a list")
newList = pyui.widgets.ListBox(onChanged, onDouble)
for i in range(0,4):
    newList.addItem("Item #%d" % i, None)
newButton = pyui.widgets.Button("add to list", onPress)

This should look something like:

Drop-down List Boxes

In addition to the regular list box, there is a Drop-down list box. This shows a single item in the list box and a down-arrow button. When the button is clicked it displays another regular list box that allows the user to select a new value.

Check Boxes

The CheckBox is a boolean on/off box with an attached label. When clicked, it flips its state and call the handler method it was created with.

Slider Bar

The SliderBar is a widget with a central horizonal axis and a knob that slides along the axis. It is created with a range and a handler method which is called when the slider is moved to a new value.

Below is an example of using the SliderBar, CheckBox, and DropDownBox.

import pyui
def onSlide(value):
    print "Slider changed to :", value
def onCheck(button):
    print "checkbox changed"
newFrame = pyui.widgets.Frame(10, 10, 250, 200, "Widgets Testing")
s = pyui.widgets.SliderBar(onSlide, 100, 2)
d = pyui.widgets.DropDownBox(4)
d.addItem("item goes here", None)
d.addItem("sdklahfkjdsafh here", None)
d.addItem("askjdhfkjksjdhf", None)
for i in range(0,25):
    d.addItem("testing%s" % i, None)
c = pyui.widgets.CheckBox("check me!", onCheck)

This should look something like:



The Entry widget is a multi-line editable text box with horizontal and vertical scroll bars. It uses a fixed width font, and can hold text of any size (be warned, large chunks of text may be slow). This widget is located in the pyui.entry file.


The GridPanel widget is a scrollable grid that can hold any other widget in its internal cells - including other grid widgets. It has optional column and row header buttons. This widgets is intended for spreadsheet or data-entry type applications. It is located in the pyui.grid file.


The FormPanel is a widget to display a data form for a python object. To use it, create a fieldList in the format:

[ (type, name, label, vertical span, data),
(type, name, label, vertical span, data)

When the FormPanel is created, pass the fieldList, and a form will be created to display and edit the data. To populate the form, call populate() on the FormPanel with an object, and the values from the "name" column of the fieldList will be used to extract data from the provided object. Below is an example of a form to display information about an employee.

import pyui
class Employee:
    def __init__(self, name, manager, salary): = name
        self.manager = manager
        self.salary = salary
newFrame = pyui.widgets.Frame(10, 10, 300, 120, "Form Testing")
fieldList = [
    ("label",  "name",        "Employee Name:", 1, ""),
    ("string", "manager",     "Manager Name:",  1, ""),
    ("int",    "salary",      "Salary:",        1, 0)
emp = Employee("someguy", "anotherguy", 20000)
form = pyui.widgets.FormPanel(fieldList)

This should look something like:

(C) Sean Riley 2002