By: Mark Mruss

Note: This article was first published the December 2007 issue of Python Magazine

While the command line will never cease to be useful, nothing will impress your friends more than your latest python masterpiece wrapped up in a slick cross-platform Graphical User Interface (GUI). This tutorial will show you how to create a simple GUI in Python using PyQt4.

1. Introduction
2. Installing PyQt4
3. Your First PyQt4 Application
4. The Main Window
5. Adding Some Widgets
6. Signal Handling
7. Displaying a Message
8. Conclusion

Introduction

While writing console applications and modules using Python can be very enjoyable, I think that almost everyone learning Python eventually wants to do one thing: create a application with a full Graphical User Interface (GUI). Fortunately for Python users, there are a few options available to achieve this. One of the more interesting options is PyQt4, Python bindings for the fourth version of the famous cross platform application development API Qt.

Qt, owned by Trolltech software, is probably most famous as the foundation for the KDE window manager on Linux. PyQt4, and PyQt version 3, were created and are maintained by Riverbank software. Qt and PyQt4 are both open source and free for open source applications, but if you wish to develop commercial applications you will need to purchase the commercial versions of both Qt and PyQt4.

One of the best features of Qt is that it is a cross platform library which means that it gives you easy access to the three main desktop environments: Linux, Windows, and OS X. This is an important requirement for me because when I’m developing a small open source application I want it available on as many platforms as possible. The nice thing about Qt’s latest version, Qt4, is that it also gives your GUI a native look and feel on the different operating systems.

This article will create a simple application to introduce you to the basic features of PyQt4. The application will consist of a single window that does the following: accepts user input, responds to a button click, and displays a message using a pop-up dialog.

Installing PyQt4

Before installing PyQt4 you need to have Python 2.5 or newer and Qt version 4 installed. You can download Python 2.5 from the main Python website.[1] Qt version 4 is available from the TrollTech website’s Downloads section.[2] Installing PyQt4 on Linux, Windows, or OS X is relatively easy, and I know since I installed it on each of them. You can download the different PyQt4 packages from the Riverbank website, including an all in one (Qt version 4 included) installer for Windows.[3] There are also installation instructions in the PyQt4 online documentation that are worth a read if you are new to installing software from source.[4] If you are using a modern Linux distribution, you may want to consider using your package manager to install PyQt4 as it should being along all the necessary dependencies for you.

Your First PyQt4 Application

Now that you have PyQT4 properly installed, let’s dive right in and create an application. The first step is to start a new Python file, I called mine PyQt4Intro.py but you can call it whatever you like. Set it up using the following code:

#!/usr/bin/env python
import PyQt4

if __name__ == "__main__":
	# Someone is launching this directly
	pass

If you’ve read any of my other columns, you may recognize this code as a general template that I use for my Python projects. The major difference in this example is that we import PyQt4. After you have set your file up run the code. If all goes well nothing will happen. If you do get an error, something like the following, it probably means that PyQt4 is not installed properly:

ImportError: No module named PyQt4

Remember that PyQT4 requires Python 2.5. If you have Python 2.5 and older versions of Python installed, try specifying python2.5 when you run the script:

python2.5 PyQt4Intro.py

Now that we have everything in order, let’s create and show a window. After all this is a GUI tutorial! If you are creating a GUI application using PyQt4 (of course, you can also create a non-GUI application using PyQt4), you will need to create a QApplication instance.

The PyQt4 documentation provides a great description of the “QApplication” class: “The QApplication class manages the GUI application’s control flow and main settings. It contains the main event loop, where all events from the window system and other sources are processed and dispatched. It also handles the application’s initialization and finalization, and provides session management. It also handles most system-wide and application-wide settings. For any GUI application that uses Qt, there is precisely one QApplication object, no matter whether the application has 0, 1, 2 or more windows at any time.”[5]

What we need to do is create the one and only QApplication instance for our application. To do this, we will import two new modules:

import sys
from PyQt4 import QtGui

The first line imports the sys module. This is needed to initialize the QApplication. The second line imports the QtGui module. It allows us to reference QApplication and other QtGui components.

In our main block, we will add the following code:

if __name__ == "__main__":
	# Someone is launching this directly
	# Create the QApplication
	app = QtGui.QApplication(sys.argv)
	# Enter the main loop
	app.exec_()

This will create the QApplication instance, initialized with the command-line parameters that may be passed to our script. This is a necessary parameter to the QApplication class and is the reason that we imported the sys module. The next call is to the exec function which “enters the main event loop and waits until exit() is called or the main widget is destroyed”.[6]

