Getting started with wxPython

A First Application: "Hello, World"

As is traditional, we are first going to write a Small "Hello, world" application. Here is the code:

   1 #!/usr/bin/env python
   2 import wx
   3 
   4 app = wx.App(False)  # Create a new app, don't redirect stdout/stderr to a window.
   5 frame = wx.Frame(None, wx.ID_ANY, "Hello World") # A Frame is a top-level window.
   6 frame.Show(True)     # Show the frame.
   7 app.MainLoop()

Explanations:

app = wx.App(False)

Every wxPython app is an instance of wx.App. For most simple applications you can use wx.App as is. When you get to more complex applications you may need to extend the wx.App class. The "False" parameter means "don't redirect stdout and stderr to a window".

wx.Frame(None,wx.ID_ANY,"Hello")

A wx.Frame is a top-level window. The syntax is wx.Frame(Parent, Id, Title). Most of the constructors have this shape (a parent object, followed by an Id). In this example, we use None for "no parent" and wx.ID_ANY to have wxWidgets pick an id for us.

frame.Show(True)

We make a frame visible by "showing" it.

app.MainLoop()

Finally, we start the application's MainLoop whose role is to handle the events.

Note: You almost always want to use wx.ID_ANY or another standard ID (v2.8) provided by wxWidgets. You can make your own IDs, but there is no reason to do that.

Run the program and you should see a window like this one:

Windows or Frames?

When people talk about GUIs, they usually speak of windows, menus and icons. Naturally then, you would expect that wx.Window should represent a window on the screen. Unfortunately, this is not the case. A wx.Window is the base class from which all visual elements are derived (buttons, menus, etc) and what we normally think of as a program window is a wx.Frame. This is an unfortunate inconsistency that has led to much confusion for new users.

Building a simple text editor

In this tutorial we are going to build a simple text editor. In the process, we will explore several widgets, and learn about features such as events and callbacks.

First steps

The first step is to make a simple frame with an editable text box inside. A text box is made with the wx.TextCtrl widget. By default, a text box is a single-line field, but the wx.TE_MULTILINE parameter allows you to enter multiple lines of text.

   1 #!/usr/bin/env python
   2 import wx
   3 class MyFrame(wx.Frame):
   4     """ We simply derive a new class of Frame. """
   5     def __init__(self, parent, title):
   6         wx.Frame.__init__(self, parent, title=title, size=(200,100))
   7         self.control = wx.TextCtrl(self, style=wx.TE_MULTILINE)
   8         self.Show(True)
   9 
  10 app = wx.App(False)
  11 frame = MyFrame(None, 'Small editor')
  12 app.MainLoop()

In this example, we derive from wx.Frame and overwrite its __init__ method. Here we declare a new wx.TextCtrl which is a simple text edit control. Note that since the MyFrame runs self.Show() inside its __init__ method, we no longer have to call frame.Show() explicitly.

Adding a menu bar

Every application should have a menu bar and a status bar. Let's add them to ours:

   1 import wx
   2 
   3 class MainWindow(wx.Frame):
   4     def __init__(self, parent, title):
   5         wx.Frame.__init__(self, parent, title=title, size=(200,100))
   6         self.control = wx.TextCtrl(self, style=wx.TE_MULTILINE)
   7         self.CreateStatusBar() # A Statusbar in the bottom of the window
   8 
   9         # Setting up the menu.
  10         filemenu= wx.Menu()
  11 
  12         # wx.ID_ABOUT and wx.ID_EXIT are standard IDs provided by wxWidgets.
  13         filemenu.Append(wx.ID_ABOUT, "&About"," Information about this program")
  14         filemenu.AppendSeparator()
  15         filemenu.Append(wx.ID_EXIT,"E&xit"," Terminate the program")
  16 
  17         # Creating the menubar.
  18         menuBar = wx.MenuBar()
  19         menuBar.Append(filemenu,"&File") # Adding the "filemenu" to the MenuBar
  20         self.SetMenuBar(menuBar)  # Adding the MenuBar to the Frame content.
  21         self.Show(True)
  22 
  23 app = wx.App(False)
  24 frame = MainWindow(None, "Sample editor")
  25 app.MainLoop()

TIP: Notice the wx.ID_ABOUT and wx.ID_EXIT ids. These are standard ids provided by wxWidgets (see a full list here). It is a good habit to use the standard ID if there is one available. This helps wxWidgets know how to display the widget in each platform to make it look more native.

Event handling

