How to build your first Desktop Application in Python
Search the entire internet for uses of the Python programming language and they list them with Desktop Applications marked as not very suited with python. But years ago in 2016 when I was hoping to move on from web development to software development, Google.com told me I should choose python because it is used to build some modern and advanced scientific applications, then they mentioned blender3d. I knew blender3d, it is an awesome 3d creation software. love
But its not their fault, the ugly things people are using as showcases for python GUIs are detestable, too old, and too expired looking windows, no young person would like that. I hope to change that notion with this simple desktop app tutorial. Lets get going.
We will be using PyQt (more on that soon) instead of Tkinter which was almost removed from the list of python standard libraries for being outdated.
What is PyQt (pronounced: pie-cute). It is one of the two ports of a framework, Qt (pronounced: cute) from C++, . That framework is known as the necessary framework for C++ developers. It is the framework behind blender3d, Tableau, Telegram, Anaconda Navigator, IPython, Jupyter Notebook, VirtualBox, VLC etc. We will use it instead of the embarrassing Tkinter.
The two ports of Qt are PySide and PyQt. They are both 99% alike. PyQt is the easiest of the two to install.
Prerequisites
- You should already know some python basics
- You should know how to install packages or libraries with pip
- You should already have python installed, of course.
Installation
The only thing we will need to install is PyQt. So open up your terminal, on windows it will be the Command Prompt or Powershell.
Type the command below into your terminal
PyQt6 because we are downloading the version 6 of PyQt. Wait for the installation to complete it will only take like a minute or two.
Project Files and Folders
Now that we are done with the installation. We should start with our project. Create a project folder for the app, we going to call it: helloApp. Create it anywhere you want on your computer, but its good to be organised.
Lets do a “Hello World”
Open up the main.py, preferably in vscode and enter the following code
In the code above; we import sys, os, QGuiApplication and QQmlApplication modules.
The QQuickWindow.setSceneGraphBackend('software') should be included in your code as a fallback option for uses with old hardware specs, other than that they would see an error information as seen below:
Also the code calls QGuiApplication and QQmlApplicationEngine Which will use Qml instead of QtWidgets as the UI layer for the Qt Application. It then connects the UI layers quit function with the app’s main quit function. So both can close when the UI has been closed by the user. Next it loads the qml file as the qml code for the Qml UI. The app.exec() is what runs the Application, it is inside the sys.exit because it returns the exit code of the Application which gets passed into the sys.exit which exits the python sytem.
Add this code to the main.qml
The above code creates a Window, the visible code is very important, without that the UI is going to run but will be invisible,with width and height as specified, with a title of “HelloApp”. And a Text that is centered in the parent(which happens to be the window), the text displayed is “Hello World”, a pixel size of 24px.
In the previous Qt5, the import codes above would have included version numbers as
Also, in Qt6 we explicitly declare a style for the Controls as
more about Controls styles later
If you have the above, you can run it and see your result.
Navigate into your helloApp folder
Now run it by doing:
If your code runs, you should see:
Update UI
Now lets update a UI a little bit, lets add an image as a background and a text that will have a time
The above has an ApplicationWindow type, a Rectangle type inside it, that is actually filling up all the space of the window. There is an Image inside of it, and a another Rectangle that looks like its beside it, but because of the non-existence of a Layout type, its actually on top of the Image type. The Rectangle has a color of transparent since by default Rectangles are white, there is a Text inside of it that reads 16:38:33, to mock up time.
If you run the app the text will appear at the top-left corner of the Window. We do not like that, and so we are going to make it appear at the bottom-left corner with some margins instead.
In your qml code, update the Text type to include anchors as shown below:
Now run it by doing
You should see something similar to this.
Now I would like the time to update
Use real time
Lets use a real time. Python provides us with native functions that give us all kinds of time and date related functions. We want a string with the current time. gmtime provides you with global time struct with all kinds of information and strftime constructs certains portions of the time as a string using the gmtime function
import the strftime, and gmtime functions
Then construct your time string below the imports, anywhere in the file
The %H, %M, %S, tells strftime, that we want to see Hours(24-hour type), minutes, and seconds. (Read more about format codes for strftime here). This variable will be passed on to the qml layer.
Lets create a property in qml that we can use to receive time string. This variable makes it easier to change the time. Lets call this property currTime
Use this property in the qml, so when this value changes all the other places where it has been used also will change.
Now send our curr_time variable we created in python to qml by setting it to the currTime qml property.
The above code will set the qml property currTime to the value of the curr_time python property. This is one way we pass information from python to the UI layer.
Run the app and you should see no errors and will also have the current time. Hooray. Onward.
Update the time
To keep our time updated. We will need to use threads. Threading in python is easy and straightforward, we will use that instead of Qt’s threading. Thread uses functions or thread calls a function. I prefer we use a technique in Qt known as signals, this is a professional method, and studying it know will make your like better and easier. Lets put our current time code into a function, use underscore(_) for the file name. I will explain why later. It is not a requirement or anything, it is just good practice
To use signals we would have to subclass QObject, straightforward.
Create a subclass of QObject, call it whatever you like. I will call it Backend.
The above code imports QObject and pyqtSignal, in pyside this is called Signal. It is one of the few differences between pyqt and pyside.
Formally, we had a property string that received our curr_time string from python, now we create a property QtObject to receive the Backend object from python. There are not that many types. Qml converts python base types into bool, int, double, string, list, QtObject and var. var can handle every python type, but its the least loved.
The above code creates a QtObject backend to hold our python object back_end. The names used are mine, feel free to change them to whatever you like
In the python pass it on
In the above code an object back_end was created from the class Backend. We then set it to the qml property named backend
In Qml, one QtObject can receive numerous functions (called signals) from python that does numerous things, but they would have to be organised under that QtObject.
Create Connections type and target it to backend. Now inside the Connections type can be functions as numerous as we want to receive for the backend.
Now thats’ how we connect with the python signals.
If we do not use threading our UI will freeze. Its quite emphatic to state that what we need here is threading and not multiprocessing.
Create two functions, one for the threading one for the actually function. Here is where the underscore comes in handy.
The above code has an underscore function that does the work creating an updated time.
Create a pyqtsignal called updated and call it from a function called updater
In the above code the pyqtSignal, updated, has as it arguments parameter the list containing the name of the function ‘updater’. From this updater function, qml shall receive data. In the updater function we call(emit) the signal updated and pass data (curr_time) to it
Update the qml, receive the signal by creating a signal handler, a signal handlers name is the capitalised form of the signal name preceded by ‘on’. So, ‘mySignal’ becomes ‘onMySignal’ and ‘mysignal’ becomes ‘onMysignal’.
In the above code you can see the signal handler for updated signal is called onUpdated. It is also has the curr_time passed to it as msg.
All is well but we are yet to call the updater function. Having a seperate function to call the signal is not necessary for a small application as this. But in a big application, it is the recommended way to do it. Change the delay seconds to 1/10 of a second. I have found this figure to the best to update time.
The bootUp function should be called immediately after the UI has loaded.
All is done.
Bonus:
Make the Window Frameless
You can make the window frameless and stick it to the bottom right of the Screen.
The above code sets x, y for the window and add flags, to make the window frameless. The Qt.Window flag ensures that even though the window is frameless, we still get a Taskbutton
Run it, and you should be glad with what you see.
At long last, the coding has ended and here are the final codes.
Apart from the names that you may have changed, everything should be similar.
Build and next steps
Building a pyqt application could be the easiest, since it is widely known.
To build, install pyinstaller, since building is a part of the bonus section, we didn’t install it before.
We could have easily done run the following code in the applications folder (helloApp) but, we have to take care of the resources that we used.
Instead, first do:
It generates a spec file for you to update first, then you can run pyinstaller again
The datas parameter can be used to include data files in your App or App’s folder. Its a list of tuples, and the tuple always has two items, the target path, we will be including, and the destination path, where it should be stored in the Application’s folder. The destination path must be relative. If you want it placed right there with the app’s executables, you make it an empty string (‘’), if you want it to be in a nested folder within the application’s folder, you specify the nested folder (‘nest/nested/really_nested’)
Update the datas parameter like you see below to match the path to your helloApp’s UI folder on your computer.
Set the console parameter to False, since this is a Gui and we are not testing it.
The name parameter in the EXE call is the name of the executable itself. eg. main.exe, or main.dmg but the name parameter in the COLLECT call is for the folder name in which the executable and all its accompanying files will be stored, both can be changed. But the names were based on the file we used to generate the spec, remember: ‘main.py’
Finally, build your application using
Now you should see a folder named ‘dist’ with another folder within it named ‘main’ with the application files. Search for the main.exe, or main executable and run it. TADAAA! And all is well.
Next Steps
Apart from the way that the UI folder was included and used in the application, all of the things we’ve talked about are used in production. Resources are bundle before being deployed in production.
But the Signals, how the background image was used, to the frameless window are all techniques used in production and so to speak, in real-world. Its just that there is more to it. Yes there is more to frameless Windows, you have to handle the titlebar, the resizing and dragging of the window among other things if you are not going to use it as a splash screen, not that complex, but it goes beyond the scope of this tutorial.
Qml is a lot more than Images, Rectangles and Text, and the Layout system are four types. They are easy to study, but practical approach is the best, so I have not bothered to explain them.
Continue with PyQt and Qml, it will lead into a career in software development, embedded systems, and in the future Data visualization. Prefer it over TKinter, its popularity keeps increasing by the day.
Собираем проект на python3&PyQT5 под Windows, используя PyInstaller
Причиной написания статьи, явилось огромное количество постоянно возникающих у новичков вопросов такого содержания: "Как собрать проект c pyqt5", "Почему не работает", "Какой инструмент выбрать" и т.д. Сегодня научимся собирать проекты без мучений и танцев с бубном.
Как-то пришлось написать небольшое desktop-приложение. В качестве языка программирования для разработки был выбран python, поскольку для решения моей задачи он подходил идеально. В стандартную библиотеку Python уже входит библиотека tkinter, позволяющая создавать GUI. Но проблема tkinter в том, что данной библиотеке посвящено мало внимания, и найти в интернете курс, книгу или FAQ по ней довольно-таки сложно. Поэтому было решено использовать более мощную, современную и функциональную библиотеку Qt, которая имеет привязки к языку программирования python в виде библиотеки PyQT5. Более подробно про PyQT можете почитать здесь. В качестве примера я буду использовать код:
Если вы более-менее опытный разработчик, то понимаете, что без интерпретатора код на python не запустить. А хотелось бы дать возможность каждому пользователю использовать программу. Вот здесь к нам на помощь и приходят специальные библиотеки позволяющие собирать проекты в .exe, которые можно потом без проблем запустить, как обычное приложение.
Существует большое количество библиотек, позволяющих это сделать, среди которых самые популярные: cx_Freeze, py2exe, nuitka, PyInstaller и др. Про каждую написано довольно много. Но надо сказать, что многие из этих решений позволяют запускать код только на компьютере, с предустановленным интерпретатором и pyqt5. Не думаю, что пользователь будет заморачиваться и ставить себе дополнительные пакеты и программы. Надеюсь, вы понимаете, что запуск программы на dev-среде и у пользователя это не одно и тоже. Также нужно отметить, что у каждого решения были свои проблемы: один не запускался, другой собирал то, что не смог потом запустить, третий вообще отказывался что-либо делать.
После долгих танцев с бубном и активным гуглением, мне все же удалось собрать проект с помощью pyinstaller, в полностью работоспособное приложение.
Немного о Pyinstaller
Pyinstaller собирает python-приложение и все зависимости в один пакет. Пользователь может запускать приложение без установки интерпретатора python или каких-либо модулей. Pyinstaller поддерживает python 2.7 и python 3.3+ и такие библиотеки как: numpy, PyQt, Django, wxPython и другие.
Pyinstaller тестировался на Windows, Mac OS X и Linux. Как бы там ни было, это не кросс-платформенный компилятор: чтобы сделать приложение под Windows, делай это на Windows; Чтобы сделать приложение под Linux, делай это на Linux и т.д.
PyInstaller успешно используется с AIX, Solaris и FreeBSD, но тестирование не проводилось.
Подробнее о PyInstaller можно почитать здесь: документация.
К тому же после сборки приложение весило всего около 15 мб. Это к слову и является преимуществом pyinstaller, поскольку он не собирает все подряд, а только необходимое. Аналогичные же библиотеки выдавали результат за 200-300 мб.
Приступаем к сборке
Прежде чем приступить к сборке мы должны установить необходимые библиотеки, а именно pywin32 и собственно pyinstaller:
Чтобы убедится, что все нормально установилось, вводим команду:
должна высветиться версия pyinstaller. Если все правильно установилось, идем дальше.
В папке с проектом запускаем cmd и набираем:
Собственно это и есть простейшая команда, которая соберет наш проект.
Синтаксис команды pyinstaller таков:
pyinstaller [options] script [script . ] | specfile
Наиболее часто используемые опции:
—onefile — сборка в один файл, т.е. файлы .dll не пишутся.
—windowed -при запуске приложения, будет появляться консоль.
—noconsole — при запуске приложения, консоль появляться не будет.
—icon=app.ico — добавляем иконку в окно.
—paths — возможность вручную прописать путь к необходимым файлам, если pyinstaller
не может их найти(например: —paths D:\python35\Lib\site-packages\PyQt5\Qt\bin)
PyInstaller анализирует файл myscript.py и делает следующее:
- Пишет файл myscript.spec в той же папке, где находится скрипт.
- Создает папку build в той же папке, где находится скрипт.
- Записывает некоторые логи и рабочие файлы в папку build.
- Создает папку dist в той же папке, где находится скрипт.
- Пишет исполняемый файл в папку dist.
В итоге наша команда будет выглядеть так:
После работы программы вы найдете две папки: dist и build. Собственно в папке dist и находится наше приложение. Впоследствии папку build можно спокойно удалить, она не влияет на работоспособность приложения.
Python and PyQt: Building a GUI Desktop Calculator
Even though web and mobile applications appear to have taken over the software development market, there’s still demand for traditional graphical user interface (GUI) desktop applications. If you’re interested in building these kinds of applications in Python, then you’ll find a wide variety of libraries to choose from. They include Tkinter, wxPython, PyQt, PySide, and a few others.
In this tutorial, you’ll learn the basics of building GUI desktop applications with Python and PyQt.
In this tutorial, you’ll learn how to:
- Create graphical user interfaces with Python and PyQt
- Connect the user’s events on the app’s GUI with the app’s logic
- Organize a PyQt app using a proper project layout
- Create a fully functional GUI application with PyQt
For this tutorial, you’ll create a calculator app with Python and PyQt. This short project will help you grasp the fundamentals and get you up and running with this GUI library.
You can download the source code for the project and all examples in this tutorial by clicking on the link below:
Download Code: Click here to download the code that you’ll use to build a calculator in Python with PyQt in this tutorial.
Getting to Know PyQt
PyQt is a Python binding for Qt, which is a set of C++ libraries and development tools providing platform-independent abstractions for graphical user interfaces (GUIs). Qt also provides tools for networking, threads, regular expressions, SQL databases, SVG, OpenGL, XML, and many other powerful features.
Developed by RiverBank Computing Ltd, PyQt’s latest editions are:
-
: An edition that’s built against Qt 5.x only : An edition that’s built against Qt 6.x only
In this tutorial, you’ll use PyQt6, as this version is the future of the library. From now on, be sure to consider any mention of PyQt as a reference to PyQt6.
Note: If you want to dive deeper into the differences between these two versions of the library, then check out the PyQt6 documentation on the topic.
PyQt6 is based on Qt v6. Therefore, it provides classes and tools for GUI creation, XML handling, network communication, regular expressions, threads, SQL databases, web browsing, and other technologies available in Qt. PyQt6 implements binding for many Qt classes in a set of Python modules, which are organized in a top-level Python package called PyQt6 . For PyQt6 to work, you need Python 3.6.1 or later.
PyQt6 is compatible with Windows, Unix, Linux, macOS, iOS, and Android. This is an attractive feature if you’re looking for a GUI framework to develop multiplatform applications that have a native look and feel on each platform.
PyQt6 is available under two licenses:
Your PyQt6 license must be compatible with your Qt license. If you use the GPL license, then your code must also use a GPL-compatible license. If you want to use PyQt6 to create commercial applications, then you need a commercial license for your installation.
Note: The Qt Company has developed and currently maintains its own Python binding for the Qt library. The Python library is called Qt for Python and is the official Qt for Python. Its Python package is called PySide.
PyQt and PySide are both built on top of Qt. Their APIs are quite similar because they reflect the Qt API. That’s why porting PyQt code to PySide can be as simple as updating some imports. If you learn one of them, then you’ll be able to work with the other with minimal effort. If you want to dive deeper into the differences between these two libraries, then you can check out PyQt6 vs PySide6.
If you need more information about PyQt6 licensing, then check out the license FAQs page on the project’s official documentation.
Installing PyQt
You have several options for installing PyQt on your system or development environment. The recommended option is to use to use binary wheels. Wheels are the standard way to install Python packages from the Python package index, PyPI.
In any case, you need to consider that wheels for PyQt6 are only available for Python 3.6.1 and later. There are wheels for Linux, macOS, and Windows (64-bit).
All of these wheels include copies of the corresponding Qt libraries, so you won’t need to install them separately.
Another installation option is to build PyQt from source. This can be a bit complicated, so you might want to avoid it if possible. If you really need to build from source, then check out what the library’s documentation recommends in those cases.
Alternatively, you have the option of using package managers, such as APT on Linux or Homebrew on macOS, to install PyQt6. In the next few sections, you’ll go through some of the options for installing PyQt6 from different sources and on different platforms.
Virtual Environment Installation With pip
Most of the time, you should create a Python virtual environment to install PyQt6 in an isolated way. To create a virtual environment and install PyQt6 in it, run the following on your command line:
- Windows
- Linux + macOS
Here, you first create a virtual environment using the venv module from the standard library. Then you activate it, and finally you install PyQt6 in it using pip . Note that you must have Python 3.6.1 or later for the install command to work correctly.
System-Wide Installation With pip
You’ll rarely need to install PyQt directly on your system Python environment. If you ever need to do this kind of installation, then run the following command on your command line or in your terminal window without activating any virtual environment:
With this command, you’ll install PyQt6 in your system Python environment directly. You can start using the library immediately after the installation finishes. Depending on your operating system, you may need root or administrator privileges for this installation to work.
Even though this is a fast way to install PyQt6 and start using it right away, it’s not the recommended approach. The recommended approach is to use a Python virtual environment, as you learned in the previous section.
Platform-Specific Installation
Several Linux distributions include binary packages for PyQt6 in their repositories. If this your case, then you can install the library using the distribution’s package manager. On Ubuntu, for example, you can use the following command:
With this command, you’ll install PyQt6 and all of its dependencies in your base system, so you can use the library in any of your GUI projects. Note that root privileges are needed, which you invoke here with the sudo command.
If you’re a macOS user, then you can install PyQt6 using the Homebrew package manager. To do this, open a terminal and run the following command:
After running this command, you’ll have PyQt6 installed on your Homebrew Python environment, and it’ll be ready for you to use.
If you use a package manager on Linux or macOS, then there’s a chance you won’t get the latest version of PyQt6. A pip installation will be better if you want to ensure that you have the latest release.
Creating Your First PyQt Application
Now that you have a working PyQt installation, you’re ready to create your first GUI app. You’ll create a Hello, World! application with Python and PyQt. Here are the steps that you’ll follow:
- Import QApplication and all the required widgets from PyQt6.QtWidgets .
- Create an instance of QApplication .
- Create your application’s GUI.
- Show your application’s GUI.
- Run your application’s event loop, or main loop.
You can download the source code for the examples that you’ll code in this section by clicking the link below:
Download Code: Click here to download the code that you’ll use to build a calculator in Python with PyQt in this tutorial.
To kick things off, start by creating a new file called hello.py in your current working directory:
First, you import sys , which will allow you to handle the application’s termination and exit status through the exit() function. Then you import QApplication , QLabel , and QWidget from QtWidgets , which is part of the PyQt6 package. With these imports, you’re done with step one.
To complete step two, you just need to create an instance of QApplication . Do this as you would create an instance of any Python class:
In this line of code, you create the instance of QApplication . You should create your app instance before you create any GUI object in PyQt.
Internally, the QApplication class deals with command-line arguments. That’s why you need to pass in a list of command-line arguments to the class constructor. In this example, you use an empty list because your app won’t be handling any command-line arguments.
Note: You’ll often find that developers pass sys.argv to the constructor of QApplication . This object contains the list of command-line arguments passed into a Python script. If your application needs to accept command-line arguments, then you should use sys.argv to handle them. Otherwise, you can just use an empty list, like you did in the above example.
Step three involves creating the application’s GUI. In this example, your GUI will be based on the QWidget class, which is the base class of all user interface objects in PyQt.
Here’s how you can create the app’s GUI:
In this code, window is an instance of QWidget , which provides all the features that you’ll need to create the application’s window, or form. As its names suggests, .setWindowTitle() sets the window’s title in your application. In this example, the app’s window will show PyQt App as its title.
Note: More precisely, this step requires you to create the app’s top-level or main window. The term application’s GUI is a bit generic. Typically, an application’s GUI consists of more than one window.
You can use .setGeometry() to define the window’s size and screen position. The first two arguments are the x and y screen coordinates where the window will be placed. The third and fourth arguments are the window’s width and height .
Every GUI application needs widgets, or graphical components that make the app’s GUI. In this example, you use a QLabel widget, helloMsg , to show the message Hello, World! on your application’s window.
QLabel objects can display HTML-formatted text, so you can use the HTML element «<h1>Hello, World!</h1>» to provide the desired text as an h1 header. Finally, you use .move() to place helloMsg at the coordinates (60, 15) on the application’s window.
Note: In PyQt, you can use any widget—a subclass of QWidget —as a top-level window. The only condition is that the target widget must not have a parent widget. When you use a widget as your top-level window, PyQt automatically provides it with a title bar and turns it into a normal window.
The parent-child relationship between widgets has two complementary purposes. A widget with no parent is considered a main or top-level window. In contrast, a widget with an explicit parent is a child widget, and it’s shown within its parent.
This relationship is also known as ownership, with parents owning their children. The PyQt ownership model ensures that if you delete a parent widget, such as your top-level window, then all of its child widgets will automatically be deleted as well.
To avoid memory leaks, you should always make sure that any QWidget object has a parent, with the sole exception of your top-level windows.
You’re done with step three, so you can continue with the final two steps and get your PyQt GUI application ready to run:
In this code snippet, you call .show() on window . The call to .show() schedules a paint event, which is a request to paint the widgets that compose a GUI. This event is then added to the application’s event queue. You’ll learn more about PyQt’s event loop in a later section.
Finally, you start the application’s event loop by calling .exec() . The call to .exec() is wrapped in a call to sys.exit() , which allows you to cleanly exit Python and release memory resources when the application terminates.
You can run your first PyQt app with the following command:
When you run this script, you’ll see a window that’ll look something like this:
Your application shows a window based on QWidget . The window displays the Hello, World! message. To show the message, it uses a QLabel widget. And with that, you’ve written your first GUI desktop application using PyQt and Python! Isn’t that cool?
Considering Code Styles
If you check the code of your sample GUI application from the previous section, then you’ll notice that PyQt’s API doesn’t follow PEP 8 coding style and naming conventions. PyQt is built around Qt, which is written in C++ and uses the camel case naming style for functions, methods, and variables. That said, when you start writing a PyQt project, you need to decide which naming style you’ll use.
In this regard, PEP 8 states that:
New modules and packages (including third party frameworks) should be written to these standards, but where an existing library has a different style, internal consistency is preferred. (Source)
In addition, the Zen of Python says:
If you want to write consistent PyQt-related code, then you should stick to the framework’s coding style. In this tutorial, you’ll follow the PyQt coding style for consistency. You’ll use camel case instead of the usual Python snake case.
Learning the Basics of PyQt
You’ll need to master the basic components of PyQt if you want to proficiently use this library to develop your GUI applications. Some of these components include:
- Widgets
- Layout managers
- Dialogs
- Main windows
- Applications
- Event loops
- Signals and slots
These elements are the building blocks of any PyQt GUI application. Most of them are represented as Python classes that live in the PyQt6.QtWidgets module. These elements are extremely important. You’ll learn more about them in the following few sections.
Widgets
Widgets are rectangular graphical components that you can place on your application’s windows to build the GUI. Widgets have several attributes and methods that allow you to tweak their appearance and behavior. They can also paint a representation of themselves on the screen.
Widgets also detect mouse clicks, keypresses, and other events from the user, the window system, and other sources. Each time a widget catches an event, it emits a signal to announce its state change. PyQt has a rich and modern collection of widgets. Each of those widgets serves a different purpose.
Some of the most common and useful PyQt widgets are:
- Buttons
- Labels
- Line edits
- Combo boxes
- Radio buttons
First up is the button. You can create a button by instantiating QPushButton , a class that provides a classic command button. Typical buttons are Ok , Cancel , Apply , Yes , No , and Close . Here’s how they look on a Linux system:
Buttons like these are perhaps the most commonly used widgets in any GUI. When someone clicks them, your app commands the computer to perform actions. This is how you can execute computations when a user clicks a button.
Up next are labels, which you can create with QLabel . Labels let you display useful information as text or images:
You’ll use labels like these to explain how to use your app’s GUI. You can tweak a label’s appearance in several ways. A label can even accept HTML-formatted text, as you saw earlier. You can also use labels to specify a keyboard shortcut to move the cursor focus to a given widget on your GUI.
Another common widget is the line edit, also known as the input box. This widget allows you to enter a single line of text. You can create line edits with the QLineEdit class. Line edits are useful when you need to get the user’s input as plain text.
Here’s how line edits look on a Linux system:
Line edits like these automatically provide basic editing operations like copy, paste, undo, redo, drag, drop, and so on. In the above figure, you can also see that the objects on the first row show placeholder text to inform the user what kind of input is required.
Combo boxes are another fundamental type of widget in GUI applications. You can create them by instantiating QComboBox . A combo box will present your user with a dropdown list of options in a way that takes up minimal screen space.
Here’s an example of a combo box that provides a dropdown list of popular programming languages:
This combo box is read-only, which means that users can select one of several options but can’t add their own options. Combo boxes can also be editable, allowing users to add new options on the fly. Combo boxes can also contain pixmaps, strings, or both.
The last widget that you’ll learn about is the radio button, which you can create with QRadioButton . A QRadioButton object is an option button that you can click to switch on. Radio buttons are useful when you need the user to select one of many options. All options in a radio button are visible on the screen at the same time:
In this radio buttons group, only one button can be checked at a given time. If the user selects another radio button, then the previously selected button will switch off automatically.
PyQt has a large collection of widgets. At the time of this writing, there are over forty available for you to use to create your application’s GUI. Here, you’ve studied only a small sample. However, that’s enough to show you the power and flexibility of PyQt. In the next section, you’ll learn how to lay out different widgets to build modern and fully functional GUIs for your applications.
Layout Managers
Now that you know about widgets and how they’re used to build GUIs, you need to know how to arrange a set of widgets so that your GUI is both coherent and functional. In PyQt, you’ll find a few techniques for laying out the widgets on a form or window. For instance, you can use the .resize() and .move() methods to give widgets absolute sizes and positions.
However, this technique can have some drawbacks. You’ll have to:
- Do many manual calculations to determine the correct size and position of every widget
- Do extra calculations to respond to window resize events
- Redo most of your calculations when the window’s layout changes in any way
Another technique involves using .resizeEvent() to calculate the widget’s size and position dynamically. In this case, you’ll have similar headaches as with the previous technique.
The most effective and recommended technique is to use PyQt’s layout managers. They’ll increase your productivity, mitigate the risk of errors, and improve your code’s maintainability.
Layout managers are classes that allow you to size and position your widgets on the application’s window or form. They automatically adapt to resize events and GUI changes, controlling the size and position of all their child widgets.
Note: If you develop internationalized applications, then you’ve probably seen translated text get cut off mid-sentence. This is likely to happen when the target natural language is more verbose than the original one. Layout managers can help you prevent this common issue by automatically adjusting the widget size to the available space. However, this feature can sometimes fail with particularly wordy natural languages.
PyQt provides four basic layout manager classes:
The first layout manager class, QHBoxLayout , arranges widgets horizontally from left to right, like with the hypothetical widgets in the following figure:
In the horizontal layout, the widgets will appear one next to the other, starting from the left. The code example below shows how to use QHBoxLayout to arrange three buttons horizontally:
Here’s how this example creates a horizontal layout of buttons:
- Line 18 creates a QHBoxLayout object called layout .
- Lines 19 to 21 add three buttons to layout by calling the .addWidget() method.
- Line 22 sets layout as your window’s layout with .setLayout() .
When you run python h_layout.py from your command line, you’ll get the following output:
The above figure shows three buttons in a horizontal arrangement. The buttons are shown from left to right in the same order as you added them in your code.
The next layout manager class is QVBoxLayout , which arranges widgets vertically from top to bottom, like in the following figure:
Each new widget will appear beneath the previous one. This layout allows you to to construct vertical layouts and organize your widgets from top to bottom on your GUI.
Here’s how you can create a QVBoxLayout object containing three buttons:
On line 18, you create an instance of QVBoxLayout called layout . In the next three lines, you add three buttons to layout . Finally, you use the layout object to arrange the widget in a vertical layout through the .setLayout() method on line 22.
When you run this sample application, you’ll get a window that looks something like this:
This figure shows three buttons in a vertical arrangement, one below the other. The buttons appear in the same order as you added them to your code, from top to bottom.
The third layout manager in your list is QGridLayout . This class arranges widgets in a grid of rows and columns. Every widget will have a relative position on the grid. You can define a widget’s position with a pair of coordinates like (row, column) . Each coordinate must be an integer number. These pairs of coordinates define which cell on the grid a given widget will occupy.
The grid layout will look something like this:
QGridLayout takes the available space, divides it up into rows and columns , and puts each child widget into its own cell.
Here’s how to create a grid layout arrangement in your GUI:
In this example, you create an application that uses a QGridLayout object to organize its widgets on the screen. Note that, in this case, the second and third arguments that you pass to .addWidget() are integer numbers defining each widget’s position on the grid.
On lines 26 to 28, you pass two more arguments to .addWidget() . These arguments are rowSpan and columnSpan , and they’re the fourth and fifth arguments passed to the function. You can use them to make a widget occupy more than one row or column, like you did in the example.
If you run this code from your command line, then you’ll get a window that looks something like this:
In this figure, you can see your widgets arranged in a grid of rows and columns. The last widget occupies two columns, as you specified on lines 26 to 28.
The last layout manager that you’ll learn about is QFormLayout . This class arranges widgets in a two-column layout. The first column usually displays messages in labels. The second column generally contains widgets like QLineEdit , QComboBox , QSpinBox , and so on. These allow the user to enter or edit data regarding the information in the first column.
The following diagram shows how form layouts work in practice:
The left column consists of labels, while the right column consists of input widgets. If you’re developing a database application, then this kind of layout can be a useful tool that’ll increase your productivity when creating input forms.
The following example shows how to create an application that uses a QFormLayout object to arrange its widgets:
Lines 18 to 23 do the hard work in this example. QFormLayout has a convenient method called .addRow() . You can use this method to add a two-widget row to the layout. The first argument to .addRow() should be a label or a string. Then, the second argument can be any widget that allows the user to enter or edit data. In this specific example, you’ve used line edits.
If you run this code, then you’ll get a window that looks something like this:
The above figure shows a window that uses a form layout. The first column contains labels to ask the user for some information. The second column shows widgets that allow the user to enter or edit the required information.
Dialogs
With PyQt, you can develop two types of GUI desktop applications. Depending on the class that you use to create the main form or window, you’ll have one of the following:
- A main window–style application: The application’s main window inherits from QMainWindow .
- A dialog-style application: The application’s main window inherits from QDialog .
You’ll start with dialog-style applications first. In the next section, you’ll learn about main window–style applications.
To develop a dialog-style application, you need to create a GUI class that inherits from QDialog , which is the base class of all dialog windows. A dialog window is a stand-alone window that you can use as the main window for your application.
Note: Dialog windows are commonly used in main window–style applications for brief communication and interaction with the user.
When you use dialog windows to communicate with the user, those dialogs can be:
- Modal: Blocks input to any other visible windows in the same application. You can display a modal dialog by calling its .exec() method.
- Modeless: Operates independently from other windows in the same application. You can display a modeless dialog by using its .show() method.
Dialog windows can also provide a return value and have default buttons, such as Ok and Cancel .
A dialog is always an independent window. If a dialog has a parent , then it’ll display centered on top of the parent widget. Dialogs with a parent will share the parent’s task bar entry. If you don’t set parent for a given dialog, then the dialog will get its own entry in the system’s task bar.
Here’s an example of how you’d use QDialog to develop a dialog-style application:
This application is a bit more elaborate. Here’s what this code does:
- Line 16 defines a Window class for the app’s GUI by inheriting from QDialog .
- Line 18 calls the parent class’s .__init__() method using super() . This call allows you to properly initialize instances of this class. In this example, the parent argument is set to None because this dialog will be your main window.
- Line 19 sets the window’s title.
- Line 20 assigns a QVBoxLayout object to dialogLayout .
- Line 21 assigns a QFormLayout object to formLayout .
- Lines 22 to 25 add widgets to formLayout .
- Line 26 calls .addLayout() on dialogLayout . This call embeds the form layout into the global dialog layout.
- Line 27 defines a button box, which provides a convenient space to display the dialog’s buttons.
- Lines 28 to 31 add two standard buttons, Ok and Cancel , to the dialog.
- Line 32 adds the button box to the dialog by calling .addWidget() .
The if __name__ == «__main__»: construct wraps up the app’s main code. This kind of conditional statement is common in Python apps. It ensures that the indented code will only run if the containing file is executed as a program rather than imported as a module. For more about this construct, check out What Does if name == “main” Do in Python?.
Note: On line 26 in the above example, you’ll note that layout managers can be nested inside one another. You can nest layouts by calling .addLayout() on the container layout with the nested layout as an argument.
The above code example will show a window that looks something like this:
This figure shows the GUI that you’ve created using a QFormLayout object to arrange the widgets and a QVBoxLayout layout for the application’s global layout.
Main Windows
Most of the time, your GUI applications will be main window–style apps. This means that they’ll have a menu bar, some toolbars, a status bar, and a central widget that’ll be the GUI’s main element. It’s also common for your apps to have several dialogs to accomplish secondary actions that depend on a user’s input.
You’ll inherit from QMainWindow to develop main window–style applications. An instance of a class that derives from QMainWindow is considered the app’s main window and should be unique.
QMainWindow provides a framework for building your application’s GUI quickly. This class has its own built-in layout, which accepts the following graphical components:
| Component | Position on Window | Description |
|---|---|---|
| One menu bar | Top | Holds the application’s main menu |
| One or more toolbars | Sides | Hold tool buttons and other widgets, such as QComboBox , QSpinBox , and more |
| One central widget | Center | Holds the window’s central widget, which can be of any type, including a composite widget |
| One or more dock widgets | Around the central widget | Are small, movable, and hidable windows |
| One status bar | Bottom | Holds the app’s status bar, which shows status information |
You can’t create a main window without a central widget. You need a central widget even if it’s just a placeholder. When this is the case, you can use a QWidget object as your central widget.
You can set the window’s central widget with the .setCentralWidget() method. The main window’s layout will allow you to have only one central widget, but it can be a single or a composite widget. The following code example shows you how to use QMainWindow to create a main window–style application:
Here’s how this code works:
- Line 15 creates a class, Window , that inherits from QMainWindow .
- Line 16 defines the class initializer.
- Line 17 calls the base class’s initializer. Again, the parent argument is set to None because this is your app’s main window, so it must not have a parent.
- Line 18 sets the window’s title.
- Line 19 sets a QLabel as the window’s central widget.
- Lines 20 to 22 call non-public methods to create different GUI elements:
- Lines 24 to 26 create the main menubar with a drop-down menu called Menu. This menu will have a menu option to exit the app.
- Lines 28 to 31 create the toolbar, which will have a toolbar button to exit the app.
- Lines 33 to 36 create the app’s status bar.
When you implement GUI components using their own methods, like you did with the menu bar, toolbar, and status bar in this example, you’re making your code more readable and more maintainable.
Note: If you’re running this example on macOS, then you may have issues with the app’s main menu. macOS hides certain menu options, like Exit. Remember that macOS shows the Exit or Quit option under the app’s entry on the top of the screen.
When you run the above sample application, you’ll get a window like the following:
As you can confirm, your main window–style application has the following components:
- One main menu generically called Menu
- One toolbar with an Exit tool button
- One central widget consisting of a QLabel object with a text message
- One status bar at the window’s bottom
That’s it! You’ve learned how to build a main window–style application with Python and PyQt. Up to this point, you’ve learned about some of the more important graphical components in PyQt’s set of widgets. In the next few sections, you’ll study other important concepts related to building GUI applications with PyQt.
Applications
QApplication is the most foundational class that you’ll use when developing PyQt GUI applications. This class is the core component of any PyQt application. It manages the application’s control flow as well as its main settings.
In PyQt, any instance of QApplication is an application. Every PyQt GUI application must have one QApplication instance. Some of the responsibilities of this class include:
- Handling the app’s initialization and finalization
- Providing the event loop and event handling
- Handling most system-wide and application-wide settings
- Providing access to global information, such as the application’s directory, screen size, and so on
- Parsing common command-line arguments
- Defining the application’s look and feel
- Providing localization capabilities
These are just some of the core responsibilities of QApplication . So, this is a fundamental class when it comes to developing PyQt GUI applications.
One of the most important responsibilities of QApplication is to provide the event loop and the entire event handling mechanism. In the following section, you’ll take a closer look at what the event loop is and how it works.
Event Loops
GUI applications are event-driven. This means that functions and methods are called in response to user actions, like clicking on a button, selecting an item from a combo box, entering or updating the text in a text edit, pressing a key on the keyboard, and so on. These user actions are commonly known as events.
Events are handled by an event loop, also known as a main loop. An event loop is an infinite loop in which all events from the user, the window system, and any other sources are processed and dispatched. The event loop waits for an event to occur and then dispatches it to perform some task. The event loop continues to work until the application is terminated.
All GUI applications have an event loop. When an event happens, then the loop checks if it’s a terminate event. In that case, the loop finishes, and the application exits. Otherwise, the event is sent to the application’s event queue for further processing, and the loop iterates again. In PyQt6, you can run the app’s event loop by calling .exec() on the QApplication object.
For an event to trigger an action, you need to connect the event with the action that you want to execute. In PyQt, you can establish that connection with the signals and slots mechanism, which you’ll explore in the next section.
Signals and Slots
PyQt widgets act as event-catchers. This means that every widget can catch specific events, like mouse clicks, keypresses, and so on. In response to these events, a widget emits a signal, which is a kind of message that announces a change in its state.
The signal on its own doesn’t perform any action. If you want a signal to trigger an action, then you need to connect it to a slot. This is the function or method that’ll perform an action whenever its associated signal is emitted. You can use any Python callable as a slot.
If a signal is connected to a slot, then the slot is called whenever the signal is emitted. If a signal isn’t connected to any slot, then nothing happens and the signal is ignored. Some of the most relevant features of signals and slots include the following:
- A signal can be connected to one or many slots.
- A signal may also be connected to another signal.
- A slot may be connected to one or many signals.
You can use the following syntax to connect a signal and a slot:
This will connect slot_function to widget.signal . From now on, whenever .signal is emitted, slot_function() will be called.
The code below shows how to use the signals and slots mechanism in a PyQt application:
On line 15, you create greet() , which you’ll use as a slot. Then in line 27, you connect the button’s .clicked signal to greet() . This way, whenever the user clicks the Greet button, the greet() slot is called and the label object’s text alternates between Hello, World! and an empty string:
When you click the Greet button, the Hello, World! message appears and disappears on your application’s main window.
Note: Every widget has its own set of predefined signals. You can check them out on the widget’s documentation.
If your slot function needs to receive extra arguments, then you can pass them using functools.partial() . For example, you can modify greet() to take an argument, like in the following code:
Now greet() needs to receive an argument called name . If you want to connect this new version of greet() to the .clicked signal, then you can do something like this:
For this code to work, you need to import partial() from functools first. The call to partial() returns a function object that behaves similarly to greet() when called with name=»World!» . Now, when the user clicks on the button, the message Hello, World! will appear in the label just like before.
Note: You can also use a lambda function to connect a signal to a slot that requires extra arguments. As an exercise, try to code the above example using lambda instead of functools.partial() .
The signals and slots mechanism is what you’ll use to give life to your PyQt GUI applications. This mechanism will allow you to turn user events into concrete actions. You can dive deeper into signals and slots by checking out the PyQt6 documentation on the topic.
Now you know the basics of several important concepts of PyQt. With this knowledge and the library’s documentation at hand, you’re ready to start developing your own GUI applications. In the next section, you’ll build your first fully functional GUI application.
Creating a Calculator App With Python and PyQt
In this section, you’ll develop a calculator GUI app using the Model-View-Controller (MVC) design pattern. This pattern has three layers of code, with each one having different roles:
The model takes care of your app’s business logic. It contains the core functionality and data. In your calculator app, the model will handle the input values and the calculations.
The view implements your app’s GUI. It hosts all the widgets that the end user would need to interact with the application. The view also receives a user’s actions and events. For your example, the view will be the calculator window on your screen.
The controller connects the model and the view to make the application work. Users’ events, or requests, are sent to the controller, which puts the model to work. When the model delivers the requested result, or data, in the right format, the controller forwards it to the view. In your calculator app, the controller will receive the target math expressions from the GUI, ask the model to perform calculations, and update the GUI with the result.
Here’s a step-by-step description of how your GUI calculator app will work:
- The user performs an action or request (event) on the view (GUI).
- The view notifies the controller about the user’s action.
- The controller gets the user’s request and queries the model for a response.
- The model processes the controller’s query, performs the required computations, and returns the result.
- The controller receives the model’s response and updates the view accordingly.
- The user finally sees the requested result on the view.
You’ll use this MVC design to build your calculator app with Python and PyQt.
Creating the Skeleton for Your PyQt Calculator App
To kick things off, you’ll start by implementing a minimal skeleton for your application in a file called pycalc.py . You can get this file and the rest of the source code for your calculator app by clicking the link below:
Download Code: Click here to download the code that you’ll use to build a calculator in Python with PyQt in this tutorial.
If you’d prefer to code the project on your own, then go ahead and create pycalc.py in your current working directory. Open the file in your favorite code editor or IDE and type the following code:
This script implements all the boilerplate code that you’ll need to run a basic GUI application. You’ll use this skeleton to build your calculator app.
Here’s how this code works:
Line 5 imports sys . This module provides the exit() function, which you’ll use to cleanly terminate the app.
Line 7 imports the required classes from PyQt6.QtWidgets .
Line 9 creates a Python constant to hold a fixed window size in pixels for your calculator app.
Line 11 creates the PyCalcWindow class to provide the app’s GUI. Note that this class inherits from QMainWindow .
Line 14 defines the class initializer.
Line 15 calls .__init__() on the super class for initialization purposes.
Line 16 sets the window’s title to «PyCalc» .
Line 17 uses .setFixedSize() to give the window a fixed size. This ensures that the user won’t be able to resize the window during the app’s execution.
Lines 18 and 19 create a QWidget object and set it as the window’s central widget. This object will be the parent of all the required GUI components in your calculator app.
Line 21 defines your calculator’s main function. Having a main() function like this is a best practice in Python. This function provides the application’s entry point. Inside main() , your program does the following:
- Line 23 creates a QApplication object named pycalcApp .
- Line 24 creates an instance of the app’s window, pycalcWindow .
- Line 25 shows the GUI by calling .show() on the window object.
- Line 26 runs the application’s event loop with .exec() .
Finally, line 29 calls main() to execute your calculator app. When you run the above script, the following window appears on your screen:
That’s it! You’ve successfully built a fully functional app skeleton for your GUI calculator app. Now you’re ready to continue building the project.
Completing the App’s View
The GUI that you have at this point doesn’t really look like a calculator. You need to finish this GUI by adding a display to show the target math operation and a keyboard of buttons representing numbers and basic math operators. You’ll also add buttons representing other required symbols and actions, like clearing the display.
First, you need to update your imports like in the code below:
You’ll use a QVBoxLayout layout manager for the calculator’s global layout. To arrange the buttons, you’ll use a QGridLayout object. The QLineEdit class will work as the calculator’s display and QPushButton will provide the required buttons.
Now you can update the initializer for PyCalcWindow :
You’ve added the highlighted lines of code. You’ll use .generalLayout as the app’s general layout. In this layout, you’ll place the display at the top and the keyboard buttons in a grid layout at the bottom.
The calls to ._createDisplay() and ._createButtons() won’t work at this point, because you haven’t implemented those methods yet. To fix this issue, you’ll start by coding ._createDisplay() .
Get back to your code editor and update pycalc.py like in the following code:
In this code snippet, you first define a new constant to hold the display height in pixels. Then you define ._createDisplay() inside PyCalcWindow .
To create the calculator’s display, you use a QLineEdit widget. Then you set a fixed height of thirty-five pixels for your display using the DISPLAY_HEIGHT constant. The display will have its text right-aligned. Finally, the display will be read-only to prevent direct editing by the user. The last line of code adds the display to the calculator’s general layout.
Next up, you’ll implement the ._createButtons() method to create the required buttons for your calculator’s keyboard. These buttons will live in a grid layout, so you need a way to represent their coordinates on the grid. Each coordinate pair will consist of a row and a column. To represent a coordinate pair, you’ll use a list of lists. Each nested list will represent a row.
Now go ahead and update the pycalc.py file with the following code:
In this piece of code, you define a new constant called BUTTON_SIZE . You’ll use this constant to provide the size of your calculator’s buttons. In this specific example, all the buttons will have a square shape with forty pixels per side.
With this initial setup, you can code the ._createButtons() method. You’ll use a list of lists to hold the keys or buttons and their position on the calculator keyboard. A QGridLayout will allow you to arrange the buttons on the calculator’s window:
You first create the empty dictionary self.buttonMap to hold the calculator buttons. Then, you create a list of lists to store the key labels. Each row or nested list will represent a row in the grid layout, while the index of each key label will represent the corresponding column on the layout.
Then you define two for loops. The outer loop iterates over the rows and the inner loop iterates over the columns. Inside the inner loop, you create the buttons and add them to both self.buttonMap and buttonsLayout . Every button will have a fixed size of 40×40 pixels, which you set with .setFixedSize() and the BUTTON_SIZE constant.
Finally, you embed the grid layout into the calculator’s general layout by calling .addLayout() on the .generalLayout object.
Note: When it comes to widget size, you’ll rarely find measurement units in the PyQt documentation. The measurement unit is assumed to be pixels, except when you’re working with QPrinter class, which uses points.
Now your calculator’s GUI will show the display and the buttons gracefully. However, you have no way to update the information shown on the display. You’ll fix this by adding a few extra methods to PyCalcWindow :
Method Description .setDisplayText() Sets and updates the display’s text .displayText() Gets the current display’s text .clearDisplay() Clears the display’s text These methods will provides the GUI’s public interface and complete the view class for your Python calculator app.
Here’s a possible implementation:
Here’s a breakdown of what each method does:
.setDisplayText() uses .setText() to set and update the display’s text. It also uses .setFocus() to set the cursor’s focus on the display.
.displayText() is a getter method that returns the display’s current text. When the user clicks the equal sign ( = ) on the calculator’s keyboard, the app will use the return value of .displayText() as the math expression to be evaluated.
.clearDisplay() sets the display’s text to an empty string ( «» ) so that the user can introduce a new math expression. This method will be triggered every time the user presses the C button on the calculator’s board.
Now your calculator’s GUI is ready for use! When you run the application, you’ll get a window like the following:
You’ve completed the calculator’s GUI, which looks pretty sleek! However, if you try to do some calculations, then the calculator won’t respond as expected. That’s because you haven’t implemented the model and the controller components. In the next section, you’ll write the calculator’s model.
Implementing the Calculator’s Model
In the MVC pattern, the model is the layer of code that takes care of the business logic. In your calculator app, the business logic is all about basic math calculations. So, your model will evaluate the math expressions that your users introduced in the calculator’s GUI.
The calculator’s model also needs to handle errors. To this end, you’ll define the following global constant:
This ERROR_MSG constant is the message that the user will see on the calculator’s display if they introduce an invalid math expression.
With the above change, you’re ready to code your app’s model, which will be a single function in this example:
In evaluateExpression() , you use eval() to evaluate a math expression that comes as a string. If the evaluation is successful, then you return result . Otherwise, you return the predefined error message. Note that this function isn’t perfect. It has a couple of important issues:
- The try … except block doesn’t catch a specific exception, so it’s using a practice that’s discouraged in Python.
- The function uses eval() , which can lead to some serious security issues.
You’re free to rework the function to make it more reliable and secure. In this tutorial, you’ll use the function as is to keep the focus on implementing the GUI.
Creating the Controller Class for Your Calculator
In this section, you’re going to code the calculator’s controller class. This class will connect the view to the model that you just coded. You’ll use the controller class to make the calculator perform actions in response to user events.
Your controller class needs to perform three main tasks:
- Access the GUI’s public interface.
- Handle the creation of math expressions.
- Connect all the buttons’ .clicked signals with the appropriate slots.
To perform all these actions, you’ll code a new PyCalc class in a moment. Go ahead and update pycalc.py with the following code:
At the top of pycalc.py , you import partial() from functools . You’ll use this function to connect signals with methods that need to take extra arguments.
Inside PyCalc , you define the class initializer, which takes two arguments: the app’s model and its view. Then you store these arguments in appropriate instance attributes. Finally, you call ._connectSignalsAndSlots() to make all the required connections of signals and slots.
In ._calculateResult() , you use ._evaluate() to evaluate the math expression that the user has just typed into the calculator’s display. Then you call .setDisplayText() on the calculator’s view to update the display text with the computation result.
As its name suggests, the ._buildExpression() method takes care of building the target math expression. To do this, the method concatenates the initial display value with every new value that the user enters on the calculator’s keyboard.
Finally, the ._connectSignalsAndSlots() method connects all the buttons’ .clicked signals with the appropriate slots method in the controller class.
That’s it! Your controller class is ready. However, for all this code to work as a real calculator, you need to update the app’s main() function like in the code below:
This piece of code creates a new instance of PyCalc . The model argument to the PyCalc class constructor holds a reference to the evaluateExpression() function, while the view argument holds a reference to the pycalcWindow object, which provides the app’s GUI. Now your PyQt calculator application is ready to run.
Running the Calculator
Now that you’ve finished writing your calculator app with Python and PyQt, it’s time for a live test! If you run the application from your command line, then you’ll get something like this:
To use PyCalc, enter a valid math expression with your mouse. Then, press Enter or click the equal sign ( = ) button to compute and show the expression result on the calculator’s display. That’s it! You’ve developed your first fully functional GUI desktop application with Python and PyQt!
Additional Tools
PyQt6 offers a useful set of additional tools that can help you build solid, modern, and full-featured GUI applications. Some of the most remarkable tools related to PyQt include Qt Designer and the internationalization kit.
Qt Designer allows you to design and build graphical user interfaces using a drag-and-drop interface. You can use this tool to design widgets, dialogs, and main windows by using on-screen forms and a drag-and-drop mechanism. The following animation shows some of Qt Designer’s features:
Qt Designer uses XML .ui files to store your GUI designs. PyQt includes a module called uic to help with .ui files. You can also convert the .ui file content into Python code with a command-line tool called pyuic6 .
Note: To dive deeper into Qt Designer and better understand how to use this tool to create graphical user interfaces, check out Qt Designer and Python: Build Your GUI Applications Faster.
PyQt6 also provides a comprehensive set of tools for the internationalization of apps into local languages. The pylupdate6 command-line tool creates and updates translation ( .ts ) files, which can contain translations of interface strings. If you prefer GUI tools, then you can use Qt Linguist to create and update .ts files with translations of interface strings.
Conclusion
Graphical user interface (GUI) applications still hold a substantial share of the software development market. Python offers a handful of frameworks and libraries that can help you develop modern and robust GUI applications.
In this tutorial, you learned how to use PyQt, which is one of the most popular and solid libraries for GUI application development in Python. Now you know how to effectively use PyQt to build modern GUI applications.
In this tutorial, you’ve learned how to:
- Build graphical user interfaces with Python and PyQt
- Connect the user’s events with the app’s logic
- Organize a PyQt application using a proper project layout
- Create a real-world GUI application with PyQt
Now you can use your Python and PyQt knowledge to give life to your own desktop GUI applications. Isn’t that cool?
You can get the source code of your calculator app project and all its associated resources by clicking the link below:
Download Code: Click here to download the code that you’ll use to build a calculator in Python with PyQt in this tutorial.
Further Reading
To dive deeper into PyQt and its ecosystem, check out some of the following resources:
Although the PyQt6 Documentation is the first resource listed here, some important parts of it are still missing or incomplete. Fortunately, you can use the Qt documentation to fill in the blanks.
Get a short & sweet Python Trick delivered to your inbox every couple of days. No spam ever. Unsubscribe any time. Curated by the Real Python team.
About Leodanis Pozo Ramos
Leodanis is an industrial engineer who loves Python and software development. He's a self-taught Python developer with 6+ years of experience. He's an avid technical writer with a growing number of articles published on Real Python and other sites.
Each tutorial at Real Python is created by a team of developers so that it meets our high quality standards. The team members who worked on this tutorial are:
Creating your first app with PyQt5
A simple Hello World! application with Python and Qt5In this tutorial we’ll learn how to use PyQt to create desktop applications with Python. First we’ll create a series of simple windows on your desktop to ensure that PyQt is working and introduce some of the basic concepts. Then we’ll take a brief look at the event loop and how it relates to GUI programming in Python. Finally we’ll look at Qt’s QMainWindow which offers some useful common interface elements such as toolbars and menus. These will be explored in more detail in the subsequent tutorials.
Creating an application
Let’s create our first application! To start create a new Python file — you can call it whatever you like (e.g. app.py ) and save it somewhere accessible. We’ll write our simple app in this file.
We’ll be editing within this file as we go along, and you may want to come back to earlier versions of your code, so remember to keep regular backups.
The source code for the application is shown below. Type it in verbatim, and be careful not to make mistakes. If you do mess up, Python will let you know what’s wrong.
First, launch your application. You can run it from the command line like any other Python script, for example —
Run it! You will now see your window. Qt automatically creates a window with the normal window decorations and you can drag it around and resize it like any window.
What you’ll see will depend on what platform you’re running this example on. The image below shows the window as displayed on Windows, macOS and Linux (Ubuntu).
Our window, as seen on Windows, macOS and Linux.Stepping through the code
Let’s step through the code line by line, so we understand exactly what is happening.
First, we import the PyQt classes that we need for the application. Here we’re importing QApplication , the application handler and QWidget , a basic empty GUI widget, both from the QtWidgets module.
The main modules for Qt are QtWidgets , QtGui and QtCore .
You could do from <module> import * but this kind of global import is generally frowned upon in Python, so we’ll avoid it here.
Next we create an instance of QApplication , passing in sys.arg , which is Python list containing the command line arguments passed to the application.
If you know you won’t be using command line arguments to control Qt you can pass in an empty list instead, e.g.
Next we create an instance of a QWidget using the variable name window .
In Qt all top level widgets are windows — that is, they don’t have a parent and are not nested within another widget or layout. This means you can technically create a window using any widget you like.
Widgets without a parent are invisible by default. So, after creating the window object, we must always call .show() to make it visible. You can remove the .show() and run the app, but you’ll have no way to quit it!
What is a window? — Holds the user-interface of your application — Every application needs at least one (. but can have more) — Application will (by default) exit when last window is closed
Finally, we call app.exec() to start up the event loop.
In PyQt5 you can also use app.exec_() . This was a legacy feature avoid a clash with the exec reserved word in Python 2.
What’s the event loop?
Before getting the window on the screen, there are a few key concepts to introduce about how applications are organized in the Qt world. If you’re already familiar with event loops you can safely skip to the next section.
The core of every Qt Applications is the QApplication class. Every application needs one — and only one — QApplication object to function. This object holds the event loop of your application — the core loop which governs all user interaction with the GUI.
Each interaction with your application — whether a press of a key, click of a mouse, or mouse movement — generates an event which is placed on the event queue. In the event loop, the queue is checked on each iteration and if a waiting event is found, the event and control is passed to the specific event handler for the event. The event handler deals with the event, then passes control back to the event loop to wait for more events. There is only one running event loop per application.
The QApplication class — QApplication holds the Qt event loop — One QApplication instance required — You application sits waiting in the event loop until an action is taken — There is only one event loop running at any time
Downloadable ebook (PDF, ePub) & Complete Source code
Purchasing Power Parity
QMainWindow
As we discovered in the last part, in Qt any widgets can be windows. For example, if you replace QtWidget with QPushButton . In the example below, you would get a window with a single push-able button in it.
This is neat, but not really very useful — it’s rare that you need a UI that consists of only a single control! But, as we’ll discover later, the ability to nest widgets within other widgets using layouts means you can construct complex UIs inside an empty QWidget .
But, Qt already has a solution for you — the QMainWindow . This is a pre-made widget which provides a lot of standard window features you’ll make use of in your apps, including toolbars, menus, a statusbar, dockable widgets and more. We’ll look at these advanced features later, but for now, we’ll add a simple empty QMainWindow to our application.
Run it! You will now see your main window. It looks exactly the same as before!
So our QMainWindow isn’t very interesting at the moment. We can fix that by adding some content. If you want to create a custom window, the best approach is to subclass QMainWindow and then include the setup for the window in the __init__ block. This allows the window behavior to be self contained. We can add our own subclass of QMainWindow — call it MainWindow to keep things simple.
For this demo we’re using a QPushButton . The core Qt widgets are always imported from the QtWidgets namespace, as are the QMainWindow and QApplication classes. When using QMainWindow we use .setCentralWidget to place a widget (here a QPushButton ) in the QMainWindow — by default it takes the whole of the window. We’ll look at how to add multiple widgets to windows in the layouts tutorial.
When you subclass a Qt class you must always call the super __init__ function to allow Qt to set up the object.
In our __init__ block we first use .setWindowTitle() to change the title of our main window. Then we add our first widget — a QPushButton — to the middle of the window. This is one of the basic widgets available in Qt. When creating the button you can pass in the text that you want the button to display.
Finally, we call .setCentralWidget() on the window. This is a QMainWindow specific function that allows you to set the widget that goes in the middle of the window.
Run it! You will now see your window again, but this time with the QPushButton widget in the middle. Pressing the button will do nothing, we’ll sort that next.
Our QMainWindow with a single QPushButton on Windows, macOS and Linux.
We’ll cover more widgets in detail shortly but if you’re impatient and would like to jump ahead you can take a look at the QWidget documentation. Try adding the different widgets to your window!
Sizing windows and widgets
The window is currently freely resizable — if you grab any corner with your mouse you can drag and resize it to any size you want. While it’s good to let your users resize your applications, sometimes you may want to place restrictions on minimum or maximum sizes, or lock a window to a fixed size.
In Qt sizes are defined using a QSize object. This accepts width and height parameters in that order. For example, the following will create a fixed size window of 400×300 pixels.
Run it! You will see a fixed size window — try and resize it, it won’t work.
Our fixed-size window, notice that the _maximize control is disabled on Windows & Linux. On macOS you can maximize the app to fill the screen, but the central widget will not resize._As well as .setFixedSize() you can also call .setMinimumSize() and .setMaximumSize() to set the minimum and maximum sizes respectively. Experiment with this yourself!
You can use these size methods on any widget.
In this section we’ve covered the QApplication class, the QMainWindow class, the event loop and experimented with adding a simple widget to a window. In the next section we’ll take a look at the mechanisms Qt provides for widgets and windows to communicate with one another and your own code.