If you run the entire script at this point, which I don’t necessarily recommend since it will seem to hang, you will be running a PyQt4 application. You won’t see anything since there is no visible component. However, the script will continue to run in its main loop instead of returning right after being executed. If you do decide to run this script, use CTRL+Z to exit.

The Main Window

GUI applications without a visible component are not that useful so let’s add a window to our application. We will do this by sub-classing the QMainWindow class. The QMainWindow class “provides a framework for building an application’s user interface. Qt has “QMainWindow” and its related classes for main window management. “QMainWindow” has its own layout to which you can add “QToolBars”, “QDockWindows”, a “QMenuBar”, and a “QStatusBar”.”[7]

Note: There are other ways to create a visible window. For example you could use a QWidget to accomplish much of what we are going to do. I chose to use the QMainWindow since it provides an application framework that you might want to use when building a full GUI application.

We can subclass the QMainWindow as follows:

class HelloWindow(QtGui.QMainWindow):

	def __init__(self, win_parent = None):
		#Init the base class
		QtGui.QMainWindow.__init__(self, win_parent)

Then in the main block we can create and show our main window like this:

app = QtGui.QApplication(sys.argv)
#The Main window
main_window = HelloWindow()
main_window.show()
# Enter the main loop
app.exec_()

The entire source code thus far is found in Listing 1. When you run the code, you will finally be greeted with your very first PyQt4 window. It will look something similar to Figure 1.

Listing 1

#!/usr/bin/env python
import PyQt4
import sys
from PyQt4 import QtGui

class HelloWindow(QtGui.QMainWindow):

	def __init__(self, win_parent = None):
		#Init the base class
		QtGui.QMainWindow.__init__(self, win_parent)

if __name__ == "__main__":
	# Someone is launching this directly
	# Create the QApplication
	app = QtGui.QApplication(sys.argv)
	#The Main window
	main_window = HelloWindow()
	main_window.show()
	# Enter the main loop
	app.exec_()

Figure 1

Adding Some Widgets

A blank window is only slightly more useful then an invisible oen. Therefore our next step is to add some functionality to our window by adding some interactive widgets. In order to do this, we will set the central widget of our main window and use a “geometry manager” (or “layout manager”) class to manage the positioning of our widgets.

We will add a new function to our HelloWindow class called create_widgets where we will create all of our widgets. We will call this function from the __init__ function. The first step in the create_widgets function is to create a widget that will serve as the “central widget” for our main window. As mentioned earlier, the QMainWindow class already has a built-in layout making it easy to add menus, toolbars, and other items common to applications. QMainWindow classes also have a “central widget” which you can think of as the main part of the application. More to the point, the “central widget” is not the toolbars, menu, or docking panes, but the actual functional area of the application. For a greater description of the “central widget” see the PyQt4 website.[8]

We will create and set our “central widget” using the following code:

def create_widgets(self):
	central_widget = QtGui.QWidget()
	self.setCentralWidget(central_widget)

So far this won’t do anything, since we still have not added anything interactive. To add interactivity, we must add widgets to our “central widget”. Rather than place the widgets in static positions, we will use a layout manager to automatically position and adjust our widgets. If you are at all familiar with modern GUI toolkits, the idea of a layout manager should be familiar to you. They serve as a way to “pack” widgets into an area where their positions will be relative to each other and to the window. When you resize the window (or area), geometry manager’s will automatically adjust the size and positions of their child widgets to accommodate the new size.

We will be creating three widgets in our simple application:

1. A QLabel widget to display some static text.
2. A QLineEdit widget to let the user enter some text into an edit field.
3. A QPushButton button widget that will pop up a dialog to display a message when the user clicks on it.

We will create the widgets using the following code. Notice that in the creation of the QLabel and QPushButton widgets we are also setting the text that will appear on each widget. (We can do the same for the QLineEdit, but for now we’ll leave it blank):

def create_widgets(self):
	#Widgets
	self.label = QtGui.QLabel("Say hello:")
	self.hello_edit = QtGui.QLineEdit()
	self.hello_button = QtGui.QPushButton("Push Me!")

Next, we will create a QHBoxLayout instance to serve as the central widget’s layout manager. The QHBoxLayout class is a specific type of layout manager that lays widgets out, and manage their positions, in the horizontal direction. Once we have created the QHBoxLayout instance, we will add our three widgets to it. Adding widgets to a QHBoxLayout will pack them from left to right:

#Horizontal layout
h_box = QtGui.QHBoxLayout()
h_box.addWidget(self.label)
h_box.addWidget(self.hello_edit)
h_box.addWidget(self.hello_button)