Reacting to events in wxPython is called event handling. An event is when "something" happens on your application (a button click, text input, mouse movement, etc). Much of GUI programming consists of responding to events. You bind an object to an event using the Bind() method:

   1 class MainWindow(wx.Frame):
   2     def __init__(self, parent, title):
   3         wx.Frame.__init__(self,parent, title=title, size=(200,100))
   4         ...
   5         menuItem = filemenu.Append(wx.ID_ABOUT, "&About"," Information about this program")
   6         self.Bind(wx.EVT_MENU, self.OnAbout, menuItem)

This means that, from now on, when the user selects the "About" menu item, the method self.OnAbout will be executed. wx.EVT_MENU is the "select menu item" event. wxWidgets understands many other events (see the full list). The self.OnAbout method has the general declaration:

   1 def OnAbout(self, event):
   2         ...

Here event is an instance of a subclass of wx.Event. For example, a button-click event - wx.EVT_BUTTON - is a subclass of wx.Event.

The method is executed when the event occurs. By default, this method will handle the event and the event will stop after the callback finishes. However, you can "skip" an event with event.Skip(). This causes the event to go through the hierarchy of event handlers. For example:

   1 def OnButtonClick(self, event):
   2     if (some_condition):
   3         do_something()
   4     else:
   5         event.Skip()
   6 
   7 def OnEvent(self, event):
   8     ...

When a button-click event occurs, the method OnButtonClick gets called. If some_condition is true, we do_something() otherwise we let the event be handled by the more general event handler. Now let's have a look at our application:

   1 import os
   2 import wx
   3 
   4 
   5 class MainWindow(wx.Frame):
   6     def __init__(self, parent, title):
   7         wx.Frame.__init__(self, parent, title=title, size=(200,100))
   8         self.control = wx.TextCtrl(self, style=wx.TE_MULTILINE)
   9         self.CreateStatusBar() # A StatusBar in the bottom of the window
  10 
  11         # Setting up the menu.
  12         filemenu= wx.Menu()
  13 
  14         # wx.ID_ABOUT and wx.ID_EXIT are standard ids provided by wxWidgets.
  15         menuAbout = filemenu.Append(wx.ID_ABOUT, "&About"," Information about this program")
  16         menuExit = filemenu.Append(wx.ID_EXIT,"E&xit"," Terminate the program")
  17 
  18         # Creating the menubar.
  19         menuBar = wx.MenuBar()
  20         menuBar.Append(filemenu,"&File") # Adding the "filemenu" to the MenuBar
  21         self.SetMenuBar(menuBar)  # Adding the MenuBar to the Frame content.
  22 
  23         # Set events.
  24         self.Bind(wx.EVT_MENU, self.OnAbout, menuAbout)
  25         self.Bind(wx.EVT_MENU, self.OnExit, menuExit)
  26 
  27         self.Show(True)
  28 
  29     def OnAbout(self,e):
  30         # A message dialog box with an OK button. wx.OK is a standard ID in wxWidgets.
  31         dlg = wx.MessageDialog( self, "A small text editor", "About Sample Editor", wx.OK)
  32         dlg.ShowModal() # Show it
  33         dlg.Destroy() # finally destroy it when finished.
  34 
  35     def OnExit(self,e):
  36         self.Close(True)  # Close the frame.
  37 
  38 app = wx.App(False)
  39 frame = MainWindow(None, "Sample editor")
  40 app.MainLoop()

Note: Instead of

   1 wx.MessageDialog( self, "A small editor in wxPython", "About Sample Editor", wx.OK)

We could have omitted the id. In that case wxWidget automatically generates an ID (just as if you specified wx.ID_ANY):

   1 wx.MessageDialog( self, "A small editor in wxPython", "About Sample Editor")

Dialogs

Of course an editor is useless if it is not able to save or open documents. That's where Common dialogs come in. Common dialogs are those offered by the underlying platform so that your application will look exactly like a native application. Here is the implementation of the OnOpen method in MainWindow:

   1     def OnOpen(self,e):
   2         """ Open a file"""
   3         self.dirname = ''
   4         dlg = wx.FileDialog(self, "Choose a file", self.dirname, "", "*.*", wx.FD_OPEN)
   5         if dlg.ShowModal() == wx.ID_OK:
   6             self.filename = dlg.GetFilename()
   7             self.dirname = dlg.GetDirectory()
   8             f = open(os.path.join(self.dirname, self.filename), 'r')
   9             self.control.SetValue(f.read())
  10             f.close()
  11         dlg.Destroy()

Explanation:

You should now be able to add the corresponding entry into the menu and connect it to the OnOpen method. If you have trouble, scroll down to the appendix for the full source code.

