An Introduction to PyQt: creating GUIs with Python’s QT bindings


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

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

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 3

Figure 4

Figure 4

Figure 5

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

selsine

del.icio.us del.icio.us

23 Responses to “An Introduction to PyQt: creating GUIs with Python’s QT bindings”

  1. meushi
    Says:

    hi, nice introduction.
    however, even if i’m not used to pyQt, i’ve tried cpp/qt and python separatly.

    QtCore.QObject.connect(self.hello_button,QtCore.SIGNAL(“clicked()”),self.on_hello_clicked)

    does’t seem very object oriented. cppQt QObjects have a connect method to keep object oriented code. would it be possible to do the same with python ? something like self.hello_button.connect( QtCore.SIGNAL(“clicked()”),self.on_hello_clicked) ?

  2. Matt
    Says:

    One of my concerns as a package maintainer is the burden on the user to install supplemental packages. In particular, we struggle with this on OSX and Linux machines. Do you have a feel for how likely it is that on a given distribution of Linux — say, Fedora Core, or Ubuntu — that the user will have PyQt already installed? Furthermore, what about on Linux clusters designed for headless usage? Both of those types of machines we have had good luck with using wxPython, because it is dependent on GTK. Qt is another set of widgets on OSX, whereas wxWidgets just binds directly to the native environment.

    Is the problem of pre-existing Qt installations becoming better or worse with time?

  3. selsine

    selsine
    Says:

    Hi meushi,

    Thanks for the comment. I spelled it out in th example so that people could see where all of the functions were coming from. I also mention the following in the article right after introducing the signal code: “Note: We could just as easily have called self.connect since a QMainWindow is a descendant of the QObject class.”

    Using the code from the note would give you code similar to the following, which appears to be the standard when using PyQt4:

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

    The code you suggest however does not work as you will get the following error:

    TypeError: argument 1 of QObject.connect() has an invalid type
  4. selsine

    selsine
    Says:

    Hi Matt,

    You bring up a good point and a problem that I have had with GUI based Python projects in general.

    I’m honestly not sure about how large the general PyQt4 install base is. I don’t think that most Linux machines will have it installed by default but I could be wrong about that.

    I have a feeling that GTK and Gnome have been getting more and more popular over the last few years, and it seems to be almost the default for more new Linux applications. That being said Qt4 is a pretty big step forward and you may start to see more applications created using it.

    Short answer: I don’t think PQt4 will be on most machines by default.

    Long answer: That may change over time.

    But these are just my opinions, someone else more familiar with the project may have more information.

  5. axl456
    Says:

    thanks for the tutorial!!

  6. nabash
    Says:

    Hi,
    Nice tutorial! I find this site very useful, it helped me with my first steps with wxPython and as thinking to start with PyQt this entry is right in time.
    One comment (usability not python…) in the blog main page when there is a preview for the post the links are not working (the table of content anchors).
    Keep on with the good job.

  7. Cynyr
    Says:

    This is probably beyond the scope of this article, but say you wanted to pass a few options to self.on_hello_clicked. How would you do it? everything i have tried has not worked.

    Thanks
    Cynyr

  8. AACF
    Says:

    Whenever I have a doubt, I come here to read about your articles, and is a great pleasure to see yours skill’s increment. keep on with excelent work.

  9. Michal
    Says:

    Hi,

    regarding the “TypeError: argument 1 of QObject.connect() has an invalid type” above…

    The trick is you shouldn’t do:
    self.connect(self.hello_button, QtCore.SINGAL(…), self.on_hello_clicked)
    but instead
    self.hello_button.connect(QtCore.SINGAL(…), self.on_hello_clicked)

    I.e. don’t call self’s connect() but hello_button’s connect().

  10. brian N.
    Says:

    hey nice tutorial..Altough..where in the code does it say to put in: self.create_widgets()

    in the :

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

    i cant seem to find where its put in.

    PS.im a newbie to python trying to learn,so maybe its just me…;)

  11. Shraddha
    Says:

    Thanks a ton for this post!
    You saved so much of my time.

  12. gavranha
    Says:

    Thanks a lot for your time writing so useful tutorial. I’m just starting and the big trouble for a newbie is to be able to see the whole thing in the first steps. You do that. Thanks!

  13. frispete
    Says:

    The connect line shoud read:

    self.hello_button.clicked.connect(self.on_hello_clicked)

  14. shadyabhi
    Says:

    @frispete
    So, whats basically the differnece between what you said and what he did?

  15. Learning Python Qt Programming with PyQt & PySide | Query7
    Says:

    [...] An Introduction to PyQt by Mark Mruss of LearningPython is an excellent beginners introduction to PyQt. It assumes no prior knowledge of PyQt or GUI programming and walks you through creating a basic hello world window. [...]

  16. dave cortesi
    Says:

    I’ll ask this here — I’m part of the new wave of readers since the Query7 post was noted in reddit/r/python, and hopefully comments here are still being monitored.

    Regarding listing 2, it is not clear to me why you take pains to make the widgets label, hello_edit and hello_button, properties of the Hello_window (“self.label =…” etc) while just a few lines later, you do not make hbox and central_widget so. If I understand the scope rules (doubtful), they are effectively locals of define_widgets()? Presumably they continue to exist after define_widgets() exits, because there is a reference to hbox in central_widget and a reference to central_widget in self. But they can’t be named in later code.

    Is that why you make self.label etc properties, because there might be need to name it in some other code?

  17. Sandeep
    Says:

    Hi Mark,
    The links to the documentation for PyQt4 aren’t working. They’re still there, only the URL has changed (you have to add a /static somewhere in the URL).

    Also, it’s a really good tutorial! Thanks a lot for taking the time to make this simple introduction to PyQt4!

  18. Helen Neely
    Says:

    Hi, I just checked as well, looks like the link is dead on the PyQT4 site. Could check that you’re pointing to the right documentation?

  19. george
    Says:

    hi, many thanks for this tutorial. I want to have a few simple dialogs and then continue with processing in my script. Is it possible to exit the main loop and return the values i got from the gui?

  20. Programowanie w PHP » Blog Archive » Learning Python Qt Programming with PyQt & PySide
    Says:

    [...] An Introduction to PyQt by Mark Mruss of LearningPython is an excellent beginners introduction to PyQt. It assumes no prior knowledge of PyQt or GUI programming and walks you through creating a basic hello world window. [...]

  21. athira
    Says:

    Thank you very much.Nice introduction to qt.

  22. blogspot.Com
    Says:

    I absolutely love your blog and find nearly all of your post’s to be just what I’m looking for.
    Does one offer guest writers to write content for you personally?
    I wouldn’t mind creating a post or elaborating on a lot of the subjects you write in relation to here.
    Again, awesome blog!

  23. Tablet popust
    Says:

    Tablet popust

    learning python » Blog Archive » An Introduction to PyQt: creating GUIs with Python?s QT bindings

Leave a Reply

 

Popular Posts