The last step in our widget creation is to set h_box as the layout manager for our central widget:

#Create central widget, add layout, and set
central_widget = QtGui.QWidget()
central_widget.setLayout(h_box)
self.setCentralWidget(central_widget)

The entire code can be seen in Listing 2. When you run this code, you will finally be greeted with a window containing actual widgets. This is illustrated in Figure 2.

Listing 2

#!/usr/bin/env python
import PyQt4
import sys
from PyQt4 import QtGui

class HelloWindow(QtGui.QMainWindow):

	def __init__(self, win_parent = None):
		#Init the base class
		QtGui.QMainWindow.__init__(self, win_parent)
		self.create_widgets()

	def create_widgets(self):
		#Widgets
		self.label = QtGui.QLabel("Say hello:")
		self.hello_edit = QtGui.QLineEdit()
		self.hello_button = QtGui.QPushButton("Push Me!")
		#Horizontal layout
		h_box = QtGui.QHBoxLayout()
		h_box.addWidget(self.label)
		h_box.addWidget(self.hello_edit)
		h_box.addWidget(self.hello_button)
		#Create central widget, add layout and set
		central_widget = QtGui.QWidget()
		central_widget.setLayout(h_box)
		self.setCentralWidget(central_widget)

if __name__ == "__main__":
	# Someone is launching this directly
	# Create the QApplication
	app = QtGui.QApplication(sys.argv)
	#The Main window
	main_window = HelloWindow()
	main_window.show()
	# Enter the main loop
	app.exec_()

Figure 2

Signal Handling

Responding to the user’s interaction with the GUI is something that must be done in all GUI applications. Therefore the next step in constructing a GUI application is signal or event handling. If you are unfamiliar with these terms you can thing of it his way: when the end user interacts with your GUI, her interaction will causes signals to be sent to your application. So if she clicks on a button the clicked() signal will be sent. If your application wants to do something when that button is clicked, then you will have to handle that widgets clicked() signal. In our example, we are going to show a pop up a dialog when the user clicks on our button widget.

I find connecting to signals in PyQt4 a bit odd because of a built in macro that needs to be called but the process is relatively easy so I shouldn’t complain too much. The idea is similar to that of other Python GUI toolkits: you connect functions that you have written to signals or events that are emitted by a widget. So whenever a widget emits a signal that has been connected to a function, that function will be called.

Note: Qt goes a bit further with the idea of built-in “slots” but for the sake of this tutorial we will be ignoring them. For more information on “slots” please see the PyQt4 documentation.

In order for the “QPushButton” to do something when pushed, we have to connect a function in our HelloWindow class with the clicked signal. To do this, we need to call the QObject classes connect static function. We must tell it three things:

1. The QWidget that will emit the signal.
2. The signal that we want to connect to.
3. The function that should be called when the QWidget emits the signal.

In our example, we will do this like so:

#connect signal
QtCore.QObject.connect(self.hello_button
	, QtCore.SIGNAL("clicked()")
	, self.on_hello_clicked)

Note: We could just as easily have called self.connect since a QMainWindow is a descendant of the QObject class.

QtCore.SIGNAL is a macro that you have to use for the second parameter. It accepts the signal name as a string (in this case clicked()) and converts it into an object that is required for the signal connection. The documentation is a bit sparse regarding exactly what the macro does, but luckily for us we don’t really need to know the details.

In order for this code to compile, we also have to import the QtCore module:

from PyQt4 import QtCore

We also have to add a new function to the HelloWindow class. This is the function on_hello_clicked that will respond to the clicked() signal:

def on_hello_clicked(self):
	print "Clicked"

When you run the code in Listing 3, you will see “Clicked” printed out to the command line every time you click the “Push Me!” button.

Listing 3

#!/usr/bin/env python
import PyQt4
import sys
from PyQt4 import QtGui
from PyQt4 import QtCore

class HelloWindow(QtGui.QMainWindow):

	def __init__(self, win_parent = None):
		#Init the base class
		QtGui.QMainWindow.__init__(self, win_parent)
		self.create_widgets()


	def create_widgets(self):
		#Widgets
		self.label = QtGui.QLabel("Say hello:")
		self.hello_edit = QtGui.QLineEdit()
		self.hello_button = QtGui.QPushButton("Push Me!")

		#connect signal
		QtCore.QObject.connect(self.hello_button
			, QtCore.SIGNAL("clicked()")
			, self.on_hello_clicked)


		#Horizontal layout
		h_box = QtGui.QHBoxLayout()
		h_box.addWidget(self.label)
		h_box.addWidget(self.hello_edit)
		h_box.addWidget(self.hello_button)
		#Create central widget, add layout and set
		central_widget = QtGui.QWidget()
		central_widget.setLayout(h_box)
		self.setCentralWidget(central_widget)

	def on_hello_clicked(self):
		print "Clicked"
		