Possible extensions

Of course, this program is far from being a decent editor. But adding other features should not be any more difficult than what has already been done. You might take inspiration from the demos that are bundled with wxPython:

Working with Windows

In this section, we are going to present the way wxPython deals with windows and their contents, including building input forms and using various widgets/controls. We are going to build a small application that calculates the price of a quote. If you are already an experienced GUI developer, this is going to be easy and you might want to move on to the Boa-Constructor Subsection in the Advanced topics chapter.

Overview

Laying out Visual Elements

Sizers

   1 import wx
   2 import os
   3 
   4 class MainWindow(wx.Frame):
   5     def __init__(self, parent, title):
   6         self.dirname=''
   7 
   8         # A "-1" in the size parameter instructs wxWidgets to use the default size.
   9         # In this case, we select 200px width and the default height.
  10         wx.Frame.__init__(self, parent, title=title, size=(200,-1))
  11         self.control = wx.TextCtrl(self, style=wx.TE_MULTILINE)
  12         self.CreateStatusBar() # A Statusbar in the bottom of the window
  13 
  14         # Setting up the menu.
  15         filemenu= wx.Menu()
  16         menuOpen = filemenu.Append(wx.ID_OPEN, "&Open"," Open a file to edit")
  17         menuAbout= filemenu.Append(wx.ID_ABOUT, "&About"," Information about this program")
  18         menuExit = filemenu.Append(wx.ID_EXIT,"E&xit"," Terminate the program")
  19 
  20         # Creating the menubar.
  21         menuBar = wx.MenuBar()
  22         menuBar.Append(filemenu,"&File") # Adding the "filemenu" to the MenuBar
  23         self.SetMenuBar(menuBar)  # Adding the MenuBar to the Frame content.
  24 
  25         # Events.
  26         self.Bind(wx.EVT_MENU, self.OnOpen, menuOpen)
  27         self.Bind(wx.EVT_MENU, self.OnExit, menuExit)
  28         self.Bind(wx.EVT_MENU, self.OnAbout, menuAbout)
  29 
  30         self.sizer2 = wx.BoxSizer(wx.HORIZONTAL)
  31         self.buttons = []
  32         for i in range(0, 6):
  33             self.buttons.append(wx.Button(self, -1, "Button &"+str(i)))
  34             self.sizer2.Add(self.buttons[i], 1, wx.EXPAND)
  35 
  36         # Use some sizers to see layout options
  37         self.sizer = wx.BoxSizer(wx.VERTICAL)
  38         self.sizer.Add(self.control, 1, wx.EXPAND)
  39         self.sizer.Add(self.sizer2, 0, wx.EXPAND)
  40 
  41         #Layout sizers
  42         self.SetSizer(self.sizer)
  43         self.SetAutoLayout(1)
  44         self.sizer.Fit(self)
  45         self.Show()
  46 
  47     def OnAbout(self,e):
  48         # Create a message dialog box
  49         dlg = wx.MessageDialog(self, " A sample editor \n in wxPython", "About Sample Editor", wx.OK)
  50         dlg.ShowModal() # Shows it
  51         dlg.Destroy() # finally destroy it when finished.
  52 
  53     def OnExit(self,e):
  54         self.Close(True)  # Close the frame.
  55 
  56     def OnOpen(self,e):
  57         """ Open a file"""
  58         dlg = wx.FileDialog(self, "Choose a file", self.dirname, "", "*.*", wx.FD_OPEN)
  59         if dlg.ShowModal() == wx.ID_OK:
  60             self.filename = dlg.GetFilename()
  61             self.dirname = dlg.GetDirectory()
  62             f = open(os.path.join(self.dirname, self.filename), 'r')
  63             self.control.SetValue(f.read())
  64             f.close()
  65         dlg.Destroy()
  66 
  67 app = wx.App(False)
  68 frame = MainWindow(None, "Sample editor")
  69 app.MainLoop()

   1 window.SetSizer(sizer)
   2 window.SetAutoLayout(True)
   3 sizer.Fit(window)

Validators

A Working Example

Our first label within a panel

   1 import wx
   2 class ExampleFrame(wx.Frame):
   3     def __init__(self, parent):
   4         wx.Frame.__init__(self, parent)
   5         panel = wx.Panel(self)
   6         self.quote = wx.StaticText(panel, label="Your quote: ", pos=(20, 30))
   7         self.Show()
   8 
   9 app = wx.App(False)
  10 ExampleFrame(None)
  11 app.MainLoop()

   1         self.quote = wx.StaticText(panel, label="Your quote: ", pos=(20, 30))

