PyQt5 Tutorial with Examples: Design GUI using PyQt in Python
What is PyQt?
PyQt is a python binding of the open-source widget-toolkit Qt, which also functions as a cross-platform application development framework. Qt is a popular C++ framework for writing GUI applications for all major desktop, mobile, and embedded platforms (supports Linux, Windows, MacOS, Android, iOS, Raspberry Pi, and more).
PyQt is a free software developed and maintained by Riverbank Computing, a company based in England, whereas Qt is developed by a Finnish firm called The Qt Company.
In this PyQt5 tutorial, you will learn:
- Features of PyQT
- PyQt Versions
- How to install PyQt5
- Basic PyQt Concepts and Programs
- Components and Widgets
Features of PyQT
Here are important features of PyQt:
Learn PyQt which consists of more than six hundred classes covering a range of features such as
- Graphical User Interfaces
- SQL Databases
- Web toolkits
- XML processing
These features can be combined to create advanced UIs as well as standalone applications. A lot of major companies across all industries use Qt. Some examples are LG, Mercedes, AMD, Panasonic, Harman, etc.
PyQt is available in two editions, PyQt4 and PyQt5. PyQt4 provides glue code for binding 4.x and 5.x versions of the Qt framework while PyQt5 provides a binding for only the 5.x versions. As a result, PyQt5 is not backward compatible with the deprecated modules of the older version. In this Qt GUI tutorial, PyQt5 will be used for the demonstration of examples. Apart from these two versions,
Riverbank Computing also provides PyQt3D—the python bindings for the Qt3D framework. Qt3D is an application framework used to create real-time simulation systems with 2D/3D rendering.
How to install PyQt5
In this PyQt5 tutorial, we will see the two ways of installing PyQt:
- Using Wheel files
- Building and Installing from Source
Qt (pronounced cute) is a complex system, and the PyQt codebase contains compiled C++ and Python code under the hood. As a result, it is a complicated process to build and install it from the source compared to other python libraries. However, you can easily install PyQt5 using wheels.
Installation with wheels
Wheels are the new standard Python packaging and distribution format. Simply speaking, a wheel is a ZIP archive with a special name and .whl file extension. Wheels can be installed using pip (Python’s package manager), which is included by default in the recent versions of Python.
So, if you have Python 3.4 or later installed, you already have pip. If, however, you are using an older version of Python, you must download and install pip before going forward. You can search for instructions for that at this link: https://pypi.org/project/pip/.
To install PyQt5,
Step 1) Open Command prompt.
Open the Command Prompt or PowerShell in your Windows machine.
Step 2) Type in the following.
pip install PyQt5
Step 3) Installation successful.
This step in this PyQt5 tutorial will download the PyQt5 whl package (about 50 MB) and install it on your system.
Alternatively, you can also download a Windows binary for the version of python installed on your computer.
Once it is complete, proceed to the next section in this PyQt5 tutorial to write your first GUI app.
Basic PyQt Concepts and Programs
Now that you have successfully installed PyQt5 in your computer, you are ready to write Python GUI design applications.
Let’s start with a simple app in this PyQt5 tutorial which will display an empty window on your screen.
Fire up your python IDLE and type in the following:
import sys from PyQt5.QtWidgets import QApplication, QWidget if __name__ == "__main__": app = QApplication(sys.argv) w = QWidget() w.resize(300,300) w.setWindowTitle("Guru99") w.show() sys.exit(app.exec_())
Save it as app.py (the name does not matter) and hit F5 to run the program. Alternatively, just double click your saved file to launch the application. If you have done everything right, a new window will open up with the title Guru99 as shown below.
Great! It’s working. It is not much, but it’s enough to grasp the basics. Now in this PyQt tutorial, let’s see in detail what each of the lines in your program does.
from PyQt5.QtWidgets import QApplication, QWidget
This statement imports all the modules you need to create a GUI into the current namespace. The QtWidgets module contains all the major widgets that you will be using in this Python Qt tutorial.
app = QApplication(sys.argv)
Here, you are creating an object of the QApplication class. This step is a necessity for PyQt5; every UI app must create an instance of QApplication, as a sort of entry point into the app. If you do not create it, errors will be shown.
sys.argv is the list of command-line parameters that you can pass to the application when launching it through the shell or while automating the interface.
In this PyQt5 example, you did not pass any arguments to QApplications. Therefore, you can also replace it with the code below and not even have to import the sys module.
app = QApplication()
w = QWidget()
Next, we make an object of the QWidget class. QWidget is the base class of all UI objects in Qt, and virtually everything you see in an app is a widget. That includes dialogs, texts, buttons, bars, and so on. The feature that allows you to design complex user interfaces is that the widgets can be nested, i.e., you can have a widget inside a widget, which is inside yet another widget. You will see this in action in the next section.
The resize method of the QWidget class allows you to set the dimensions of any widget. In this case, you have resized the window to 300px by 300px.
Here, you should remember that widgets could be nested together, the outermost widget (i.e., the widget with no parent) is called a Window.
The setWindowTitle() method allows you to pass a string as an argument which will set the title of the window to the string you pass. In the PyQt5 example, the title bar will display Guru99.
show() simply displays the widget on the monitor screen.
The app.exec_() method starts the Qt/C++ event loop. As you know, PyQt is largely written in C++ and uses the event loop mechanism to implement parallel execution. app.exec_() passes the control over to Qt which will exit the application only when the user closes it from the GUI. That is why ctrl+c will not exit the application as in other python programs. Since Qt has control over the app, python events are not processed unless we set them up inside the application. Also, note that the exec method has an underscore in its name; this is because exec() was already a keyword in python and the underscore resolves naming conflict.
Beyond empty windows
In the previous section, you saw how to make a basic widget in Qt. It’s now time to make some more involved interfaces with which the users can truly interact. Again, fire up your IDLE and write the following.
import sys from PyQt5.QtWidgets import QApplication, QWidget, QLabel, QPushButton, QMessageBox def dialog(): mbox = QMessageBox() mbox.setText("Your allegiance has been noted") mbox.setDetailedText("You are now a disciple and subject of the all-knowing Guru") mbox.setStandardButtons(QMessageBox.Ok | QMessageBox.Cancel) mbox.exec_() if __name__ == "__main__": app = QApplication(sys.argv) w = QWidget() w.resize(300,300) w.setWindowTitle("Guru99") label = QLabel(w) label.setText("Behold the Guru, Guru99") label.move(100,130) label.show() btn = QPushButton(w) btn.setText('Beheld') btn.move(110,150) btn.show() btn.clicked.connect(dialog) w.show() sys.exit(app.exec_())
Save the file as appone.py or anything you like and press F5 to run the program. If you haven’t made any mistakes, the IDLE will open a new window with some text and a button as shown below.
- Once you click on the button in the first window, a new message box will pop open with the text that you had written.
- You can now click on the Hide Details/Show Details button to toggle the visibility of additional text.
As you can see, since we had not set any window title in the message box, a default title was provided by python itself.
Now that it’s working let’s take a look at the extra code that you have added to the previous PyQt5 example.
from PyQt5.QtWidgets import QApplication, QWidget, QLabel, QPushButton, QMessageBox
This imports some more widgets that you have used in PyQt5 examples, namely QLabel, QPushButton, and QMessageBox.
def dialog(): mbox = QMessageBox() mbox.setText("Your allegiance has been noted") mbox.setDetailedText("You are now a disciple and subject of the all-knowing Guru") mbox.setStandardButtons(QMessageBox.Ok | QMessageBox.Cancel) mbox.exec_()
Here, you have defined a method named dialog which creates a message box widget and sets some text to the buttons and other fields.
The dialog method is called from the main block of the program when a button is pressed in a specific widget (in this case, the btn PushButton). The click event triggered on that button causes this function to execute. Such a function is called a slot in Qt, and you will learn more about signals and slots in the upcoming paragraphs.
if __name__ == "__main__": app = QApplication(sys.argv) w = QWidget() w.resize(300,300) w.setWindowTitle("Guru99")
This is the main section of the app and as in the previous example, you start by creating an instance of QApplication followed by a simple widget, i.e. an instance of QWidget.
label = QLabel(w) btn = QPushButton(w)
You have added two new widgets in this application: QLabel and QPushButton. QLabel is used to print non-editable text or placeholders inside a widget, whereas QPushButton is used to create a clickable button.
The critical thing to notice here is that when you create the label and btn objects, you are passing the window object (w) to the constructors of QLabel and QPushButton. This is how nesting works in PyQt5. To create a widget inside another widget, you pass the reference of the parent widget to the child’s constructor.
move() is used to set the position of a widget with respect to its parent widget. In the first case, the label will be moved 100px from the left and 130px from the top of the window.
Similarly, the button will be placed 110px from the left and 150px from the top of the window. This example is a crude way of achieving layouts and is generally not used in production; it is only included here for learning purposes. Qt supports different layouts that you will see in detail in the upcoming sections of this PyQt tutorial.
Finally, this is an example of signals and slots in Qt. In GUI based applications, functions are executed based on the actions performed by the user, like hovering over an element or clicking a button. These actions are called events. Recall that the app.exec_() method transfers control to the Qt event-loop. This is what the event loop is there for: to listen for events and perform actions in response.
Whenever an event occurs, like a user clicking a button, the corresponding Qt widget raises a signal. These signals can be connected to python functions (like the dialog function in this example) so that the function is executed when a signal is triggered. These functions are called slots in Qt lingo.
Subsequently, the basic syntax to trigger a slot function in response to the signal from an event is as follows
Which means that whenever a signal is triggered by a widget, the connected slot function will be executed. In summary, signals and slots are used by Qt to communicate between objects and facilitate component reusability and interactivity.
Now that you know how to nest widgets and implement interactions using signals and slots, here is a list of useful widgets and other classes that you can use in your PyQt apps.
Components and Widgets
There is a large number of widgets available in PyQt for creating GUI apps. However, with PyQt5, there has been a reshuffling of classes into different modules and revisions in the licenses.
Therefore, it’s crucial to have a high-level view of the structure of PyQt5. In this section, you will see how PyQt5 is organized internally and learn about the different modules, libraries, and API classes provided by PyQt5.
PyQt5 Directory Structure
These are the fundamental modules used by Python’s Qt binding, specifically PyQt5.
- Qt: It combines all the classes/modules mentioned below into a single module. It considerably increases the memory used by the application. However, it’s easier to manage the framework by only importing one module.
- QtCore: Contains the core non-graphical classes used by other modules. This is where the Qt event loop, signals, and slot-connectivity, etc. are implemented.
- QtWidgets: Contains most of the widgets available in Pyqt5.
- QtGui: Contains GUI components and extends the QtCore module.
- QtNetwork: Contains classes used to implement network programming through Qt. It supports TCP servers, TCP sockets, UDP sockets, SSL handling, network sessions, and DNS lookups.
- QtMultimedia provides low-level multimedia functionality.
- QtSql: implements database integration for SQL databases. Supports ODBC, MySQL, Oracle, SQLite, and PostgreSQL.
Here is a list of the most frequently used widgets in PyQt5
- QLineEdit: This is an input field which allows one line of text to be entered by the user.
line = QLineEdit()
- QRadioButton: This is an input field with a selectable button, similar to the radio buttons in html.
rad = QRadioButton("button title") rad.setChecked(True) #to select the button by default.
- QComboBox: It is used to display a dropdown menu with a list of selectable items.
drop = QComboBox(w) drop.addItems(["item one", "item two", "item three"])
- QCheckBox: Displays a selectable square box in front of the label that is ticked if selected, similar to radio buttons.
check = QCheckBox("button title")
- QMenuBar: it displays a horizontal menu bar at the top of a window. You can only add objects of the QMenu class to this bar. Those QMenu objects can further contain strings, QAction objects or other QMenu objects.
- QToolBar: It is a horizontal bar or pane which can be moved within the window. It may contain buttons and other widgets.
- QTab: it is used to break down the contents of a window into multiple pages that can be accessed through different tabs on top of the widget. It consists of two sections: the tab bar and the tab page.
- QScrollBar: It is used to create scroll bars which allow the user to scroll up and down within a window. It consists of a movable slider, a slider track, and two buttons to scroll the slider up or down.
scroll = QScrollBar()
- QSplitter: Splitters are used to separate the contents of a window so that the widgets are grouped properly and do not appear cluttered. QSplitter is one of the primary layout handlers available in PyQt5 and is used to split the content both horizontally and vertically.
- QDock: A dock widget is a sub-window with two properties:
- It can be moved within the main window and
- It can be docked outside the parent window to another location on the screen.
Layouts and Themes
In the previous PyQt5 examples, you have only been using the move() and resize() methods to set the positions of widgets in your GUI.
However, PyQt has a robust layout management engine which can be used to create advanced user interfaces for applications. In this section, you will learn about two important classes that are used in Qt to create and manage layouts.
QBoxLayout is used to align the child widgets of the layout in a horizontal or vertical row. The two classes of interest that inherit from QBoxLayout are:
- QHBoxLayout: used to line the child widgets horizontally.
- QVBoxLayout: used to line the child widgets vertically.
For example, this is how three buttons aligned with QHBoxLayout will look.
import sys from PyQt5.QtWidgets import * if __name__ == "__main__": app = QApplication() w = QWidget() w.setWindowTitle("Musketeers") btn1 = QPushButton("Athos") btn2 = QPushButton("Porthos") btn3 = QPushButton("Aramis") hbox = QHBoxLayout(w) hbox.addWidget(btn1) hbox.addWidget(btn2) hbox.addWidget(btn3) w.show() sys.exit(app.exec_())
And this is how they will look in QVBoxLayout.
import sys from PyQt5.QtWidgets import * if __name__ == "__main__": app = QApplication() w = QWidget() w.setWindowTitle("Musketeers") btn1 = QPushButton("Athos") btn2 = QPushButton("Porthos") btn3 = QPushButton("Aramis") vb = QVBoxLayout(w) vb.addWidget(btn1) vb.addWidget(btn2) vb.addWidget(btn3) w.show() sys.exit(app.exec_())
The only function that needs any explanation at this point is the addWidget() method. It is used to insert widgets into the HBox or VBox layout. It is also used in other layouts where it takes a different number of parameters as you will see in the next section. The widgets will appear inside the layout in the order in which you insert them.
QGridLayout is used to create interfaces in which the widgets are laid out in the form of a grid (like a matrix or 2D array). To insert elements in a grid layout, you can use the matrix representation to define the number of rows and columns in the grid as well as the position of those elements.
For example, to create a 3*3 grid (i.e., a grid with three rows and three columns), you will write the following code:
Import sys from PyQt5.QtWidgets import * if __name__ == "__main__": app = QApplication() w = QWidget() grid = QGridLayout(w) for i in range(3): for j in range(3): grid.addWidget(QPushButton("Button"),i,j) w.show() sys.exit(app.exec_())
This will be the output:
The addWidget() method In the grid layout takes these arguments:
- The widget object that you want to add to the grid
- The x-coordinate of the object
- The y-coordinate of the object
- The row-span (default =0)
- The col-span (default=0)
To understand it better, you can manually insert each widget as shown below
import sys from PyQt5.QtWidgets import * if __name__ == "__main__": app = QApplication() w = QWidget() grid = QGridLayout(w) grid.addWidget(QPushButton("Button one"),0,0) grid.addWidget(QPushButton("Button two"),0,1) grid.addWidget(QPushButton("Button three"),1,0) grid.addWidget(QPushButton("Button four"),1,1) w.show() sys.exit(app.exec_())
This is what the grid will look like:
You can also pass the rowspan and colspan parameters to addWidget() in order to span more than one row or column.
This will create a button that stretches over both columns.
PyQt5 comes with some built-in themes that you can use in your apps. The setStyle() method called on the QApplication instance is used to set a particular theme to your application.
For example, adding the following line of code will change the theme of your application from default to Fusion
This is how the previous example will look in Fusion Theme
Another useful function for theming your apps is the setPalette() method. Here’s the code for changing the colour of different widgets using setPalette().
import sys from PyQt5.QtCore import Qt from PyQt5.QtWidgets import * from PyQt5.QtGui import QPalette if __name__ == "__main__": app = QApplication() app.setStyle("Fusion") qp = QPalette() qp.setColor(QPalette.ButtonText, Qt.black) qp.setColor(QPalette.Window, Qt.black) qp.setColor(QPalette.Button, Qt.gray) app.setPalette(qp) w = QWidget() grid = QGridLayout(w) grid.addWidget(QPushButton("Button one"),0,0) grid.addWidget(QPushButton("Button two"),0,1) grid.addWidget(QPushButton("Button three"),1,0) grid.addWidget(QPushButton("Button four"),1,1) w.show() sys.exit(app.exec_())
Here’s the result.
To use the setPalette() method, you first need to define a palette. This is done by creating an object of the QPalette class.
qp = QPalette()
Notice that the QPalette class belongs to the QtGui module and you will need to import it for this to work. Once you’ve created the QPalette object, use the setColor() method to pass the name of a widget whose colour you want to change and the colour you want to be set.
This will change the colour of the window to black. After you have defined your color-scheme, use the setPalette() function to apply the palette to your application.
That is all you need to do if you want to create some basic themes for your app. PyQt also allows you to use stylesheets to define the look of your widgets. If you are familiar with CSS, you can easily define advanced styles for your app using Qt Style Sheets.
- PyQt is the python binding for the C++ UI framework, Qt.
- PyQt4 and PyQt5 are the two major versions developed by Riverbank Computing.
- The main modules of the PyQt framework are:
- Text labels
- Text fields
- Radio buttons and Checkboxes
- Toolbars and Menu bars
- Box Layout
- Grid Layout