if __name__ == "__main__":
	# Someone is launching this directly
	# Create the QApplication
	app = QtGui.QApplication(sys.argv)
	#The Main window
	main_window = HelloWindow()
	main_window.show()
	# Enter the main loop
	app.exec_()

Displaying a Message

Now that we have a function connected to the clicking of the button widget we need to read the text from the QLineEdit widget and display it to the user. Fortunately both tasks are quite easy in PyQt4.

In order to get the text from a QLineEdit widget, the QLineEdit classes member function displayText needs to be called. The displayText function simply returns the contents of the QLineEdit widget.

Showing a pop-up dialog using PyQt4 is just as easy as getting the contents of a QLineEdit widget, thanks to the QMesssageBox classes static function information. This function allows you to set the title, text and what buttons are on a simple “information dialog”. Calling it from our PyQt4 application in response to the button click is very simple:

def on_hello_clicked(self):
	QtGui.QMessageBox.information(self
		, "Hello!"
		, "Hello %s" % self.hello_edit.displayText()
		, QtGui.QMessageBox.Ok)

In this code, we call the information function, set its title text to be “Hello!”, set its main message to be “Hello ” followed by the contents of the hello_edit QInputEdit, and give it one button, an “ok” button. All of the code is found in Listing 4. What this looks like running on Linux, Windows and OS X can be seen in Figure 3, Figure 4, and Figure 5 respectively.

Listing 4

#!/usr/bin/env python
import PyQt4
import sys
from PyQt4 import QtGui
from PyQt4 import QtCore

class HelloWindow(QtGui.QMainWindow):

	def __init__(self, win_parent = None):
		#Init the base class
		QtGui.QMainWindow.__init__(self, win_parent)
		self.create_widgets()


	def create_widgets(self):
		#Widgets
		self.label = QtGui.QLabel("Say hello:")
		self.hello_edit = QtGui.QLineEdit()
		self.hello_button = QtGui.QPushButton("Push Me!")

		#connect signal
		QtCore.QObject.connect(self.hello_button
			, QtCore.SIGNAL("clicked()")
			, self.on_hello_clicked)


		#Horizontal layout
		h_box = QtGui.QHBoxLayout()
		h_box.addWidget(self.label)
		h_box.addWidget(self.hello_edit)
		h_box.addWidget(self.hello_button)
		#Create central widget, add layout and set
		central_widget = QtGui.QWidget()
		central_widget.setLayout(h_box)
		self.setCentralWidget(central_widget)

	def on_hello_clicked(self):
		QtGui.QMessageBox.information(self
			, "Hello!"
			, "Hello %s" % self.hello_edit.displayText()
			, QtGui.QMessageBox.Ok)

if __name__ == "__main__":
	# Someone is launching this directly
	# Create the QApplication
	app = QtGui.QApplication(sys.argv)
	#The Main window
	main_window = HelloWindow()
	main_window.show()
	# Enter the main loop
	app.exec_()

Figure 3

Figure 4

Figure 5

Conclusion

That’s it for this quick introduction to PyQt4. All-in-all, I was pleasantly surprised by PyQt4. Even during my first foray into the toolkit, I found it very straightforward and was able to get things going in a matter of minutes. Granted, what I was trying to accomplish was pretty simple, but it’s always a good sign when doing something simple is easy!

You should now have enough information to go and create your very own “GUIfied” applications. Of course, there is much, much more to PyQt4 than I have covered in this tutorial. But if you use the PyQt4 documentation and the fundamentals from this tutorial, you shouldn’t have much trouble moving forward.

[1] http://www.python.org/download/
[2] http://www.riverbankcomputing.co.uk/pyqt/download.php
[3] http://trolltech.com/downloads
[4] http://www.riverbankcomputing.com/Docs/PyQt4/pyqt4ref.html#installing-pyqt
[5] http://www.riverbankcomputing.com/Docs/PyQt4/html/qapplication.html
[6] http://www.riverbankcomputing.com/Docs/PyQt4/html/qapplication.html#exec
[7] http://www.riverbankcomputing.com/Docs/PyQt4/html/qmainwindow.html#details
[8] http://www.riverbankcomputing.com/Docs/PyQt4/html/qmainwindow.html#details