[7] According to wxPython documentation:

[8] A label is used to display text that is not supposed to interact with the user.

Adding a few more controls

   1 clearButton = wx.Button(self, wx.ID_CLEAR, "Clear")
   2 self.Bind(wx.EVT_BUTTON, self.OnClear, clearButton)

   1 textField = wx.TextCtrl(self)
   2 self.Bind(wx.EVT_TEXT, self.OnChange, textField)
   3 self.Bind(wx.EVT_CHAR, self.OnKeyPress, textField)

   1 import wx
   2 class ExamplePanel(wx.Panel):
   3     def __init__(self, parent):
   4         wx.Panel.__init__(self, parent)
   5         self.quote = wx.StaticText(self, label="Your quote :", pos=(20, 30))
   6 
   7         # A multiline TextCtrl - This is here to show how the events work in this program, don't pay too much attention to it
   8         self.logger = wx.TextCtrl(self, pos=(300,20), size=(200,300), style=wx.TE_MULTILINE | wx.TE_READONLY)
   9 
  10         # A button
  11         self.button =wx.Button(self, label="Save", pos=(200, 325))
  12         self.Bind(wx.EVT_BUTTON, self.OnClick,self.button)
  13 
  14         # the edit control - one line version.
  15         self.lblname = wx.StaticText(self, label="Your name :", pos=(20,60))
  16         self.editname = wx.TextCtrl(self, value="Enter here your name", pos=(150, 60), size=(140,-1))
  17         self.Bind(wx.EVT_TEXT, self.EvtText, self.editname)
  18         self.Bind(wx.EVT_CHAR, self.EvtChar, self.editname)
  19 
  20         # the combobox Control
  21         self.sampleList = ['friends', 'advertising', 'web search', 'Yellow Pages']
  22         self.lblhear = wx.StaticText(self, label="How did you hear from us ?", pos=(20, 90))
  23         self.edithear = wx.ComboBox(self, pos=(150, 90), size=(95, -1), choices=self.sampleList, style=wx.CB_DROPDOWN)
  24         self.Bind(wx.EVT_COMBOBOX, self.EvtComboBox, self.edithear)
  25         self.Bind(wx.EVT_TEXT, self.EvtText,self.edithear)
  26 
  27         # Checkbox
  28         self.insure = wx.CheckBox(self, label="Do you want Insured Shipment ?", pos=(20,180))
  29         self.Bind(wx.EVT_CHECKBOX, self.EvtCheckBox, self.insure)
  30 
  31         # Radio Boxes
  32         radioList = ['blue', 'red', 'yellow', 'orange', 'green', 'purple', 'navy blue', 'black', 'gray']
  33         rb = wx.RadioBox(self, label="What color would you like ?", pos=(20, 210), choices=radioList,  majorDimension=3,
  34                          style=wx.RA_SPECIFY_COLS)
  35         self.Bind(wx.EVT_RADIOBOX, self.EvtRadioBox, rb)
  36 
  37     def EvtRadioBox(self, event):
  38         self.logger.AppendText('EvtRadioBox: %d\n' % event.GetInt())
  39     def EvtComboBox(self, event):
  40         self.logger.AppendText('EvtComboBox: %s\n' % event.GetString())
  41     def OnClick(self,event):
  42         self.logger.AppendText(" Click on object with Id %d\n" %event.GetId())
  43     def EvtText(self, event):
  44         self.logger.AppendText('EvtText: %s\n' % event.GetString())
  45     def EvtChar(self, event):
  46         self.logger.AppendText('EvtChar: %d\n' % event.GetKeyCode())
  47         event.Skip()
  48     def EvtCheckBox(self, event):
  49         self.logger.AppendText('EvtCheckBox: %d\n' % event.Checked())
  50 
  51 
  52 app = wx.App(False)
  53 frame = wx.Frame(None)
  54 panel = ExamplePanel(frame)
  55 frame.Show()
  56 app.MainLoop()

The notebook

Note how ExamplePanel's parent is the Notebook. This is important.

   1 app = wx.App(False)
   2 frame = wx.Frame(None, title="Demo with Notebook")
   3 nb = wx.Notebook(frame)
   4 
   5 
   6 nb.AddPage(ExamplePanel(nb), "Absolute Positioning")
   7 nb.AddPage(ExamplePanel(nb), "Page Two")
   8 nb.AddPage(ExamplePanel(nb), "Page Three")
   9 frame.Show()
  10 app.MainLoop()

Improving the layout - Using Sizers

Here is the sample above re-written to use sizers: