Python GUIs - tutorials

Getting Started With Flet for GUI Development — Your First Steps With the Flet Library for Desktop and Web Python GUIs

2025-12-15T06:00:00+00:00

Getting started with a new GUI framework can feel daunting. This guide walks you through the essentials of Flet, from installation and a first app to widgets, layouts, and event handling.

With Flet, you can quickly build modern, high‑performance desktop, web, and mobile interfaces using Python.

What Is Flet? A Cross-Platform Python GUI Framework

Flet is a cross-platform GUI framework for Python. It enables the development of interactive applications that run as native desktop applications on Windows, macOS, and Linux. Flet apps also run in the browser and even as mobile apps. Flet uses Flutter under the hood, providing a modern look and feel with responsive layouts.

The library's key features include:

Modern, consistent UI across desktop, web, and mobile
No HTML, CSS, or JS required, only write pure Python
Rich set of widgets for input, layout, data display, and interactivity
Live reload for rapid development
Built-in support for theming, navigation, and responsive design
Easy event handling and state management

Flet is great for building different types of GUI apps, from utilities and dashboards to data-science tools, business apps, and even educational or hobby projects.

Installing Flet

You can install Flet from PyPI using the following pip command:

$ pip install flet

This command downloads and installs Flet into your current Python environment. That's it! You can now write your first app.

Writing Your First Flet GUI App

To build a Flet app, you typically follow these steps:

Import flet and define a function that takes a Page object as an argument.
Add UI controls (widgets) to the page.
Use flet.app() to start the app by passing the function as an argument.

Here's a quick Hello, World! application in Flet:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet First App"
    page.window.width = 200
    page.window.height = 100
    page.add(ft.Text("Hello, World!"))

ft.app(target=main)

In the main() function, we get the page object as an argument. This object represents the root of our GUI. Then, we set the title and window size and add a Text control that displays the "Hello, World!" text.

Use page.add() to add controls (UI elements or widgets) to your app. To manipulate the widgets, you can use page.controls, which is a list containing the controls that have been added to the page.

Run it! Here's what your first app looks like.

First Flet GUI application

You can run a Flet app as you'd run any Python app in the terminal. Additionally, Flet allows you to use the flet run command for live reload during development.

Exploring Flet Controls (Widgets)

Flet includes a wide variety of widgets, known as controls, in several categories. Some of these categories include the following:

In the following sections, you'll code simple examples showcasing a sample of each category's controls.

Flet Button Controls

Buttons are key components in any GUI application. Flet has several types of buttons that we can use in different situations, including the following:

FilledButton: A filled button without a shadow. Useful for important, final actions that complete a flow, like Save or Confirm.
ElevatedButton: A filled tonal button with a shadow. Useful when you need visual separation from a patterned background.
FloatingActionButton: A Material Design floating action button.

Here's an example that showcases these types of buttons:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Buttons Demo"
    page.window.width = 200
    page.window.height = 200

    page.add(ft.ElevatedButton("Elevated Button"))
    page.add(ft.FilledButton("Filled Button"))
    page.add(ft.FloatingActionButton(icon=ft.Icons.ADD))

ft.app(target=main)

Here, we call the add() method on our page object to add instances of ElevatedButton, FilledButton, and FloatingActionButton. Flet arranges these controls vertically by default.

Run it! You'll get a window that looks like the following.

Flet buttons demo

Input and Selection Controls

Input and selection controls enable users to enter data or select values in your app's GUI. Flet provides several commonly used controls in this category, including the following:

TextField: A common single-line or multi-line text entry control.
Dropdown: A selection control that lets users pick a value from a list of options.
Checkbox: A control for boolean input, often useful for preferences and agreement toggles.
Radio: A selection radio button control commonly used inside a RadioGroup to choose a single option from a set.
Slider: A control for selecting a numeric value along a track.
Switch: A boolean on/off toggle.

Here's an example that showcases some of these input and selection controls:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Input and Selections Demo"
    page.window.width = 360
    page.window.height = 320

    name = ft.TextField(label="Name")
    agree = ft.Checkbox(label="I agree to the terms")
    level = ft.Slider(
        label="Experience level",
        min=0,
        max=10,
        divisions=10,
        value=5,
    )
    color = ft.Dropdown(
        label="Favorite color",
        options=[
            ft.dropdown.Option("Red"),
            ft.dropdown.Option("Green"),
            ft.dropdown.Option("Blue"),
        ],
    )
    framework = ft.RadioGroup(
        content=ft.Column(
            [
                ft.Radio(value="Flet", label="Flet"),
                ft.Radio(value="Tkinter", label="Tkinter"),
                ft.Radio(value="PyQt6", label="PyQt6"),
                ft.Radio(value="PySide6", label="PySide6"),
            ]
        )
    )
    notifications = ft.Switch(label="Enable notifications", value=True)

    page.add(
        ft.Text("Fill in the form and adjust the options:"),
        name,
        agree,
        level,
        color,
        framework,
        notifications,
    )

ft.app(target=main)

After setting the window's title and size, we create several input controls:

A TextField for the user's name
A Checkbox to agree to the terms
A Slider to select an experience level from 0 to 10
A Dropdown to pick a favorite color
A RadioGroup with several framework choices
A Switch to enable or disable notifications, which defaults to ON

We add all these controls to the page using page.add(), preceded by a simple instruction text. Flet lays out the controls vertically (the default) in the order you pass them.

Run it! You'll see a simple form that uses text input, dropdowns, checkboxes, radio buttons, sliders, and switches.

Flet input and selection controls demo

Navigation Controls

Navigation controls allow users to move between different sections or views within an app. Flet provides several navigation controls, including the following:

NavigationBar: A bottom navigation bar with multiple destinations, which is useful for switching between three to five primary sections of your app.
AppBar: A top app bar that can display a title, navigation icon, and action buttons.

Here's an example that uses NavigationBar to navigate between different views:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Navigation Bar Demo"
    page.window.width = 360
    page.window.height = 260

    info = ft.Text("You are on the Home tab")

    def on_nav_change(e):
        idx = page.navigation_bar.selected_index
        if idx == 0:
            info.value = "You are on the Home tab"
        elif idx == 1:
            info.value = "You are on the Search tab"
        else:
            info.value = "You are on the Profile tab"
        page.update()

    page.navigation_bar = ft.NavigationBar(
        selected_index=0,
        destinations=[
            ft.NavigationBarDestination(icon=ft.Icons.HOME, label="Home"),
            ft.NavigationBarDestination(icon=ft.Icons.SEARCH, label="Search"),
            ft.NavigationBarDestination(icon=ft.Icons.PERSON, label="Profile"),
        ],
        on_change=on_nav_change,
    )

    page.add(
        ft.Container(content=info, alignment=ft.alignment.center, padding=20),
    )

ft.app(target=main)

The NavigationBar has three tabs: Home, Search, and Profile, each with a representative icon that you provide using ft.Icons. Assigning this bar to page.navigation_bar tells Flet to display it as the app's bottom navigation component.

The behavior of the bar is controlled by the on_nav_change() callback (more on this in the section on events and callbacks). Whenever the user clicks a tab, Flet calls on_nav_change(), which updates the text with the appropriate message.

Run it! Click the different tabs to see the text on the page update as you navigate between sections.

Flet navigation bar demo

Information Display Controls

We can use information-display controls to present content to the user, such as text, images, and rich list items. These controls help communicate status, context, and details without requiring user input.

Some common information-display controls include the following:

Text: The basic control for showing labels, paragraphs, and other readable text.
Image: A control for displaying images from files, assets, or URLs.

Here's an example that combines these controls:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Information Displays Demo"
    page.window.width = 340
    page.window.height = 400

    header = ft.Text("Latest image", size=18)

    hero = ft.Image(
        src="https://picsum.photos/320/320",
        width=320,
        height=320,
        fit=ft.ImageFit.COVER,
    )

    page.add(
        header,
        hero,
    )

ft.app(target=main)

In main(), we create a Text widget called header to show "Latest image" with a larger font size. The hero variable is an Image control that loads an image from the URL https://picsum.photos/320/320.

We use a fixed width and height together with ImageFit.COVER so that the image fills its box while preserving aspect ratio and cropping if needed.

Run it! You'll see some text and a random image from Picsum.photos.

Flet information display demo

Dialogs, Alerts, and Panels

Dialogs, alerts, and panels enable you to draw attention to important information or reveal additional details without leaving the current screen. They are useful for confirmations, warnings, and expandable content.

Some useful controls in this category are listed below:

AlertDialog: A modal dialog that asks the user to acknowledge information or make a decision.
Banner: A prominent message bar displayed at the top of the page for important, non-modal information.
DatePicker: A control that lets the user pick a calendar date in a pop-up dialog.
TimePicker: A control for selecting a time of day from a dialog-style picker.

Here's an example that shows an alert dialog to ask for exit confirmation:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Dialog Demo"
    page.window.width = 300
    page.window.height = 300

    def on_dlg_button_click(e):
        if e.control.text == "Yes":
            page.window.close()
        page.close(dlg_modal)

    dlg_modal = ft.AlertDialog(
        modal=True,
        title=ft.Text("Confirmation"),
        content=ft.Text("Do you want to exit?"),
        actions=[
            ft.TextButton("Yes", on_click=on_dlg_button_click),
            ft.TextButton("No", on_click=on_dlg_button_click),
        ],
        actions_alignment=ft.MainAxisAlignment.END,
    )

    page.add(
        ft.ElevatedButton(
            "Exit",
            on_click=lambda e: page.open(dlg_modal),
        ),
    )

ft.app(target=main)

In this example, we first create an AlertDialog with a title, some content text, and two action buttons labeled Yes and No.

The on_dlg_button_click() callback checks which button was clicked and closes the application window if the user selects Yes. The page shows a single Exit button that opens the dialog. After the user responds, the dialog is closed.

Run it! Try clicking the button to open the dialog. You'll see a window similar to the one shown below.

Flet dialog demo

Laying Out Your GUI With Flet Layouts

Controls in this category are often described as container controls that can hold child controls. These controls enable you to arrange widgets on an app's GUI to create a well-organized and functional interface.

Flet has many container controls. Here are some of them:

Page: This control is the root of the control hierarchy or tree. It is also listed as an adaptive container control.
Column: A container control used to arrange child controls in a column.
Row: A container control used to arrange child controls horizontally in a row.
Container: A container control that allows you to modify its size (e.g., height) and appearance.
Stack: A container control where properties like bottom, left, right, and top allow you to place children in specific positions.
Card: A container control with slightly rounded corners and an elevation shadow.

By default, Flet stacks widgets vertically using the Column container. Here's an example that demonstrates basic layout options in Flet:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Layouts Demo"
    page.window.width = 250
    page.window.height = 300

    main_layout = ft.Column(
        [
            ft.Text("1) Vertical layout:"),
            ft.ElevatedButton("Top"),
            ft.ElevatedButton("Middle"),
            ft.ElevatedButton("Bottom"),
            ft.Container(height=12),  # Spacer

            ft.Text("2) Horizontal layout:"),
            ft.Row(
                [
                    ft.ElevatedButton("Left"),
                    ft.ElevatedButton("Center"),
                    ft.ElevatedButton("Right"),
                ]
            ),
        ],
    )

    page.add(main_layout)

ft.app(target=main)

In this example, we use a Column object as the app's main layout. This layout stacks text labels and buttons vertically, while the inner Row object arranges three buttons horizontally. The Container object with a fixed height acts as a spacer between the vertical and horizontal sections.

Run it! You'll get a window like the one shown below.

Flet layouts demo

Handling Events and Callbacks in Flet

Flet uses event handlers to manage user interactions and perform actions. Most controls accept an on_* argument, such as on_click or on_change, which you can set to a Python function or other callable that will be invoked when an event occurs on the target widget.

The example below provides a text input and a button. When you click the button, it opens a dialog displaying the input text:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Event & Callback Demo"
    page.window.width = 340
    page.window.height = 360

    def on_click(e):  # Event handler or callback function
        dialog_text.value = f'You typed: "{txt_input.value}"'
        page.open(dialog)
        page.update()

    txt_input = ft.TextField(label="Type something and press Click Me!")
    btn = ft.ElevatedButton("Click Me!", on_click=on_click)
    dialog_text = ft.Text("")
    dialog = ft.AlertDialog(
        modal=True,
        title=ft.Text("Dialog"),
        content=dialog_text,
        actions=[ft.TextButton("OK", on_click=lambda e: page.close(dialog))],
        open=False,
    )

    page.add(
        txt_input,
        btn,
    )

ft.app(target=main)

When you click the button, the on_click() handler or callback function is automatically called. It sets the dialog's text and opens the dialog. The dialog has an OK button that closes it by calling page.close(dialog).

Run it! You'll get a window like the one shown below.

Flet event handling and callback demo

To see this app in action, type some text into the input and click the Click Me! button.

Conclusion

Flet offers a powerful and modern toolkit for developing GUI applications in Python. It allows you to create desktop and web GUIs from a single codebase. In this tutorial, you've learned the basics of using Flet for desktop apps, including controls, layouts, and event handling.

Now that you understand the fundamentals of Flet, try building your first web app and experimenting with widgets, callbacks, layouts, and more advanced features like theming and navigation.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Getting Started With NiceGUI for Web UI Development in Python — Your First Steps With the NiceGUI Library for Web UI Development

2025-11-27T06:00:00+00:00

NiceGUI is a Python library that allows developers to create interactive web applications with minimal effort. It's intuitive and easy to use. It provides a high-level interface for building modern web-based graphical user interfaces (GUIs) without requiring deep knowledge of web technologies like HTML, CSS, or JavaScript.

In this tutorial, you'll learn how to use NiceGUI to develop web apps with Python. You'll begin with an introduction to NiceGUI and its capabilities. Then, you'll learn how to create a simple NiceGUI app in Python and explore the basics of the framework's elements. Finally, you'll use NiceGUI to handle events and customize your app's appearance.

To get the most out of this tutorial, you should have a basic knowledge of Python. Familiarity with general GUI programming concepts, such as event handling, widgets, and layouts, will also be beneficial.

Installing NiceGUI

Before using any third-party library like NiceGUI, you must install it in your working environment. Installing NiceGUI is as quick as running the python -m pip install nicegui command in your terminal or command line. This command will install the library from the Python Package Index (PyPI).

It's a good practice to use a Python virtual environment to manage dependencies for your project. To create and activate a virtual environment, open a command line or terminal window and run the following commands in your working directory:

```sh:Windows PS> python -m venv .\venv PS> .\venv\Scripts\activate

python


```sh:macOS
$ python -m venv venv/
$ source venv/bin/activate

```sh:Linux $ python3 -m venv venv/ $ source venv/bin/activate

python


The first command will create a folder called `venv/` containing a Python virtual environment. The Python version in this environment will match the version you have installed on your system.

Once your virtual environment is active, install NiceGUI by running:

```sh
(venv) $ python -m pip install nicegui

With this command, you've installed NiceGUI in your active Python virtual environment and are ready to start building applications.

Writing Your First NiceGUI App in Python

Let's create our first app with NiceGUI and Python. We'll display the traditional "Hello, World!" message in a web browser. To create a minimal NiceGUI app, follow these steps:

Import the ui object from nicegui.
Create a GUI element.
Run the application using the run() method.

Create a Python file named app.py and add the following code:

python

from nicegui import ui

ui.label('Hello, World!').classes('text-h1')

ui.run()

This code defines a web application whose UI consists of a label showing the Hello, World! message. To create the label, we use the ui.label element. The call to ui.run() starts the app.

Run the application by executing the following command in your terminal:

(venv) $ python app.py

This will open your default browser, showing a page like the one below:

First NiceGUI Application

Congratulations! You've just written your first NiceGUI web app using Python. The next step is to explore some features of NiceGUI that will allow you to create fully functional web applications.

If the above command doesn't open the app in your browser, navigate to http://localhost:8080.

Exploring NiceGUI Graphical Elements

NiceGUI elements are the building blocks that we'll arrange to create pages. They represent UI components like buttons, labels, text inputs, and more. The elements are classified into the following categories:

In the following sections, you'll code simple examples showcasing a sample of each category's graphical elements.

Text Elements

NiceGUI has a rich set of text elements that allow you to display text in several ways. This set includes some of the following elements:

The following demo app shows how to create some of these text elements:

python

from nicegui import ui

# Text elements
ui.label("Label")

ui.link("PythonGUIs", "https://pythonguis.com")

ui.chat_message("Hello, World!", name="PythonGUIs Chatbot")

ui.markdown(
    """
# Markdown Heading 1
**bold text**
*italic text*
`code`
"""
)

ui.restructured_text(
    """
==========================
reStructuredText Heading 1
==========================
**bold text**
*italic text*
``code``
"""
)

ui.html("<strong>bold text using HTML tags</strong>")

ui.run(title="NiceGUI Text Elements")

In this example, we create a simple web interface showcasing various NiceGUI text elements. The page shows several text elements, including a basic label, a hyperlink, a chatbot message, and formatted text using the Markdown and reStructuredText markup languages. Finally, it shows some raw HTML.

Each text element allows us to present textual content on the page in a specific way or format, which gives us a lot of flexibility for designing modern web UIs.

Run it! Your browser will open with a page that looks like the following.

Text Elements Demo App in NiceGUI

Control Elements

When it comes to control elements, NiceGUI offers a variety of them. As their name suggests, these elements allow us to control how our web UI behaves. Here are some of the most common control elements available in NiceGUI:

The demo app below showcases some of these NiceGUI control elements:

python

from nicegui import ui

# Control elements
ui.button("Button")

with ui.dropdown_button("Edit", icon="edit", auto_close=True):
    ui.item("Copy")
    ui.item("Paste")
    ui.item("Cut")

ui.toggle(["ON", "OFF"], value="ON")

ui.radio(["NiceGUI", "PyQt6", "PySide6"], value="NiceGUI").props("inline")

ui.checkbox("Enable Feature")

ui.slider(min=0, max=100, value=50, step=5)

ui.switch("Dark Mode")

ui.input("Your Name")

ui.number("Age", min=0, max=120, value=25, step=1)

ui.date(value="2025-04-11")

ui.run(title="NiceGUI Control Elements")

In this app, we include several control elements: a button, a dropdown menu with editing options (Copy, Paste, Cut), and a toggle switch between ON and OFF states. We also have a radio button group to choose between GUI frameworks (NiceGUI, PyQt6, PySide6), a checkbox labeled Enable Feature, and a slider to select a numeric value within a range.

Further down, we have a switch to toggle Dark Mode, a text input field for entering a name, a number input for providing age, and a date picker. Each of these controls has its own properties and methods that you can tweak to customize your web interfaces using Python and NiceGUI.

Note that the elements in this app don't perform any actions. Later in this tutorial, you'll learn about events and actions. For now, we're just showcasing some of the available graphical elements in NiceGUI.

Run it! You'll get a page that will look something like the following.

Control Elements Demo App in NiceGUI

Data Elements

If you're in the data science field, then you'll be thrilled with the variety of data elements that NiceGUI offers. You'll find elements for some of the following tasks:

Representing data in a tabular format
Creating plots and charts
Building different types of progress charts
Displaying 3D objects
Using maps
Creating tree and log views
Presenting and editing text in different formats, including plain text, code, and JSON

Here's a NiceGUI app where we use a table and a Matplotlib plot to present temperature measurements against time:

python

from matplotlib import pyplot as plt
from nicegui import ui

# Data elements
time = [1, 2, 3, 4, 5, 6]
temperature = [30, 32, 34, 32, 33, 31]

columns = [
    {
        "name": "time",
        "label": "Time (min)",
        "field": "time",
        "sortable": True,
        "align": "right",
    },
    {
        "name": "temperature",
        "label": "Temperature (°C)",
        "field": "temperature",
        "required": True,
        "align": "right",
    },
]
rows = [{"time": t, "temperature": temp} for t, temp in zip(time, temperature)]

ui.table(columns=columns, rows=rows, row_key="time")

with ui.pyplot(figsize=(5, 4)):
    plt.plot(time, temperature, "-o", color="blue", label="Temperature")
    plt.title("Temperature vs Time")
    plt.xlabel("Time (min)")
    plt.ylabel("Temperature (°C)")
    plt.ylim(25, 40)
    plt.legend()

ui.run(title="NiceGUI Data Elements")

In this example, we create a web interface that displays a table and a line plot. The data is stored in two lists: one for time (in minutes) and one for temperature (in degrees Celsius). These values are formatted into a table with columns for time and temperature. To render the table, we use the ui.table element.

Below the table, we create a Matplotlib plot of temperature versus time and embed it in the ui.pyplot element. The plot has a title, axis labels, and a legend.

Run it! You'll get a page that looks something like the following.

Data Elements Demo App in NiceGUI

Audiovisual Elements

NiceGUI also has elements that allow us to display audiovisual content in our web UIs. The audiovisual content may include some of the following:

Below is a small demo app that shows how to add a local image to your NiceGUI-based web application:

python

from nicegui import ui

with ui.image("./otje.jpg"):
    ui.label("Otje the cat!").classes("absolute-bottom text-subtitle2 text-center")

ui.run(title="NiceGUI Audiovisual Elements")

In this example, we use the ui.image element to display a local image in your NiceGUI app. The image will show a subtitle at the bottom.

NiceGUI elements provide the classes() method, which allows you to apply Tailwind CSS classes to the target element. To learn more about using CSS for styling your NiceGUI apps, check the Styling & Appearance section in the official documentation.

Run it! You'll get a page that looks something like the following.

Audiovisual Elements Demo App in NiceGUI

Laying Out Pages in NiceGUI

Laying out a GUI so that every graphical component is in the right place is a fundamental step in any GUI project. NiceGUI offers several layout elements that allow us to arrange graphical elements to build a nice-looking UI for our web apps.

Here are some of the most common NiceGUI layout elements:

Cards wrap another element in a frame.
Column arranges elements vertically.
Row arranges elements horizontally.
Grid organizes elements in a grid of rows and columns.
List displays a list of elements.
Tabs organize elements in dedicated tabs.

You'll find several other elements that allow you to tweak how your app's UI looks. Below is a demo app that combines a few of these layout elements to create a minimal but well-organized user profile form:

python

from nicegui import ui

with ui.card().classes("w-full max-w-3xl mx-auto shadow-lg"):
    ui.label("Profile Page").classes("text-xl font-bold")

    with ui.row().classes("w-full"):
        with ui.card():
            ui.image("./profile.png")

            with ui.card_section():
                ui.label("Profile Image").classes("text-center font-bold")
                ui.button("Change Image", icon="photo_camera")

        with ui.card().classes("flex-grow"):
            with ui.column().classes("w-full"):
                ui.input(placeholder="Your Name").classes("w-full")
                ui.select(["Male", "Female", "Other"]).classes("w-full")
                ui.input(placeholder="Eye Color").classes("w-full")
                ui.number(min=0, max=250, value=170, step=1).classes("w-full")
                ui.number(min=0, max=500, value=60, step=0.1).classes("w-full")

            with ui.row().classes("justify-end gap-2 q-mt-lg"):
                ui.button("Reset", icon="refresh").props("outline")
                ui.button("Save", icon="save").props("color=primary")

ui.run(title="NiceGUI Layout Elements")

In this app, we create a clean, responsive profile information page using a layout based on the ui.card element. We center the profile form and cap it at a maximum width for better readability on larger screens.

We organize the elements into two main sections:

A profile image card on the left and a form area on the right. The left section displays a profile picture using the ui.image element with a Change Image button underneath.
A series of input fields for personal information, including the name in a ui.input element, the gender in a ui.select element, the eye color in a ui.input element, and the height and weight in ui.number elements. At the bottom of the form, we add two buttons: Reset and Save.

We use consistent CSS styling throughout the layout to ensure proper spacing, shadows, and responsive controls. This ensures that the interface looks professional and works well across different screen sizes.

Run it! Here's how the form looks in the browser.

A Demo Profile Page Layout in NiceGUI

Handling Events and Actions in NiceGUI

In NiceGUI, you can handle events like mouse clicks, keystrokes, and similar interactions, just as you can in other Python GUI frameworks. Elements typically have arguments like on_click and on_change which are the most direct and convenient way to bind events to actions.

Here's a quick app that shows how to make a NiceGUI app perform actions in response to user events:

python

from nicegui import ui

def on_button_click():
    ui.notify("Button was clicked!")

def on_checkbox_change(event):
    state = "checked" if event.value else "unchecked"
    ui.notify(f"Checkbox is {state}")

def on_slider_change(event):
    ui.notify(f"Slider value: {event.value}")

def on_input_change(event):
    ui.notify(f"Input changed to: {event.value}")

ui.label("Event Handling Demo")

ui.button("Click Me", on_click=on_button_click)
ui.checkbox("Check Me", on_change=on_checkbox_change)
ui.slider(min=0, max=10, value=5, on_change=on_slider_change)
ui.input("Type something", on_change=on_input_change)

ui.run(title="NiceGUI Events & Actions Demo")

In this app, we first define four functions we'll use as actions. When we create the control elements, we use the appropriate argument to bind an event to a function. For example, in the ui.button element, we use the on_click argument, which makes the button call the associated function when we click it.

We do something similar with the other elements, but use different arguments depending on the element's supported events.

You can check the NiceGUI documentation for individual elements to learn about the specific events they can handle.

Using the on_* type of arguments is not the only way to bind events to actions in NiceGUI. You can also use the on() method, which allows you to attach event handlers manually. This approach is handy for less common events or when you want to attach multiple handlers to a single element.

Here's a quick example:

python

from nicegui import ui

def on_click(event):
    ui.notify("Button was clicked!")

def on_hover(event):
    ui.notify("Button was hovered!")

button = ui.button("Button")
button.on("click", on_click)
button.on("mouseover", on_hover)

ui.run()

In this example, we create a small web app with a single button that responds to two different events. When you click the button, the on_click() function triggers a notification. Similarly, when you hover the mouse over the button, the on_hover() function displays a notification.

To bind the events to the corresponding function, we use the on() method. The first argument is a string representing the name of the target event. The second argument is the function that we want to run when the event occurs.

Conclusion

In this tutorial, you've learned the basics of creating web applications with NiceGUI, a powerful Python library for building browser-based user interfaces.

You've explored common NiceGUI elements including text, controls, data, and audiovisual components. You've also learned how to arrange elements using layouts like cards, rows, and columns, and how to handle user events to make your apps interactive. This gives you the foundation to build modern and interactive web interfaces entirely in Python. For further exploration and advanced features, refer to the official NiceGUI documentation.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Getting Started With DearPyGui for GUI Development — Your First Steps With the DearPyGui Library for Desktop Python GUIs

2025-11-19T08:00:00+00:00

Getting started with a new GUI framework can feel daunting. This guide walks you through the essentials of DearPyGui—from installation and your first app to widgets, layouts, event handling, and plotting.

With DearPyGui, you can quickly build modern, high‑performance desktop interfaces using Python.

What Is DearPyGui?

DearPyGui is a GPU‑accelerated and cross‑platform GUI framework for Python, built on Dear ImGui with a retained‑mode Python API. It renders all UI using the GPU rather than native OS widgets, ensuring consistent, high‑performance UI across Windows, Linux, macOS, and even Raspberry Pi 4.

Note that official wheels for Raspberry Pi may lag behind. Users sometimes compile from source.

DearPyGui's key features include the following:

Modern, consistent UI across platforms
High performance via GPU rendering and C/C++ core
Customizable styles/themes and full developer tools
Over 70 widgets, including plots, node editors, and tables
Built-in demo app, theme inspector, logging, metrics, and debugger

This Python GUI framework is ideal for building interfaces ranging from simple utilities to real-time dashboards, data‑science tools, or interactive applications.

Installing DearPyGui

You can install DearPyGui from PyPI using pip:

$ pip install dearpygui

This command installs DearPyGui from PyPI.

Writing Your First DearPyGui Application

In general, DearPyGui apps follow the following structure:

dpg.create_context() — Initialize DearPyGui and call it before anything else
dpg.create_viewport() — Create the main application window or viewport
Define UI widgets within windows or groups — Add and configure widgets and containers to build your interface
dpg.setup_dearpygui() — Set up DearPyGui internals and resources before showing the viewport
dpg.show_viewport() — Make the viewport window visible to the user
dpg.start_dearpygui() — Start the DearPyGui main event and render loop
dpg.destroy_context() — Clean up and release all DearPyGui resources on exit

Here's a quick Hello World application displaying a window with basic widgets:

python

import dearpygui.dearpygui as dpg

def main():
    dpg.create_context()
    dpg.create_viewport(title="Viewport", width=300, height=100)

    with dpg.window(label="DearPyGui Demo", width=300, height=100):
        dpg.add_text("Hello, World!")

    dpg.setup_dearpygui()
    dpg.show_viewport()
    dpg.start_dearpygui()
    dpg.destroy_context()

if __name__ == "__main__":
    main()

Inside main(), we initialize the library with dpg.create_context(), create a window (viewport) via dpg.create_viewport(), define the GUI, set up the library with dpg.setup_dearpygui(), show the viewport with dpg.show_viewport(), and run the render loop using dpg.start_dearpygui(). When you close the window, dpg.destroy_context() cleans up resources.

You define the GUI itself inside a dpg.window() context block, which parents a text item with the label "Hello, World!".

Always follow the lifecycle order: create context → viewport → setup → show → start → destroy. Otherwise, the app may crash.

Run it! Here's what your first DearPyGui app looks like.

DearPyGui first app

Exploring DearPyGui Widgets

DearPyGui includes a wide variety of widgets for building Python GUIs:

Basic widgets, including buttons, text input, sliders, and checkboxes
Containers like windows, groups (horizontal and vertical grouping), tabs, collapsing headers, and menus
Interactive widgets, such as color pickers, combo boxes, tables, and menus

Here's an example that showcases some commonly used DearPyGui widgets:

python

import dearpygui.dearpygui as dpg

def main():
    dpg.create_context()
    dpg.create_viewport(title="Widgets Demo", width=400, height=450)

    with dpg.window(
        label="Common DearPyGui Widgets",
        width=380,
        height=420,
        pos=(10, 10),
    ):
        dpg.add_text("Static label")
        dpg.add_input_text(
            label="Text Input",
            default_value="Type some text here...",
            tag="widget_input",
        )
        dpg.add_button(label="Click Me!")
        dpg.add_checkbox(label="Check Me!")
        dpg.add_radio_button(
            ("DearPyGui", "PyQt6", "PySide6"),
        )

        dpg.add_slider_int(
            label="Int Slider",
            default_value=5,
            min_value=0,
            max_value=10,
        )
        dpg.add_slider_float(
            label="Float Slider",
            default_value=0.5,
            min_value=0.0,
            max_value=1.0,
        )

        dpg.add_combo(
            ("DearPyGui", "PyQt6", "PySide6"),
            label="GUI Library",
        )
        dpg.add_color_picker(label="Pick a Color")
        dpg.add_progress_bar(
            label="Progress",
            default_value=0.5,
            width=250,
        )

    dpg.setup_dearpygui()
    dpg.show_viewport()
    dpg.start_dearpygui()
    dpg.destroy_context()

if __name__ == "__main__":
    main()

This code uses the following functions to add the widgets to the GUI:

add_text(): A label for static text or instructions
add_input_text(): A single‑line text entry field
add_button(): A clickable button for user actions
add_checkbox(): A toggle for boolean values
add_radio_button(): A group of radio buttons for selecting one from several options
add_slider_int(), add_slider_float(): Sliders with integer and floating-point steps
add_combo(): A dropdown selection widget
add_color_picker(): A color picker widget
add_progress_bar(): A progress bar widget to display visual progress

Run it! Here's what the app will look like.

DearPyGui basic widgets

Laying Out Your DearPyGui Interface

By default, DearPyGui stacks widgets vertically. However, additional positioning options include the following:

Horizontal grouping using with dpg.group(horizontal=True):
Vertical spacing using dpg.add_spacer()
Indentation using the per-item indent keyword argument, like in dpg.add_checkbox(label="Option A", indent=30) or after creation with dpg.configure_item(tag, indent=30)
Absolute positioning via pos=(x, y) when creating items, or with dpg.set_item_pos(tag, (x, y)) after creation

Widgets go inside containers like dpg.window(). You can nest containers to build complex GUI layouts:

python

import dearpygui.dearpygui as dpg

def main():
    dpg.create_context()
    dpg.create_viewport(title="Layout Demo", width=520, height=420)

    with dpg.window(
        label="Layout Demo",
        width=500,
        height=380,
        pos=(10, 10),
    ):
        dpg.add_text("1) Vertical layout:")
        dpg.add_button(label="Top")
        dpg.add_button(label="Middle")
        dpg.add_button(label="Bottom")

        dpg.add_spacer(height=12)

        dpg.add_text("2) Horizontal layout:")
        with dpg.group(horizontal=True):
            dpg.add_button(label="Left")
            dpg.add_button(label="Center")
            dpg.add_button(label="Right")

        dpg.add_spacer(height=12)

        dpg.add_text("3) Indentation:")
        dpg.add_checkbox(label="Indented at creation (30px)", indent=30)
        dpg.add_checkbox(label="Indented after creation (35px)", tag="indent_b")
        dpg.configure_item("indent_b", indent=35)

        dpg.add_spacer(height=12)

        dpg.add_text("4) Absolute positioning:")
        dpg.add_text("Positioned at creation: (x=100, y=300)", pos=(100, 300))
        dpg.add_text("Positioned after creation: (x=100, y=320)", tag="move_me")
        dpg.set_item_pos("move_me", (100, 320))

    dpg.setup_dearpygui()
    dpg.show_viewport()
    dpg.start_dearpygui()
    dpg.destroy_context()

if __name__ == "__main__":
    main()

In this example, we create an app that showcases basic layout options in DearPyGui. The first section of widgets shows the default vertical stacking by adding three buttons one after another. Then, you use dpg.add_spacer(height=12) to insert vertical whitespace between sections.

Then, we create a horizontal row of buttons with dpg.group(horizontal=True), which groups items side-by-side. Next, we have an indentation section that demonstrates how to indent widgets at creation (indent=30) and after creation using dpg.configure_item().

Finally, we use absolute positioning by placing one text item at a fixed coordinate using pos=(100, 300) and moving another after creation with dpg.set_item_pos(). These patterns are all part of DearPyGui's container and item-configuration model, which we can use to arrange the widgets in a user-friendly GUI.

Run it! You'll get a window like the following.

DearPyGui layouts

Handling Events with DearPyGui Callbacks

DearPyGui uses callbacks to handle events. Most widgets accept a callback argument, which is executed when we interact with the widget itself.

The example below provides a text input and a button. When we click the button, it opens a dialog showing the input text:

python

import dearpygui.dearpygui as dpg

def on_click_callback(sender, app_data, user_data):
    text = dpg.get_value("input_text")
    dpg.set_value("dialog_text", f'You typed: "{text}"')
    dpg.configure_item("dialog", show=True)

def main() -> None:
    dpg.create_context()
    dpg.create_viewport(title="Callback Example", width=270, height=120)

    with dpg.window(label="Callback Example", width=250, height=80, pos=(10, 10)):
        dpg.add_text("Type something and press Click Me!")
        dpg.add_input_text(label="Input", tag="input_text")
        dpg.add_button(label="Click Me!", callback=on_click_callback)
        with dpg.window(
            label="Dialog",
            modal=True,
            show=False,
            width=230,
            height=80,
            tag="dialog",
            no_close=True,
            pos=(10, 10),
        ):
            dpg.add_text("", tag="dialog_text")
            dpg.add_button(
                label="OK",
                callback=lambda s, a, u: dpg.configure_item("dialog", show=False),
            )

    dpg.setup_dearpygui()
    dpg.show_viewport()
    dpg.start_dearpygui()
    dpg.destroy_context()

if __name__ == "__main__":
    main()

The button takes the on_click_callback() callback as an argument. When we click the button, DearPyGui invokes the callback with three standard arguments:

sender, which holds the button's ID
app_data, which holds extra data specific to certain widgets
user_data, which holds custom data you could have supplied

Inside the callback, we pull the current text from the input widget using dpg.get_value(), and finally, we display the input text in a modal window.

Run it! You'll get a window like the following.

DearPyGui callbacks

To see this app in action, type some text into the input and click the Click Me! button.

Creating Plots and Charts with DearPyGui

DearPyGui comes with powerful plotting capabilities built in. It includes high-performance plots such as lines, bars, scatter plots, and histograms. These plots allow interactive zoom and pan and real-time data updates, making them excellent for scientific visualizations and data dashboards.

Here's an example of how to create a line plot using DearPyGui's plotting widgets:

python

import dearpygui.dearpygui as dpg
import numpy as np

def main() -> None:
    dpg.create_context()
    dpg.create_viewport(title="Plotting Example", width=420, height=320)

    x = np.linspace(0, 2 * np.pi, 100)
    y1 = np.sin(x)
    y2 = np.cos(x)

    with dpg.window(label="Plot Window", width=400, height=280, pos=(10, 10)):
        with dpg.plot(label="Sine and Cosine Plot", height=200, width=360):
            dpg.add_plot_legend()
            dpg.add_plot_axis(dpg.mvXAxis, label="X")
            with dpg.plot_axis(dpg.mvYAxis, label="Y"):
                dpg.add_line_series(x.tolist(), y1.tolist(), label="sin(x)")
                dpg.add_line_series(x.tolist(), y2.tolist(), label="cos(x)")

    dpg.setup_dearpygui()
    dpg.show_viewport()
    dpg.start_dearpygui()
    dpg.destroy_context()

if __name__ == "__main__":
    main()

In this example, we create two line series: sine and cosine curves. To plot them, we use NumPy‑generated data. We also add X and Y axes, plus a legend for clarity. You can update the series in a callback for live data dashboards.

Run it! You'll get a plot like the one shown below.

DearPyGui plotting demo

Conclusion

DearPyGui offers a powerful and highly customizable GUI toolkit for building desktop applications in Python. With a rich widget set, interactive plotting, node editors, and built-in developer tools, it's a great choice for both simple utilities and complex interfaces.

In this tutorial, you learned how to install DearPyGui, create your first application, work with widgets and layouts, handle events with callbacks, and create interactive plots. Try building your own DearPyGui app and experimenting with these features to create professional Python desktop GUIs!

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Kivy's Complex Widgets — Learn How to Use Kivy's Complex UX Widgets in Your Apps

2025-04-28T06:00:00+00:00

Kivy is a powerful framework for developing multi-touch GUI applications using Python. It provides a set of rich built-in widgets which you can use to build complex GUI applications.

In a previous tutorial we covered the basic Kivy widgets such as text inputs, buttons and checkboxes. In this tutorial, we will take things further, exploring some of the more complex widgets that Kivy provides. These include: Bubble, DropDown, FileChooser, Popup, Spinner, RecycleView, TabbedPanel, VideoPlayer, and VKeyboard. With these complex Kivy widgets, you can add advanced features to your Python GUI apps.

Writing an Outline Kivy App

We'll start this tutorial with a simple application skeleton, which we will then modify below. Save the following code in a file named app.py:

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout

class WidgetNameApp(App):
    title = "WidgetName Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (360, 640)

        root = BoxLayout()

        return root

WidgetNameApp().run()

Here, we've created a Kivy application with an empty window. The BoxLayout acts as the root widget, this will act as the container to add our complex widgets to. The build() method sets the window's background color to a dark teal shade and adjusts the window size to 360x640 pixels, which is a mobile-friendly size.

To learn more about creating your first Kivy app, check out the Getting Started With Kivy for GUI Development tutorial.

Providing Option Selections With the Kivy `Spinner` Widget

The Kivy Spinner widget is a dropdown selector that allows users to choose one option from multiple choices. This is ideal when working with a list of simple text choices. Below is an example that builds a Spinner that lets you select from different parts of this website.

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.floatlayout import FloatLayout
from kivy.uix.spinner import Spinner

class SpinnerApp(App):
    title = "Spinner Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (300, 300)

        root = FloatLayout()

        # Create the Spinner
        spinner = Spinner(
            text="Home",
            values=("Home", "Latest", "FAQ", "Forum", "Contact", "About"),
            size_hint=(None, None),
            size=(200, 70),
            pos_hint={"center_x": 0.2, "center_y": 0.9},
            sync_height=True,
        )

        root.add_widget(spinner)

        return root

SpinnerApp().run()

The Spinner widget works as a simple dropdown list, allowing users to select one option from multiple text choices. We've set the Spinner to start with "Home" as the default text and provided other options ("Latest", "FAQ", "Forum", "Contact", and "About") as a list of values.

You need to repeat the "Home" option in values so that you don't lose it when you select another option.

Run it! You'll get an app that looks as shown below.

A Kivy app showing a Spinner Widget

The dropdown spinner allows users to select from predefined choices. You can use this widget to create elements that work like a dropdown list, optimizing space and providing a clean UI.

Providing Options With the Kivy `DropDown` List Widget

The Kivy DropDown widget provides a more complex menu component that allows users to choose from multiple options. Like the Spinner, this provides an intuitive way for users to select from a set of choices, but here you can display more than just text. This makes it more complex to use, but allows for more flexibility.

Below is an example of using the DropDown widget to create a dropdown list that lets you select your favorite Python GUI library, displayed on a series of Button objects.

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button
from kivy.uix.dropdown import DropDown

class DropDownApp(App):
    title = "DropDown Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (200, 200)

        root = BoxLayout(orientation="vertical", padding=10, spacing=10)

        # Create a dropdown with 4 buttons
        dropdown = DropDown()
        for item in ["Kivy", "PyQt6", "PySide6", "Tkinter"]:
            option_btn = Button(text=item, size_hint_y=None, height=50, width=150)
            option_btn.bind(on_release=lambda btn: dropdown.select(btn.text))
            dropdown.add_widget(option_btn)

        # Create a main button to show the dropdown
        button = Button(
            text="Library",
            size_hint=(None, None),
            size=(150, 50),
        )
        button.bind(on_release=dropdown.open)
        dropdown.bind(
            on_select=lambda instance, text: setattr(button, "text", text),
        )
        root.add_widget(button)
        return root

DropDownApp().run()

In this example, we have a DropDown widget that lets the user select a library from a list of options. You populate the dropdown with four options "Kivy", "PyQt6", "PySide6", and "Tkinter", which are displayed in Button objects.

We set each button to trigger the dropdown.select() method when clicked, passing the button's text as the selected value.

Then, we anchor the dropdown to a Library button. When we press the Library button, the dropdown menu opens, displaying the options. Once we select an option, the on_select event updates the main button's text to reflect the chosen library.

Run it! You'll get a window with a dropdown list in the lower left corner. Click in the dropdown widget to change the current selection.

A Kivy app showing a DropDown widget

Accessing Files With the Kivy `FileChooser` Widget

The Kivy filechooser module provides classes for describing, displaying and browsing file systems. In this module there are two ready-made widget views which present the file system as either a list, or as icons. The example below demonstrates both FileChooserIconView and FileChooserListView in action.

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.filechooser import FileChooserIconView, FileChooserListView

class FileChooserApp(App):
    title = "FileChooser Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (360, 640)

        root = BoxLayout(orientation="vertical")

        # Create icon-view and list-view file choosers
        filechooser_icons = FileChooserIconView()
        filechooser_list = FileChooserListView()

        root.add_widget(filechooser_icons)
        root.add_widget(filechooser_list)

        return root

FileChooserApp().run()

In this example, we create file chooser widgets to browse and select files using two different views:

Icon view (FileChooserIconView)
List view (FileChooserListView)

The icon view displays files as wrapped rows of icons, clicking on a folder icon will navigate down into that folder. The list view presents them in a list-tree like format, where clicking on a folder will show files and folders nested under it.

Run it! On macOS, you'll see a window that looks something like the following. Try clicking on the folder icons and entries in the list view to see how navigation works in the two examples.

A Kivy app showing file chooser widgets

Building Quick Dialogs With the Kivy `Popup` Widget

The Kivy Popup widget allows us to display modal dialogs with custom content, layouts and widgets. Popups can be used to show messages or ask for input. The following example displays a simple popup message with a title, message and OK button.

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button
from kivy.uix.floatlayout import FloatLayout
from kivy.uix.label import Label
from kivy.uix.popup import Popup

class PopupApp(App):
    title = "Popup Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (400, 400)

        root = FloatLayout()

        button = Button(
            text="Open Popup",
            on_press=lambda x: self.show_popup(),
            size_hint=(None, None),
            size=(200, 50),
            pos_hint={"center_x": 0.5, "center_y": 0.5},
        )

        root.add_widget(button)

        return root

    def show_popup(self):
        # Create and show the Popup
        popup = Popup(
            title="Info",
            size_hint=(0.6, 0.6),
            size=(300, 300),
            auto_dismiss=False,
        )

        layout = BoxLayout(orientation="vertical", spacing=10, padding=10)

        message = Label(text="Hello, World!")

        ok_button = Button(text="OK", size_hint=(None, None), size=(80, 40))
        ok_button.bind(on_release=popup.dismiss)

        layout.add_widget(message)
        layout.add_widget(ok_button)

        popup.content = layout
        popup.open()

PopupApp().run()

In this example, you create a Popup widget that displays information as a modal dialog. When the user clicks the Open Popup button, the show_popup() method is triggered, creating a Popup that occupies 60% of the screen in both directions.

We set auto_dismiss to False, which means the popup won't close if we click outside of it. The popup contains the Hello, World! message and an OK button. When we click the button, we dismiss (close) the popup. Popups are effective for displaying alerts, confirmations, or other information in a Kivy app.

Run it! You'll get a window with a button labeled "Open Popup". Click on the Open Popup button to display the popup window.

A Kivy app showing a popup dialog

Creating Contextual Popups With the Kivy `Bubble` Widget

The Kivy Bubble widget is a UI element commonly used for contextual popups, tooltips, or chat applications. Below is a quick Kivy application that shows some text and lets you click on it to change its format. We'll start by importing the necessary objects and subclassing the Bubble class:

python

from kivy.app import App
from kivy.core.window import Window
from kivy.metrics import dp
from kivy.uix.bubble import Bubble, BubbleButton, BubbleContent
from kivy.uix.floatlayout import FloatLayout
from kivy.uix.label import Label

class FormattingBubble(Bubble):
    def __init__(self, target_text, **kwargs):
        super().__init__(**kwargs)

        # Customizing the bubble
        self.size_hint = (None, None)
        self.size = (dp(120), dp(50))
        self.arrow_pos = "top_mid"
        self.orientation = "horizontal"
        self.target_label = target_text

        # Add formatting buttons
        bold_btn = BubbleButton(text="Bold")
        italic_btn = BubbleButton(text="Italic")
        bold_btn.bind(on_release=lambda x: self.on_format("bold"))
        italic_btn.bind(on_release=lambda x: self.on_format("italic"))

        # Add the buttons to the bubble
        bubble_content = BubbleContent()
        bubble_content.add_widget(bold_btn)
        bubble_content.add_widget(italic_btn)

        self.add_widget(bubble_content)

    def on_format(self, format_type):
        if format_type == "bold":
            self.target_label.text = f"[b]{self.target_label.text}[/b]"
        elif format_type == "italic":
            self.target_label.text = f"[i]{self.target_label.text}[/i]"
        self.parent.remove_widget(self)

class BubbleApp(App):
    title = "Bubble Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (360, 640)

        root = FloatLayout()

        self.text = Label(
            text="Click this text to apply formatting",
            size_hint=(0.8, 0.2),
            pos_hint={"center_x": 0.5, "center_y": 0.5},
            markup=True,
        )
        self.text.bind(on_touch_down=self.show_bubble)

        root.add_widget(self.text)
        root.bind(on_touch_down=self.dismiss_bubbles)

        return root

    def show_bubble(self, instance, touch):
        if instance.collide_point(*touch.pos):
            self.remove_all_bubbles()
            bubble = FormattingBubble(target_text=self.text)
            bubble.pos = (
                touch.x - bubble.width / 2, touch.y - bubble.height - dp(10)
            )
            self.root.add_widget(bubble)

    def dismiss_bubbles(self, instance, touch):
        if instance == self.root and not self.text.collide_point(*touch.pos):
            self.remove_all_bubbles()

    def remove_all_bubbles(self):
        for widget in self.root.children[:]:
            if isinstance(widget, FormattingBubble):
                self.root.remove_widget(widget)
                return

BubbleApp().run()

The FormattingBubble class inherits from Bubble and provides text formatting options for a label. It initializes with a specific size, arrow position, and horizontal layout. The bubble will contain two buttons: Bold and Italic. When pressed, these buttons apply the respective formatting to the target text by triggering the on_format() method. This method wraps the text in Kivy's markup tags [b]...[/b] for bold and [i]...[/i] for italic.

The BubbleApp class represents the Kivy application. It sets up a FloatLayout with a centered Label displaying a message. When the user taps the label, the show_bubble() method creates and positions a FormattingBubble above the tapped location.

The app also ensures that only one bubble is visible at a time by removing existing ones before showing a new one. Additionally, tapping outside the label dismisses any active bubbles using the dismiss_bubbles() method.

Run it! The app features a dark teal background and a mobile-friendly window size. The Bubble widget appears when we click the text.

A Kivy app showing a Bubble widget

Displaying Large Data Sets With the Kivy `RecycleView` Widget

The Kivy RecycleView widget efficiently displays large data sets by recycling views or graphical elements. Instead of creating a widget for every item in the dataset, RecycleView reuses a small number of widgets to display visible items only, significantly improving performance.

To illustrate, let's create a view that lets you inspect a database of employee profiles. The data is stored in a CSV file that looks like the following:

csv

name,job,department
John Smith,Developer,IT
Jane Doe,Designer,Graphics
Anne Frank,Artist,Painting
David Lee,Engineer,Civil
Ella Brown,Doctor,Medical
Frank Thomas,Chef,Culinary
Henry Ford,Driver,Transport
Nathan Young,Consultant,Business
Olivia King,Manager,Administration
Peter Wright,Director,Management
Queen Bell,President,Executive
Walter Thompson,Assistant,Support
Xena Garcia,Associate,Associate
Zack Harris,Consultant,Consulting

You can read and load this data with the csv module. To visualize the data, you can create a view with the RecycleView widget. For the individual views, you can use the Button widget, which will let you display the employee's profile:

python

import csv

from kivy.app import App
from kivy.core.window import Window
from kivy.metrics import dp
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button
from kivy.uix.label import Label
from kivy.uix.popup import Popup
from kivy.uix.recycleboxlayout import RecycleBoxLayout
from kivy.uix.recycleview import RecycleView

class EmployeesView(RecycleView):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.employees_data = self._read_from_csv()

        # Load the employees data into the data attribute
        self.data = [
            {
                "text": f"{employee['name']}",
                "on_release": self._create_callback(employee["name"]),
            }
            for employee in self.employees_data
        ]

        layout_manager = RecycleBoxLayout(
            default_size=(None, dp(56)),
            default_size_hint=(1, None),
            size_hint_y=None,
            orientation="vertical",
        )
        layout_manager.bind(minimum_height=layout_manager.setter("height"))

        self.add_widget(layout_manager)
        self.viewclass = "Button"

    def _create_callback(self, name):
        return lambda: self.on_button_click(name)

    def _read_from_csv(self):
        with open("employees.csv", mode="r") as file:
            return [row for row in csv.DictReader(file)]

    def on_button_click(self, name):
        popup = Popup(
            title=f"{name}'s Profile",
            size_hint=(0.8, 0.5),
            size=(300, 300),
            auto_dismiss=False,
        )
        employees_data = [
            employee for employee in self.employees_data if employee["name"] == name
        ]
        profile = "\n".join(
            [f"{key.capitalize()}: {value}" for key, value in employees_data[0].items()]
        )
        layout = BoxLayout(orientation="vertical", spacing=10, padding=10)
        message = Label(text=profile)
        ok_button = Button(text="OK", size_hint=(None, None))
        ok_button.bind(on_release=popup.dismiss)
        layout.add_widget(message)
        layout.add_widget(ok_button)
        popup.content = layout
        popup.open()

class RecycleViewApp(App):
    title = "RecycleView Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (360, 640)

        return EmployeesView()

RecycleViewApp().run()

In this example, we subclass RecycleView to display the list of employees loaded from a CSV file. The _read_from_csv() method opens the file and reads the data using the csv.DictReader() class, which converts each CSV line into a dictionary whose keys come from the file header line.

The data attribute is key for the app to work because it'll hold the data that we want to display. To arrange widgets in a RecycleView, we use a RecycleBoxLayout. The viewclass attribute lets us set the widget that we'll use to display each data item.

It's important to note that for the RecycleView to work properly, we should set viewclass at the end when the data is already loaded and the layout is set up.

Then, we populate the RecycleView view with buttons, each displaying an employee's name. Clicking a button triggers _create_callback(), which generates a callback that opens a popup displaying the selected employee's profile details.

Run it! You'll get a nice-looking window listing the employees. Click a button to view the associated employee's profile. Scroll down to load more profiles.

A Kivy app showing a RecycleView Widget

Building Tabbed UIs With the Kivy `TabbedPanel` Widget

The Kivy TabbedPanel widget lets us organize content into tabs, to improve navigation and optimize the use of space. This is commonly used in settings dialogs where there are lots of options available.

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.label import Label
from kivy.uix.tabbedpanel import TabbedPanel, TabbedPanelHeader

class TabbedPanelApp(App):
    title = "TabbedPanel Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (360, 640)

        # Create the TabbedPanel
        root = TabbedPanel(do_default_tab=False)

        # Create the tabs
        general_tab = TabbedPanelHeader(text="General")
        general_content = BoxLayout(orientation="vertical", padding=10, spacing=10)
        general_content.add_widget(Label(text="General Settings", font_size=40))
        general_tab.content = general_content
        root.add_widget(general_tab)

        editor_tab = TabbedPanelHeader(text="Editor")
        editor_content = BoxLayout(orientation="vertical", padding=10, spacing=10)
        editor_content.add_widget(Label(text="Editor Settings", font_size=40))
        editor_tab.content = editor_content
        root.add_widget(editor_tab)

        profile_tab = TabbedPanelHeader(text="Profile")
        profile_content = BoxLayout(orientation="vertical", padding=10, spacing=10)
        profile_content.add_widget(Label(text="User Profile", font_size=40))
        profile_tab.content = profile_content
        root.add_widget(profile_tab)

        return root

TabbedPanelApp().run()

In this example, we create a Kivy app that shows a tabbed interface using the TabbedPanel widget. It disables the default tab and manually adds three tabs: General, Editor, and Profile, each represented by a TabbedPanelHeader object.

Inside the tabs, we place a BoxLayout to hold a label that displays a description as a placeholder tab content. Tabs allow us to organize content into visually distinct sections within an application's UI.

Run it! Your app will display three tabs. When you click the tab header, the app shows the tab's content. The active tab shows a light blue line at the bottom.

A Kivy app showing a TabbedPanel Widget

Try and add some more widgets to each tab panel.

Allowing User Input With the Kivy `VKeyboard` Widget

The Kivy VKeyboard widget allows you to create a virtual keyboard that is useful for touchscreen applications that require the user to type in text. Below is a short app that demonstrates a virtual keyboard in action. When you type text using the keyboard, it is displayed on the label.

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.label import Label
from kivy.uix.vkeyboard import VKeyboard

class VKeyboardApp(App):
    title = "VKeyboard Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (360, 640)

        root = BoxLayout(orientation="vertical")

        self.display_label = Label(text="Type in!", font_size=40)
        root.add_widget(self.display_label)

        # Create the virtual keyboard
        keyboard = VKeyboard(size_hint=(1, 0.4))
        keyboard.bind(on_key_up=self.keyboard_on_key_up)
        root.add_widget(keyboard)

        return root

    def keyboard_on_key_up(self, *args):
        keycode = args[1]
        text = args[2]
        if keycode == "backspace":
            if (
                len(self.display_label.text) > 0
                and self.display_label.text != "Type in!"
            ):
                self.display_label.text = self.display_label.text[:-1]
                if self.display_label.text == "":
                    self.display_label.text = "Type in!"
        elif keycode == "spacebar":
            if self.display_label.text == "Type in!":
                self.display_label.text = " "
            else:
                self.display_label.text += " "
        elif keycode in {"enter", "shift", "alt", "ctrl", "escape", "tab", "capslock"}:
            pass
        else:
            if self.display_label.text == "Type in!":
                self.display_label.text = text
            else:
                self.display_label.text += text

VKeyboardApp().run()

In this example, we manually add a virtual keyboard to our app's interface using the VKeyboard widget and display typed text using a label.

When a key is released, the keyboard_on_key_up() method processes the input. Printable characters are appended to the label text. Backspace removes the last character, and the spacebar inserts a space.

You typically wouldn't use the VKeyboard widget as in the example above. Input widgets, like TextInput, will automatically bring up the virtual keyboard when focused on mobile devices.

We ignore special keys like Enter, Shift, Alt, Ctrl, and Escape. This allows us to interact with a virtual keyboard and see the input displayed dynamically in the label.

Run it! A virtual keyboard appears at the button of the app's window, allowing you to enter text in touch-based devices. When you type on the virtual keyboard at the bottom of the app's window, the label reflects what you've typed.

A Kivy app showing a VKeyboard Widget

Conclusion

Kivy provides a rich set of complex UX widgets that you can use to create cross-platform Python GUI applications. In this tutorial, you learned how to use the Spinner for dropdown selections, DropDown for custom menus, FileChooser for file browsing, Popup for modal dialogs, Bubble for contextual popups, RecycleView for efficiently displaying large data sets, TabbedPanel for tabbed interfaces, and VKeyboard for virtual keyboard input. Using the examples above as inspiration, you should now be able to integrate these complex Kivy widgets into your own Python apps. See if you can extend these examples further, adding more widgets or functionality to them.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Getting Started with Streamlit — Build your first Streamlit app and explore some basic features

2025-04-02T06:00:00+00:00

Streamlit is an open-source Python library that makes it easy to create and share custom web apps for machine learning and data science. In this tutorial we'll take a first look at Streamlit, walking through how to install it, set it up, and build a simple interactive app with Python.

Installing Streamlit

Because Streamlit is a third-party library, we need to install it on our system before using it. Streamlit can be easily installed using pip. Open your terminal (Mac/Linux) or Command Prompt (Windows) and type the following command:

pip install streamlit

This command will download and install Streamlit and its dependencies. Once the installation is complete, we can create a simple Streamlit app.

Open your editor and create a file named app.py. This file will be our main Python file to write and edit the Streamlit app. In order to make sure that Streamlit is running on our system, let us import it and run the app.

python

import streamlit as st

To run the app, open the terminal in the same directory and enter the following command:

streamlit run app.py

This command will open a new tab in your default browser. It will be empty right now, but this is where we'll be building the interface of our app.

Adding Titles, Headings, and Paragraphs in Streamlit

Streamlit allows you to create clean and structured web apps with ease, making it perfect for data visualization and interactive dashboards. One of the key features that make Streamlit user-friendly is its ability to format text with titles, headings, and paragraphs. Let's walk through how to add these elements to your Streamlit app.

Adding a Title

Titles in Streamlit are added using the st.title() function. This function displays the text in a large, bold font, ideal for the heading of your app.

python

import streamlit as st

st.title("This is the title of our app")

Save the changes and refresh the browser tab to see the changes. This will create a large, centered title at the top of your app.

The streamlit application open in your browser

Adding Headings

Streamlit provides several levels of headings to structure your content, similar to HTML's <h1> to <h6> tags. You can use st.header() and st.subheader() for the primary and secondary sections, respectively.

python

import streamlit as st

st.title("This is the title of our app")
st.header("This is a Header")
st.subheader("This is a Subheader")

In this code, we use st.header() to create the prominent heading, ideal for section titles. Then we call st.subheader() to create a slightly smaller heading, suitable for subsections under a header.

Save the changes and refresh the browser. It will create the following changes to our app.

Subheaders added through Streamlit

Adding Paragraphs

To add regular text or paragraphs, use the st.write() function. This function can handle text, Markdown, and even complex objects like data frames.

python

import streamlit as st

st.title("This is the title of our app")
st.header("This is a Header")
st.subheader("This is a Subheader")
st.write("You can write text here and it will appear as a paragraph.")

Save the change and refresh the browser tab.

Paragraph text added through Streamlit

Adding Interactive Buttons to a Streamlit App

Buttons are fundamental interactive elements in any web application. Streamlit provides simple yet versatile options for adding buttons to your app, enabling users to trigger actions, navigate between sections, or submit data. This section will guide you through adding different kinds of buttons to your Streamlit app and how to handle user interactions.

Basic Button

The simplest button in Streamlit is created using the st.button() function. It generates a clickable button that can trigger specific actions.

python

import streamlit as st

st.title("This is the title of our app")

st.button("Click Me")

A button in your Streamlit UI

Notice that a small button is shown in our app. Right now, it is a static button which means nothing will happen when we click it. To make it interactive, we have to use conditional statements. When the button is clicked in a Streamlit app, it returns a True value. So, we can use this in our conditional statement.

python

import streamlit as st

st.title("This is the title of our app")

button = st.button("Click Me")
if button: # button is True if clicked
    st.write("You clicked the button")

We create the button by calling st.button() passing in the label as a string "Click Me". If the button is clicked in the browser, the value of button will be True and the if branch will be executed: outputting the message to the UI.

A button with clickable behavior

Download Button

You can create a download button using st.download_button(), which allows users to download files directly from your app.

python

import streamlit as st

st.title("This is the title of our app")

text_file_content = "This is a sample text file. This content will be downloaded as a text file."

st.download_button(
    label="Download Text File",
    data=text_file_content,
    file_name="sample.txt",
    mime="text/plain"
)

In this code we use st.download_button() to create a button that, when clicked, lets users download a file. The parameters of the download button are:

label: The text on the button.
data: The content to be downloaded.
file_name: The name of the file.
mime: The MIME type of the file (e.g., text/plain).

This gives the following updated UI:

A download button

Radio Buttons for Options

Radio buttons allow users to select one option from a set of choices. Streamlit provides this functionality using st.radio().

python

import streamlit as st

st.title("This is the title of our app")

choice = st.radio("Choose an option:", ["Option 1", "Option 2", "Option 3"])

if choice == "Option 1":
    st.write("You selected Option 1")
elif choice == "Option 2":
    st.write("You selected Option 2")
else:
    st.write("You selected Option 3")

In this case we used st.radio() to create a set of radio buttons. The selected option is stored in the variable choice, which you can use to control the app's behavior.

This will give the following result:

Radio buttons in your Streamlit UI

Adding a Slider to Your Streamlit App

A slider in Streamlit is a UI element that allows users to select a value by moving a handle along a track. This is particularly useful for adjusting parameters in data visualizations, setting thresholds, or selecting ranges for filtering data.

Streamlit provides st.slider() which you can use to add sliders to your app. This function supports both single-value and range sliders.

A single value slider allows users to select a single value within a specified range. Here's how to add a simple slider to your Streamlit app:

python

import streamlit as st

st.title("This is the title of our app")

age = st.slider("Select your age:", 0, 100, 25)

st.write(f"Your age is: {age}")

Here we've used st.slider() to add a slider to your app. The first argument is the label for the slider. The next two arguments define the minimum and maximum values, while the last argument is the default value the slider starts at.

A simple slider in your Streamlit UI

Streamlit also allows you to create a range slider, where users can select an upper and lower bound of a range. This is useful for filtering where you want to select some data within the given range. You can add a range slider to your application as follows:

python

import streamlit as st

st.title("This is the title of our app")

start, end = st.slider("Select a range of values:", 0, 100, (20, 80))

st.write(f"Selected range: {start} to {end}")

A range slider in your Streamlit UI

Here, st.slider() is used to create a range slider by passing a tuple (20, 80) as the default value. The tuple represents the initial start and end values of the slider range.

When you run this app, the slider will allow users to select a range between 0 and 100, starting with a default range from 20 to 80. The selected range is then displayed on the app. The initial and returned tuple represent the selected range in the slider.

Don't confuse this with a Python range! Unlike a Python range, they are inclusive: that is, if you select 80 as the upper bound, then 80 will be returned (not 79).

Dropdown menus are a powerful and versatile UI component that allows users to select an option from a predefined list. Streamlit makes it easy to add dropdown menus to your web app, providing an intuitive way for users to interact with your data or application.

Streamlit provides a straightforward way to add dropdown menus through the st.selectbox() function. This function not only adds a dropdown to your app but also allows you to capture the selected value for further processing. Let's start with a simple example where users can choose their favorite fruit from a list:

python

import streamlit as st

st.title("This is the title of our app")

fruit = st.selectbox("Select your favorite fruit:", ["Apple", "Banana", "Orange", "Grapes", "Mango"])

st.write(f"You selected: {fruit}")

A dropdown box in your Streamlit UI

In the above code we used st.selectbox() to create a dropdown menu. The first argument is the label for the dropdown and the second argument is the list of options users can choose from.

A sidebar is an additional panel that appears on the left side of the app. It can be used to house interactive widgets like sliders, buttons, and dropdowns, or to display information that should be easily accessible throughout the app.

This allows the main part of the app to focus on displaying results, visualizations, or other content, while the sidebar handles user inputs and navigation.

Streamlit makes it easy to add a sidebar using the st.sidebar attribute, which you can use to place any widget or content into the sidebar.

To add a sidebar to your Streamlit app, you can use the st.sidebar attribute followed by the widget you want to add. Here's a basic example of adding a sidebar with a simple slider:

python

import streamlit as st

st.title("This is the title of our app")

age = st.sidebar.slider("Select your age:", 0, 100, 25)

st.write(f"Your age is: {age}")

This will produce the following output:

Adding a sidebar to your Streamlit UI

st.sidebar.slider() is a function that adds a slider widget to the sidebar instead of the main page. The rest of the code works just like a regular slider.

You can add multiple widgets to the sidebar, allowing users to control various aspects of your app from one convenient location. Here's an example with a dropdown menu, a slider, and a button:

python

import streamlit as st

st.title("This is the title of our app")

color = st.sidebar.selectbox("Select a color:", ["Red", "Green", "Blue"])

# Add a slider to the sidebar
level = st.sidebar.slider("Select the intensity level:", 0, 100, 50)

# Add a button to the sidebar
if st.sidebar.button("Apply Settings"):
    st.write(f"Settings applied: Color={color}, Level={level}")

The updated UI is shown below:

Multiple widgets in the sidebar of your Streamlit UI

In this code we used st.sidebar.selectbox() to add a dropdown menu to the sidebar, st.sidebar.slider() to add a slider to the sidebar and finally st.sidebar.button() to add a button to the sidebar. The action associated with the button click is displayed on the main page.

Building a Simple Data Dashboard with Streamlit

Now, we will combine all the basic concepts that we have learned about Streamlit and put them together to create a simple interactive web app.

In this example we'll be using the Iris dataset. This data is widely available, for example from this repository. Download the csv file into the same folder as your Streamlit app and then we can load it using pandas.

Using this dataset we're going to build a data exploration dashboard with the following features:

Dataset Display showing the full Iris dataset.
Sidebar Controls to allow users to select a feature and filter the data based on that feature using sliders.
Filtered Data Display to show the filtered dataset based on the user's input.
Basic Statistics like mean, median, standard deviation, calculated live based on the selected feature in the filtered dataset.

The UI is simple, but shows some of the neat features of Streamlit.

python

import streamlit as st
import pandas as pd

# Load the Iris dataset
df = pd.read_csv('iris.csv')

# Set the title of the app
st.title("Iris Dataset Explorer")

# Display the entire dataframe
st.write("### Full Iris Dataset")
st.dataframe(df)

# Sidebar configuration
st.sidebar.header("Filter Options")

# Feature selection
feature = st.sidebar.selectbox("Select a feature to filter by:", df.columns[:-1])

# Range selection based on the selected feature
min_value = float(df[feature].min())
max_value = float(df[feature].max())

range_slider = st.sidebar.slider(f"Select range of {feature}:", min_value, max_value, (min_value, max_value))

# Filter the dataframe based on the selected range
filtered_df = df[(df[feature] >= range_slider[0]) & (df[feature] <= range_slider[1])]

# Display the filtered dataset
st.write(f"### Filtered Iris Dataset by {feature} between {range_slider[0]} and {range_slider[1]}")
st.dataframe(filtered_df)

# Display basic statistics for the filtered data
st.write(f"### Statistics for {feature}")
st.write(filtered_df[feature].describe())

The iris.csv path is relative, so will only work if you run the script from the same folder. If you want to run it from elsewhere (a parent folder) you will need to modify the path.

Below is the final UI, showing the sidebar on the left and the full & filtered Iris dataset in the middle panel. Change the feature and adjust the parameter to filter the data.

Data filtering demo using Pandas & Streamlit

This simple Streamlit app provides an easy way to explore the Iris dataset. It demonstrates how you can use sidebars, dropdown menus, and sliders to create an interactive and user-friendly data exploration tool.

You can take this simple app and adapt it for other datasets or expand it with additional features, such as advanced filtering or data manipulation options.

Tkinter Widgets — A walkthrough of Tkinter's basic widgets

2025-05-19T06:00:00+00:00

In Tkinter (and most GUI libraries), widget is the name given to a component of the GUI that the user can interact with. User interfaces are made up of multiple widgets arranged within the window to make it functional and intuitive to use.

Tkinter comes with a decent set of widgets and even allows you to create your own custom widgets or customize existing ones.

A Quick Demo

First, let's have a look at some of the most common Tkinter widgets. The following code creates a range of Tkinter widgets and adds them to a window layout so you can see them together:

python

import tkinter as tk
from tkinter import ttk

root = tk.Tk()
root.title("Widgets Demo")

widgets = [
    tk.Label,
    tk.Checkbutton,
    ttk.Combobox,
    tk.Entry,
    tk.Button,
    tk.Radiobutton,
    tk.Scale,
    tk.Spinbox,
]

for widget in widgets:
    try:
        widget = widget(root, text=widget.__name__)
    except tk.TclError:
        widget = widget(root)
    widget.pack(padx=5, pady=5, fill="x")

root.mainloop()

Tkinter's Widgets Demo on macOS

You can learn how the pack() geometry manager works in our Using the Pack Geometry Manager in Tkinter tutorial.

Let's have a look at all the example widgets, from top to bottom:

Widget	Description
`Label`	Just a label, not interactive
`Checkbutton`	A checkbox
`Combobox`	A dropdown list box
`Entry`	Enter a line of text
`Button`	A button
`Radiobutton`	A toggle set, with only one active item
`Scale`	A slider
`Spinbox`	An integer spinner

There are a few more widgets in Tkinter, but they don't fit so well for a quick demo example! You can see them all by checking the TkDocs.

Now, we'll step through each of those widgets in turn, adding them to our application and seeing how they behave.

`Label`

We'll start the tour with Label, arguably one of the simplest widgets available in the Tkinter toolbox. This is a simple one-line piece of text that you can position in your application. You can set the text by passing in a str as you create it:

python

label = tk.Label(self, text="Hello")

Or, by using the .config() function:

python

label = tk.Label(self, text="1")  # The label is created with the text 1.
label.config(text="2")   # The label now shows 2.

You can also adjust font properties, such as the family and size. Here's an app that showcases these features:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Label")
root.geometry("200x80")

label = tk.Label(root, text="Hello!", font=("Helvetica", 30))
label.pack(expand=True)

root.mainloop()

Tkinter's Label Widget on macOS

Note that if you want to change the properties of a widget font, it is usually better to set the font when creating the widget to ensure consistency.

The alignment is specified by using the anchor configuration option. The possible horizontal text alignments are:

Option	Behavior
`"w"`, `tk.W` (for West)	Aligns with the left edge
`"e"`, `tk.E` (for East)	Aligns with the right edge
`"center"`, `tk.CENTER`	Centers horizontally in the available space

The options available for vertical alignment are:

Option	Behavior
`"n"`, `tk.N` (for North)	Aligns with the top
`"s"`, `tk.S` (for South)	Aligns with the bottom
`"center"`, `tk.CENTER`	Centers vertically in the available space

You can combine these by setting the anchor option:

python

label = tk.Label(self, text="Hello", anchor="center")

Note that you use the anchor option to combine the alignment settings.

Finally, you can also use Label to display an image using PhotoImage. This function accepts an image file, and you can create it as follows:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Label Image")

photo = tk.PhotoImage(file="otje.png").subsample(2)
label = tk.Label(root, image=photo)
label.pack(expand=True)

root.mainloop()

Otje, the cat, displayed in a window

What a lovely face!

`Button`

The Button widget is one of the most commonly used widgets in Tkinter. It represents a clickable button that can trigger an action when pressed. We typically use buttons for submitting forms, opening dialogs, or starting processes.

Here's a simple example:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Button")
root.geometry("200x100")

def on_click():
    label.config(text="Button clicked!")

button = tk.Button(
    root,
    text="Click Me",
    command=on_click,
)
button.pack(padx=5, pady=5)

# A helper label to show the result of the click
label = tk.Label(root, text="Waiting for click...")
label.pack(padx=5, pady=5)

root.mainloop()

Tkinter's Button Widget on macOS

In this example, you create a button with the label "Click Me". The command argument connects the button to the on_click() function, which updates the label's text when we click the button.

You can customize the button by adjusting its width, height, font, bg (background color), and fg (foreground/text color). For example:

python

button = tk.Button(
    root,
    text="Styled Button",
    bg="blue",
    fg="white",
    font=("Arial", 14)
)

Buttons are versatile and form the backbone of interactive Tkinter applications.

`Checkbutton`

The next widget to explore is Checkbutton. As its name suggests, it presents a checkable box to the user. As with all Tkinter widgets, it has a number of configuration options to change the widget behaviors:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Checkbutton")
root.geometry("210x80")

def show_state():
    checked = "Checked" if var.get() else "Unchecked"
    checkbox.config(text=f"Check me! ({checked})")

var = tk.IntVar()
checkbox = tk.Checkbutton(root, text="Check me! (Checked)", variable=var)
checkbox.select()
checkbox.config(command=show_state)
checkbox.pack(padx=5, pady=10)

root.mainloop()

Tkinter's Checkbutton Widget on macOS

You can programmatically set a checkbox state using select() or deselect(). You can access the state using a tk.IntVar() variable, which holds the checkbox's state: 1 for checked and 0 for unchecked.

`Combobox`

The Combobox widget is a drop-down list, closed by default with an arrow to open it. You can select a single item from the list, and the currently selected item is shown as a label on the widget. The combo box is suited to selecting a choice from a long list of options.

You can add items to a Combobox by passing a list of strings to its values argument. The items will be added in the order we provide them:

python

import tkinter as tk
from tkinter import ttk

root = tk.Tk()
root.title("Tkinter Combobox")
root.geometry("200x80")

def selection_changed(event):
    label.config(text=f"{event.widget.get()} selected!")

combobox = ttk.Combobox(root, values=["One", "Two", "Three"])
combobox.set("One")
combobox.bind("<<ComboboxSelected>>", selection_changed)
combobox.pack(padx=5, pady=5, fill="x")

# A helper label to show the selected value
label = tk.Label(root, text="One selected!")
label.pack(padx=5, pady=5, fill="x")

root.mainloop()

Tkinter's Combobox Widget on macOS

In this example, we create a combo box whose values come from a Python list. Then, we set the current value to "One" with the set() function.

The bind() function connects the <<ComboboxSelected>> event to the selection_changed() function. This event is triggered when the currently selected item changes. The function updates the text of the helper label to reflect the selected item.

Combobox widgets can also be editable, allowing users to enter values not currently in the list. To achieve this, you need to set the state argument to "normal":

python

widget.config(state="normal")

You can also set a limit to the number of items allowed by configuring the list or using custom validation.

`Listbox`

The Listbox widget is similar to Combobox, except that its options are presented as a scrollable list of items. It also supports the selection of multiple items at once. The Listbox class offers a <<ListboxSelect>> event that sends the selected item's index:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Listbox")

def selection_changed(event):
    selection = event.widget.curselection()
    if selection:
        index = selection[0]
        label.config(text=f"{event.widget.get(index)} selected!")
        event.widget.get(index)

listbox = tk.Listbox(root)
for item in ["One", "Two", "Three"]:
    listbox.insert(tk.END, item)
listbox.bind("<<ListboxSelect>>", selection_changed)
listbox.pack(padx=5, pady=5, fill="both", expand=True)

# A helper label to show the selected value
label = tk.Label(root, text="One selected!")
label.pack(padx=5, pady=5, fill="x")

root.mainloop()

Tkinter's Listbox Widget on macOS

In this example, you create a list box and populate it through a for loop and the insert() function. Then, you connect the "<<ListboxSelect>>" event with the selection_changed() function. The helper label at the bottom of the window shows the selected item.

`Entry`

The Entry widget is a simple single-line text editing box, into which users can type input. These are used for form fields, or settings where there is no restricted list of valid inputs. For example, when entering an email address or computer name:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Entry")

def return_pressed(event):
    label.config(text=event.widget.get())

entry = tk.Entry(root)
entry.insert(0, "Enter your text")
entry.bind("<Return>", return_pressed)
entry.pack(padx=5, pady=5, fill="x")

# A helper label to show the selected value
label = tk.Label(root, text="Entry demo!")
label.pack(padx=5, pady=5, fill="x")

root.mainloop()

Tkinter's Entry Widget on macOS

In this example, you create a text entry using the Entry widget. Then, you insert a placeholder text using the insert() function. The Entry widget allows you to handle various text events, including when the Return key is pressed. Binding this even to return_pressed() ensures that when you press Enter, the helper label displays the text that you type into the entry.

The Entry class has several useful features. They even allow you to perform input validation using custom validation functions and regular expressions.

`Spinbox`

The Spinbox widget provides an input box for numerical values. It has arrows to increase and decrease the value. It supports integers natively:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Spinbox")
root.geometry("200x80")

spinbox_var = tk.StringVar(value="0")
spinbox = tk.Spinbox(
    root,
    from_=-10,
    to=10,
    textvariable=spinbox_var,
)
spinbox.pack(padx=5, pady=5, fill="x")

# A helper label to show the selected value
label = tk.Label(root, textvariable=spinbox_var)
label.pack(padx=5, pady=5, fill="x")

root.mainloop()

Tkinter's Spinbox Widget on macOS

The code above shows the various features available for the Spinbox widget. You can set the interval extremes with the from_ and to arguments. In practice, you'll often use the textvariable option to control the spin box value.

`Scale`

The Scale widget provides a slide-bar widget that works much like a Spinbox. Rather than displaying the current value numerically, it displays the position of the slider handle along the length of the widget.

This widget is often useful when we need to adjust between two extremes but where absolute accuracy is not required. The most common use of this type of widget is for volume controls in multimedia apps:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Scale")
root.geometry("200x80")

def value_changed(event):
    label.config(text=event.widget.get())

scale = tk.Scale(root, from_=0, to=10, orient="horizontal")
scale.bind("<Motion>", value_changed)
scale.pack(padx=5, pady=5, fill="x")

# A helper label to show the selected value
label = tk.Label(root, text="0")
label.pack(padx=5, pady=5, fill="x")

root.mainloop()

Run this and you'll see a slider widget. Drag the slider to change the value.

Tkinter's Scale Widget on macOS

You can also construct a slider with a vertical or horizontal orientation by setting the orient option.

Conclusion

This concludes our brief tour of the common widgets used in Tkinter applications. To see the full list of available widgets, including all their options and attributes, take a look at the Tkinter Documentation or TkDocs site.

Getting Started With PyCharm for Python GUI Development — The Python-Specific Integrated Development Environment

2025-01-04T06:00:00+00:00

Setting up a good development environment for Python GUI programming can make the coding process friendly and provide the necessary tools to maintain the codebase for many years to come. Choosing the right tools and being comfortable with them is a critical step for any Python developer.

Code editors are among the most common and used development tools. They're where we write the code. While most modern code editors support features like syntax highlighting, which shows visual cues to differentiate parts of the source code, we often need to rely on external tools to help us debug and look for errors, install packages, manage Python environments, and so on.

To have all these features in a single program, you'll need an integrated development environment (IDE). Although there are several Python IDEs, in this article, we'll be exploring PyCharm, which is a powerful IDE for Python developers. We'll walk through setting up PyCharm and building a simple PyQt6 GUI application from scratch.

Install Python

Before installing PyCharm, we need to make sure that Python is installed on the development machine. If it isn't installed yet, then we can go to the official download page and grab the specific installer for either Windows or macOS.

Make sure to select the Add Python to PATH option during the installation process.

On Linux systems, you can check if Python is already installed by running python3 --version in a terminal. If this command returns an error, then you need to install Python from your distribution's repository or from the source.

If you're running a Debian-based distribution, such as Ubuntu and Linux Mint, you can install Python by running sudo apt install python3. It may be necessary to run sudo apt install python3-pip python3-venv, so that PyCharm can use pip and venv to install packages and manage virtual environments.

Install PyCharm

We have a few different ways to install PyCharm. The recommended way is to head over to the official download page and grab the standalone installer for Windows, macOS, or Linux. Then, you'll need to run the installer and follow the on-screen instructions.

If you're using a Linux distro that supports Snaps, you can also install it by running sudo snap install pycharm-community --classic in your terminal.

PyCharm has a Community edition, which is free and open-source. It also has a Professional edition, which is paid. While this tutorial uses PyCharm Community edition, the covered topics apply to both editions. Check out the comparison between both editions for the details.

Alternatively, you could install PyCharm via the Toolbox app, which makes it easier to update or rollback to any version of PyCharm. This app can also be used to install and manage other JetBrains products.

NOTE: For more platform-specific information, check out PyCharm's installation guide.

Create a New PyQt6 Project in PyCharm

To demonstrate PyCharm's workflow, we'll create a basic Python GUI app using PyQt. Before we start writing code, we need to first launch PyCharm and create a new project. Creating a project helps you differentiate between files, code, packages, and settings.

Go ahead and launch PyCharm. Depending on your operating system, you can run PyCharm by going to the Start Menu on Windows, Launchpad on macOS, or by running the pycharm executable (under install-folder/bin) on Linux. However, if you installed PyCharm using Toolbox, then open the Toolbox app and launch PyCharm from there.

Read the PyCharm documentation to learn how to run PyCharm from the command-line interface.

When we launch PyCharm, the first thing we'll see is its Welcome to PyCharm window:

PyCharm's Welcome window

Here's where we can create new projects or open existing ones—either stored locally on our computer or in online code repositories like GitHub.

To continue, click the New Project button and then choose a project's name and location folder in the New Project window. You can also define the Python environment to use but keep the default configuration for now:

PyCharm's New Project window

Finally, click the Create button on the lower, right corner to create the project and open it in PyCharm's main window, also known as Project Window.

Get Familiar With PyCharm's Interface

The Project Window is where we'll spend most of our time in PyCharm. It's where we manage files, write code, install packages, and do everything related to the project we are working on.

NOTE: This article covers PyCharm's modern user interface. You can also use the classic user interface by going to File -> Settings and disabling New UI under Appearance & behavior. On macOS, you can access the Settings menu from the Menu Bar at the top of your screen.

Let's examine the components of PyCharm's interface and see what they do:

PyCharm's Project Window

The Project Window interface has the following four main components:

Window Header
Editor
Sidebar
Status bar

In the following sections, we'll explore these UI components in more detail.

Window Header

The Window Header is at the very top of PyCharm's Project Window and gives us quick access to some commonly used features, most notably the Run button. Using the Run button, we can run or debug our Python project directly from PyCharm — without having to type the relevant Python command in a terminal.

The Window Header looks something like this:

PyCharm's Window Header

Other significant components of the Window Header are the Main Menu and the Project widget.

PyCharm's Main Menu is accessible by clicking on the hamburger menu, whereas the Project widget displays the name of the current project and allows us to switch between projects as well as create new ones.

On macOS, however, we don't have a hamburger menu in the Window Header but we can still access PyCharm's Main Menu through the Menu Bar at the top of the screen, like with other macOS apps.

Editor

The Editor is where we actually read, write, and edit code. It has a scrollbar on the right to help us navigate large files. It also has a Gutter on the left, which displays line numbers for the file. The Gutter also provides us with context-dependent actions like running code or temporarily hiding functions and classes:

PyCharm's Editor window

At the top, the Editor has a tabbed interface to display the open files and switch between them at any time. To switch to another open file, we can either click the relevant tab or press CTRL + TAB to scroll through all of them. If necessary, we can also open files from external folders that are outside the project's folder by attaching that folder to the current project.

The Editor can open any plaintext file format, such as .py and .md, for editing. It also supports viewing both raster and vector image formats, such as PNG and SVG. However, note that most binary files, such as video, audio, and executable files are not supported by the Editor and will be opened outside of PyCharm.

Sidebar and Tool Windows

The Sidebar has buttons to open and close tool windows, which are displayed at the bottom or left side of PyCharm's Project Window:

PyCharm's sidebar and the Project tool window

The Project tool window is normally open by default. It displays the folder structure of the current project and allows us to open, create, and delete files and folders. If you have any external folders attached to the current project, the Project tool window will also display the structure of those folders.

PyCharm also has tool windows for running code, installing packages from PyPI using a graphical interface, and using version control software. Throughout the rest of this article, we'll learn how to use these tool windows as we build our sample Python GUI app.

Status Bar

The Status Bar is the horizontal bar at the bottom of PyCharm's workspace. It indicates the status of both our project and the entire IDE:

PyCharm's status bar

It provides information about the file that's currently opened in the Editor, such as its encoding, line separator, cursor position, and indentation type. It also gives quick access to the Python Interpreter settings, which we'll cover in more detail later.

Install PyQt6 in PyCharm

One thing we need to do before starting our GUI app is to install the PyQt library. We'll use this library to build the app's GUI. This library doesn't come with Python but can be installed from the PyPI software repository using the pip command.

However, PyCharm simplifies the installation by providing a tool window for us to search, install, and manage Python packages. To open the Python Packages tool window, go to the Sidebar and look for the Python Packages button, which is shown in blue in the following screenshot:

PyCharm's Python Packages tool window

Using the search field, look for the PyQt6 package. We can have a look at the README file (on the right side) for each package by clicking on the package's name (on the left side). Once we've found the package, we can click Install next to the package's name and choose the package version we want to install.

A README file typically provides information about what a package does, how to install and use the package, what license the package is distributed under, and so on.

When we clear the search field, PyQt6 should now be listed as Installed:

PyCharm's Python Packages tool window with PyQt6 ready to be installed

If a newer version of an installed package is available, then PyCharm will indicate it by displaying a link with the current and next version (next to the package name) that we can click to upgrade:

PyCharm's Python Packages tool window with PyQt6 installed

You can also uninstall a Python package. To do this, click the package's name and go to the kebab menu on the top-right corner of the README preview section. Then, click Delete Package to uninstall the package:

PyCharm's Python Packages tool window showing how to uninstall a package

Uninstalling Python packages from a virtual environment isn't something that we do often but PyCharm has a nice interface to do it if we need to.

Write a PyQt6 GUI Application in PyCharm

In this section, we will focus on writing and editing code in PyCharm to build our sample GUI app. For its GUI, the app will have one window with a Press Me button. To start coding though, we need a Python file.

NOTE: This guide will not cover PyQt extensively. To learn more about this library, check out the Creating your first app with PyQt6 tutorial.

To create a file, go to the Projects tool window and right-click the project's folder to open its context menu. Then, go to New and select Python File as the desired file type:

PyCharm's context menu to create a new Python file

This action will open a dialog where PyCharm will ask you to enter a filename. For this project, we will just name the file as app and press ENTER:

PyCharm's dialog to name a new Python file

The Project tool window will now list a file named app.py under the project's folder. To open that file in the Editor, double-click on the filename and you'll see a blank Python file:

The app.py file opened in PyCharm's Editor

The Editor works like any other standard text editor or code editor. We enter text using the keyboard and press ENTER to create a new line. We can use the Gutter to track the line number we are currently on.

Now that we have a Python file in our project folder, we can start coding. First, we will import the required Python modules, packages, and classes:

python

import sys
from PyQt6.QtCore import QSize, Qt
from PyQt6.QtWidgets import QApplication, QMainWindow, QPushButton

As we type the import statements in the Editor, PyCharm will offer suggestions for matching keywords and Python packages using a pop-up:

PyCharm's code suggestions pop-up

You can use the Up and Down arrow keys to navigate the list of suggestions. Then, press TAB to select the highlighted suggestion.

Using PyCharm's Error Detection and Code Fixes

Another useful feature of PyCharm is its ability to detect errors and provide fixes for problematic code. The following code block deliberately includes a few errors to demonstrate this feature:

python

QApplication
window = MainWindow()
window.show()
app.exec()

In this code, we haven't instantiated QApplication correctly. This error produces a cascade of errors that PyCharm nicely spots for us:

PyCharm's error detection feature

PyCharm detects a few errors in the code we just typed. It indicates the error by highlighting the relevant piece of code with a squiggly line.

The color of the squiggly line indicates the severity of the problem PyCharm detected. Any problem highlighted in red is a critical error that prevents the program from running and everything else is marked in yellow.

To discover what an error is about, we can drag the mouse pointer to the highlighted section and hover over it to see a tooltip as shown below:

PyCharm's error tips: statement with no effect

PyCharm's tooltip says that the statement QApplication has no effect. This is because we are just referencing a class without creating a concrete object. As a result, PyCharm flags a critical error in the last line because the app name hasn't been assigned yet.

We can fix both errors by instantiating QApplication to create an object named app:

python

app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

We've taken care of two problems detected by PyCharm, but there is still one critical error remaining. If we hover the mouse's pointer over the highlighted object, we'll see that PyCharm is complaining about window = MainWindow() because we are using a class that we haven't defined yet:

PyCharm's error tips: unresolved reference

To fix the issue, right-click the highlighted object to open the associated Context Menu. Once you see the menu, select Show Context Actions. This will open another pop-up where PyCharm offers smart suggestions to fix the problem.

For this particular problem, we'll choose the option Create class 'MainWindow' in module app.py as shown below:

PyCharm's Context Actions pop-up

PyCharm automatically generates an empty class named MainWindow. Update the class as follows in order to specify how the app's GUI will look:

python

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("My App")
        button = QPushButton("Press Me!")
        self.setFixedSize(QSize(400, 300))
        self.setCentralWidget(button)

Complete PyQt6 Application Code

With this update done, the complete code for app.py should look something like the following:

python

import sys
from PyQt6.QtCore import QSize, Qt
from PyQt6.QtWidgets import QApplication, QMainWindow, QPushButton

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("My App")
        button = QPushButton("Press Me!")
        self.setFixedSize(QSize(400, 300))
        self.setCentralWidget(button)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Now you have a working PyQt6 desktop application. The next step is to run the app using PyCharm's features but before that, let's summarize what we've learned so far.

We learned how to create a file using the Project tool window and then edit it using the Editor. We also learned how to use some of the assistive coding features provided by PyCharm to get code suggestions, fix problems in our code, and generate boilerplate code for a faster coding experience.

Run Python GUI Code in PyCharm

PyCharm provides a convenient way to run code through its interface. To run our PyQt6 app, right-click on the Editor's work area to open the Context Menu. Then, select the Run 'app' option:

Running code with PyCharm's Run option from the Editor's context menu

The option to run code using the Run option in the context menu can be appropriate for short apps or scripts. However, when you have a much larger project with more than one file, it's often convenient to configure a default Python file for a project to run.

To do so, right-click on the app.py file in the Editor to show the Context Menu. Then, select Modify Run Configuration... as in the following screenshot:

Modifying the Run Configuration in PyCharm

Once you select the Modify Run Configuration..., you get presented with the Edit Run Configuration dialog:

PyCharm's Edit Run Configuration dialog

In the Edit Run Configuration dialog, we can modify the path to the Python script or set additional command-line arguments to pass when running the project. We can also set a name for this configuration at the top of the dialog and click the OK button.

Now, we'll see the app configuration next to the green Run button on the Window Header. This indicates which script PyCharm will run by default. If we have more than one Run Configuration, then we can switch between them by clicking on the dropdown menu next to the Run button.

Once we have set the project's default Run Configuration, we can run the associated script regardless of which file we are currently working on the Editor by clicking on the Run button in the Window Header:

Running code with PyCharm's Run button from the Window Header

To terminate the app's execution from the PyCharm interface, click the Stop button in the Window Header.

Configure a Python Virtual Environment in PyCharm

Python's best practices recommend avoiding the system interpreter in favor of using a virtual environment. A Python virtual environment is an isolated copy of the system interpreter that we create for development purposes.

For most large projects, you should create a dedicated virtual environment. As we noted earlier, PyCharm creates a virtual environment by default whenever we create a new project. This allows us to manage the project's dependencies separately because they are installed in the dedicated Python environments rather than globally in your system.

We can see the installed packages in our current Python environment by clicking on the Python interpreter selector (in the Status Bar) and clicking on the Manage Packages... option. This action opens the Python Packages tool window, which we previously used to install PyQt6:

Managing Python packages in PyCharm

We can create a new Python virtual environment for our project by going to Add New Interpreter > Add Local Interpreter:

Creating a new Python virtual environment in PyCharm - Step 1

After clicking on the Add Local Interpreter option, you get presented with the Add Python Interpreter dialog. There, you'll find several options to create working environments for Python coding. For the purposes of this guide, we'll only look at creating a standard Virtualenv Environment:

Creating a new Python virtual environment in PyCharm - Step 2

Specify where to create the Python virtual environment and select a base interpreter from the dropdown list if you have more than one version of Python. Then, click the OK button to create the new Python environment for the active project. We can see the current Python environment by looking at the Python interpreter selector in the right bottom corner of the Status Bar.

Because this is a brand new virtual environment, trying to run the app now will fail because we haven't installed PyQt6 in this Python environment.

To switch back to the previous Python environment, click on the interpreter selector and select the relevant interpreter from the list:

Changing the Python virtual environment in PyCharm

To get back to the original Python environment, select the Python 3.10 (PyQt6app) menu option in the dropdown list.

Use Git for Version Control in PyCharm

Version control systems (VCS) allow us to track changes to a project's codebase. They are useful because they let us know what has changed in the app and who is responsible, which is particularly important when working with teams. VCSs also make it easy to revert any changes we make, giving us more freedom to test out new features.

PyCharm has built-in support for several VCSs. In this tutorial, we'll focus on Git, which is one of the most popular. In this section, we'll go over how to create and manage a Git repository for a Python GUI project in PyCharm.

WARNING: To use Git-related features in PyCharm, Git needs to be installed. If you haven't done so already, please follow this guide to install and set up Git on your computer.

Track Changes in a Project

You can use Git via its command-line interface. However, PyCharm allows us to perform common version control tasks through a graphical interface.

To enable version control for the current project, go to the Version Control tool window at the bottom of the Sidebar and click on Create Git Repository link:

PyCharm's Version Control tool window

Once you click the Create Git Repository link, you get the Create Git Repository dialog:

PyCharm's Create Git Repository dialog

Once you create the Git repository, the tool window will update its view to provide additional information. It should be mostly blank right now because we haven't started tracking any files.

To start tracking project files, we need to commit to the Git repository. To do that, a tool window named Commit will appear in the Sidebar (near the top).

A commit is a snapshot of the current state of all the files in a project. Each time we make a significant change to our codebase, we make a commit to mark what changed and by whom.

Open the tool window and look at the section named Changes:

PyCharm's Commit tool window

The Changes section under Commit shows any project files that have changed or aren't being tracked. Because we aren't tracking any files for now, all of our project files appear under Unversioned Files.

We can select which files we would like to include in a commit by marking the checkbox next to each filename. For this project, select all of the Unversioned Files in the first commit.

There's a text box right below the Changes section where you can type a commit message to describe what changed in these files. Because this will be our first commit for the current project, we can write a message like "Initial commit":

Select the files to commit and add a commit message in PyCharm

Once we've selected the files to include in the commit and typed the commit message, we can make the commit by pressing the Commit button underneath. The commit we made should now appear in the Version Control tool window:

PyCharm's Version Control tool window showing a commit

We'll make one more commit to this project by changing the text of the button in app.py from "Press Me!" to "Press This Button!":

python

class MainWindow(QMainWindow):
    def __init__(self):
        ...
        button = QPushButton("Press This Button!")
        ...

When a project is version-controlled, PyCharm will indicate when a line has been added, modified, or deleted from a file by showing a colored indicator next to the line number in the gutter. The indicator disappears once we commit the changed file to the repository again:

PyCharm showing a colored indicator for modified lines

Go to the Commit tool window, select app.py under Changes, type a commit message like "Changed button text," and then press the Commit button again. You'll see the new commit appear above the previous one in the Version Control tool window:

PyCharm's Version Control tool window showing the commit history

This is called the commit history, where we can see all the changes or commits that we've made in a project.

Push a PyCharm Project to GitHub

We've created a local Git repository and want to publish the project to a remote repository on GitHub. Before doing that, we need to authenticate so that PyCharm can access, create, and delete remote repositories on our GitHub account.

We could authenticate manually using SSH. However, PyCharm simplifies the process by integrating GitHub and GitLab right into the IDE. To authenticate, go to Settings and look for GitHub under Version Control. Then, click on the plus (+) sign and select the Log In via GitHub option:

Log in to GitHub through PyCharm's UI

A browser window should open and ask you to confirm whether you want to authorize PyCharm to access your GitHub account. Once you confirm by selecting Authorize in GitHub, you will be redirected to GitHub:

Authorize PyCharm in GitHub

If you aren't already signed in, you will be shown the login page where you can sign up too if you don't already have a GitHub account:

GitHub's log in page for authorizing PyCharm

Once you provide your GitHub credentials and click the Sign in button, you'll get your GitHub account listed in the Version Control screen:

GitHub account authorized in PyCharm

PyCharm only needs to be authorized once for each user on a computer.

Once PyCharm is authorized, we also need to create a new, empty remote repository. Go back to the GitHub website and click on the plus sign (+) at the top of your Dashboard to create a new repository:

Creating a new GitHub repository from the Dashboard

Let's give this repository a unique name related to the project we are working on:

Create a new repository page on GitHub

Depending on who you plan to share this project with, you can also set the repository's visibility to be public or private. Then, click the Create Repository button and copy the remote repository URL:

New repository on GitHub

Finally, click on the VCS widget in PyCharm's Window Header to Push all the commits we've made in the local repository to the remote repository we just created on GitHub:

Pushing to GitHub through PyCharm's UI

Then, we need to specify where the remote repository is located. So, click on Define Remote and paste the repository's URL into the corresponding input box:

Setting the GitHub repository's URL through PyCharm's UI

Click OK and then select the Push button:

Pushing commits to GitHub through PyCharm's UI

Now, any commits we made to our project will be visible in the remote repository on GitHub. If we go back to GitHub, we can see that it's no longer an empty repository:

Populated repository on GitHub

The Version Control tool window should also display the name we set for the remote next to the latest commit:

PyCharm's Version Control tool window showing the remote repository

To make the next commit, make your changes and go to the Commit tool window, where you can click the Commit and Push... button to do both actions in one go:

Committing new changes through PyCharm's UI

We can also go to the VCS widget and select Push to do this at any time.

Explore Other Useful PyCharm Features for GUI Development

PyCharm has several features that help us write Python GUI code more efficiently and make development smoother. In this section, we'll explore some of these features and learn how to use them.

Search Everywhere

Projects can become quite large spanning multiple files and folders. By using the Search Everywhere feature, we can look through the whole project for files, classes, lines of code and even specific actions like Commit or Push. This feature also allows us to quickly find PyCharm's Settings and tool windows without using our mouse.

To use Search Everywhere, double-tap the SHIFT key. You'll get presented with the search window:

PyCharm's Search Everywhere window

To specify what you are looking for, press TAB to switch between Classes, Files, Symbols, Actions, and so on. It also supports evaluating mathematical expressions and filtering out certain file types via the Filter button at the top-right corner.

Code With Me

There are times when we need to give temporary access to other developers so that they can review our code and provide assistance. In these cases, we can use PyCharm's Code With Me feature to create a shared session between a host and one or more guests.

The guests can see what the host is doing in PyCharm and can be allowed to edit files in the project in real time. We can also share the camera and microphone so we can discuss with others who joined that session.

To start a session, click on the Code With Me icon at the top-right of the window header next to the Run button:

PyCharm's Code With Me feature

After selecting the Start Session... option from the menu, PyCharm will allow you to configure what guests can and can't do in this session:

PyCharm's Code With Me: Start Session dialog

NOTE: You can use Code With Me for free in PyCharm Community edition but there are limits on the number of guests allowed and the session time. You can learn more about the specific limits for the Community plan of Code With Me on their website.

Once we set permissions for our guests, PyCharm will create a link we need to send to the guests we are inviting. To copy the link, click on the Code With Me icon again and select Copy Session Link from the menu.

When a guest clicks the link, we will receive a popup in PyCharm asking us to either accept or decline the guest. If we accept, they will be able to use a lightweight installation of PyCharm just using their web browser through which we can collaborate.

It is always recommended to use Git for collaborating with others on a project. Code With Me can't tell who made a change or why that change was made. More importantly, it requires an active connection to the host's computer to make changes to the project and guests have limited access to PyCharm's features.

Sync Python Requirements

Earlier in this guide, we installed the PyQt6 package to build the interface of our sample app. Most software we develop depends on third-party Python packages for essential features. In collaborative contexts, we often need to keep track of our project's dependencies so that everyone working with us knows what to install.

In Python, developers typically create a requirements.txt file that lists all the needed packages and their recommended versions. You can create this file manually. However, PyCharm provides tools to generate a requirements.txt file using its UI.

As a best practice, you should update a project's requirements.txt file whenever the dependencies change.

To generate the file, use Search Everywhere to find the Sync Python Requirements action:

Searching for the Sync Python Requirements action in PyCharm's Search Everywhere

Selecting the Sync Python Requirements action will open a dialog where we can specify how to handle package versions and manage the requirements file:

PyCharm's Sync Python Requirements dialog

Once we click the OK button, PyCharm will create the file and populate it with the names and versions of the required Python packages.

If we look at the Project tool window, we'll see the new requirements.txt file in the project directory. If we open the file, we will see PyQt6 listed with its package version:

The requirements.txt file listed on PyCharm's Project tool window

Remember to run the Sync Python Requirements action again whenever you install or update Python packages in your project.

TODOs

Keeping track of changes already made in a project is important, but so is tracking what we still need to do. We can keep track of what needs to be done using TODOs. A TODO is a comment in our code that we start with # TODO:

A TODO comment on PyCharm's editor and TODO tool window

PyCharm will track these comments across the whole project, and we can view them all at any time in the TODO tool window. This tool window has several options to filter the TODOs:

PyCharm's TODO filtering options

We can see every single TODO across the project by selecting the Project tab or just the ones in the current file with Current File. We can be even more specific by looking only at files that were recently viewed, changed, or are currently open by selecting the Scope Based option.

When we use Git for version control, PyCharm will also show the number of remaining TODOs in each commit:

PyCharm showing the number of remaining TODOs

Scratches

Scratches are another interesting PyCharm feature that allows us to write temporary notes or draft code without touching any of the project files. To add a scratch, go to the Project tool window and right-click on Scratches and Consoles entry:

Creating a Scratch file from PyCharm's Project tool window

The New -> Scratch File option will open a dialog where you can select the type of scratch file you want to create.

Plugin Marketplace

While PyCharm is already packed with features to aid development, it is also highly extensible thanks to its Plugin marketplace. We can customize our PyCharm installation by getting themes and other plugins that provide additional functionality.

To use the Plugin marketplace, click on the Settings icon on the Window Header and select Plugins:

PyCharm's Plugin marketplace

In the Plugin marketplace, we can see installed plugins as well as those that are available in the marketplace. To install a plugin, click the Install button and wait for PyCharm to download and install it.

Summary

In this tutorial, you have learned how to install and set up the PyCharm IDE for Python GUI development with PyQt6. You've also learned how to write and run Python code in PyCharm as well as how to install external Python packages like PyQt6 using the IDE's graphical interface. You are now able to create and configure a Python virtual environment and use Git for version control in your projects.

Finally, you explored several additional useful features for working with GUI applications in PyCharm, including Search Everywhere, Code With Me, requirements syncing, TODOs, scratches, and the plugin marketplace. With this knowledge, you are now ready to confidently use PyCharm to develop your own Python GUI apps and desktop applications.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Introduction to the QGraphics Framework in PySide6 — Creating vector interfaces using the QGraphics View framework

2024-09-27T07:00:00+00:00

The Qt Graphics View Framework allows you to develop fast and efficient 2D vector graphic scenes. Scenes can contain millions of items, each with their own features and behaviors. By using the Graphics View via PySide6 you get access to this highly performant graphics layer in Python. Whether you're integrating vector graphics views into an existing PySide6 application, or simply want a powerful vector graphics interface for Python, Qt's Graphics View is what you're looking for.

Some common uses of the Graphics View include data visualization, mapping applications, 2D design tools, modern data dashboards and even 2D games.

In this tutorial we'll take our first steps looking at the Qt Graphics View framework, building a scene with some simple vector items. This will allow us to familiarize ourselves with the API and coordinate system, which we'll use later to build more complex examples.

What is the QGraphics View Framework?

The Graphics View framework consists of 3 main parts QGraphicsView, QGraphicsScene, and QGraphicsItem, each with different responsibilities.

The framework can be interpreted using the Model-View paradigm, with the QGraphicsScene as the Model and the QGraphicsView as the View. Each scene can have multiple views. The QGraphicsItems within the scene can be considered as items within the model, holding the visual data that the scene combines to define the complete image.

QGraphicsScene is the central component that glues everything together. It acts as a whiteboard on which all items are drawn (circles, rectangles, lines, pixmaps, etc). The QGraphicsView has the responsibility of rendering a given scene -- or part of it, with some transformation (scaling, rotating, shearing) -- to display it to the user. The view is a standard Qt widget and can be placed inside any Qt layout.

QGraphicsScene provides some important functionalities out of the box, so we can use them to develop advanced applications without struggling with low-level details. For example:

Collision Detection: detect when a graphics item has collided with another item.
Item Selection: gives us the ability to deal with multiple items at the same time, for example, the user can select multiple items, and when pressing delete, a function asks the scene to give the list for all selected items, and then delete them.
Items discovery: the scene can tell us what items are present (or part of them) at a specific point or inside some defined region, for example, if the user adds an item that intersects with a forbidden area, the program will detect them and give them another (mostly red) color.
Events Propagation: the scene receives the events and then propagates them to items.

To define a QGraphicsScene you define its boundaries or sceneRect which defines the x & y origins and dimensions of the scene. If you don't provide a sceneRect it will default to the minimum bounding rectangle for all child items -- updating as items are added, moved or removed. This is flexible but less efficient.

Items in the scene are represented by QGraphicsItem objects. These are the basic building block of any 2D scene, representing a shape, pixmap or SVG image to be displayed in the scene. Each item has a relative position inside the sceneRect and can have different transformation effects (scale, translate, rotate, shear).

Finally, the QGraphicsView is the renderer of the scene, taking the scene and displaying it -- either wholly or in part -- to the user. The view itself can have transformations (scale, translate, rotate and shear) applied to modify the display without affecting the underlying scene. By default the view will forward mouse and keyboard events to the scene allowing for user interaction. This can be disabled by calling view.setInteractive(False).

Creating a Simple `QGraphicsScene`

Let's start by creating a simple scene. The following code creates a QGraphicsScene, defining a 400 x 200 scene, and then displays it in a QGraphicsView:

python

import sys
from PySide6.QtWidgets import QGraphicsScene, QGraphicsView, QApplication

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with its origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

view = QGraphicsView(scene)
view.show()
app.exec()

If you run this example you'll see an empty window:

The empty graphics scene, shown in a QGraphicsView window.

Not very exciting yet -- but this is our QGraphicsView displaying our empty scene.

As mentioned earlier, QGraphicsView is a widget. In Qt any widgets without a parent display as windows. This is why our QGraphicsView appears as a window on the desktop.

Adding Graphic Items to the Scene

Let's start adding some items to the scene. There are a number of built-in graphics items which you can customize and add to your scene. In the example below we use QGraphicsRectItem which draws a rectangle. We create the item passing in its dimensions, and then set its position, pen and brush before adding it to the scene:

python

import sys
from PySide6.QtWidgets import (
    QGraphicsScene, QGraphicsView, QGraphicsRectItem, QApplication
)
from PySide6.QtGui import QBrush, QPen
from PySide6.QtCore import Qt

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with its origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

# Draw a rectangle item, setting the dimensions.
rect = QGraphicsRectItem(0, 0, 200, 50)

# Set the origin (position) of the rectangle in the scene.
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.GlobalColor.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.GlobalColor.cyan)
pen.setWidth(10)
rect.setPen(pen)

scene.addItem(rect)

view = QGraphicsView(scene)
view.show()
app.exec()

Running the above you'll see a single, rather ugly colored, rectangle in the scene:

A single rectangle in the scene

Adding more items is simply a case of creating the objects, customizing them and then adding them to the scene. In the example below we add a circle, using QGraphicsEllipseItem -- a circle is just an ellipse with equal height and width:

python

import sys
from PySide6.QtWidgets import (
    QGraphicsScene,
    QGraphicsView,
    QGraphicsRectItem,
    QGraphicsEllipseItem,
    QApplication
)
from PySide6.QtGui import QBrush, QPen
from PySide6.QtCore import Qt

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with its origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

# Draw a rectangle item, setting the dimensions.
rect = QGraphicsRectItem(0, 0, 200, 50)

# Set the origin (position) of the rectangle in the scene.
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.GlobalColor.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.GlobalColor.cyan)
pen.setWidth(10)
rect.setPen(pen)

ellipse = QGraphicsEllipseItem(0, 0, 100, 100)
ellipse.setPos(75, 30)

brush = QBrush(Qt.GlobalColor.blue)
ellipse.setBrush(brush)

pen = QPen(Qt.GlobalColor.green)
pen.setWidth(5)
ellipse.setPen(pen)

# Add the items to the scene. Items are stacked in the order they are added.
scene.addItem(ellipse)
scene.addItem(rect)

view = QGraphicsView(scene)
view.show()
app.exec()

The above code will give the following result:

A scene with two items

Controlling Item Stacking Order with ZValue

The order you add items affects the stacking order in the scene -- items added later will always appear on top of items added first. However, if you need more control you can set the stacking order using .setZValue:

python

ellipse.setZValue(500)
rect.setZValue(200)

Now the circle (ellipse) appears above the rectangle:

Using ZValue to order items in the scene

Try experimenting with setting the Z value of the two items -- you can set it before or after the items are in the scene, and can change it at any time.

Z in this context refers to the Z coordinate. The X & Y coordinates are the horizontal and vertical position in the scene respectively. The Z coordinate determines the relative position of items toward the front and back of the scene -- coming "out" of the screen towards the viewer.

There is also the convenience method .stackBefore() which allows you to place one QGraphicsItem behind another item in the scene. To place the ellipse in front of the rectangle, you can swap the order and place the rectangle before the ellipse:

python

rect.stackBefore(ellipse)

You can achieve the same effect by setting the ellipse Z value relative to the rectangle:

python

ellipse.setZValue(rect.zValue() + 1)

Making Items Moveable and Selectable

Our two QGraphicsItem objects are currently fixed in position where we place them, but they don't have to be! As already mentioned Qt's Graphics View framework allows items to respond to user input, for example allowing them to be dragged and dropped around the scene at will. Simple functionality like this is actually already built in, you just need to enable it on each QGraphicsItem. To do that we need to set the flag QGraphicsItem.GraphicsItemFlags.ItemIsMovable on the item.

The full list of graphics item flags is available here.

python

import sys
from PySide6.QtWidgets import (
    QGraphicsScene,
    QGraphicsView,
    QGraphicsItem,
    QGraphicsRectItem,
    QGraphicsEllipseItem,
    QApplication
)
from PySide6.QtGui import QBrush, QPen
from PySide6.QtCore import Qt

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with its origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

# Draw a rectangle item, setting the dimensions.
rect = QGraphicsRectItem(0, 0, 200, 50)

# Set the origin (position) of the rectangle in the scene.
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.GlobalColor.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.GlobalColor.cyan)
pen.setWidth(10)
rect.setPen(pen)

ellipse = QGraphicsEllipseItem(0, 0, 100, 100)
ellipse.setPos(75, 30)

brush = QBrush(Qt.GlobalColor.blue)
ellipse.setBrush(brush)

pen = QPen(Qt.GlobalColor.green)
pen.setWidth(5)
ellipse.setPen(pen)

# Add the items to the scene. Items are stacked in the order they are added.
scene.addItem(ellipse)
scene.addItem(rect)

ellipse.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsMovable)

view = QGraphicsView(scene)
view.show()
app.exec()

In the above example we've set ItemIsMovable on the ellipse only. You can drag the ellipse around the scene -- including behind the rectangle -- but the rectangle itself will remain locked in place. Experiment with adding more items and configuring the moveable status.

If you want an item to be selectable you can enable this by setting the ItemIsSelectable flag, for example here using .setFlags() to set multiple flags at the same time:

python

ellipse.setFlags(QGraphicsItem.ItemIsMovable | QGraphicsItem.ItemIsSelectable)

If you click on the ellipse you'll now see it surrounded by a dashed line to indicate that it is selected. We'll look at how to use item selection in more detail in a later tutorial.

A selected item highlighted with a dashed line

Alternative Way to Create Graphic Items

So far we've been creating items by creating the objects and then adding them to the scene. But you can also create an object in the scene directly by calling one of the helper methods on the scene itself, e.g. scene.addEllipse(). This creates the object and returns it so you can modify it as before:

python

import sys
from PySide6.QtWidgets import (
    QGraphicsScene,
    QGraphicsView,
    QGraphicsRectItem,
    QApplication
)
from PySide6.QtGui import QBrush, QPen
from PySide6.QtCore import Qt

app = QApplication(sys.argv)

scene = QGraphicsScene(0, 0, 400, 200)

rect = scene.addRect(0, 0, 200, 50)
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.GlobalColor.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.GlobalColor.cyan)
pen.setWidth(10)
rect.setPen(pen)

view = QGraphicsView(scene)
view.show()
app.exec()

Feel free to use whichever form you find most comfortable in your code.

You can only use this approach for the built-in QGraphicsItem object types.

Building a Complex Scene with Shapes, Text, and Images

So far we've built a simple scene using the basic QGraphicsRectItem and QGraphicsEllipseItem shapes. Now let's use some other QGraphicsItem objects to build a more complex scene, including lines, text and QPixmap images:

python

from PySide6.QtCore import QPointF, Qt
from PySide6.QtWidgets import (
    QGraphicsRectItem,
    QGraphicsScene,
    QGraphicsView,
    QApplication
)
from PySide6.QtGui import QBrush, QPainter, QPen, QPixmap, QPolygonF
import sys

app = QApplication(sys.argv)

scene = QGraphicsScene(0, 0, 400, 200)

rectitem = QGraphicsRectItem(0, 0, 360, 20)
rectitem.setPos(20, 20)
rectitem.setBrush(QBrush(Qt.GlobalColor.red))
rectitem.setPen(QPen(Qt.GlobalColor.cyan))
scene.addItem(rectitem)

textitem = scene.addText("QGraphics is fun!")
textitem.setPos(100, 100)

scene.addPolygon(
    QPolygonF(
        [
            QPointF(30, 60),
            QPointF(270, 40),
            QPointF(400, 200),
            QPointF(20, 150),
        ]),
    QPen(Qt.GlobalColor.darkGreen),
)

pixmap = QPixmap("cat.jpg")
pixmapitem = scene.addPixmap(pixmap)
pixmapitem.setPos(250, 70)

view = QGraphicsView(scene)
view.setRenderHint(QPainter.RenderHint.Antialiasing)
view.show()
app.exec()

If you run the example above you'll see the following scene:

Scene with multiple items including a rectangle, polygon, text and a pixmap.

Let's step through the code looking at the interesting bits.

Polygons are defined using a series of QPointF objects which give the coordinates relative to the item's position. So, for example if you create a polygon object with a point at 30, 20 and then move this polygon object X & Y coordinates 50, 40 then the point will be displayed at 80, 60 in the scene.

Points inside an item are always relative to the item itself, and item coordinates are always relative to the scene -- or the item's parent, if it has one. We'll take a closer look at the Graphics View coordinate system in the next tutorial.

To add an image to the scene we can open it from a file using QPixmap(). This creates a QPixmap object, which can then in turn be added to the scene using scene.addPixmap(pixmap). This returns a QGraphicsPixmapItem which is the QGraphicsItem type for the pixmap -- a wrapper that handles displaying the pixmap in the scene. You can use this object to perform any changes to the item in the scene.

The multiple layers of objects can get confusing, so it's important to choose sensible variable names which make clear the distinction between, e.g. the pixmap itself and the pixmap item that contains it.

Finally, we set the flag RenderHint.Antialiasing on the view to smooth the edges of diagonal lines. You almost always want to enable this on your views as otherwise any rotated objects will look very ugly indeed. Below is our scene without antialiasing enabled, you can see the jagged lines on the polygon:

Scene with antialiasing disabled.

Antialiasing has a (small) performance impact however, so if you are building scenes with millions of rotated items it may in some cases make sense to turn it off.

Adding a `QGraphicsView` to a PySide6 Layout

The QGraphicsView is subclassed from QWidget, meaning it can be placed in layouts just like any other widget. In the following example we add the view to a simple interface, with buttons which perform a basic effect on the view -- raising and lowering selected item's ZValue. This has the effect of allowing us to move items in front and behind other objects.

The full code is given below:

python

import sys

from PySide6.QtCore import Qt
from PySide6.QtGui import QBrush, QPainter, QPen
from PySide6.QtWidgets import (
    QApplication,
    QGraphicsEllipseItem,
    QGraphicsItem,
    QGraphicsRectItem,
    QGraphicsScene,
    QGraphicsView,
    QHBoxLayout,
    QPushButton,
    QSlider,
    QVBoxLayout,
    QWidget,
)

class Window(QWidget):
    def __init__(self):
        super().__init__()

        # Defining a scene rect of 400x200, with its origin at 0,0.
        # If we don't set this on creation, we can set it later with .setSceneRect
        self.scene = QGraphicsScene(0, 0, 400, 200)

        # Draw a rectangle item, setting the dimensions.
        rect = QGraphicsRectItem(0, 0, 200, 50)
        rect.setPos(50, 20)
        brush = QBrush(Qt.GlobalColor.red)
        rect.setBrush(brush)

        # Define the pen (line)
        pen = QPen(Qt.GlobalColor.cyan)
        pen.setWidth(10)
        rect.setPen(pen)

        ellipse = QGraphicsEllipseItem(0, 0, 100, 100)
        ellipse.setPos(75, 30)

        brush = QBrush(Qt.GlobalColor.blue)
        ellipse.setBrush(brush)

        pen = QPen(Qt.GlobalColor.green)
        pen.setWidth(5)
        ellipse.setPen(pen)

        # Add the items to the scene. Items are stacked in the order they are added.
        self.scene.addItem(ellipse)
        self.scene.addItem(rect)

        # Set all items as moveable and selectable.
        for item in self.scene.items():
            item.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsMovable)
            item.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsSelectable)

        # Define our layout.
        vbox = QVBoxLayout()

        up = QPushButton("Up")
        up.clicked.connect(self.up)
        vbox.addWidget(up)

        down = QPushButton("Down")
        down.clicked.connect(self.down)
        vbox.addWidget(down)

        rotate = QSlider()
        rotate.setRange(0, 360)
        rotate.valueChanged.connect(self.rotate)
        vbox.addWidget(rotate)

        view = QGraphicsView(self.scene)
        view.setRenderHint(QPainter.RenderHint.Antialiasing)

        hbox = QHBoxLayout(self)
        hbox.addLayout(vbox)
        hbox.addWidget(view)

        self.setLayout(hbox)

    def up(self):
        """Iterate all selected items in the view, moving them forward."""
        items = self.scene.selectedItems()
        for item in items:
            z = item.zValue()
            item.setZValue(z + 1)

    def down(self):
        """Iterate all selected items in the view, moving them backward."""
        items = self.scene.selectedItems()
        for item in items:
            z = item.zValue()
            item.setZValue(z - 1)

    def rotate(self, value):
        """Rotate the object by the received number of degrees."""
        items = self.scene.selectedItems()
        for item in items:
            item.setRotation(value)

app = QApplication(sys.argv)
w = Window()
w.show()
app.exec()

If you run this, you will get a window like that shown below. By selecting an item in the graphics view and then clicking either the "Up" or "Down" button you can move items up and down within the scene -- behind and in front of one another. The items are all moveable, so you can drag them around too. Clicking on the slider will rotate the currently selected items by the set number of degrees:

A graphics scene with some custom controls

The raising and lowering is handled by our custom methods up and down, which work by iterating over the currently selected items in the scene -- retrieved using scene.selectedItems() and then getting the item's z value and increasing or decreasing it respectively:

python

    def up(self):
        """Iterate all selected items in the view, moving them forward."""
        items = self.scene.selectedItems()
        for item in items:
            z = item.zValue()
            item.setZValue(z + 1)

While rotation is handled using the item.setRotation method. This receives the current angle from the QSlider and again, applies it to any currently selected items in the scene:

python

    def rotate(self, value):
        """Rotate the object by the received number of degrees."""
        items = self.scene.selectedItems()
        for item in items:
            item.setRotation(value)

Take a look at the QGraphicsItem documentation for some other properties you can control with widgets and try extending the interface to allow you to change them dynamically.

Summary

In this tutorial, you've learned the fundamentals of PySide6's QGraphics framework to create interactive 2D vector graphics scenes in Python. We covered the three core components: QGraphicsScene, QGraphicsView, and QGraphicsItem. We walked through adding shapes, images and text, controlling stacking order with Z values, making items moveable and selectable, enabling antialiasing, and integrating a QGraphicsView into a standard PySide6 layout with interactive controls.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Basic Kivy Widgets — Learn the Basics of UX Widgets in Kivy

2025-02-01T06:00:00+00:00

Widgets are elements of the graphical user interface (GUI) that provide an application functionality. From buttons and labels to more complex elements like checkboxes, sliders and canvases, widgets receive input and display output. They are the building blocks we use to build user interfaces.

In this tutorial we'll get ourselves up to speed with Kivy's system of widgets, going through the most commonly used widget classes and their basic usage. Before you start, you'll want to be familiar with the basics of how to create apps in Kivy.

Getting to Know Kivy's UX Widgets

Widgets are an integral part of modern graphical user interfaces. We can define a widget as a graphical user interface component that displays information or provides specific functionality. They provide different ways for your users to interact with your app's interface, whether for input or output. Buttons, text labels, text fields, drop-down lists, scrollbars, and progress bars are common examples of widgets.

In Kivy, everything visible in an application window is a widget, including the window itself.

Kivy includes a rich library of widgets which you can use in your own applications. Each widget is implemented as a Python class that implements the look and functionality of the widget they create. For example, you can use the Button class to create a Kivy button. We refer to these as widget classes.

Kivy defines widget classes in dedicated modules that we can find in the kivy.uix package. Each dedicated module is named after the widget that it defines. For example, the kivy.uix.button module and the kivy.uix.label define the Button and Label widgets, respectively.

Kivy groups its widgets into five categories:

UX widgets — basic interactive elements like buttons, labels, and text inputs
Layouts — containers that arrange child widgets on screen
Complex UX widgets — advanced components like file choosers and color pickers
Behavior widgets — mixins that add reusable behavior to other widgets
Screen manager — handles transitions between different app screens

In this section, we will go through some of the UX widgets, their features, and how to use them in your application code.

At the end of this tutorial, we will have created a Kivy application that uses most of the UX widgets. The app will look something like this:

Kivy demo application with multiple UX widgets

We'll start with a simple application outline and start adding widgets from there. Add the following code to a new file named main.py:

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout

Window.clearcolor = (0, 0.31, 0.31, 1.0)

class ApplicationFormApp(App):
    def build(self):
        layout = BoxLayout()
        return layout

ApplicationFormApp().run()

Run this from the command line, as follows.

$ python main.py

You will see a window, in a blue green color (as defined by Window.clearcolor) which contains no other widgets.

Kivy demo app's window

Now, let's start adding widgets to our Kivy demo app. To kick things off, we'll start with an image to display the Kivy logo.

Displaying a Logo With the Kivy `Image` Widget

You can use the Image widget to display images in your UI. It requires a source argument, which should be a Python string representing the file path to your image.

The Image class can be used for various things in your Kivy applications. For example, you could:

Display images in an image gallery app
Add a background image or scene for an app or game
Display an app's logo on a welcome screen

In our sample app, we'll use the Image class to display Kivy's logo at the top of the form:

python

from pathlib import Path

import kivy
from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.image import Image

Window.clearcolor = (0, 0.31, 0.31, 1.0)

class ApplicationFormApp(App):
    def build(self):
        layout = BoxLayout(orientation="vertical", padding=[20, 30])

        logo_path = (
            Path(kivy.__file__).parent / "data" / "logo" / "kivy-icon-512.png"
        )

        layout.add_widget(Image(source=str(logo_path)))

        return layout

ApplicationFormApp().run()

In this code, we create a Kivy application by inheriting the App class. In the build() method, we create a BoxLayout to organize the widget in your Kivy window. Then, we create a pathlib.Path object to represent the path to the Kivy logo. Next, we add an Image instance with the logo as its source argument. Finally, we return the layout, which will be the app's root.

Here's how our application will look:

Kivy demo app with the Kivy logo

At this point, the image takes up the entire window because there are no other widgets in the layout. As we add other widgets, the BoxLayout automatically resizes each, stacking the widgets vertically. The orientation is determined by the orientation parameter we passed when creating the BoxLayout.

Displaying Text With the Kivy `Label` Widget

The Label class creates a widget to display text in a Kivy GUI. We're going to add a Label to our UI to display the title "Application Form" at the top of our window. We'll also add additional Label widgets for the labels on the form.

python

from pathlib import Path

import kivy
from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.image import Image
from kivy.uix.label import Label  # <-- update

YELLOW = (1, 1, 0, 1)

Window.clearcolor = (0, 0.31, 0.31, 1.0)

class ApplicationFormApp(App):
    def build(self):
        layout = BoxLayout(orientation="vertical", padding=[20, 30])

        logo_path = (
            Path(kivy.__file__).parent / "data" / "logo" / "kivy-icon-512.png"
        )

        # updated -->
        title_label = Label(
            text="Application Form", color=YELLOW, font_size=24
        )
        fullname_label = Label(text="Full Name", color=YELLOW, font_size=20)
        about_label = Label(text="About Yourself", color=YELLOW, font_size=20)
        status_label = Label(
            text="[size=18][i]Progress: Page 1/2[/i][/size]",
            color=YELLOW,
            markup=True,
        )
        # <-- updated

        layout.add_widget(Image(source=str(logo_path)))
        # updated -->
        layout.add_widget(title_label)
        layout.add_widget(fullname_label)
        layout.add_widget(about_label)
        layout.add_widget(status_label)
        # <-- updated
        return layout

ApplicationFormApp().run()

In this update, we add four labels to our app. These labels will display the "Application Form", the "Full Name", the "About Yourself" and the "Progress: Page 1/2" text. To define each label, we use the text, color, and font_size arguments.

When creating the object you can pass various arguments to alter the label's appearance. For example:

text
font_size
color
markup

In Kivy, the properties of a widget class are also arguments to the class constructor. So, in this tutorial, we call them either properties or arguments.

The text argument is a Python string whose value will be displayed on your screen. The color argument determines the color of your text. Its value must be a tuple or list of three or four numbers in (red, green, blue, alpha) or (red, green, blue) format, with each value in the range of 0 to 1. By default, the display color is white or (1, 1, 1, 1).

The font_size argument controls how large your text will be and accepts a string, float, or integer value. If you use a string value, then it must have a unit, say font_size="14sp". Otherwise, a default unit (px for pixels) is used. Other units available include pt, mm, cm, in, and dp.

The markup argument in the status label introduces HTML-like tags for styling a label's appearance. You can use this feature to achieve the same effect as you would have gotten using other individual properties. In this example, we have used the markup property to render its text in italics and also to set its font size to 18.

Run the updated code. You'll see a window like the following:

The Kivy demo app with four additional labels

Now, your sample app has the logo at the top and the labels all the way to the bottom. Note that all the objects are spaced uniformly and the logo we added has now shrunk to take the same amount of space as the other elements. This is the default behavior of Kivy's BoxLayout.

Collecting Text Input Data With the Kivy `TextInput` Widget

For an application form to work, users need to be able to enter their information. Next we'll add some input fields, which we'll define using the TextInput class. As the name suggests, this widget provides a way for users to input text.

Let's modify our code to add the fields for "Full Name" and "About Yourself" so we can now accept information from an applicant:

python

from pathlib import Path

import kivy
from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.image import Image
from kivy.uix.label import Label
from kivy.uix.textinput import TextInput  # <-- update

YELLOW = (1, 1, 0, 1)

Window.clearcolor = (0, 0.31, 0.31, 1.0)

class ApplicationFormApp(App):
    def build(self):
        layout = BoxLayout(orientation="vertical", padding=[20, 30])

        logo_path = (
            Path(kivy.__file__).parent / "data" / "logo" / "kivy-icon-512.png"
        )
        title_label = Label(
            text="Application Form", color=YELLOW, font_size=24
        )
        fullname_label = Label(text="Full Name", color=YELLOW, font_size=20)
        about_label = Label(text="About Yourself", color=YELLOW, font_size=20)
        status_label = Label(
            text="[size=18][i]Progress: Page 1/2[/i][/size]",
            color=YELLOW,
            markup=True,
        )

        # update -->
        fullname = TextInput(
            hint_text="Full name", padding=[5, 5], multiline=False
        )
        about = TextInput(hint_text="About yourself", padding=[5, 5])
        # <-- update

        layout.add_widget(Image(source=str(logo_path)))
        layout.add_widget(title_label)
        layout.add_widget(fullname_label)
        layout.add_widget(fullname)  # <-- update
        layout.add_widget(about_label)
        layout.add_widget(about)  # <-- update
        layout.add_widget(status_label)

        return layout

ApplicationFormApp().run()

In this update, we've created the fullname and about text inputs, passing the following arguments to TextInput:

hint_text
padding
multiline
focused

The hint_text argument accepts string values and gives the user an idea of what the text input is meant for. The padding argument holds a list of values that define the padding around the text.

The multiline argument accepts only values of True or False and enables or disables the use of multiple lines of text in a text input widget. Its default value is True, and we have set this to False for the full name field to accept only a single line of input.

If you run the application now, then you'll see the following:

The Kivy demo app with two additional text inputs

While the full name text input allows only a single line of input, you'll notice that it still appears the same as a multi-line input. This can be confusing for users, so we could adjust the size of the widget. To do this, you can set the size_hint_y argument to None and the height argument to an appropriate value in the call to TextInput().

Adding a Save Progress? Option With Boolean Widgets

Now we'll add a Save Progress? option to our app. This is a Boolean option, which we can provide with a few different widgets. In the following sections, we'll add three different UX widgets that allow us to provide Boolean options. We will add a CheckBox, ToggleButton, and Switch widget as a demonstration.

Using the Kivy `CheckBox` Widget

Checkboxes are widgets that give the user the ability to select multiple options from a list of options. You can use these widgets to give the user a choice of disabling/enabling a feature on an interface.

To create checkboxes, we can use the CheckBox widget and instantiate it with a few arguments, including the following:

active
group

As we have done so far with other widgets, let's update our GUI by adding a checkbox. We'll also add a label displaying the "Save Progress?" text:

python

from pathlib import Path

import kivy
from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.checkbox import CheckBox  # <-- update
from kivy.uix.image import Image
from kivy.uix.label import Label
from kivy.uix.textinput import TextInput

YELLOW = (1, 1, 0, 1)

Window.clearcolor = (0, 0.31, 0.31, 1.0)

class ApplicationFormApp(App):
    def build(self):
        layout = BoxLayout(orientation="vertical", padding=[20, 30])

        logo_path = (
            Path(kivy.__file__).parent / "data" / "logo" / "kivy-icon-512.png"
        )
        title_label = Label(
            text="Application Form", color=YELLOW, font_size=24
        )
        fullname_label = Label(text="Full Name", color=YELLOW, font_size=20)
        about_label = Label(text="About Yourself", color=YELLOW, font_size=20)
        status_label = Label(
            text="[size=18][i]Progress: Page 1/2[/i][/size]",
            color=YELLOW,
            markup=True,
        )
        fullname = TextInput(
            hint_text="Full name", padding=[5, 5], multiline=False
        )
        about = TextInput(hint_text="About yourself", padding=[5, 5])

        # update -->
        save_progress = Label(
            text="Save progress?", font_size=18, color=YELLOW
        )
        save_checkbox = CheckBox(active=False)
        h_layout = BoxLayout(padding=[0, 5])
        h_layout.add_widget(save_progress)
        h_layout.add_widget(save_checkbox)
        # <-- update

        layout.add_widget(Image(source=str(logo_path)))
        layout.add_widget(title_label)
        layout.add_widget(fullname_label)
        layout.add_widget(fullname)
        layout.add_widget(about_label)
        layout.add_widget(about)
        layout.add_widget(h_layout)  # <-- update
        layout.add_widget(status_label)

        return layout

ApplicationFormApp().run()

In this updated version of our app, we add the save_progress label and the save_checkbox check box. Note that we've used a horizontal layout to arrange these widgets in a row under the About Yourself text input.

Here's how the app looks now:

The Kivy demo app with an additional checkbox

The CheckBox class accepts an active argument, which we can use to set its state. The state can be either checked or unchecked. However, active can only take values of True or False.

Using the Kivy `ToggleButton` Widget

A ToggleButton is like a regular button, but it stays either ON or OFF when we click it and remains in the corresponding state until we click it again. We can use this widget to provide a toggle option ON/OFF, much like a CheckBox.

Among others, ToggleButton accepts the state argument, which accepts a string value. The allowed values can be either "down" or "normal".

Once more, let's add to our code to include the toggle button:

python

from pathlib import Path

import kivy
from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.checkbox import CheckBox
from kivy.uix.image import Image
from kivy.uix.label import Label
from kivy.uix.textinput import TextInput
from kivy.uix.togglebutton import ToggleButton  # <-- update

YELLOW = (1, 1, 0, 1)

Window.clearcolor = (0, 0.31, 0.31, 1.0)

class ApplicationFormApp(App):
    def build(self):
        layout = BoxLayout(orientation="vertical", padding=[20, 30])

        logo_path = (
            Path(kivy.__file__).parent / "data" / "logo" / "kivy-icon-512.png"
        )
        title_label = Label(
            text="Application Form", color=YELLOW, font_size=24
        )
        fullname_label = Label(text="Full Name", color=YELLOW, font_size=20)
        about_label = Label(text="About Yourself", color=YELLOW, font_size=20)
        status_label = Label(
            text="[size=18][i]Progress: Page 1/2[/i][/size]",
            color=YELLOW,
            markup=True,
        )
        fullname = TextInput(
            hint_text="Full name", padding=[5, 5], multiline=False
        )
        about = TextInput(hint_text="About yourself", padding=[5, 5])
        save_progress = Label(
            text="Save progress?", font_size=18, color=YELLOW
        )
        save_checkbox = CheckBox(active=False)
        h_layout = BoxLayout(padding=[0, 5])
        h_layout.add_widget(save_progress)
        h_layout.add_widget(save_checkbox)

        # update -->
        toggle = ToggleButton(text="Yes")
        h_layout.add_widget(toggle)
        # <-- update

        layout.add_widget(Image(source=str(logo_path)))
        layout.add_widget(title_label)
        layout.add_widget(fullname_label)
        layout.add_widget(fullname)
        layout.add_widget(about_label)
        layout.add_widget(about)
        layout.add_widget(h_layout)
        layout.add_widget(status_label)

        return layout

ApplicationFormApp().run()

In this update, we add a toggle button with the text "Yes". Again, we use the horizontal layout under the About Yourself text input to arrange the widget in our GUI. Here's how the app looks after this update:

The Kivy demo app with an additional toggle button

Now, when you click the Yes toggle button once, you see that it changes to its checked state. You'll know that because the button changes its color to a light blue. If you click the button again, then it gets back to its unchecked or normal state.

Using the Kivy `Switch` Widget

Just like the CheckBox and ToggleButton, we want to add another way of offering the user an option to save the form's progress. We can do that with a Switch widget.

The key property of a Switch is the active property. This property can have a value of True or False corresponding to an ON/OFF position like a light switch.

So, let's add our switch now:

python

from pathlib import Path

import kivy
from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.checkbox import CheckBox
from kivy.uix.image import Image
from kivy.uix.label import Label
from kivy.uix.switch import Switch  # <-- update
from kivy.uix.textinput import TextInput
from kivy.uix.togglebutton import ToggleButton

YELLOW = (1, 1, 0, 1)

Window.clearcolor = (0, 0.31, 0.31, 1.0)

class ApplicationFormApp(App):
    def build(self):
        layout = BoxLayout(orientation="vertical", padding=[20, 30])

        logo_path = (
            Path(kivy.__file__).parent / "data" / "logo" / "kivy-icon-512.png"
        )
        title_label = Label(
            text="Application Form", color=YELLOW, font_size=24
        )
        fullname_label = Label(text="Full Name", color=YELLOW, font_size=20)
        about_label = Label(text="About Yourself", color=YELLOW, font_size=20)
        status_label = Label(
            text="[size=18][i]Progress: Page 1/2[/i][/size]",
            color=YELLOW,
            markup=True,
        )
        fullname = TextInput(
            hint_text="Full name", padding=[5, 5], multiline=False
        )
        about = TextInput(hint_text="About yourself", padding=[5, 5])
        save_progress = Label(
            text="Save progress?", font_size=18, color=YELLOW
        )
        save_checkbox = CheckBox(active=False)
        h_layout = BoxLayout(padding=[0, 5])
        h_layout.add_widget(save_progress)
        h_layout.add_widget(save_checkbox)
        toggle = ToggleButton(text="Yes")
        h_layout.add_widget(toggle)

        # update -->
        switch = Switch(active=True)
        h_layout.add_widget(switch)
        # <-- update

        layout.add_widget(Image(source=str(logo_path)))
        layout.add_widget(title_label)
        layout.add_widget(fullname_label)
        layout.add_widget(fullname)
        layout.add_widget(about_label)
        layout.add_widget(about)
        layout.add_widget(h_layout)
        layout.add_widget(status_label)

        return layout

ApplicationFormApp().run()

In this new update, we've added a Switch widget. The active argument allows you to define whether the switch is ON or OFF. In this example, we set it to True so the switch is ON. Here's how the application looks at this point:

The Kivy demo app with an additional switch

So now we have three different ways of selecting options. In a regular application, we definitely would need only one of these, preferably the CheckBox widget.

Creating a `Button` Widget in Kivy

The Button class comes next. It is one of the most common components of any user interface. It inherits from the Label class directly, which means it possesses all the properties of a label, together with some button-specific properties.

We can use the Button widget to call methods and functions when the user presses or releases the button itself. Around this specific capability, the Button class has two properties to handle that:

on_press
on_release

On our form, we will create a Submit button and attach a method that will close the app when we click the button. Here's the updated code:

python

from pathlib import Path

import kivy
from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button  # <-- update
from kivy.uix.checkbox import CheckBox
from kivy.uix.image import Image
from kivy.uix.label import Label
from kivy.uix.switch import Switch
from kivy.uix.textinput import TextInput
from kivy.uix.togglebutton import ToggleButton

YELLOW = (1, 1, 0, 1)

Window.clearcolor = (0, 0.31, 0.31, 1.0)

class ApplicationFormApp(App):
    def build(self):
        layout = BoxLayout(orientation="vertical", padding=[20, 30])

        logo_path = (
            Path(kivy.__file__).parent / "data" / "logo" / "kivy-icon-512.png"
        )
        layout.add_widget(Image(source=str(logo_path)))
        title_label = Label(
            text="Application Form", color=YELLOW, font_size=24
        )
        fullname_label = Label(text="Full Name", color=YELLOW, font_size=20)
        about_label = Label(text="About Yourself", color=YELLOW, font_size=20)
        status_label = Label(
            text="[size=18][i]Progress: Page 1/2[/i][/size]",
            color=YELLOW,
            markup=True,
        )
        fullname = TextInput(
            hint_text="Full name", padding=[5, 5], multiline=False
        )
        about = TextInput(hint_text="About yourself", padding=[5, 5])
        save_progress = Label(
            text="Save progress?", font_size=18, color=YELLOW
        )
        save_checkbox = CheckBox(active=False)
        h_layout = BoxLayout(padding=[0, 5])
        h_layout.add_widget(save_progress)
        h_layout.add_widget(save_checkbox)
        toggle = ToggleButton(text="Yes")
        h_layout.add_widget(toggle)
        switch = Switch(active=True)
        h_layout.add_widget(switch)

        # update -->
        submit_button = Button(text="Submit")
        submit_button.bind(on_press=self.stop)
        # <-- update

        layout.add_widget(title_label)
        layout.add_widget(fullname_label)
        layout.add_widget(fullname)
        layout.add_widget(about_label)
        layout.add_widget(about)
        layout.add_widget(h_layout)
        layout.add_widget(submit_button)  # <-- update
        layout.add_widget(status_label)

        return layout

ApplicationFormApp().run()

Here, we've created a button with the text Submit. Then, we use the .bind() method to connect the on_press argument to the stop() method. This connection makes it possible to call the method when we click the button. This method terminates the app's execution.

Now your app looks like in the following screenshot:

The Kivy demo app with an additional button

To close a Kivy app, we use the .stop() method. This method will gracefully shut down the application and exit the program. It stops all scheduled events, closes the windows, and cleans up any allocated resources.

Adding a `ProgressBar` Widget in Kivy

The ProgressBar widget is a horizontal bar that displays the progress of an ongoing process, as the name suggests. According to the official documentation, only horizontal progress bars are currently officially supported.

The following arguments are useful when creating a ProgressBar widget:

value
value_normalized
max

We can use the value_normalized and value arguments to set the current progress of the progress bar to a numerical value between 0 and max. The difference between these two arguments is that value allows us to set the value directly, while value_normalized normalizes value inside the range between 0 and 1.

The max argument allows us to set the maximum value of a progress bar. For example, let's say that we have two pages of forms to fill out in our sample app. In this case, we can set max to 2. If we're working with percentages, then the max argument can be 100, which is the default.

Adding a progress bar to our previous code, we now have the final code:

python

from pathlib import Path

import kivy
from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button
from kivy.uix.checkbox import CheckBox
from kivy.uix.image import Image
from kivy.uix.label import Label
from kivy.uix.progressbar import ProgressBar  # <-- update
from kivy.uix.switch import Switch
from kivy.uix.textinput import TextInput
from kivy.uix.togglebutton import ToggleButton

YELLOW = (1, 1, 0, 1)

Window.clearcolor = (0, 0.31, 0.31, 1.0)

class ApplicationFormApp(App):
    def build(self):
        layout = BoxLayout(orientation="vertical", padding=[20, 30])

        logo_path = (
            Path(kivy.__file__).parent / "data" / "logo" / "kivy-icon-512.png"
        )
        title_label = Label(
            text="Application Form", color=YELLOW, font_size=24
        )
        fullname_label = Label(text="Full Name", color=YELLOW, font_size=20)
        about_label = Label(text="About Yourself", color=YELLOW, font_size=20)
        status_label = Label(
            text="[size=18][i]Progress: Page 1/2[/i][/size]",
            color=YELLOW,
            markup=True,
        )
        fullname = TextInput(
            hint_text="Full name", padding=[5, 5], multiline=False
        )
        about = TextInput(hint_text="About yourself", padding=[5, 5])
        save_progress = Label(
            text="Save progress?", font_size=18, color=YELLOW
        )
        save_checkbox = CheckBox(active=False)
        h_layout = BoxLayout(padding=[0, 5])
        h_layout.add_widget(save_progress)
        h_layout.add_widget(save_checkbox)
        toggle = ToggleButton(text="Yes")
        h_layout.add_widget(toggle)
        switch = Switch(active=True)
        h_layout.add_widget(switch)
        submit_button = Button(text="Submit")
        submit_button.bind(on_press=self.stop)

        # update -->
        status_progress = ProgressBar(value=1, max=2)
        # <-- update

        layout.add_widget(Image(source=str(logo_path)))
        layout.add_widget(title_label)
        layout.add_widget(fullname_label)
        layout.add_widget(fullname)
        layout.add_widget(about_label)
        layout.add_widget(about)
        layout.add_widget(h_layout)
        layout.add_widget(submit_button)
        layout.add_widget(status_label)
        layout.add_widget(status_progress)  # <-- update

        return layout

ApplicationFormApp().run()

In the added code, we create a progress bar to track the completion of our hypothetical form. Here's how the app looks after this addition:

The Kivy demo app with an additional progress bar

Because the form is supposed to have two pages, we set max to 2 and value to 1. So, the progress bar shows that we're on the first page.

Exploring Other Kivy UI Widgets

So far we've looked at some of the most common GUI widgets which are useful for building standard forms. However, Kivy also has a few more specialized widgets which you may find useful in your own applications. Next, we'll look at the Video widget for playing videos and the Slider widget, which allows you to select from a range of numerical values.

The Kivy `Video` Widget

The Video widget can be used to play video files. It supports a wide range of video formats. Much like the Image class, the Video widget class accepts a source argument that points to the location of the video file we want to play. We can also pass in a value of "play" to the state argument to make the video start playing once loaded.

The following app shows a window playing the specified video file:

python

from kivy.app import App
from kivy.uix.video import Video

class MainApp(App):
    def build(self):
        player = Video(source="sample-video.mp4", state="play")
        return player

MainApp().run()

Make sure to change the file name to the file path of a video on your local drive, or move an MP4 video into the same folder as your script and rename it to sample-video.mp4.

Run the above code and you'll see a window playing the video passed in the source argument.

The Video widget may come in handy when you want to build a video player app or display an intro video in a game before it starts.

The Kivy `Slider` Widget

We can use the Slider widget to allow users to select from a range of numerical values by moving a thumb along a track. Sliders are commonly used to select numerical values where there are known upper or lower bounds, or for representing progress through a media file.

The Slider class has the following basic arguments:

value
value_normalized
min
max
step
orientation

The value, value_normalized, and max arguments work similarly to those in the ProgressBar widget. The min argument allows us to set the minimum numerical value of the slider.

We can use the step argument to make the slider's progression in discrete steps, rather than being continuous. For example, a step value of 10 makes the slider go from minimum to maximum values in steps of 10.

Then, we have the orientation argument, which accepts either "horizontal" or "vertical" as a value. You can use this argument to create either a horizontal or vertical slider. Its default value is "horizontal".

The example below creates two sliders with values ranging from 0 to 100, set at a current value of halfway in this range:

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.slider import Slider

Window.clearcolor = (0, 0.31, 0.31, 1.0)

class MainApp(App):
    def build(self):
        vertical_slider = Slider(
            min=0,
            max=100,
            value=50,
            step=10,
            orientation="vertical",
        )
        horizontal_slider = Slider(
            min=0,
            max=100,
            value=50,
        )

        layout = BoxLayout()
        layout.add_widget(vertical_slider)
        layout.add_widget(horizontal_slider)

        return layout

MainApp().run()

The first slider is vertically oriented, and it progresses in steps of 10. You can try it out by holding the click on the slider indicator and dragging it up and down. The second slider is horizontally oriented, which is the default orientation. In this case, you have a continuous slider.

Go ahead and run the app. You'll get the following window on your screen:

A Kivy app showing a vertical and a horizontal slider

We can use sliders for a variety of purposes. For example, you can use them to provide volume controls in a media player app. You can also use them in image editing apps for tweaking an image's properties like brightness and contrast.

Conclusion

In this tutorial, we've learned about some of the most important widgets that Kivy provides for building Python GUIs. From buttons and labels to text inputs, checkboxes, switches, sliders, images, and video players, these widgets provide the essential building blocks for creating graphical user interface applications with Kivy.

With these widgets you will be able to start building your own Python GUI applications with Kivy!

Remember to refer to the widgets documentation as you continue to create apps with Kivy. Each widget discussed here has many useful properties that give you wide control over the appearance and functionality to offer in your GUIs.

Introduction to the QGraphics Framework in PyQt6 — Creating vector interfaces using the QGraphics View framework

2024-04-27T07:00:00+00:00

The Qt Graphics View Framework allows you to develop fast and efficient 2D vector graphic scenes. Scenes can contain millions of items, each with their own features and behaviors. By using the Graphics View via PyQt6 you get access to this highly performant graphics layer in Python. Whether you're integrating vector graphics views into an existing PyQt6 application, or simply want a powerful vector graphics interface for Python, Qt's Graphics View is what you're looking for.

Some common uses of the Graphics View include data visualization, mapping applications, 2D design tools, modern data dashboards and even 2D games.

What is the QGraphics View Framework?

The Graphics View framework consists of 3 main parts QGraphicsView, QGraphicsScene, and QGraphicsItem, each with different responsibilities.

QGraphicsScene provides some important functionalities out of the box, so we can use them to develop advanced applications without struggling with low-level details. For example:

Collision Detection: detect when a graphics item has collided with another item.
Item Selection: gives us the ability to deal with multiple items at the same time, for example, the user can select multiple items, and when pressing delete, a function asks the scene to give the list for all selected items, and then delete them.
Items discovery: the scene can tell us what items are present (or part of them) at a specific point or inside some defined region, for example, if the user adds an item that intersects with a forbidden area, the program will detect them and give them another (mostly red) color.
Events Propagation: the scene receives the events and then propagates them to items.

Creating a Simple `QGraphicsScene`

Let's start by creating a simple scene. The following code creates a QGraphicsScene, defining a 400 x 200 scene, and then displays it in a QGraphicsView:

python

import sys
from PyQt6.QtWidgets import QGraphicsScene, QGraphicsView, QApplication

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with its origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

view = QGraphicsView(scene)
view.show()
app.exec()

If you run this example you'll see an empty window:

The empty graphics scene, shown in a QGraphicsView window.

Not very exciting yet -- but this is our QGraphicsView displaying our empty scene.

As mentioned earlier, QGraphicsView is a widget. In Qt any widgets without a parent display as windows. This is why our QGraphicsView appears as a window on the desktop.

Adding Graphic Items to the Scene

python

import sys
from PyQt6.QtWidgets import (
    QGraphicsScene, QGraphicsView, QGraphicsRectItem, QApplication
)
from PyQt6.QtGui import QBrush, QPen
from PyQt6.QtCore import Qt

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with its origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

# Draw a rectangle item, setting the dimensions.
rect = QGraphicsRectItem(0, 0, 200, 50)

# Set the origin (position) of the rectangle in the scene.
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.GlobalColor.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.GlobalColor.cyan)
pen.setWidth(10)
rect.setPen(pen)

scene.addItem(rect)

view = QGraphicsView(scene)
view.show()
app.exec()

Running the above you'll see a single, rather ugly colored, rectangle in the scene:

A single rectangle in the scene

python

import sys
from PyQt6.QtWidgets import (
    QGraphicsScene,
    QGraphicsView,
    QGraphicsRectItem,
    QGraphicsEllipseItem,
    QApplication
)
from PyQt6.QtGui import QBrush, QPen
from PyQt6.QtCore import Qt

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with its origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

# Draw a rectangle item, setting the dimensions.
rect = QGraphicsRectItem(0, 0, 200, 50)

# Set the origin (position) of the rectangle in the scene.
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.GlobalColor.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.GlobalColor.cyan)
pen.setWidth(10)
rect.setPen(pen)

ellipse = QGraphicsEllipseItem(0, 0, 100, 100)
ellipse.setPos(75, 30)

brush = QBrush(Qt.GlobalColor.blue)
ellipse.setBrush(brush)

pen = QPen(Qt.GlobalColor.green)
pen.setWidth(5)
ellipse.setPen(pen)

# Add the items to the scene. Items are stacked in the order they are added.
scene.addItem(ellipse)
scene.addItem(rect)

view = QGraphicsView(scene)
view.show()
app.exec()

The above code will give the following result:

A scene with two items

Controlling Item Stacking Order with ZValue

python

ellipse.setZValue(500)
rect.setZValue(200)

Now the circle (ellipse) appears above the rectangle:

Using ZValue to order items in the scene

Try experimenting with setting the Z value of the two items -- you can set it before or after the items are in the scene, and can change it at any time.

python

rect.stackBefore(ellipse)

You can achieve the same effect by setting the ellipse Z value relative to the rectangle:

python

ellipse.setZValue(rect.zValue() + 1)

Making Items Moveable and Selectable

The full list of graphics item flags is available here.

python

import sys
from PyQt6.QtWidgets import (
    QGraphicsScene,
    QGraphicsView,
    QGraphicsItem,
    QGraphicsRectItem,
    QGraphicsEllipseItem,
    QApplication
)
from PyQt6.QtGui import QBrush, QPen
from PyQt6.QtCore import Qt

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with its origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

# Draw a rectangle item, setting the dimensions.
rect = QGraphicsRectItem(0, 0, 200, 50)

# Set the origin (position) of the rectangle in the scene.
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.GlobalColor.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.GlobalColor.cyan)
pen.setWidth(10)
rect.setPen(pen)

ellipse = QGraphicsEllipseItem(0, 0, 100, 100)
ellipse.setPos(75, 30)

brush = QBrush(Qt.GlobalColor.blue)
ellipse.setBrush(brush)

pen = QPen(Qt.GlobalColor.green)
pen.setWidth(5)
ellipse.setPen(pen)

# Add the items to the scene. Items are stacked in the order they are added.
scene.addItem(ellipse)
scene.addItem(rect)

ellipse.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsMovable)

view = QGraphicsView(scene)
view.show()
app.exec()

If you want an item to be selectable you can enable this by setting the ItemIsSelectable flag, for example here using .setFlags() to set multiple flags at the same time:

python

ellipse.setFlags(QGraphicsItem.ItemIsMovable | QGraphicsItem.ItemIsSelectable)

If you click on the ellipse you'll now see it surrounded by a dashed line to indicate that it is selected. We'll look at how to use item selection in more detail in a later tutorial.

A selected item highlighted with a dashed line

Alternative Way to Create Graphic Items

python

import sys
from PyQt6.QtWidgets import (
    QGraphicsScene,
    QGraphicsView,
    QGraphicsRectItem,
    QApplication
)
from PyQt6.QtGui import QBrush, QPen
from PyQt6.QtCore import Qt

app = QApplication(sys.argv)

scene = QGraphicsScene(0, 0, 400, 200)

rect = scene.addRect(0, 0, 200, 50)
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.GlobalColor.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.GlobalColor.cyan)
pen.setWidth(10)
rect.setPen(pen)

view = QGraphicsView(scene)
view.show()
app.exec()

Feel free to use whichever form you find most comfortable in your code.

You can only use this approach for the built-in QGraphicsItem object types.

Building a Complex Scene with Shapes, Text, and Images

python

from PyQt6.QtCore import QPointF, Qt
from PyQt6.QtWidgets import (
    QGraphicsRectItem,
    QGraphicsScene,
    QGraphicsView,
    QApplication
)
from PyQt6.QtGui import QBrush, QPainter, QPen, QPixmap, QPolygonF
import sys

app = QApplication(sys.argv)

scene = QGraphicsScene(0, 0, 400, 200)

rectitem = QGraphicsRectItem(0, 0, 360, 20)
rectitem.setPos(20, 20)
rectitem.setBrush(QBrush(Qt.GlobalColor.red))
rectitem.setPen(QPen(Qt.GlobalColor.cyan))
scene.addItem(rectitem)

textitem = scene.addText("QGraphics is fun!")
textitem.setPos(100, 100)

scene.addPolygon(
    QPolygonF(
        [
            QPointF(30, 60),
            QPointF(270, 40),
            QPointF(400, 200),
            QPointF(20, 150),
        ]),
    QPen(Qt.GlobalColor.darkGreen),
)

pixmap = QPixmap("cat.jpg")
pixmapitem = scene.addPixmap(pixmap)
pixmapitem.setPos(250, 70)

view = QGraphicsView(scene)
view.setRenderHint(QPainter.RenderHint.Antialiasing)
view.show()
app.exec()

If you run the example above you'll see the following scene:

Scene with multiple items including a rectangle, polygon, text and a pixmap.

Let's step through the code looking at the interesting bits.

Scene with antialiasing disabled.

Antialiasing has a (small) performance impact however, so if you are building scenes with millions of rotated items it may in some cases make sense to turn it off.

Adding a `QGraphicsView` to a PyQt6 Layout

The full code is given below:

python

import sys

from PyQt6.QtCore import Qt
from PyQt6.QtGui import QBrush, QPainter, QPen
from PyQt6.QtWidgets import (
    QApplication,
    QGraphicsEllipseItem,
    QGraphicsItem,
    QGraphicsRectItem,
    QGraphicsScene,
    QGraphicsView,
    QHBoxLayout,
    QPushButton,
    QSlider,
    QVBoxLayout,
    QWidget,
)

class Window(QWidget):
    def __init__(self):
        super().__init__()

        # Defining a scene rect of 400x200, with its origin at 0,0.
        # If we don't set this on creation, we can set it later with .setSceneRect
        self.scene = QGraphicsScene(0, 0, 400, 200)

        # Draw a rectangle item, setting the dimensions.
        rect = QGraphicsRectItem(0, 0, 200, 50)
        rect.setPos(50, 20)
        brush = QBrush(Qt.GlobalColor.red)
        rect.setBrush(brush)

        # Define the pen (line)
        pen = QPen(Qt.GlobalColor.cyan)
        pen.setWidth(10)
        rect.setPen(pen)

        ellipse = QGraphicsEllipseItem(0, 0, 100, 100)
        ellipse.setPos(75, 30)

        brush = QBrush(Qt.GlobalColor.blue)
        ellipse.setBrush(brush)

        pen = QPen(Qt.GlobalColor.green)
        pen.setWidth(5)
        ellipse.setPen(pen)

        # Add the items to the scene. Items are stacked in the order they are added.
        self.scene.addItem(ellipse)
        self.scene.addItem(rect)

        # Set all items as moveable and selectable.
        for item in self.scene.items():
            item.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsMovable)
            item.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsSelectable)

        # Define our layout.
        vbox = QVBoxLayout()

        up = QPushButton("Up")
        up.clicked.connect(self.up)
        vbox.addWidget(up)

        down = QPushButton("Down")
        down.clicked.connect(self.down)
        vbox.addWidget(down)

        rotate = QSlider()
        rotate.setRange(0, 360)
        rotate.valueChanged.connect(self.rotate)
        vbox.addWidget(rotate)

        view = QGraphicsView(self.scene)
        view.setRenderHint(QPainter.RenderHint.Antialiasing)

        hbox = QHBoxLayout(self)
        hbox.addLayout(vbox)
        hbox.addWidget(view)

        self.setLayout(hbox)

    def up(self):
        """Iterate all selected items in the view, moving them forward."""
        items = self.scene.selectedItems()
        for item in items:
            z = item.zValue()
            item.setZValue(z + 1)

    def down(self):
        """Iterate all selected items in the view, moving them backward."""
        items = self.scene.selectedItems()
        for item in items:
            z = item.zValue()
            item.setZValue(z - 1)

    def rotate(self, value):
        """Rotate the object by the received number of degrees."""
        items = self.scene.selectedItems()
        for item in items:
            item.setRotation(value)

app = QApplication(sys.argv)
w = Window()
w.show()
app.exec()

A graphics scene with some custom controls

python

    def up(self):
        """Iterate all selected items in the view, moving them forward."""
        items = self.scene.selectedItems()
        for item in items:
            z = item.zValue()
            item.setZValue(z + 1)

While rotation is handled using the item.setRotation method. This receives the current angle from the QSlider and again, applies it to any currently selected items in the scene:

python

    def rotate(self, value):
        """Rotate the object by the received number of degrees."""
        items = self.scene.selectedItems()
        for item in items:
            item.setRotation(value)

Take a look at the QGraphicsItem documentation for some other properties you can control with widgets and try extending the interface to allow you to change them dynamically.

Summary

In this tutorial, you've learned the fundamentals of PyQt6's QGraphics framework to create interactive 2D vector graphics scenes in Python. We covered the three core components: QGraphicsScene, QGraphicsView, and QGraphicsItem. We walked through adding shapes, images and text, controlling stacking order with Z values, making items moveable and selectable, enabling antialiasing, and integrating a QGraphicsView into a standard PyQt6 layout with interactive controls.

Hopefully this introduction to the Qt Graphics View framework has given you some ideas of what you can do with it. In the next tutorials we'll look at how events and user interaction can be handled on items and how to create custom & compound items for your own scenes.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Working With Python Virtual Environments — Setting Your Python Working Environment, the Right Way

2024-03-04T06:00:00+00:00

As Python developers, we often need to add functionality to our applications which isn't provided by the standard library. Rather than implement everything ourselves, we can instead install 3rd party Python packages from the official Python package index at PyPI using pip. The pip tool downloads and installs these 3rd party packages into our Python installation so we can immediately use them in our scripts and applications.

The Python standard library is a set of Python modules and packages that come bundled with Python installers. This library includes modules and packages like math and usually Tkinter.

There is a caveat here though: we can only install a single version of a package at any one time. While this isn't a problem when you create your first project, when you create the second any changes you make to the dependencies will also affect the first project. If any of your dependencies depend on other packages themselves (usually the case!) you may encounter conflicts where fixing the dependencies for one project breaks the dependencies for another.

This is known as dependency hell.

Thankfully, Python has a solution for this: Python virtual environments. Using virtual environments you can manage the packages for each project independently.

In this tutorial, we will learn how to create virtual environments using venv and use them to manage our Python projects and their dependencies. We will also learn why virtual environments are an essential tool in any Python developer's arsenal.

Why You Need Python Virtual Environments

When working on a Python project, we often rely on specific external or third-party package versions. However, as packages get updated, their way of working may change.

If we update a package, the changes in that package may mean other projects stop functioning. To solve this issue, we have a few different options:

Continue using the outdated version of the package in all our projects.
Update all our projects whenever a new version of the package comes out.
Use Python virtual environments to isolate the projects and their dependencies.

Not updating packages means that we won't be able to take advantage of new features or improvements. It can also affect the security of our project because we're not up-to-date with essential security updates and bug fixes for the Python packages our project relies on.

On the other hand, constantly updating our projects to keep them functional isn't much fun. While not always necessary, it quickly can become tedious and impractical, depending on the scale and the number of projects we have.

The last and best option is to use Python virtual environments. They allow us to manage the Python packages needed for each application separately. So we can choose when to update dependencies without affecting other projects that rely on those packages.

Using virtual environments gives us the benefit of being able to update packages without the risk of breaking all our projects at once. It gives us more time to make sure that each project works properly with the updated package version. It also avoids conflicts between package requirements and dependency requirements in our various projects.

Finally, using Python virtual environments is also recommended to avoid system conflicts because updating a package may break essential system tools or libraries that rely on a particular version of the package.

How Python Virtual Environments Work

A Python virtual environment is a folder containing a lightweight installation of Python. It creates a stripped-down and isolated copy of the base Python installation on our system without requiring us to install Python again.

Because a virtual environment is an isolated copy of our current system Python, we will find a copy of the python and pip executables inside each virtual environment folder. Once we activate a virtual environment, any python or pip commands will point to these executables instead of the ones in our system installation.

We can check where our system currently points Python commands by running python -c "import sys; print(sys.executable)". If we are not using a virtual environment, this command will show us where the system Python installation is located. Inside a virtual environment, it will point to the environment's executable.

Using a virtual environment also means that pip will install external packages in the environment's site folder rather than in the system's. This way, we can keep different versions of a Python package installed in independent virtual environments. However, we still can only have one version of a given package per virtual environment.

Install Python On Your System

In case you haven't done it yet, you need to install Python on your development machine before being able to create virtual environments.

Install Python on Windows or macOS

You can install Python by going to its download page and grabbing the specific installer for either Windows or macOS. Then, you have to run the installer and follow the on-screen instructions. Make sure you select the option to Add Python to PATH during the installation process.

Python is also available for installation through Microsoft Store on Windows machines. For a more detailed walkthrough, see our guide on how to install Python on Windows.

Install Python on Linux

If you are on Linux, you can check if Python is installed on your machine by running the python3 --version command in a terminal. If this command results in an error, you can install Python from your Linux distribution repository.

You will find that the Python version available in most Linux repositories is relatively old. To work around this issue, you can use tools like pyenv, which allows the installation of multiple Python versions.

For example, on Ubuntu and Debian, you can install Python by executing:

$ sudo apt install python3

You may also need to install pip, the Python package installer, and venv, the module that allows you to create virtual environments. To do this, run the following command:

$ sudo apt install python3-pip python3-venv

You only need to install pip and venv separately in some Linux distributions, including Ubuntu and Debian.

Create a Python Virtual Environment With `venv`

The standard way to create virtual environments in Python is to use the venv module, which is a part of the standard library, so you shouldn't need to install anything additional on most systems.

A virtual environment is a stripped-down and isolated copy of an existing Python installation, so it doesn't require downloading anything.

You'll typically create a virtual environment per project. However, you can also have custom virtual environments with different purposes in your system.

To add a new virtual environment to a project, go to your project folder and run the following command in a terminal:

$ python -m venv ./venv

If you check inside your project folder now, you'll see a new subfolder named venv. This folder contains the virtual environment you just made.

Using venv, env, or .venv as the virtual environment name is a common and accepted practice in the Python community.

How to Activate and Use a Python Virtual Environment

Now that you've successfully created your Python virtual environment, you can start using it to install whatever packages you need for your project. Note that every new virtual environment is like a fresh Python installation, with no third-party packages available.

Unless you choose to pass the --system-site-packages switch to the venv command when you create the virtual environment, it will only contain the Python standard library and a couple of required packages. For any additional packages, we need to use pip to install them.

In the following sections, you'll learn how to activate your virtual environment for use, install packages, manage dependencies, and more.

Activate the Virtual Environment

To start using a virtual environment, you need to activate it. The command to do this depends on your operating system and terminal shell.

On Unix systems, such as macOS and Linux, you can run the following command:

$ source venv/bin/activate

This command activates your virtual environment, making it ready for use. You'll know that because your prompt will change from $ to (venv) $. Go ahead and run the following command to check your current Python interpreter:

(venv) $ python -c "import sys; print(sys.executable)"
/path/to/project/venv/bin/python

The output of this command will contain the path to the virtual environment interpreter. This interpreter is different from your system interpreter.

If you're on Windows and using PowerShell, then you can activate your virtual environment by running the following command:

PS> venv\Scripts\activate

Again, you'll know the environment is active because your prompt will change from PS> to (venv) PS>.

Great! With these steps completed, we're now ready to start using our Python virtual environment.

Install Packages in the Virtual Environment With pip

Once the virtual environment is active, we can start using pip to install any packages our project requires. For example, say you want to install the PyQt GUI framework to create desktop apps. In this case, you can run the following command:

(venv) $ python -m pip install pyqt6

This command downloads and installs PyQt from the Python package index directly. Now you can start working on your GUI project. If you're unsure which Python GUI library to choose, there are several options available depending on your needs.

Once you've activated a virtual environment, you can use pip directly without the python -m prefix. However, best practices recommend using this command format.

You can also install multiple packages in one go:

(venv) $ python -m pip install black flake8 mypy pytest

To install multiple packages with a single command, you only have to list the desired packages separated by spaces, as you did in the above command.

Finally, sometimes it's also useful to update a given package to its latest version:

(venv) $ python -m pip install --upgrade pyqt6

The --upgrade flag tells pip to install the latest available version of an already installed package.

Deactivate a Virtual Environment

Once you are done working on your GUI app, you need to deactivate the virtual environment so you can switch back to your system shell or terminal. Remember that you'll have to reactivate this virtual environment next time you need to work on your project.

Here's how you can deactivate a Python virtual environment:

(venv) $ deactivate

This command deactivates your virtual environment and gets you back into your system shell. You can run the python -c "import sys; print(sys.executable)" command to check that your current Python interpreter is your system Python.

Manage the Locations of Your Virtual Environments

Although you can place your virtual environments anywhere on your computer, there are a few standardized places for them to live. The most common one is inside the relevant project folder. As you already learned, the folder will usually be named venv or .venv.

If you use Git for version control, make sure to ignore the virtual environment folder by adding it to .gitignore.

If you want to have all your virtual environments in a central location, then you can place them in your home folder. Directories like ~/.venvs and ~/.virtualenvs are commonly used locations.

The Python extension for Visual Studio Code automatically looks for any virtual environments in a couple of places, including inside your current project folder and specific folders in your home folder (if they exist). If you want to specify additional external folders for it to look in, go to Settings and configure python.venvFolders or python.venvPath. To avoid confusion, it's a good idea to name each virtual environment in this folder after the relevant project name.

Delete a Python Virtual Environment

If you are no longer working with a given virtual environment, you can get rid of it and all the related Python packages by simply deleting the virtual environment folder.

If you delete the virtual environment associated with a given project, to run the project again, you'll have to create a new virtual environment and install the required packages.

Manage Your Project's Dependencies With pip and requirements.txt

You've already learned how to create Python virtual environments to isolate the dependencies of your projects and avoid package versioning issues across different projects. You also learned how to install external dependencies with pip.

In the following sections, you'll learn how to efficiently manage a project's dependencies using pip and requirement files.

Generate a Requirements File With pip freeze

An important advantage of using a dedicated virtual environment for each of our Python projects is that the environment will only contain the packages for that specific project. We can use the pip freeze command to get the list of currently installed packages in any active virtual environment:

(venv) $ python -m pip freeze
PyQt6==6.5.0
PyQt6-Qt6==6.5.0
PyQt6-sip==13.5.1

This command allows us to create a requirements.txt file containing the list of the packages our project needs to run. To do this, go ahead and run the following command:

(venv) $ python -m pip freeze > requirements.txt

After running the above command, you'll have a new file called requirements.txt in your project's directory.

By convention, the Python community uses the name requirements.txt for those files containing the list of dependencies of a given project. This file typically lives in the project's root directory.

Run the following command to check the content of this new file:

$ cat requirements.txt
PyQt6==6.5.0
PyQt6-Qt6==6.5.0
PyQt6-sip==13.5.1

As you can see, your requirements.txt file lists those packages that you've installed in the active virtual environment. Once you have this file in place, anyone who needs to run your project from its source will know which packages they need to install. More importantly, they can use the file to install all the dependencies automatically, as you'll learn in the following section.

Install Project Dependencies From a Requirements File

Besides being able to see the list of Python packages our application needs, the requirements file also makes installing those packages in a new virtual environment just one command away:

(new_venv) $ python -m pip install -r requirements.txt

The -r option of pip install allows you to provide a requirement file as an argument. Then, pip will read that file and install all the packages listed in it. If you run pip freeze again, you'll note that this new environment has the same packages installed.

Tweak the Requirements File

Although using pip freeze is quite convenient, it often creates a lot of unnecessary clutter by populating the requirement file with Python packages that our application may not rely on directly—for example, packages that are dependencies of required packages and packages that are only needed for development.

The generated file will also include the exact version of each package we have installed. While this may be useful, it is best to keep the requirement file clean. For example, dependencies of dependencies can often be ignored, since managing those is the responsibility of the corresponding package. That way, it'll be easy to know which packages are really required.

For example, in a GUI project, the requirements.txt file may only need to include PyQt6. In that case it would look like this:

$ cat requirements.txt
PyQt6==6.5.0

Specifying the highest or lowest version of required packages may also be beneficial. To do this, we can replace the equality operator (==) with the less than (<=) or greater than (>=) operators, depending on your needs. If we completely omit the package version, pip will install the latest version available.

Create a Development Requirements File

We should consider splitting our project requirement file into two separate files—for example, requirements.txt and requirements_dev.txt. This separation lets other developers know which packages are required for your project and which are solely relevant for development and testing purposes.

For example, you may use Black for formatting, flake8 for linting, mypy for type checking, and pytest for testing your code. In this case, your requirements_dev.txt file should look something like this:

$ cat requirements_dev.txt
black
flake8
mypy
pytest

With this file in place, developers who want to contribute to your project can install the required development dependencies easily.

Conclusion

By now, you have a good understanding of how Python virtual environments work. They are straightforward to create with the venv module and make it easy to manage the Python packages you need for developing your applications and projects.

Avoid installing Python packages outside of a virtual environment whenever possible. Creating a dedicated environment for a small Python script may not make sense. However, it's always a good idea to start any Python project that requires external packages by creating its own virtual environment. This is especially important when packaging your applications for distribution, where having clean, well-defined dependencies makes the process much smoother.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

How to Create a Custom Title Bar for a PyQt6 Window — Build Modern, Stylish Custom Title Bars for Your Python Desktop Apps

2023-11-27T13:00:00+00:00

PyQt provides plenty of tools for creating unique and visually appealing graphical user interfaces (GUIs). One aspect of your applications that you may not have considered customizing is the title bar. The title bar is the topmost part of the window, where your users find the app's name, window controls & other elements.

This part of the window is usually drawn by the operating system or desktop environment, and its default look and feel may not gel well with the rest of your application. However, you may want to customize it to add additional functionality. For example, in web browsers the document tabs are now typically collapsed into the title bar to maximize available space for viewing pages.

In this tutorial, you will learn how to create custom title bars in PyQt6 step by step. We'll cover creating frameless windows, adding window control buttons, handling window dragging with the mouse, and styling the title bar with a modern unified look. By the end, you'll have the knowledge to enhance your PyQt applications with personalized and stylish title bars.

Creating Frameless Windows in PyQt6

The first step to providing a PyQt application with a custom title bar is to remove the default title bar and window decoration provided by the operating system. If we don't take this step, we'll end up with multiple title bars at the top of our windows.

In PyQt, we can create a frameless window using the setWindowFlags() method available on all QWidget subclasses, including QMainWindow. We call this method, passing in the FramelessWindowHint flag, which lives in the Qt namespace under the WindowType enumeration.

Here's the code of a minimal PyQt app whose main window is frameless:

python

from PyQt6.QtCore import Qt
from PyQt6.QtWidgets import QApplication, QMainWindow

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()

After importing the required classes, we create a window by subclassing QMainWindow. In the class initializer method, we set the window's title and resize the window using the resize() method. Then we use the setWindowFlags() to make the window frameless. The rest is the usual boilerplate code for creating PyQt applications.

If you run this app from your command line, you'll get the following window on your screen:

A frameless window in PyQt6

As you can see, the app's main window doesn't have a title bar or any other decoration. It's only a gray rectangle on your screen.

Because the window has no buttons, you need to press Alt-F4 on Windows and Linux or Cmd+Q on macOS to close the app.

This isn't very helpful, of course, but we'll be adding back in our custom title bar shortly.

Setting Up the Main Window

Before creating our custom title bar, we'll finish the initialization of our app's main window, import some additional classes and create the window's central widget and layouts.

Here's the code update:

python

from PyQt6.QtCore import Qt
from PyQt6.QtWidgets import (
    QApplication,
    QLabel,
    QMainWindow,
    QVBoxLayout,
    QWidget,
)

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        central_widget = QWidget()
        self.title_bar = CustomTitleBar(self)

        work_space_layout = QVBoxLayout()
        work_space_layout.setContentsMargins(11, 11, 11, 11)
        work_space_layout.addWidget(QLabel("Hello, World!", self))

        centra_widget_layout = QVBoxLayout()
        centra_widget_layout.setContentsMargins(0, 0, 0, 0)
        centra_widget_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
        centra_widget_layout.addWidget(self.title_bar)
        centra_widget_layout.addLayout(work_space_layout)

        central_widget.setLayout(centra_widget_layout)
        self.setCentralWidget(central_widget)

# ...

First, we import the QLabel, QVBoxLayout, and QWidget classes. In our window's initializer, we create a central widget by instantiating QWidget(). Next, we create an instance attribute called title_bar by instantiating a class called CustomTitleBar. We still need to implement this class—we'll do this in a moment.

The next step is to create a layout for our window's workspace. In this example, we're using a QVBoxLayout, but you can use the layout that best fits your needs. We also set some margins for the layout content and added a label containing the phrase "Hello, World!".

Next, we create a global layout for our central widget. Again, we use a QVBoxLayout. We set the layout's margins to 0 and aligned it on the top of our frameless window. In this layout, we need to add the title bar at the top and the workspace at the bottom. Finally, we set the central widget's layout and the app's central widget.

That's it! We have all the boilerplate code we need for our window to work correctly. Now we're ready to write our custom title bar.

In this section, we will create a custom title bar for our main window. To do this, we will create a new class by inheriting from QWidget. First, go ahead and update your imports like in the code below:

python

from PyQt6.QtCore import QSize, Qt
from PyQt6.QtGui import QPalette
from PyQt6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QStyle,
    QToolButton,
    QVBoxLayout,
    QWidget,
)

# ...

Here, we've imported a few new classes. We will use these classes as building blocks for our title bar. Without further ado, let's get into the title bar code. We'll introduce the code in small consecutive chunks to facilitate the explanation. Here's the first piece:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        self.setAutoFillBackground(True)
        self.setBackgroundRole(QPalette.ColorRole.Highlight)
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)

In this code snippet, we create a new class by inheriting from QWidget. This way, our title bar will have all the standard features and functionalities of any PyQt widgets. In the class initializer, we set autoFillBackground to true because we want to give a custom color to the bar. The next line of code sets the title bar's background color to QPalette.ColorRole.Highlight, which is a blueish color.

The next line of code creates and initializes an instance attribute called initial_pos. We'll use this attribute later on when we deal with moving the window around our screen.

The final three lines of code allow us to create a layout for our title bar. Because the title bar should be horizontally oriented, we use a QHBoxLayout class to structure it.

Adding a Window Title Label

The piece of code below deals with our window's title:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        # ...
        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setStyleSheet(
            """QLabel {
                   font-weight: bold;
                   border: 2px solid black;
                   border-radius: 12px;
                   margin: 2px;
                }
            """
        )
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        if title := parent.windowTitle():
            self.title.setText(title)
        title_bar_layout.addWidget(self.title)

The first line of new code creates a title attribute. It's a QLabel object that will hold the window's title. Because we want to build a cool title bar, we'd like to add some custom styling to the title. To do this, we use the setStyleSheet() method with a string representing a CSS style sheet as an argument. The style sheet tweaks the font, borders, and margins of our title label.

Next, we center the title using the setAlignment() method with the Qt.AlignmentFlag.AlignCenter flag as an argument.

In the conditional statement, we check whether our window has a title. If that's the case, we set the text of our title label to the current window's title. Finally, we added the title label to the title bar layout.

Adding Minimize, Maximize, Close, and Restore Buttons

The next step in our journey to build a custom title bar is to provide standard window controls. In other words, we need to add the minimize, maximize, close, and normal buttons. These buttons will allow our users to interact with our window. To create the buttons, we'll use the QToolButton class.

Here's the required code:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        # ...
        # Min button
        self.min_button = QToolButton(self)
        min_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMinButton
        )
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMaxButton
        )
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarCloseButton
        )
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarNormalButton
        )
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)

In this code snippet, we define all the required buttons by instantiating the QToolButton class. The minimize, maximize, and close buttons follow the same pattern. We create the button, define an icon for the buttons at hand, and set the icon using the setIcon() method.

Note that we use the standard icons that PyQt provides. For example, the minimize button uses the SP_TitleBarMinButton icon. Similarly, the maximize and close buttons use the SP_TitleBarMaxButton and SP_TitleBarCloseButton icons. We find all these icons in the QStyle.StandardPixmap namespace.

Finally, we connect the button's clicked() signal to the appropriate slot. For the minimize button, the proper slot is .showMinimized(). For the maximize and close buttons, the right slots are .showMaximized() and close(), respectively. All these slots are part of the main window's class.

The normal button at the end of the above code uses the SP_TitleBarNormalButton icon and showNormal() slot. This button has an extra setting. We've set its visibility to False, meaning that the button will be hidden by default. It'll only appear when we maximize the window to allow us to return to the normal state.

Styling and Adding Buttons to the Layout

Now that we've created and tweaked the buttons, we must add them to our title bar. To do this, we can use the following for loop:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        # ...
        buttons = [
            self.min_button,
            self.normal_button,
            self.max_button,
            self.close_button,
        ]
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(28, 28))
            button.setStyleSheet(
                """QToolButton {
                        border: 2px solid white;
                        border-radius: 12px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

This loop iterates over our four buttons in a predefined order. The first thing to do inside the loop is to define the focus policy of each button. We don't want these buttons to steal focus from widgets in the window's workspace, so we set their focus policy to NoFocus.

Next, we set a fixed size of 28 by 28 pixels for the three buttons using the setFixedSize() method with a QSize object as an argument.

Our main goal in this section is to create a custom title bar. A handy way to customize the look and feel of PyQt widgets is to use CSS style sheets. In the above piece of code, we use the setStyleSheet() method to apply a custom CSS style sheet to our four buttons. The sheet defines a white and round border for each button.

The final line in the above code calls the addWidget() method to add each custom button to our title bar's layout. That's it! We're now ready to give our title bar a try. Go ahead and run the application from your command line. You'll see a window like the following:

A PyQt6 window with a custom title bar

This is pretty simple styling, but you get the idea. You can tweak the title bar further, depending on your needs. For example, you can change the colors and borders, customize the title's font, add other widgets to the bar, and more.

We'll apply some nicer styles later, once we have the functionality in place! Keep reading.

Even though the title bar looks different, it has limited functionality. For example, if you click the maximize button, then the window will change to its maximized state. However, the normal button won't show up to allow you to return the window to its previous state.

In addition to this, if you try to move the window around your screen, you'll quickly notice a problem: it's impossible to move the window!

In the following sections, we'll write the necessary code to fix these issues and make our custom title bar fully functional. To kick things off, let's start by fixing the state issues.

Updating the Window's State on Maximize and Restore

To fix the issue related to the window's state, we'll override the changeEvent() method on the MainWindow class. This method is called directly by Qt whenever the window state changes, e.g. if the window is maximized or hidden. By overriding this event, we can add our own custom behavior.

Here's the code that overrides the changeEvent() method:

python

from PyQt6.QtCore import QSize, Qt, QEvent
# ...

class MainWindow(QMainWindow):
    # ...

    def changeEvent(self, event):
        if event.type() == QEvent.Type.WindowStateChange:
            self.title_bar.window_state_changed(self.windowState())
        super().changeEvent(event)
        event.accept()

This method is fairly straightforward. We check the event type to see if it is a WindowStateChange. If that's the case, we call the window_state_changed() method of our custom title bar, passing the current window's state as an argument. In the final two lines, we call the parent class's changeEvent() method and accept the event to signal that we've correctly processed it.

Here's the implementation of our window_state_changed() method in CustomTitleBar:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def window_state_changed(self, state):
        if state == Qt.WindowState.WindowMaximized:
            self.normal_button.setVisible(True)
            self.max_button.setVisible(False)
        else:
            self.normal_button.setVisible(False)
            self.max_button.setVisible(True)

This method takes a window's state as an argument. Depending on the value of the state parameter, we will show or hide the maximize and restore buttons.

First, if the window is currently maximized we will show the normal button and hide the maximize button. Alternatively, if the window is currently not maximized we will hide the normal button and show the maximize button.

The effect of this, together with the order we added the buttons above, is that when you maximize the window the maximize button will appear to be replaced with the normal button. When you restore the window to its normal size, the normal button will be replaced with the maximize button.

Go ahead and run the app again. Click the maximize button. You'll note that when the window gets maximized, the middle button changes its icon. Now you have access to the normal button. If you click it, then the window will recover its previous state.

Handling Window Dragging with Mouse Events

Now it's time to write the code that enables us to move the window around the screen while holding the mouse's left button on the title bar. To do this, we only need to add code to the CustomTitleBar class.

In particular, we need to override three mouse events:

mousePressEvent() will let us know when the user clicks on our custom title bar using the mouse's left button. This may indicate that the window movement should start.
mouseMoveEvent() will let us process window movement.
mouseReleaseEvent() will let us know when the user has released the mouse's left button so that we can stop moving the window.

Here's the code that overrides the mousePressEvent() method:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            self.initial_pos = event.position().toPoint()
        super().mousePressEvent(event)
        event.accept()

In this method, we first check if the user clicks on the title bar using the mouse's left-click button. If that's the case, then we update our initial_pos attribute to the clicked point. Remember that we defined initial_pos and initialized it to None back in the __init__() method of CustomTitleBar.

Next, we need to override the mouseMoveEvent() method. Here's the required code:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def mouseMoveEvent(self, event):
        if self.initial_pos is not None:
            delta = event.position().toPoint() - self.initial_pos
            self.window().move(
                self.window().x() + delta.x(),
                self.window().y() + delta.y(),
            )
        super().mouseMoveEvent(event)
        event.accept()

This if statement in mouseMoveEvent() checks if the initial_pos attribute is not None. If this condition is true, then the if code block executes because we have a valid initial position.

The first line in the if code block calculates the difference, or delta, between the current and initial mouse positions. To get the current position, we call the position() method on the event object and convert that position into a QPoint object using the toPoint() method.

The following four lines update the position of our application's main window by adding the delta values to the current window position. The move() method does the hard work of moving the window.

In summary, this code updates the window position based on the movement of our mouse. It tracks the initial position of the mouse, calculates the difference between the initial position and the current position, and applies that difference to the window's position.

Finally, we can complete the mouseReleaseEvent() method:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def mouseReleaseEvent(self, event):
        self.initial_pos = None
        super().mouseReleaseEvent(event)
        event.accept()

This method's implementation is pretty straightforward. Its purpose is to reset the initial position by setting it back to None when the mouse is released, indicating that the drag is complete.

That's it! Go ahead and run your app again. Click on your custom title bar and move the window around while holding the mouse's left-click button. Can you move the window? Great! Your custom title bar is now fully functional.

The completed code for the custom title bar is shown below:

python

from PyQt6.QtCore import QEvent, QSize, Qt
from PyQt6.QtGui import QPalette
from PyQt6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QStyle,
    QToolButton,
    QVBoxLayout,
    QWidget,
)

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        self.setAutoFillBackground(True)
        self.setBackgroundRole(QPalette.ColorRole.Highlight)
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)

        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setStyleSheet(
            """QLabel {
                   font-weight: bold;
                   border: 2px solid black;
                   border-radius: 12px;
                   margin: 2px;
                }
            """
        )
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        if title := parent.windowTitle():
            self.title.setText(title)
        title_bar_layout.addWidget(self.title)

        # Min button
        self.min_button = QToolButton(self)
        min_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMinButton,
        )
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMaxButton,
        )
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarCloseButton
        )
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarNormalButton
        )
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)
        # Add buttons
        buttons = [
            self.min_button,
            self.normal_button,
            self.max_button,
            self.close_button,
        ]
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(28, 28))
            button.setStyleSheet(
                """QToolButton {
                        border: 2px solid white;
                        border-radius: 12px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

    def window_state_changed(self, state):
        if state == Qt.WindowState.WindowMaximized:
            self.normal_button.setVisible(True)
            self.max_button.setVisible(False)
        else:
            self.normal_button.setVisible(False)
            self.max_button.setVisible(True)

    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            self.initial_pos = event.position().toPoint()
        super().mousePressEvent(event)
        event.accept()

    def mouseMoveEvent(self, event):
        if self.initial_pos is not None:
            delta = event.position().toPoint() - self.initial_pos
            self.window().move(
                self.window().x() + delta.x(),
                self.window().y() + delta.y(),
            )
        super().mouseMoveEvent(event)
        event.accept()

    def mouseReleaseEvent(self, event):
        self.initial_pos = None
        super().mouseReleaseEvent(event)
        event.accept()

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        central_widget = QWidget()
        self.title_bar = CustomTitleBar(self)

        work_space_layout = QVBoxLayout()
        work_space_layout.setContentsMargins(11, 11, 11, 11)
        work_space_layout.addWidget(QLabel("Hello, World!", self))

        central_widget_layout = QVBoxLayout()
        central_widget_layout.setContentsMargins(0, 0, 0, 0)
        central_widget_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
        central_widget_layout.addWidget(self.title_bar)
        central_widget_layout.addLayout(work_space_layout)

        central_widget.setLayout(central_widget_layout)
        self.setCentralWidget(central_widget)

    def changeEvent(self, event):
        if event.type() == QEvent.Type.WindowStateChange:
            self.title_bar.window_state_changed(self.windowState())
        super().changeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()

Styling a Modern Unified Title Bar with QSS

So far, we've covered the technical aspects of styling our window with a custom title bar, and added the code to make it function as expected. But it doesn't look great. In this section we'll take our existing code & tweak the styling and buttons to produce something that's a little more professional looking.

One common reason for wanting to apply custom title bars to a window is to integrate the title bar with the rest of the application. This technique is called a unified title bar and can be seen in some popular applications such as web browsers, or Spotify:

In this section, we'll look at how we can reproduce the same effect in PyQt using a combination of stylesheets and icons. Below is a screenshot of the final result which we'll be building:

As you can see the window and the toolbar blend nicely together and the window has rounded corners. There are a few different ways to do this, but we'll cover a simple approach using Qt stylesheets to apply styling over the entire window.

Creating a Translucent Background Window

In order to customize the shape of the window, we need to first tell the OS to stop drawing the default window outline and background for us. We do that by setting a window attribute on the window. This is similar to the flags we already discussed, in that it turns on and off different window manager behaviors:

python

# ...
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
        # ...

We've added a call to self.setAttribute(), which sets the attribute Qt.WidgetAttribute.WA_TranslucentBackground on the window. If you run the code now, you will see the window has become transparent, with only the widget text and toolbar visible.

Applying Rounded Corners with a Container Widget

Next, we'll tell Qt to draw a new custom background for us. If you've worked with QSS before, the most obvious way to apply curved edges to the window using QSS stylesheets would be to set border-radius styles on the main window directly:

python

#...
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        # ...
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
        self.setStyleSheet("background-color: gray; border-radius: 10px;")
#...

However, if you try this, you'll notice that it doesn't work. If you enable a translucent background, the background of the window is not drawn (including your styles). If you don't set translucent background, the window is filled to the edges with a solid color ignoring the border radius:

The good news is that, with a bit of lateral thinking, there is a simple solution. We already know that we can construct interfaces by nesting widgets in layouts. Since we can't style the border-radius of a window, but we can style any other widget, the solution is to simply add a container widget into our window and apply the curved-edge and background styles to that.

On our MainWindow class, we already have a central widget which contains our layout, so we can apply the styles there:

python

# ...

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        # ...
        central_widget = QWidget()
        # This container holds the window contents, so we can style it.
        central_widget.setObjectName("Container")
        central_widget.setStyleSheet(
            """#Container {
                    background: qlineargradient(x1:0 y1:0, x2:1 y2:1, stop:0 #051c2a stop:1 #44315f);
                    border-radius: 5px;
                }
            """
        )
        self.title_bar = CustomTitleBar(self)
        # ...

We've taken the existing central_widget object and assigned an object name to it. This is an ID which we can use to refer to the widget from QSS and apply our styles specifically to that widget.

If you're familiar with CSS, you might expect that IDs like #Container must be unique. However, they are not: you can give multiple widgets the same object name if you like. So you can re-use this technique and QSS on multiple windows in your application without problems.

With this style applied on our window, we have a nice gradient background with curved corners.

Making the Title Bar Transparent

Unfortunately, the title bar we created is drawn filled, so the background and curved corners of our window are overwritten. To make things look coherent we need to make our title bar also transparent by removing the background color & auto-fill behavior we set earlier.

We don't need to set any flags or attributes on this widget because it is not a window. A QWidget object is transparent by default.

We can also make some tweaks to the style of the title label, such as making the title capitalized using text-transform: uppercase, adjusting the font size and color -- feel free to customize this yourself:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        # self.setAutoFillBackground(True) # <-- remove
        # self.setBackgroundRole(QPalette.ColorRole.Highlight) # <-- remove
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)
        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.title.setStyleSheet(
            """QLabel {
                    text-transform: uppercase;
                    font-size: 10pt;
                    margin-left: 48px;
                    color: white;
                }
            """
        )

QSS is very similar to CSS, especially for text styling.

The margin-left: 48px is to compensate for the 3 × 16 px window icons on the right-hand side so the text aligns centrally.

Using Custom SVG Icons for Window Buttons

The icons are currently using built-in Qt icons which are a little bit plain & ugly. Next let's update the icons, using custom SVG icons of simple colored circles, for the minimize, maximize, close & restore buttons:

python

from PyQt6.QtGui import QIcon
# ...
class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        # ...
        # Min button
        self.min_button = QToolButton(self)
        min_icon = QIcon()
        min_icon.addFile('min.svg')
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = QIcon()
        max_icon.addFile('max.svg')
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = QIcon()
        close_icon.addFile('close.svg') # Close has only a single state.
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = QIcon()
        normal_icon.addFile('normal.svg')
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)
        # ...

This code follows the same basic structure as before, but instead of using the built-in icons here we're loading our icons from SVG images. These images are very simple, consisting of a single circle in green, red or yellow for the different states mimicking macOS.

The normal.svg file for returning a maximized window to normal size shows a semi-transparent green circle for simplicity's sake, but you can include iconography and hover behaviors on the buttons if you prefer.

The final step is to iterate through the created buttons, adding them to the title bar layout. This is slightly tweaked from before to remove the border styling replacing it with simple padding and setting the icon sizes to 16px. Because we are using SVG files, the icons will automatically scale to the available space:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        # ...
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(16, 16))
            button.setStyleSheet(
                """QToolButton {
                        border: none;
                        padding: 2px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

And that's it! With these changes, you can now run your application and you'll see a nice sleek modern-looking UI with unified title bar and custom controls:

The final result, showing our unified title bar and window design.

Complete Code for the Styled Custom Title Bar

The complete code is shown below:

python

from PyQt6.QtCore import QEvent, QSize, Qt
from PyQt6.QtGui import QIcon
from PyQt6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QToolButton,
    QVBoxLayout,
    QWidget,
)

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)
        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.title.setStyleSheet(
            """QLabel {
                    text-transform: uppercase;
                    font-size: 10pt;
                    margin-left: 48px;
                    color: white;
                }
            """
        )

        if title := parent.windowTitle():
            self.title.setText(title)
        title_bar_layout.addWidget(self.title)

        # Min button
        self.min_button = QToolButton(self)
        min_icon = QIcon()
        min_icon.addFile("min.svg")
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = QIcon()
        max_icon.addFile("max.svg")
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = QIcon()
        close_icon.addFile("close.svg")  # Close has only a single state.
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = QIcon()
        normal_icon.addFile("normal.svg")
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)
        # Add buttons
        buttons = [
            self.min_button,
            self.normal_button,
            self.max_button,
            self.close_button,
        ]
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(16, 16))
            button.setStyleSheet(
                """QToolButton {
                        border: none;
                        padding: 2px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

    def window_state_changed(self, state):
        if state == Qt.WindowState.WindowMaximized:
            self.normal_button.setVisible(True)
            self.max_button.setVisible(False)
        else:
            self.normal_button.setVisible(False)
            self.max_button.setVisible(True)

    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            self.initial_pos = event.position().toPoint()
        super().mousePressEvent(event)
        event.accept()

    def mouseMoveEvent(self, event):
        if self.initial_pos is not None:
            delta = event.position().toPoint() - self.initial_pos
            self.window().move(
                self.window().x() + delta.x(),
                self.window().y() + delta.y(),
            )
        super().mouseMoveEvent(event)
        event.accept()

    def mouseReleaseEvent(self, event):
        self.initial_pos = None
        super().mouseReleaseEvent(event)
        event.accept()

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
        central_widget = QWidget()
        # This container holds the window contents, so we can style it.
        central_widget.setObjectName("Container")
        central_widget.setStyleSheet(
            """#Container {
                    background: qlineargradient(x1:0 y1:0, x2:1 y2:1, stop:0 #051c2a stop:1 #44315f);
                    border-radius: 5px;
                }
            """
        )
        self.title_bar = CustomTitleBar(self)

        work_space_layout = QVBoxLayout()
        work_space_layout.setContentsMargins(11, 11, 11, 11)
        hello_label = QLabel("Hello, World!", self)
        hello_label.setStyleSheet("color: white;")
        work_space_layout.addWidget(hello_label)

        centra_widget_layout = QVBoxLayout()
        centra_widget_layout.setContentsMargins(0, 0, 0, 0)
        centra_widget_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
        centra_widget_layout.addWidget(self.title_bar)
        centra_widget_layout.addLayout(work_space_layout)

        central_widget.setLayout(centra_widget_layout)
        self.setCentralWidget(central_widget)

    def changeEvent(self, event):
        if event.type() == QEvent.Type.WindowStateChange:
            self.title_bar.window_state_changed(self.windowState())
        super().changeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()

Note that you've also set the color of the "Hello, World!" label to white so that it's visible on a dark background.

Conclusion

In this tutorial, we have learned the fundamentals of creating custom title bars in PyQt. To do this, we have combined PyQt's widgets, layouts, and styling capabilities to create a visually appealing title bar for a PyQt app.

With this skill under your belt, you're now ready to create title bars that align perfectly with your application's unique style and branding. This will allow you to break away from the standard window decoration provided by your operating system and add a personal touch to your user interface.

Now let your imagination run and transform your PyQt application's UX.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

How to Restore the Window's Geometry in a PyQt6 App — Make Your Windows Remember Their Last Position and Size

2023-11-13T06:00:00+00:00

In GUI applications the window's position & size are known as the window geometry. Saving and restoring the geometry of a window between executions is a useful feature in many applications. With persistent geometry users can arrange applications on their desktop for an optimal workflow and have the applications return to those positions every time they are launched.

In this tutorial, we will explore how to save and restore the geometry and state of a PyQt window using the QSettings class. With this functionality, you will be able to give your PyQt6 applications a usability boost.

To follow along with this tutorial, you should have prior knowledge of creating GUI apps with Python and PyQt. Additionally, having a basic understanding of using the QSettings class to manage an application's settings will be beneficial.

Understanding a Window's Geometry in PyQt6

PyQt defines the geometry of a window using a few properties. These properties represent a window's position on the screen and size. Here's a summary of PyQt's geometry-related properties:

Property	Description	Access Method
`x`	Holds the `x` coordinate of a widget relative to its parent. If the widget is a window, `x` includes any window frame and is relative to the desktop. This property defaults to `0`.	`x()`
`y`	Holds the `y` coordinate of a widget relative to its parent. If the widget is a window, `y` includes any window frame and is relative to the desktop. This property defaults to `0`.	`y()`
`pos`	Holds the position of the widget within its parent widget. If the widget is a window, the position is relative to the desktop and includes any frame.	`pos()`
`geometry`	Holds the widget's geometry relative to its parent and excludes the window frame.	`geometry()`
`width`	Holds the width of the widget, excluding any window frame.	`width()`
`height`	Holds the height of the widget, excluding any window frame.	`height()`
`size`	Holds the size of the widget, excluding any window frame.	`size()`

In PyQt, the QWidget class provides the access methods in the table above. Note that when your widget is a window or form, the first three methods operate on the window and its frame, while the last four methods operate on the client area, which is the window's workspace without the external frame.

Additionally, the x and y coordinates are relative to the screen of your computer. The origin of coordinates is the upper left corner of the screen, at which point both x and y are 0.

Let's create a small demo app to inspect all these properties in real time. To do this, go ahead and fire up your code editor or IDE and create a new Python file called geometry_properties.py. Then add the following code to the file and save it in your favorite working directory:

python

from PyQt6.QtWidgets import (
    QApplication,
    QLabel,
    QMainWindow,
    QPushButton,
    QVBoxLayout,
    QWidget,
)

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.resize(400, 200)
        self.central_widget = QWidget()
        self.global_layout = QVBoxLayout()
        self.geometry_properties = [
            "x",
            "y",
            "pos",
            "width",
            "height",
            "size",
            "geometry",
        ]
        for prop in self.geometry_properties:
            self.__dict__[f"{prop}_label"] = QLabel(f"{prop}:")
            self.global_layout.addWidget(self.__dict__[f"{prop}_label"])
        button = QPushButton("Update Geometry Properties")
        button.clicked.connect(self.update_labels)
        self.global_layout.addWidget(button)
        self.central_widget.setLayout(self.global_layout)
        self.setCentralWidget(self.central_widget)

    def update_labels(self):
        for prop in self.geometry_properties:
            self.__dict__[f"{prop}_label"].setText(
                f"{prop}: {getattr(self, prop)()}"
            )

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

Wow! There's a lot of code in this file. First, we import the required classes from PyQt6.QtWidgets. Then, we create our app's main window by inheriting from QMainWindow.

In the initializer method, we set the window's title and size using setWindowTitle() and resize(), respectively. Next, we define a central widget and a layout for our main window.

We also define a list of properties. We'll use that list to add some QLabel objects. Each label will show a geometry property and its current values. The Update Geometry Properties button allows us to update the value of the window's geometry properties.

Finally, we define the update_labels() method to update the values of all the geometry properties using their corresponding access methods. That's it! Go ahead and run the app. You'll get the following window on your screen:

A Window Showing Labels for Every Geometry Property

Looking good! Now go ahead and click the Update Geometry Properties button. You'll see how all the properties get updated. Your app's window will look something like this:

A Window Showing the Current Value of Every Geometry Property

As you can see, x and y are numeric values, while pos is a QPoint object with x and y as its coordinates. These properties define the position of this window on your computer screen.

The width and height properties are also numeric values, while the size property is a QSize object defined after the current width and height.

Finally, the geometry property is a QRect object. In this case, the rectangle comprises x, y, width, and height.

Great! With this first approach to how PyQt defines a window's geometry, we're ready to continue digging into this tutorial's main topic: saving and restoring the geometry of a window in PyQt6.

Saving and Loading Window Geometry Settings With `QSettings`

Users of GUI apps will generally expect the apps to remember their settings across sessions. This information is often referred to as settings or preferences. In PyQt applications, you'll manage settings and preferences using the QSettings class. This class allows you to have persistent platform-independent settings in your GUI app.

A commonly expected feature is that the app remembers the geometry of its windows, particularly the main window.

In this section, you'll learn how to save and restore the window's geometry in a PyQt6 application. Let's start by creating a skeleton PyQt application to kick things off. Go ahead and create a new Python file called geometry.py. Once you have the file opened in your favorite code editor or IDE, then add the following code:

python

from PyQt6.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

This code creates a minimal PyQt app with an empty main window. The window will appear at 50 pixels from the upper left corner of your computer screen and have a size of 400 by 200 pixels.

We'll use the above code as a starting point to make the app remember and restore the main window's geometry across sessions.

First, we need to have a QSettings instance in our app. Therefore, you have to import QSettings from PyQt6.QtCore and instantiate it as in the code below:

python

from PyQt6.QtCore import QSettings
from PyQt6.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")

When instantiating QSettings, we must provide the name of our company or organization and the name of our application. We use "PythonGUIs" as the organization and "GeometryApp" as the application name.

Now that we have a QSettings instance, we should implement two methods. The first method should allow you to save the app's settings and preferences. The second method should help you read and load the settings. In this tutorial, we'll call these methods write_settings() and read_settings(), respectively:

python

class Window(QMainWindow):
    # ...

    def write_settings(self):
        # Write settings here...

    def read_settings(self):
        # Read settings here...

Note that our methods don't do anything yet. You'll write them in a moment. For now, they're just placeholders.

The write_settings() method must be called when the user closes or terminates the application. This way, you guarantee that all the modified settings get saved for the next session. So, the appropriate place to call write_settings() is from the main window's close event handler.

Let's override the closeEvent() method as in the code below:

python

class Window(QMainWindow):
    # ...

    def closeEvent(self, event):
        self.write_settings()
        super().closeEvent(event)
        event.accept()

In this code, we override the closeEvent() handler method. The first line calls write_settings() to ensure that we save the current state of our app's settings. Then, we call the closeEvent() of our superclass QMainWindow to ensure the app's window closes correctly. Finally, we accept the current event to signal that it's been processed.

Now, where should we call read_settings() from? In this example, the best place for calling the read_settings() method is .__init__(). Go ahead and add the following line of code to the end of your __init__() method:

python

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.read_settings()

By calling the read_settings() method from __init__(), we ensure that our app will read and load its settings every time the main window gets created and initialized.

Great! We're on the way to getting our application to remember and restore its window's geometry. First, you need to know that you have at least two ways to restore the geometry of a window in PyQt6:

Using the pos and size properties
Using the geometry property

In both cases, you need to save the current value of the selected property and load the saved value when the application starts. To kick things off, let's start with the first approach.

Restoring the Window's Geometry With `pos` and `size`

In this section, we'll first write the required code to save the current value of pos and size by taking advantage of our QSettings object. The code snippet below shows the changes that you need to make on your write_settings() method to get this done:

python

class Window(QMainWindow):
    # ...

    def write_settings(self):
        self.settings.setValue("pos", self.pos())
        self.settings.setValue("size", self.size())

This code is straightforward. We call the setValue() method on our setting object to set the "pos" and "size" configuration parameters. Note that we get the current value of each property using the corresponding access method.

With the write_settings() method updated, we're now ready to read and load the geometry properties from our app's settings. Go ahead and update the read_settings() method as in the code below:

python

class Window(QMainWindow):
    # ...

    def read_settings(self):
        self.move(self.settings.value("pos", defaultValue=QPoint(50, 50)))
        self.resize(self.settings.value("size", defaultValue=QSize(400, 200)))

The first line inside read_settings() retrieves the value of the "pos" setting parameter. If there's no saved value for this parameter, then we use QPoint(50, 50) as the default value. Next, the move() method moves the app's window to the resulting position on your screen.

The second line in read_settings() does something similar to the first one. It retrieves the current value of the "size" parameter and resizes the window accordingly.

Great! It's time for a test! Go ahead and run your application. Then, move the app's window to another position on your screen and resize the window as desired. Finally, close the app's window to terminate the current session. When you run the app again, the window will appear in the same position. It will also have the same size.

If you have any issues completing and running the example app, then you can grab the entire code below:

python

from PyQt6.QtCore import QPoint, QSettings, QSize
from PyQt6.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.read_settings()

    def write_settings(self):
        self.settings.setValue("pos", self.pos())
        self.settings.setValue("size", self.size())

    def read_settings(self):
        self.move(self.settings.value("pos", defaultValue=QPoint(50, 50)))
        self.resize(self.settings.value("size", defaultValue=QSize(400, 200)))

    def closeEvent(self, event):
        self.write_settings()
        super().closeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

Now you know how to restore the geometry of a window in a PyQt6 app using the pos and size properties. It's time to change gears and learn how to do this using the geometry property.

Restoring the Window's Geometry With `saveGeometry()` and `restoreGeometry()`

We can also restore the geometry of a PyQt window using the saveGeometry() and restoreGeometry() methods. This approach is often preferred because it handles edge cases like multi-monitor setups more robustly. To do that, we first need to save the current geometry using our QSettings object.

Go ahead and create a new Python file in your working directory. Once you have the file in place, add the following code to it:

python

from PyQt6.QtCore import QByteArray, QSettings
from PyQt6.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.read_settings()

    def write_settings(self):
        self.settings.setValue("geometry", self.saveGeometry())

    def read_settings(self):
        self.restoreGeometry(self.settings.value("geometry", QByteArray()))

    def closeEvent(self, event):
        self.write_settings()
        super().closeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

There are only two changes in this code compared to the code from the previous section. We've modified the implementation of the write_settings() and read_settings() methods.

In write_settings(), we use setValue() to save the current geometry of our app's window. The saveGeometry() method serializes the window's geometry into a QByteArray, which includes position, size, and additional metadata. In read_settings(), we call the value() method to retrieve the saved geometry value. Then, we use restoreGeometry() to restore the geometry of our window.

Again, you can run the application consecutive times and change the position and size of its main window to ensure your code works correctly.

Restoring the Window's Geometry and State Including Toolbars and Dock Widgets

If your app's window has toolbars and dock widgets, then you want to restore their state on the parent window. To do that, you can use the restoreState() method. To illustrate this, let's reuse the code from the previous section.

Update the content of write_settings() and read_settings() as follows:

python

class Window(QMainWindow):
    # ...

    def write_settings(self):
        self.settings.setValue("geometry", self.saveGeometry())
        self.settings.setValue("windowState", self.saveState())

    def read_settings(self):
        self.restoreGeometry(self.settings.value("geometry", QByteArray()))
        self.restoreState(self.settings.value("windowState", QByteArray()))

In write_settings(), we add a new setting value called "windowState". To keep this setting, we use the saveState() method, which saves the current state of this window's toolbars and dock widgets. Meanwhile, in read_settings(), we restore the window's state by calling the value() method, as usual, to get the state value back from our QSettings object. Finally, we use restoreState() to restore the state of toolbars and dock widgets.

Now, to make sure that this new code works as expected, let's add a sample toolbar and a dock window to our app's main window. Go ahead and add the following methods right after the __init__() method:

python

from PyQt6.QtCore import QByteArray, QSettings, Qt
from PyQt6.QtWidgets import QApplication, QDockWidget, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's State")
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.create_toolbar()
        self.create_dock()
        self.read_settings()

    def create_toolbar(self):
        toolbar = self.addToolBar("Toolbar")
        toolbar.addAction("One")
        toolbar.addAction("Two")
        toolbar.addAction("Three")

    def create_dock(self):
        dock = QDockWidget("Dock", self)
        dock.setAllowedAreas(
            Qt.DockWidgetArea.LeftDockWidgetArea
            | Qt.DockWidgetArea.RightDockWidgetArea
        )
        self.addDockWidget(Qt.DockWidgetArea.LeftDockWidgetArea, dock)

    # ...

In this new update, we first import the Qt namespace from PyQt6.QtCore and QDockWidget from PyQt6.QtWidgets. Then we call the two new methods from __init__() to create the toolbar and dock widget at initialization time.

In the create_toolbar() method, we create a sample toolbar with three sample buttons. This toolbar will show at the top of our app's window by default.

Next, we create a dock widget in create_dock(). This widget will occupy the rest of our window's working area.

That's it! You're now ready to give your app a try. You'll see a window like the following:

A Window Showing a Sample Toolbar and a Dock Widget

Play with the toolbar and the dock widget. Move them around. Then close the app's window and run the app again. Your toolbar and dock widget will show in the last position you left them.

Conclusion

Through this tutorial, you have learned how to save and restore the geometry and state of a window in PyQt6 applications using the QSettings class. By utilizing the pos, size, saveGeometry(), restoreGeometry(), saveState(), and restoreState() methods, you can give your users the convenience of persistent window position and size across sessions.

With this knowledge, you can enhance the usability of your PyQt6 applications, making your app more intuitive and user-friendly. Remembering window geometry is a small detail that significantly improves the overall user experience of desktop Python GUI applications.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Customizing Your Tkinter App's Windows — Make Your Tkinter App's Windows Have Different Looks

2023-07-25T06:00:00+00:00

Different desktop applications have different design requirements. If you look at the applications on your computer, you will see that most of them have different window designs. Some applications, like games, run in full-screen mode. Utility applications, like calculators, run in fixed-size mode with the maximize or minimize button disabled.

Forms or windows have different appearances based on their app's requirements. As you create your own Tkinter applications, you might also want to have windows without a title bar, windows that can't be resized, windows that are zoomed, and even windows that show some level of transparency.

In this tutorial, you will learn some Tkinter tricks and techniques that you can use to customize your applications' windows.

Getting to Know Window Configurations

In Tkinter, a window configuration is either a setting or an attribute that you can use to specify a property of that window. These properties may include the window's width, height, position, transparency, title bar, background color, and more.

These configurations allow you to tweak and customize the look and feel of your application's windows and forms so that they look modern and nice in the eyes of your app's users.

For example, let's say you want to create a game, and you need to remove the main window's title bar. Keep reading to learn how to do this in Tkinter.

Creating a Simple Window in Tkinter

To kick things off, let's create a minimal Tkinter app that will work as our starting point for learning how to remove a window's title bar. Here's the required code:

python

from tkinter import Tk

# Create the app's main window
root = Tk()
root.title("Window With a Title Bar")
root.geometry("400x300+300+120")

# Run the app's main loop
root.mainloop()

Here, we import Tk from tkinter. Then we create the app's main window, root, by instantiating Tk. Next, we give our window a title and geometry using the title() and geometry() methods, respectively.

Go ahead and save this code to a file called app.py. Then run the file from your command line. The output will look something like this:

A Tkinter app showing a window with the default title bar

On your screen, you'll get a regular Tkinter window with the title bar and the decoration provided by your current operating system.

Removing the Window's Title Bar in Tkinter

Tkinter makes it possible for you to remove the system-provided title bar of your app's main window. This tweak is handy when building a custom GUI that doesn't use the default window decorations.

The default title bar highlighted on our example window

In the image above, the red border highlights the window's title bar. That's what we want to remove. To do that, we can use a method called overrideredirect(). If we pass True as an argument to this method, then we'll get a frameless window.

Go ahead and update your code. Make it look something like this:

python

from tkinter import Tk

# Create the app's main window
root = Tk()
root.geometry("400x300+300+120")

# Removes the window's title bar
root.overrideredirect(True)

# Run the app's main loop
root.mainloop()

By calling root.overrideredirect(True), we tell the window manager (which manages windows on your desktop) not to wrap the window in the usual window decorations. If you run the app again, then you will get the following output:

A Tkinter app showing a window without title bar

You have successfully created a Tkinter app with a window that doesn't have the standard window decorations from your desktop window manager.

Because the app's window has no close button, you must press Alt+F4 to close the window and terminate the app.

Disabling the Window's Maximize/Minimize Button

There are some situations where we would want to have a window with a title bar but with a fixed size. That would be the case with a calculator application, for example. To do that, we can use the resizable() method, which takes two boolean arguments:

width specifies whether the window can be horizontally resized.
height specifies whether the window can be vertically resized.

If you pass False for both arguments, you will disable resizing in both directions. Below we've modified the code for our simple Tkinter app, preventing users from resizing the main window:

python

from tkinter import Tk

# Create the app's main window
root = Tk()
root.title("Fixed Size Window")
root.geometry("400x300+300+120")

# Disable the window's resizing capability
root.resizable(False, False)

# Run the app's main loop
root.mainloop()

In this example, the code calls resizable() with its width and height argument set to False. This call makes the window unresizable. If you run this app, then you'll get the output shown below:

A Tkinter app showing a fixed size window

Try to resize this window by dragging any of its borders, and you'll find that you can't resize it in either direction. You will also discover that the maximize/minimize buttons are now also disabled, preventing you from resizing the window in this way.

Displaying the App's Window in Zoomed Mode

Tkinter also allows you to display an app's window in zoomed mode. In zoomed mode, your application's window will display in fullscreen. A common scenario where this mode comes in handy is when you want to provide an immersive experience to your users.

On Windows and macOS, the method for displaying the app's window in zoomed mode is state(). You can pass the "zoomed" string as an argument to this method to get the desired result. The code for that will look like below:

python

from tkinter import Tk

# Create the app's main window
root = Tk()
root.title("Zoomed Window")
root.geometry("400x300+300+120")

# Set the window to a zoomed mode
root.state("zoomed")

# Run the app's main loop
root.mainloop()

The line root.state("zoomed") makes the window display already zoomed on both Windows and macOS. If you are on Linux, then use root.attributes("-zoomed", True) instead. The app's window looks something like this:

A Tkinter app showing a zoomed window

In this screenshot, you can see that the application's main window occupies the entire screen, which gives you a larger working area.

Changing the Window's Transparency Level

What if you wanted to change the transparency of your app's main window? You can do this using the attributes() method. To set the transparency, you provide two arguments: first the string "-alpha", then a floating-point number that ranges from 0.0 to 1.0. A value of 0.0 represents the highest transparency level (full transparency, your window will become invisible), while a value of 1.0 value represents the lowest level (no transparency).

Let's create a window with a 0.6 transparency level:

python

from tkinter import Tk

# Create the app's main window
root = Tk()
root.title("0.6 Transparency Window")
root.geometry("400x300+300+120")

# Set the -alpha value to 0.6
root.attributes("-alpha", 0.6)

# Run the app's main loop
root.mainloop()

In this example, we set the "-alpha" attribute to 0.6. This tweak generates a window that looks something like this:

A Tkinter app showing a transparent window

Your app's main window is now 60% transparent. Isn't that cool? Do you have any creative ideas for your next application?

Conclusion

In this tutorial, you've gone through the process of customizing the root window of a Tkinter application using several different methods, attributes, and properties. You've learned how to remove the title bar of a window, make a window have a fixed size, display a window in zoomed mode, and more.

Now that you know how to customize your app's windows, you might want to explore adding widgets and layouts to build more complete interfaces, or learn how to style your Tkinter applications with themes for a more polished look. If you're ready to build a full project, check out our guide to building a calculator with Tkinter.

Getting Started With Kivy for GUI Development in Python — Your First Steps Building Cross-Platform Apps With the Kivy Library

2023-05-31T08:00:00+00:00

Kivy is an open-source Python library for building graphical user interfaces (GUIs). It supports cross-platform development for the desktop as well as the creation of multi-touch apps for mobile devices.

Kivy apps can run across several platforms, including Windows, Linux, macOS, Android, and iOS. One place where Kivy particularly shines is in game development. By combining Kivy's 2D physics capabilities with a simple physics engine, you can create impressive 2D simulations and games.

In this tutorial, you'll learn how to build Python GUI applications with Kivy. We'll cover installing Kivy, creating a simple app, working with widgets and layouts, drawing 2D shapes on the Kivy canvas, and styling your interfaces with the Kv language.

To get the most out of this tutorial, you should have basic knowledge of Python. Previous knowledge of general concepts of GUI programming, such as event loops, widgets, layouts, and forms, is also a plus.

There are many different Python GUI libraries available, and choosing one for your project can be a really tough and confusing decision to make. For advice see our guide Which Python GUI Library to Choose for your Project.

Let's get started. We'll first take a few moments to install and set up Kivy on your computer.

How to Install Kivy for Python

Before using a third-party library like Kivy, we must install it in our working environment. Installing Kivy is as quick as running the python -m pip install kivy command on your terminal or command line. This command will install the library from the Python package index (PyPI).

Note that as of the time of writing this tutorial, Kivy only officially supports Python versions up to 3.10. For detailed information about installing Kivy, visit the official installation guide.

However, when working with third-party libraries, it's good practice to create a Python virtual environment, which is a self-contained Python installation for a particular version of Python that you can use to isolate the dependencies of a given project.

To create a virtual environment, you'll typically use Python's venv module from the standard library. Fire up a command-line window and type in the following command in your working directory.

$ python -m venv kivy_env

This command will create a folder called kivy_env containing a Python virtual environment. The Python version in this environment is the same as you get when you run python --version on your command line.

Next, we need to activate the virtual environment. Use the appropriate command, depending on whether you're on Windows, macOS, or Linux:

Windows
macOS
Linux

sh
C:/> .\kivy_env\Scripts\activate

sh
$ source kivy_env/bin/activate

sh
$ source kivy_env/bin/activate

Once that's confirmed to be working, you can then install Kivy within the virtual environment you just created by running the following:

(kivy_env) $ python -m pip install kivy

With this command, you'll install Kivy in your active Python virtual environment, so you're now ready to go.

You can also install Kivy by downloading its source code directly from GitHub and doing a manual installation on the command line. For more information on following this installation path, check out the section about installing Kivy from source in the documentation.

Writing Your First Kivy GUI App in Python

Without further ado, let's get right into creating our first app with Kivy and Python. For this app, we will use a Label object to display the traditional "Hello, World!" message on our screen. To write a minimal Kivy GUI app, we need to run a few steps:

Subclassing the App class
Implementing its build() method, which returns a Widget instance
Instantiating this class and calling its run() method

Let's start by importing the required classes. For our example, we only need the App and Label classes. Create a Python file called app.py and add the following imports:

python

from kivy.app import App
from kivy.uix.label import Label

The App class provides the base functionality required to create GUI apps with Kivy, such as managing the event loop. Meanwhile, the Label class will work as the root visual element or widget for our GUI.

Next, we can create our subclass of App. We have called it MainApp here. However, you can call it whatever you like:

python

from kivy.app import App
from kivy.uix.label import Label

class MainApp(App):
    def build(self):
        return Label(text="Hello, World!")

This subclass uses the concept of inheritance in object-oriented programming (OOP) in Python. All the attributes and methods defined in the superclass, App, are automatically inherited by the subclass, MainApp.

In order for our app to create a UI, we need to define a build() method. In build(), we create and return either a widget or layout, which will be the root object in our UI structure.

The build() method is the entry point to whatever will be drawn on the screen. In our example, it creates and returns a label with the "Hello, World!" text on it.

Finally, we need to create an instance of MainApp and call its run() method:

python

from kivy.app import App
from kivy.uix.label import Label

class MainApp(App):
    def build(self):
        return Label(text="Hello, World!")

MainApp().run()

In the final line, we create an instance of MainApp and call its run() method. This method launches the application and runs its main loop. That's it! We're ready to run our first Kivy app. Open your command line and run the following command:

$ python app.py

You'll see the following window on your screen:

First Kivy GUI Application

Great! You've just written your first Kivy GUI app using Python. It shows a black window with the message "Hello, World!" In its center. Note that the window's title bar shows the title Main, which comes from the name of your App subclass.

The next step is to explore some other essential features of Kivy that will allow you to write fully-functional GUI apps with this library.

Exploring Kivy Widgets and Layouts

In the previous section, we mentioned widgets and layouts a few times -- you may be wondering what they are! A widget is an element of a GUI that displays information or provides a specific function. They allow your users to interact with your app's GUI.

A layout, on the other hand, provides a way of arranging widgets into a particular structure in your application's windows. A layout can also give certain behaviors to widgets that belong to it, like the ScatterLayout, which enables multi-touch resizing of a child widget.

In Kivy, you'll find widget and layout classes in their corresponding module under the kivy.uix module. For example, to import the Button class, we can use:

python

from kivy.uix.button import Button

In Kivy, widgets and layout classes are usually located in modules named after the class itself. However, the class uses CamelCase, and the containing module uses lower casing.

For example, take the following imports:

python

# Widgets
from kivy.uix.label import Label
from kivy.uix.image import Image

# Layouts
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.floatlayout import FloatLayout

You'll find some exceptions to this naming convention. For example:

python

from kivy.uix.image import AsyncImage
from kivy.uix.screenmanager import FadeTransition

This commonly happens with modules that define multiple and closely related classes, such as Image and AsyncImage.

Common Kivy Widgets

Widgets are the building blocks of Kivy-based GUIs. Some of the most commonly used GUI widgets in Kivy apps include the following:

Widget is the base class required for creating widgets.
Label is used for rendering text on windows and dialogs.
TextInput provides a box for editable plain text.
Button triggers actions when the user presses it.
CheckBox provides a two-state button that can be either checked or unchecked.
Image is used to display an image on your GUIs.
ProgressBar visualizes the progress of some tasks.
DropDown provides a versatile drop-down list that can list different widgets.

With these widgets and some others that Kivy provides, you can build complex and user-friendly interfaces for your applications.

Kivy Layout Classes

Kivy also has a rich set of layout classes that allows you to arrange your widgets coherently and functionally to build up GUIs. Some examples of common layouts include:

BoxLayout arranges widgets sequentially in either a vertical or horizontal fashion.
FloatLayout arranges widgets in a specific position on the containing window.
RelativeLayout arranges child widgets according to relative positions.
GridLayout arranges widgets in a grid defined by the rows and columns.
PageLayout creates multi-page layouts in a way that allows flipping from one page to another.
ScatterLayout positions its child widgets similarly to a RelativeLayout.
StackLayout stacks in a left-to-right and then top-to-bottom order, or top-to-bottom then left-to-right order.

You can combine and nest layouts together to build complex user interfaces.

Using Kivy Widgets and Layouts: A Practical Example

As an example of how to use widgets and layouts in Kivy, let's look at a commonly used layout class: the GridLayout. With this class, we can create a grid of rows and columns. Each cell of the grid has a unique pair of zero-based coordinates. Consider the following example:

python

from kivy.app import App
from kivy.uix.button import Button
from kivy.uix.gridlayout import GridLayout

ROWS = COLS = 3

class GridApp(App):
    def build(self):
        root = GridLayout(rows=ROWS, cols=COLS)
        for i in range(ROWS):
            for j in range(COLS):
                root.add_widget(Button(text=f"({i}, {j})"))
        return root

GridApp().run()

In the build() method, we instantiate the GridLayout with three rows and three columns. Then use a for loop to add button widgets to the layout using the add_widget() method.

When we run this app, we get the window that is shown below:

Grid Layout in Kivy

Each button on the grid shows its corresponding pair of coordinates. The first coordinate represents the row, while the second represents the column. Like the rest of the layout classes, GridLayout can take several arguments that you can use to fine-tune its behavior.

Drawing 2D Shapes in Kivy With the `canvas` Property

To deeply customize a GUI or design a 2D video game, we may need to draw 2D shapes, such as a rectangle, circle, ellipse, or triangle. Doing this is straightforward in Kivy. The library provides a rich set of shape classes that you can find in the kivy.graphics package. Some of these classes include:

To draw a shape on the screen with Kivy, we need to use the canvas property of a Widget object. This property holds an instance of the Canvas class, which lives in the kivy.graphics package.

Let's see how this works with an example of a white square drawn on the screen:

python

from kivy.app import App
from kivy.core.window import Window
from kivy.graphics import Rectangle
from kivy.uix.widget import Widget

class CanvasApp(App):
    def build(self):
        root = Widget()
        size = 200
        width, height = Window.size
        pos_x = 1/2 * (width - size)
        pos_y = 1/2 * (height - size)
        with root.canvas:
            Rectangle(size=[size, size], pos=[pos_x, pos_y])
        return root

CanvasApp().run()

Inside build(), we create the root widget and define the size of our shape. It'll be a square shape, so each side is equal.

Next, we compute the coordinates to center our shape on the window. The coordinates passed when creating the shape are for the top left corner of the window.

To calculate the correct values, we take the width and height of our main window, halving these values to get the center. We then subtract half of the width or height of our shape to position the center of our shape in the middle of the window. This can be simplified to 1/2 * (width - size) or 1/2 * (height - size). We store the resulting top left coordinates in pos_x and pos_y.

Next, we use the canvas property of our root window to draw the shape. This property supports the with statement, which provides the appropriate context for creating our shapes. Inside the with block, we define our Rectangle instance with the size and pos arguments.

Finally, we return the root widget as expected. The final line of code creates the app instance and calls its run() method. If you run this app from your command line, then you'll get the following window on the screen:

Drawing Shapes in Kivy With Canvas

Cool! You've drawn a square on your Kivy app. The computed coordinates place the square in the center of the window. The default color is white. However, we can change it:

python

# ...
from kivy.graphics import Color, Rectangle
from kivy.uix.widget import Widget
# ...

class CanvasApp(App):
    def build(self):
        # ...
        with root.canvas:
            Color(1, 1, 0, 1)
            Rectangle(size=[size, size], pos=[pos_x, pos_y])
 # ...

In this code snippet, we have added an import for the Color class from the graphics package. The Color class accepts four numeric arguments between 0 and 1 representing the red, green, blue, and transparency components of our target color.

For example, the values (1, 0, 0, 1) represent an entirely red and fully opaque color. The value (0, 1, 0, 0.5) is fully green, half opaque, and half transparent. Consequently, the value (1, 1, 0, 1) gives a fully opaque yellow color. So, if you run the app, then you'll get the following output:

Drawing Shapes in Color With Kivy

We can experiment with different color values and also with different shape classes, which is cool.

Finally, note that to see the effect of the Color() on the drawn rectangle, the Color class must be instantiated before the Rectangle class. You can think of this as dipping your paintbrush on a palette before using it to paint on your canvas! Interestingly, any drawing that comes after the Color instance is painted accordingly so long as a different color has not been applied.

Using the with statement is pretty convenient and facilitates working with shapes. Alternatively, we can use the canvas.add() method:

python

root.canvas.add(Color(1, 1, 0, 1))
root.canvas.add(
    Rectangle(size=[side, side], pos=[pos_x, pos_y])
)

These statements are equivalent to the statements we have in the with block. Go ahead and give it a try yourself.

Styling Kivy GUIs With the Kv Language

Kivy also provides a declarative language known as the Kv language, which aims at separating your application's GUI design and business logic. In this tutorial, we will not go deep into using the Kv language. However, we will highlight some of its main features and strengths.

With Kv language, you can declare and style the widgets and graphical components of your GUI apps. You will put your Kv code in files with the .kv extension. Then you can load the content of these files into your app to build the GUI. You'll have at least two ways to load the content of a .kv file:

Relying on the automatic loading mechanism
Using the Builder class for manual loading

In the following sections, you'll learn the basics of these two ways of using the Kv language to build the GUI of your Kivy apps.

Relying on Automatic Widget Loading

As stated earlier, the Kv language helps you separate business logic from GUI design. Let's illustrate this possibility with an updated version of our "Hello, World!" app:

python

from kivy.app import App
from kivy.uix.label import Label

class CustomLabel(Label):
    pass

class MainApp(App):
    def build(self):
        root = CustomLabel()
        return root

MainApp().run()

As you can see we have subclassed the Label class to create a new CustomLabel haven't made any modifications to the subclass, so it functions exactly like the Label class but with a different name. We add a pass statement, which is a Python placeholder statement which makes the code syntactically valid.

Next, create a file called main.kv alongside your app's file. Define a label using the following code:

<CustomLabel>:
    text: "Hello, World!"

Note that your label must have the same name as your custom Python class in the app's file. Additionally, the .kv file must have the same name as your subclass of App, but without the App suffix and in lowercase. In this example, your subclass is named MainApp, so your .kv file must be main.kv.

Now you can run the app from your command line. You'll get the following window on your screen:

Kivy Application Using the Kv Language

The Kv language, also known as kivy language or just kvlang, allows us to create widget trees in a declarative way. It also lets you bind widget properties to each other or to callbacks.

Loading Widgets Through the `Builder` Class

When your Kivy project grows, your .kv file will grow as well. So, it is recommended that you split up the file into different files for readability. In such cases, you will end up with multiple .kv files, and the automatic loading mechanism will not be sufficient. You'll have to use the Builder class from kivy.lang.Builder.

To explore how to use Builder, let's build a sample GUI consisting of a label and button in a BoxLayout. The label will be provided in the labels.kv file, while the buttons will live in the buttons.kv file.

Here's the Python code for this app:

python

from kivy.app import App
from kivy.lang import Builder
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button
from kivy.uix.label import Label

Builder.load_file("labels.kv")
Builder.load_file("buttons.kv")

class CustomLabel(Label):
    pass

class CustomButton(Button):
    pass

class MainApp(App):
    def build(self):
        root = BoxLayout(orientation="vertical")
        root.add_widget(CustomLabel())
        root.add_widget(CustomButton())
        return root

MainApp().run()

After importing the required classes, we call the load_file() method. This method takes the filename of a .kv file as an argument and loads it into your app.

Next, you create the custom label and button following the pattern used in the previous section. Inside build(), you create a BoxLayout and add the two widgets to it. Now you need to provide the required .kv files.

Go ahead and create a labels.kv file with the following content:

<CustomLabel>:
    text: "This is a custom label!"
    font_size: 50
    bold: True

This file provides a label with the text "This is a custom label!". Its font will have a size of 50 pixels and will be bold.

The buttons.kv will have the following code:

<CustomButton>:
    text: "Click me!"

Your custom button will be quite minimal. It'll only have the text "Click me!" on it. Go ahead and run the app from your command line. You'll get the following window on your screen:

Kivy Application Using the Kv Language With Multiple kv Files

In addition to using the load_file() to build Kv language files, you can also parse and load Kv language directly in a multi-line string in your Python file:

python

Builder.load_string("""
<CustomLabel>:
    text: "This is a custom label!"
    font_size: 50
    bold: True
""")
Builder.load_string("""
<CustomButton>:
    text: "Click me!"
""")

These calls to load_string() are completely equivalent to the corresponding calls to load_file() in our original code example.

Drawing Shapes With the Kv Language

Let's take a look at a final example of using the Kv language. This time we'll use the language to draw shapes. Create a rectangle.py file with the following content:

python

from kivy.app import App
from kivy.uix.widget import Widget

class CustomRectangle(Widget):
    pass

class MainApp(App):
    def build(self):
        return CustomRectangle()

MainApp().run()

Now go ahead and create another file in the same directory and save it as main.kv. Then add the following content:

<CustomRectangle>:
  canvas:
    Color:
      rgba: 1, 1, 0, 1
    Rectangle:
      size: 200, 200
      pos: 0, 0

If you run the rectangle.py file, then you will see a 200×200 pixels rectangle ---square in this case--- at the lower left corner of your window! For more guidelines on using Kv Language, check out its official documentation.

More Kivy Resources and Next Steps

For some more examples of what you can do with Kivy, take a look at the Kivy examples section in the documentation. Depending on your interest, you can also explore the other resources below:

If you're interested in 3D rendering, then the Kivy 3D demo gives a good demonstration of the framework's rendering abilities.
If you're interested in using Kivy to develop for mobile, you can write functional Android apps (APKs) with Python and pack them using tools like Buildozer and Python-For-Android without learning Java.
If you want a complete vision of where you can use Kivy, then check out the gallery of examples provided by the Kivy community.

Conclusion

What you've learned in this tutorial is just the tip of the Kivy iceberg. There's so much more to Kivy than what meets the eye. It's a powerful Python GUI library that provides a well-structured hierarchy of classes and objects that you can use to create modern and cross-platform graphical user interfaces for your desktop and mobile applications.

How to Restore the Window's Geometry in a PyQt5 App — Make Your Windows Remember Their Last Geometry

2023-05-27T06:00:00+00:00

In this tutorial, we will explore how to save and restore the geometry and state of a PyQt window using the QSettings class. With this functionality, you will be able to give your applications a usability boost.

Understanding a Window's Geometry

PyQt defines the geometry of a window using a few properties. These properties represent a window's position on the screen and size. Here's a summary of PyQt's geometry-related properties:

Property	Description	Access Method
`x`	Holds the `x` coordinate of a widget relative to its parent. If the widget is a window, `x` includes any window frame and is relative to the desktop. This property defaults to `0`.	`x()`
`y`	Holds the `y` coordinate of a widget relative to its parent. If the widget is a window, `y` includes any window frame and is relative to the desktop. This property defaults to `0`.	`y()`
`pos`	Holds the position of the widget within its parent widget. If the widget is a window, the position is relative to the desktop and includes any frame.	`pos()`
`geometry`	Holds the widget's geometry relative to its parent and excludes the window frame.	`geometry()`
`width`	Holds the width of the widget, excluding any window frame.	`width()`
`height`	Holds the height of the widget, excluding any window frame.	`height()`
`size`	Holds the size of the widget, excluding any window frame.	`size()`

Additionally, the x and y coordinates are relative to the screen of your computer. The origin of coordinates is the upper left corner of the screen, at which point both x and y are 0.

python

from PyQt5.QtWidgets import (
    QApplication,
    QLabel,
    QMainWindow,
    QPushButton,
    QVBoxLayout,
    QWidget,
)

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.resize(400, 200)
        self.central_widget = QWidget()
        self.global_layout = QVBoxLayout()
        self.geometry_properties = [
            "x",
            "y",
            "pos",
            "width",
            "height",
            "size",
            "geometry",
        ]
        for prop in self.geometry_properties:
            self.__dict__[f"{prop}_label"] = QLabel(f"{prop}:")
            self.global_layout.addWidget(self.__dict__[f"{prop}_label"])
        button = QPushButton("Update Geometry Properties")
        button.clicked.connect(self.update_labels)
        self.global_layout.addWidget(button)
        self.central_widget.setLayout(self.global_layout)
        self.setCentralWidget(self.central_widget)

    def update_labels(self):
        for prop in self.geometry_properties:
            self.__dict__[f"{prop}_label"].setText(
                f"{prop}: {getattr(self, prop)()}"
            )

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

Wow! There's a lot of code in this file. First, we import the required classes from PyQt5.QtWidgets. Then, we create our app's main window by inheriting from QMainWindow.

In the initializer method, we set the window's title and size using setWindowTitle() and resize(), respectively. Next, we define a central widget and a layout for our main window.

A Window Showing Labels for Every Geometry Property

Looking good! Now go ahead and click the Update Geometry Properties button. You'll see how all the properties get updated. Your app's window will look something like this:

A Window Showing the Current Value of Every Geometry Property

As you can see, x and y are numeric values, while pos is a QPoint object with x and y as its coordinates. These properties define the position of this window on your computer screen.

The width and height properties are also numeric values, while the size property is a QSize object defined after the current width and height.

Finally, the geometry property is a QRect object. In this case, the rectangle comprises x, y, width, and height.

Great! With this first approach to how PyQt defines a window's geometry, we're ready to continue digging into this tutorial's main topic: restoring the geometry of a window in PyQt.

Keeping an App's Geometry Settings: The `QSetting` Class

A commonly expected feature is that the app remembers the geometry of its windows, particularly the main window.

In this section, you'll learn how to save and restore the window's geometry in a PyQt application. Let's start by creating a skeleton PyQt application to kick things off. Go ahead and create a new Python file called geometry.py. Once you have the file opened in your favorite code editor or IDE, then add the following code:

python

from PyQt5.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

This code creates a minimal PyQt app with an empty main window. The window will appear at 50 pixels from the upper left corner of your computer screen and have a size of 400 by 200 pixels.

We'll use the above code as a starting point to make the app remember and restore the main window's geometry across sessions.

First, we need to have a QSettings instance in our app. Therefore, you have to import QSettings from PyQt5.QtCore and instantiate it as in the code below:

python

from PyQt5.QtCore import QSettings
from PyQt5.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PyhonGUIs", "GeometryApp")

When instantiating QSettings, we must provide the name of our company or organization and the name of our application. We use "PyhonGUIs" as the organization and "GeometryApp" as the application name.

python

class Window(QMainWindow):
    # ...

    def write_settings(self):
        # Write settings here...

    def read_settings(self):
        # Read settings here...

Note that our methods don't do anything yet. You'll write them in a moment. For now, they're just placeholders.

Let's override the closeEvent() method as in the code below:

python

class Window(QMainWindow):
    # ...

    def closeEvent(self, event):
        self.write_settings()
        super().closeEvent(event)
        event.accept()

python

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.read_settings()

By calling the read_settings() method from __init__(), we ensure that our app will read and load its settings every time the main window gets created and initialized.

Great! We're on the way to getting our application to remember and restore its window's geometry. First, you need to know that you have at least two ways to restore the geometry of a window in PyQt:

Using the pos and size properties
Using the geometry property

In both cases, you need to save the current value of the selected property and load the saved value when the application starts. To kick things off, let's start with the first approach.

Restoring the Window's Geometry With `pos` and `size`

python

class Window(QMainWindow):
    # ...

    def write_settings(self):
        self.settings.setValue("pos", self.pos())
        self.settings.setValue("size", self.size())

With the write_settings() method updated, we're now ready to read and load the geometry properties from our app's settings. Go ahead and update the read_settings() method as in the code below:

python

class Window(QMainWindow):
    # ...

    def read_settings(self):
        self.move(self.settings.value("pos", defaultValue=QPoint(50, 50)))
        self.resize(self.settings.value("size", defaultValue=QSize(400, 200)))

The second line in read_settings() does something similar to the first one. It retrieves the current value of the "size" parameter and resizes the window accordingly.

If you have any issues completing and running the example app, then you can grab the entire code below:

python

from PyQt5.QtCore import QPoint, QSettings, QSize
from PyQt5.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PyhonGUIs", "GeometryApp")
        self.read_settings()

    def write_settings(self):
        self.settings.setValue("pos", self.pos())
        self.settings.setValue("size", self.size())

    def read_settings(self):
        self.move(self.settings.value("pos", defaultValue=QPoint(50, 50)))
        self.resize(self.settings.value("size", defaultValue=QSize(400, 200)))

    def closeEvent(self, event):
        self.write_settings()
        super().closeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

Now you know how to restore the geometry of a window in a PyQt app using the pos and size properties. It's time to change gears and learn how to do this using the geometry property.

Restoring the Window's Geometry With `geometry`

We can also restore the geometry of a PyQt window using its geometry property and the restoreGeometry() method. To do that, we first need to save the current geometry using our QSettings object.

Go ahead and create a new Python file in your working directory. Once you have the file in place, add the following code to it:

python

from PyQt5.QtCore import QByteArray, QSettings
from PyQt5.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.read_settings()

    def write_settings(self):
        self.settings.setValue("geometry", self.saveGeometry())

    def read_settings(self):
        self.restoreGeometry(self.settings.value("geometry", QByteArray()))

    def closeEvent(self, event):
        self.write_settings()
        super().closeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

There are only two changes in this code compared to the code from the previous section. We've modified the implementation of the write_settings() and read_settings() methods.

In write_settings(), we use the setValue() to save the current geometry of our app's window. The saveGeometry() allows us to access and save the current window's geometry. In read_settings(), we call the value() method to retrieve the saved geometry value. Then, we use restoreGeometry() to restore the geometry of our window.

Again, you can run the application consecutive times and change the position and size of its main window to ensure your code works correctly.

Restoring the Window's Geometry and State

Update the content of write_settings() and read_settings() as follows:

python

class Window(QMainWindow):
    # ...

    def write_settings(self):
        self.settings.setValue("geometry", self.saveGeometry())
        self.settings.setValue("windowState", self.saveState())

    def read_settings(self):
        self.restoreGeometry(self.settings.value("geometry", QByteArray()))
        self.restoreState(self.settings.value("windowState", QByteArray()))

python

from PyQt5.QtCore import QByteArray, QSettings, Qt
from PyQt5.QtWidgets import QApplication, QDockWidget, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's State")
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.create_toolbar()
        self.create_dock()
        self.read_settings()

    def create_toolbar(self):
        toolbar = self.addToolBar("Toolbar")
        toolbar.addAction("One")
        toolbar.addAction("Two")
        toolbar.addAction("Three")

    def create_dock(self):
        dock = QDockWidget("Dock", self)
        dock.setAllowedAreas(
            Qt.DockWidgetArea.LeftDockWidgetArea
            | Qt.DockWidgetArea.RightDockWidgetArea
        )
        self.addDockWidget(Qt.DockWidgetArea.LeftDockWidgetArea, dock)

    # ...

In this new update, we first import the Qt namespace from PyQt5.QtCore and QDockWidget from PyQt5.QtWidgets. Then we call the two new methods from __init__() to create the toolbar and dock widget at initialization time.

In the create_toolbar() method, we create a sample toolbar with three sample buttons. This toolbar will show at the top of our app's window by default.

Next, we create a dock widget in create_dock(). This widget will occupy the rest of our window's working area.

That's it! You're now ready to give your app a try. You'll see a window like the following:

A Window Showing a Sample Toolbar and a Dock Widget

Play with the toolbar and the dock widget. Move them around. Then close the app's window and run the app again. Your toolbar and dock widget will show in the last position you left them.

Conclusion

Through this tutorial, you have learned how to restore the geometry and state of a window in PyQt applications using the QSettings class. By utilizing the pos, size, geometry, and state properties, you can give your users the convenience of persistent position and size on your app's windows.

With this knowledge, you can enhance the usability of your PyQt applications, making your app more intuitive and user-friendly.

For an in-depth guide to building Python GUIs with PyQt5 see my book, Create GUI Applications with Python & Qt5.

Input Validation in Tkinter GUI Apps — Validate User Input When Creating Apps With Tkinter and Python

2023-04-25T06:00:00+00:00

When writing GUI applications you often need to accept data from users. A reliable application must verify and validate all its input data before taking any further action or doing any processing. Input validation is the process of examining the data your users provide to your applications to ensure its validity.

In this tutorial, we'll look at some examples of common input data validation strategies you can use when developing GUI applicatipons with the Tkinter UI library.

Input Validation Strategies in GUI Apps

Input data validation is commonly needed in dialog windows where we provide input widgets for the user to enter information that our program requires to work properly. When validating input data in a dialog or any other component of our app's GUI, there are two main approaches we can take:

Real-time validation: This strategy is also called widget-level validation and involves validating the user's input as soon as they enter it in the app's GUI.
Batch validation: This strategy is also known as form-level validation and involves validating all input fields at once, usually when the user clicks the submit button on a dialog.

Real-time validation works best in situations where input data is continuously entered and needs to be verified quickly. For example, when we're using a table widget to update a table in a database in real time.

Batch validation is suitable when there are interdependencies between different pieces of input. In this case, the input data needs to be validated all at once. A good example of this type of validation is a login form which typically verifies the user and the password at once when we click the Login button.

In the following sections, you'll learn how to implement these two validation strategies in a Tkinter application.

Form-Level Input Validation in Tkinter

Tkinter is a popular GUI library in Python. It provides a basic set of widgets that you can use for building GUI applications quickly. The library comes with a few widgets for data entry, including Entry, Text, Spinbox, and others.

To demonstrate the form-level validation strategy, we'll use the Entry widget, which presents a simple text box to the user. For this example, we'll create a form with an Entry and a Button. The Entry widget will only accept numeric values. We'll run the input data validation when the user clicks on the button to submit the information for processing.

Below is the starter code for our small Tkinter app:

python

from tkinter import Tk, ttk

# Create the app's main window
root = Tk()
root.title("Form-Level Input Validation")
root.geometry("490x100")

# Add widgets
entry = ttk.Entry(root, width=35)
entry.grid(row=0, column=0, padx=5, pady=5)
button = ttk.Button(root, text="Validate", command=validate_numbers)
button.grid(row=0, column=1, padx=5, pady=5)
label = ttk.Label(root, text="Display")
label.grid(row=1, column=0, columnspan=2, padx=5, pady=5)

# Run the app's main loop
root.mainloop()

In the first line of the code, we import Tk and ttk from the tkinter package. Tk is Tkinter's main GUI class which provides the application window and main loop. The ttk module provides styled widgets for you to create modern Tkinter apps.

Next, we create the parent window, root, by instantiating the Tk class. The window will have a title and a geometry (shape), which we set using the title() and geometry() methods.

Then, we create three different widgets: an entry, a label, and a button using the ttk.Entry, ttk.Label and ttk.Button classes, respectively.

To create the Entry widget, we use the parent window, root, and width as arguments. To place the entry widget in the parent window, we use the grid() geometry manager. This lays widgets out in a grid, at the specified row and column positions, with padx and pady (horizontal and vertical padding) in pixels.

Then we create a button using the ttk.Button class with the parent window and text as arguments. Again, we use grid() to place the button on the parent window, on the same row as the Entry but now in column 1.

Finally, we create a ttk.Label widget using a parent window and text as arguments. Using the grid() method, we place this on the next row in column 0, using colspan=2 to stretch it across two columns.

With our application complete, we run it by calling mainloop() on root. You'll get the following output:

An example Tkinter application with Entry, Button, and Label widgets

Great! We have a working Tkinter app with a simple form.

Let's jump into input validation. So far, the button doesn't do anything when we click it. We want the button to run code for validating the data provided through the entry widget. Let's create a function for validating numeric values:

python

from tkinter import Tk, ttk

# Create the app's main window
root = Tk()
root.title("Form-Level Input Validation")
root.geometry("490x100")

# Create a validation function
def validate_numbers():
    input_data = entry.get()
    if input_data:
        try:
            float(input_data)
            label.config(
                text=f"Valid numeric value: {input_data}",
                foreground="green",
            )
        except ValueError:
            label.config(
                text=f'Numeric value expected, got "{input_data}"',
                foreground="red",
            )
    else:
        label.config(
            text="Entry is empty",
            foreground="red",
        )

# ...

Here we have implemented a validate_numbers() function to test if the user's input is a valid number. Inside the function, we get the input data from the entry widget using the get() method, storing it in the variable input_data.

First, we use an if statement to check whether input_data contains anything at all. If input_data is an empty string, which is falsey, the else clause will change the label's text to "Entry is empty" in red.

If input_data contains some text, we further validate this by attempting to cast the value to a float using the built-in float() type. If the value is not a valid float, the code will throw a ValueError exception. If this occurs, we catch this exception and display an informative message in red.

Finally, in the case where input_data contains something which is a valid numeric value, a success message will be shown in green.

Now that we have implemented our validation function, we can bind it to our button by passing it as the command argument. Update the Button instantiation as follows:

python

# Add widgets
# ...
button = ttk.Button(root, text="Validate", command=validate_numbers)
# ...

Here, the command argument points to the function that we want to trigger when the button is clicked. If you run the program again and enter valid numbers, you'll get an output similar to the following when clicking the Validate button:

Entry box with a valid number, showing the success message

Great, the app validated the input successfully! What will happen if we provide an invalid input? Check out the form below:

Entry box with an invalid number, showing the failure message

Great! Everything works! If you enter something which is not a number, your app will now correctly identify the invalid input.

With the widget-level validation strategy, we validate the input data using widget-specific events. For example, an input validation function can run when an entry widget gets or loses focus. This approach comes in handy when we want to validate input data in real time, widget by widget.

To see this strategy in action, let's create a window with two entry widgets. The code for that is as follows:

python

from tkinter import Tk, ttk

# Create the app's main window
root = Tk()
root.title("Widget-Level Validation")
root.geometry("490x120")

# Add widgets
name_label = ttk.Label(root, text="Name:")
name_label.grid(row=0, column=0, padx=5, pady=5)
name_entry = ttk.Entry(root, width=35)
name_entry.grid(row=0, column=1, padx=5, pady=5)
age_label = ttk.Label(root, text="Age:")
age_label.grid(row=1, column=0, padx=5, pady=5)
age_entry = ttk.Entry(root, width=35)
age_entry.grid(row=1, column=1, padx=5, pady=5)
label = ttk.Label(root, text="Display")
label.grid(row=2, column=0, columnspan=2, padx=5, pady=5)

# Run the app's main loop
root.mainloop()

In this example, we are creating a window with two entry widgets and a label for displaying a message after the validation process.

If you run this example, you'll get the following window:

Window showing two Entry boxes with a validation message

In this next example, we'll validate the age input when the user moves the focus out of the age entry. First, let's create the function for validating input:

python

from tkinter import Tk, ttk

# Create the app's main window
root = Tk()
root.title("Widget-Level Validation")
root.geometry("490x120")


# Create a validation function
def validate_age():
    age = age_entry.get()
    if age:
        if age.isdigit() and int(age) in range(1, 151):
            label.config(
                text=f"Valid age: {age}",
                foreground="green",
            )
            return True
        else:
            label.config(
                text="Age must be a number between 1 and 150",
                foreground="red",
            )
            return False
    else:
        label.config(
            text="Entry is empty",
            foreground="red",
        )
        return False

# ...

The validate_age() function gets the input using the get() method, storing the value in the variable age.

We again use an if statement to check whether the input value is empty or not. If the entry is empty, the else clause runs, showing the failure message.

If the user has provided a value, then we validate the input data using the isdigit() method and the built-in range() function.

It's important to note that functions used for widget-level validation must be predicate functions, returning either True or False.

Finally, we need to bind this function to the entry widget which input we want to validate. To do this, we need to pass two new arguments to the Entry() constructor:

python

# Add widgets
# ...
age_entry = ttk.Entry(
    root,
    width=35,
    validatecommand=validate_age,
    validate="focusout"
)
# ...

The validatecommand argument specifies the function to be called for input validation, and the validate command specifies on which event this function should be called. In this example, we have used "focusout". However, the validate argument can take any of the following values:

"focus" triggers the validation whenever the widget receives or loses focus.
"focusin" triggers the validation whenever the widget receives focus.
"focusout" triggers the validation whenever the widget loses focus.
"key" triggers the validation whenever any keystroke changes the widget's content.
"all" triggers the validation in all the above situations.
"none" turns the validation off.

Go ahead and run your program. Enter a name and play with different input values for the age. After entering the age value, move the focus to the name entry to trigger the validation. Here's how the app works with a valid age:

Window showing validation of a valid age

When you move the focus to the Name entry, the age entry triggers the age validation function. Now let's try an invalid age:

Window showing validation of an invalid age

The validation works as expected! Whenever you enter an invalid age value and move the focus out of the age entry, you get an error message pointing out the problem. That's great!

Conclusion

In this tutorial, you've learned about input validation in GUI applications. You now know how to validate user input in Tkinter using two different validation strategies: form-level validation and widget-level validation.

You can now apply these two strategies to validate user input in your own applications.

Getting Started With Git and GitHub in Your Python Projects — Version-Controlling Your Python Projects With Git and GitHub

2023-03-20T06:00:00+00:00

Using a version control system (VCS) is crucial for any software development project. These systems allow developers to track changes to the project's codebase over time, removing the need to keep multiple copies of the project folder.

VCSs also facilitate experimenting with new features and ideas without breaking existing functionality in a given project. They also enable collaboration with other developers that can contribute code, documentation, and more.

In this article, we'll learn about Git, the most popular VCS out there. We'll cover everything you need to get started with Git, from installation and configuration to creating repositories, working with branches, and publishing your code to GitHub.

Installing and Setting Up Git

To use Git in our coding projects, we first need to install it on our computer. To do this, we need to navigate to Git's download page and choose the appropriate installer for our operating system. Once we've downloaded the installer, we need to run it and follow the on-screen instructions.

We can check if everything is working correctly by opening a terminal or command-line window and running git --version.

Once we've confirmed the successful installation, we should provide Git with some personal information. You'll only need to do this once for every computer. Now go ahead and run the following commands with your own information:

shell

$ git config --global user.name <"YOUR NAME">
$ git config --global user.email <name@email.com>

The first command adds your full name to Git's config file. The second command adds your email. Git will use this information in all your repositories.

If you publish your projects to a remote server like GitHub, then your email address will be visible to anyone with access to that repository. If you don't want to expose your email address this way, then you should create a separate email address to use with Git.

As you'll learn in a moment, Git uses the concept of branches to manage its repositories. A branch is a copy of your project's folder at a given time in the development cycle. The default branch of new repositories is named either master or main, depending on your current version of Git.

You can change the name of the default branch by running the following command:

shell

$ git config --global init.defaultBranch <branch_name>

This command will set the name of Git's default branch to branch_name. Remember that this is just a placeholder name. You need to provide a suitable name for your installation.

Another useful setting is the default text editor Git will use to type in commit messages and other messages in your repo. For example, if you use an editor like Visual Studio Code, then you can configure Git to use it:

shell

# Visual Studio Code
$ git config --global core.editor "code --wait"

With this command, we tell Git to use VS Code to process commit messages and any other message we need to enter through Git.

Finally, to inspect the changes we've made to Git's configuration files, we can run the following command:

shell

$ git config --global -e

This command will open the global .gitconfig file in our default editor. There, we can fix any error we have made or add new settings. Then we just need to save the file and close it.

Understanding How Git Works

Git works by allowing us to take a snapshot of the current state of all the files in our project's folder. Each time we save one of those snapshots, we make a Git commit. Then the cycle starts again, and Git creates new snapshots, showing how our project looked like at any moment.

Git was created in 2005 by Linus Torvalds, the creator of the Linux kernel. Git is an open-source project that is licensed under the GNU General Public License (GPL) v2. It was initially made to facilitate kernel development due to the lack of a suitable alternative.

The general workflow for making a Git commit to saving different snapshots goes through the following steps:

Change the content of our project's folder.
Stage or mark the changes we want to save in our next commit.
Commit or save the changes permanently in our project's Git database.

As the third step mentions, Git uses a special database called a repository. This database is kept inside your project's directory under a folder called .git.

Version-Controlling a Python Project With Git: The Basics

In this section, we'll create a local repository and learn how to manage it using the Git command-line interface (CLI). On macOS and Linux, we can use the default terminal application to follow along with this tutorial.

On Windows, we recommend using Git Bash, which is part of the Git For Windows package. Go to the Git Bash download page, get the installer, run it, and follow the on-screen instruction. Make sure to check the Additional Icons -> On the Desktop to get direct access to Git Bash on your desktop so that you can quickly find and launch the app.

Alternatively, you can also use either Windows' Command Prompt or PowerShell. However, some commands may differ from the commands used in this tutorial.

Initializing a Git Repository With `git init`

To start version-controlling a project, we need to initialize a new Git repository in the project's root folder or directory. In this tutorial, we'll use a sample project to facilitate the explanation. Go ahead and create a new folder in your file system. Then navigate to that folder in your terminal by running these commands:

shell

$ mkdir sample_project
$ cd sample_project

The first command creates the project's root folder or directory, while the second command allows you to navigate into that folder. Don't close your terminal window. You'll be using it throughout the next sections.

To initialize a Git repository in this folder, we need to use the git init command like in the example below:

shell

$ git init
Initialized empty Git repository in /.../sample_project/.git/

This command creates a subfolder called .git inside the project's folder. The leading dot in the folder's name means that this is a hidden directory. So, you may not see anything on your file manager. You can check the existence of .git with the ls -a, which lists all files in a given folder, including the hidden ones.

Checking the Repository Status With `git status`

Git provides the git status command to allow us to identify the current state of a Git repository. Because our sample_project folder is still empty, running git status will display something like this:

shell

$ git status
On branch main

No commits yet

nothing to commit (create/copy files and use "git add" to track)

When we run git status, we get detailed information about the current state of our Git repository. This command is pretty useful, and we'll turn back to it in multiple moments.

As an example of how useful the git status command is, go ahead and create a file called main.py inside the project's folder using the following commands:

shell

$ touch main.py

$ git status
On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    main.py

nothing added to commit but untracked files present (use "git add" to track)

With the touch command, we create a new main.py file under our project's folder. Then we run git status again. This time, we get information about the presence of an untracked file called main.py. We also get some basic instructions on how to add this file to our Git repo. Providing these guidelines or instructions is one of the neatest features of git status.

Now, what is all that about untracked files? In the following section, we'll learn more about this topic.

Tracking and Committing Changes With `git add` and `git commit`

A file in a Git repository can be either tracked or untracked. Any file that wasn't present in the last commit is considered an untracked file. Git doesn't keep a history of changes for untracked files in your project's folder.

In our example, we haven't made any commits to our Git repo, so main.py is naturally untracked. To start tracking it, run the git add command as follows:

shell

$ git add main.py

$ git status
On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
    new file:   main.py

This git add command has added main.py to the list of tracked files. Now it's time to save the file permanently using the git commit command with an appropriate commit message provided with the -m option:

shell

$ git commit -m "Add main.py"
[main (root-commit) 5ac6586] Add main.py
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 main.py

$ git status
On branch master
nothing to commit, working tree clean

We have successfully made our first commit, saving main.py to our Git repository. The git commit command requires a commit message, which we can provide through the -m option. Commit messages should clearly describe what we have changed in our project.

After the commit, our main branch is completely clean, as you can conclude from the git status output.

Now let's start the cycle again by modifying main.py, staging the changes, and creating a new commit. Go ahead and run the following commands:

shell

$ echo "print('Hello, World!')" > main.py
$ cat main.py
print('Hello, World!')

$ git add main.py

$ git commit -m "Create a 'Hello, World!' script  on  main.py"
[main 2f33f7e] Create a 'Hello, World!' script  on  main.py
 1 file changed, 1 insertion(+)

The echo command adds the statement "print('Hello, World!')" to our main.py file. You can confirm this addition with the cat command, which lists the content of one or more target files. You can also open main.py in your favorite editor and update the file there if you prefer.

We can also use the git stage command to stage or add files to a Git repository and include them in our next commit.

We've made two commits to our Git repo. We can list our commit history using the git log command as follows:

shell

$ git log --oneline
2f33f7e (HEAD -> main) Create a 'Hello, World!' script  on  main.py
5ac6586 Add main.py

The git log command allows us to list all our previous commits. In this example, we've used the --oneline option to list commits in a single line each. This command takes us to a dedicated output space. To leave that space, we can press the letter Q on our keyboard.

Using a `.gitignore` File to Skip Unneeded Files

While working with Git, we will often have files and folders that we must not save to our Git repo. For example, most Python projects include a venv/ folder with a virtual environment for that project. Go ahead and create one with the following command:

shell

$ python -m venv venv

Once we've added a Python virtual environment to our project's folder, we can run git status again to check the repo state:

shell

$ git status
On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
    venv/

nothing added to commit but untracked files present (use "git add" to track)

Now the venv/ folder appears as an untracked file in our Git repository. We don't need to keep track of this folder because it's not part of our project's codebase. It's only a tool for working on the project. So, we need to ignore this folder. To do that, we can add the folder to a .gitignore file.

Go ahead and create a .gitignore file in the project's folder. Add the venv/ folders to it and run git status:

shell

$ touch .gitignore
$ echo "venv/" > .gitignore
$ git status
On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
    .gitignore

nothing added to commit but untracked files present (use "git add" to track)

Now git status doesn't list venv/ as an untracked file. This means that Git is ignoring that folder. If we take a look at the output, then we'll see that .gitignore is now listed as an untracked file. We must commit our .gitignore files to the Git repository. This will prevent other developers working with us from having to create their own local .gitignore files.

We can also list multiple files and folders in our .gitignore file one per line. The file even accepts glob patterns to match specific types of files, such as *.txt. If you want to save yourself some work, then you can take advantage of GitHub's gitignore repository, which provides a rich list of predefined .gitignore files for different programming languages and development environments.

We can also set up a global .gitignore file on our computer. This global file will apply to all our Git repositories. If you decide to use this option, then go ahead and create a .gitignore_global in your home folder.

Working With Branches in Git

One of the most powerful features of Git is that it allows us to create multiple branches. A branch is a copy of our project's current status and commits history. Having the option to create and handle branches allows us to make changes to our project without messing up the main line of development.

We'll often find that software projects maintain several independent branches to facilitate the development process. A common Git branching model distinguishes between four different types of branches:

A main or master branch that holds the main line of development
A develop branch that holds the last developments
One or more feature branches that hold changes intended to add new features
One or more bugfix branches that hold changes intended to fix critical bugs

However, the branching model to use is up to you. In the following sections, we'll learn how to create, manage, and merge branches using Git.

Creating New Branches With `git branch`

Working all the time on the main or master branch isn't a good idea. We can end up creating a mess and breaking the code. So, whenever we want to experiment with a new idea, implement a new feature, fix a bug, or just refactor a piece of code, we should create a new branch.

To kick things off, let's create a new branch called hello on our Git repo under the sample_project folder. To do that, we can use the git branch command followed by the branch's name:

shell

$ git branch hello
$ git branch --list
* main
  hello

The first command creates a new branch in our Git repo. The second command allows us to list all the branches that currently exist in our repository. Again, we can press the letter Q on our keyboard to get back to the terminal prompt.

The star symbol denotes the currently active branch, which is main in the example. We want to work on hello, so we need to activate that branch. In Git's terminology, we need to check out to hello.

Checking Out to a New Branch With `git checkout`

Although we have just created a new branch, in order to start working on it, we need to switch to or check out to it by using the git checkout command as follows:

shell

$ git checkout hello
Switched to branch 'hello'

$ git branch --list
  main
* hello

$ git log --oneline
2f33f7e (HEAD -> hello, main) Create a 'Hello, World!' script  on  main.py
5ac6586 Add main.py

The git checkout command takes the name of an existing branch as an argument. Once we run the command, Git takes us to the target branch.

We can derive a new branch from whatever branch we need.

As you can see, git branch --list indicates which branch we are currently on by placing a * symbol in front of the relevant branch name. If we check the commit history with git log --oneline, then we'll get the same as we get from main because hello is a copy of it.

The git checkout can take a -b flag that we can use to create a new branch and immediately check out to it in a single step. That's what most developers use while working with Git repositories. In our example, we could have run git checkout -b hello to create the hello branch and check out to it with one command.

Let's make some changes to our project and create another commit. Go ahead and run the following commands:

shell

$ echo "print('Welcome to PythonGUIs!')" >> main.py
$ cat main.py
print('Hello, World!')
print('Welcome to PythonGUIs!')

$ git add main.py
$ git commit -m "Extend our 'Hello, World' program with a welcome message."
[hello be62476] Extend our 'Hello, World' program with a welcome message.
 1 file changed, 1 insertion(+)

The final command committed our changes to the hello branch. If we compare the commit history of both branches, then we'll see the difference:

shell

$ git log --oneline -1
be62476 (HEAD -> hello) Extend our 'Hello, World' program with a welcome message.

$ git checkout main
Switched to branch 'main'

$ git log --oneline -1
2f33f7e (HEAD -> main) Create a 'Hello, World!' script  on  main.py

In this example, we first run git log --oneline with -1 as an argument. This argument tells Git to give us only the last commit in the active branch's commit history. To inspect the commit history of main, we first need to check out to that branch. Then we can run the same git log command.

Now say that we're happy with the changes we've made to our project in the hello branch, and we want to update main with those changes. How can we do this? We need to merge hello into main.

Merging Two Branches Together With `git merge`

To add the commits we've made in a separate branch back to another branch, we can run what is known as a merge. For example, say we want to merge the new commits in hello into main. In this case, we first need to switch back to main and then run the git merge command using hello as an argument:

shell

$ git checkout main
Already on 'main'

$ git merge hello
Updating 2f33f7e..be62476
Fast-forward
 main.py | 1 +
 1 file changed, 1 insertion(+)

To merge a branch into another branch, we first need to check out the branch we want to update. Then we can run git merge. In the example above, we first check out to main. Once there, we can merge hello.

Deleting Unused Branches

Once we've finished working in a given branch, we can delete the entire branch to keep our repo as clean as possible. Following our example, now that we've merged hello into main, we can remove hello.

To remove a branch from a Git repo, we use the git branch command with the --delete option. To successfully run this command, make sure to switch to another branch before:

shell

$ git checkout main
Already on 'main'

$ git branch --delete hello
Deleted branch hello (was be62476).

$ git branch --list
* main

Deleting unused branches is a good way to keep our Git repositories clean, organized, and up to date. Also, deleting them as soon as we finish the work is even better because having old branches around may be confusing for other developers collaborating with our project. They might end up wondering why these branches are still alive.

Using a GUI Client for Git

In the previous sections, we've learned to use the git command-line tool to manage Git repositories. If you prefer to use GUI tools, then you'll find a bunch of third-party GUI frontends for Git. While they won't completely replace the need for using the command-line tool, they can simplify your day-to-day workflow.

You can get a complete list of standalone GUI clients available on the Git official documentation.

Most popular IDEs and code editors, including PyCharm and Visual Studio Code, come with basic Git integration out-of-the-box. Some developers will prefer this approach as it is directly integrated with their development environment of choice.

If you need something more advanced, then GitKraken is probably a good choice. This tool provides a standalone, cross-platform GUI client for Git that comes with many additional features that can boost your productivity.

Managing a Python Project With GitHub

If we publish a project on a remote server with support for Git repositories, then anyone with appropriate permissions can clone our project, creating a local copy on their computer. Then, they can make changes to our project, commit them to their local copy, and finally push the changes back to the remote server. This workflow provides a straightforward way to allow other developers to contribute code to your projects.

In the following sections, we'll learn how to create a remote repository on GitHub and then push our existing local repository to it. Before we do that, though, head over to GitHub.com and create an account there if you don't have one yet. Once you have a GitHub account, you can set up the connection to that account so that you can use it with Git.

Setting Up a Secure SSH Connection to GitHub

In order to work with GitHub via the git command, we need to be able to authenticate ourselves. There are a few ways of doing that. However, using SSH is the recommended way. The first step in the process is to generate an SSH key, which you can do with the following command:

shell

$ ssh-keygen -t ed25519 -C "GitHub - name@email.com"

Replace the placeholder email address with the address you've associated with your GitHub account. Once you run this command, you'll get three different prompts in a row. You can respond to them by pressing Enter to accept the default option. Alternatively, you can provide custom responses.

Next, we need to copy the contents of our id_ed25519.pub file. To do this, you can run the following command:

shell

$ cat ~/.ssh/id_ed25519.pub

Select the command's output and copy it. Then go to your GitHub Settings page and click the SSH and GPG keys option. There, select New SSH key, set a descriptive title for the key, make sure that the Key Type is set to Authentication Key, and finally, paste the contents of id_ed25519.pub in the Key field. Finally, click the Add SSH key button.

At this point, you may be asked to provide some kind of Two-Factor Authentication (2FA) code. So, be ready for that extra security step.

Now we can test our connection by running the following command:

shell

$ ssh -T git@github.com
The authenticity of host 'github.com (IP ADDRESS)' can not be established.
ECDSA key fingerprint is SHA256:p2QAMXNIC1TJYWeIOttrVc98/R1BUFWu3/LiyKgUfQM.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Make sure to check whether the key fingerprint shown on your output matches GitHub's public key fingerprint. If it matches, then enter yes and press Enter to connect. Otherwise, don't connect.

If the connection is successful, we will get a message like this:

shell

Hi USERNAME! You have successfully authenticated, but GitHub does not provide shell access.

Congrats! You've successfully connected to GitHub via SSH using a secure SSH key. Now it's time to start working with GitHub.

Creating and Setting Up a GitHub Repository

Now that you have a GitHub account with a proper SSH connection, let's create a remote repository on GitHub using its web interface. Head over to the GitHub page and click the + icon next to your avatar in the top-right corner. Then select New repository.

Give your new repo a unique name and choose who can see this repository. To continue with our example, we can give this repository the same name as our local project, sample_project.

To avoid conflicts with your existing local repository, don't add .gitignore, README, or LICENSE files to your remote repository.

Next, set the repo's visibility to Private so that no one else can access the code. Finally, click the Create repository button at the end of the page.

If you create a Public repository, make sure also to choose an open-source license for your project to tell people what they can and can't do with your code.

You'll get a Quick setup page as your remote repository has no content yet. Right at the top, you'll have the choice to connect this repository via HTTPS or SSH. Copy the SSH link and run the following command to tell Git where the remote repository is hosted:

shell

$ git remote add origin git@github.com:USERNAME/sample_project.git

This command adds a new remote repository called origin to our local Git repo.

The name origin is commonly used to denote the main remote repository associated with a given project. This is the default name Git uses to identify the main remote repo.

Git allows us to add several remote repositories to a single local one using the git remote add command. This allows us to have several remote copies of your local Git repo.

Pushing a Local Git Repository to GitHub With `git push`

With a new and empty GitHub repository in place, we can go ahead and push the content of our local repo to its remote copy. To do this, we use the git push command providing the target remote repo and the local branch as arguments:

shell

$ git push -u origin main
Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 8 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (9/9), 790 bytes | 790.00 KiB/s, done.
Total 9 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:USERNAME/sample_project.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

This is the first time we push something to the remote repo sample_project, so we use the -u option to tell Git that we want to set the local main branch to track the remote main branch. The command's output provides a pretty detailed summary of the process.

Note that if you don't add the -u option, then Git will ask what you want to do. A safe workaround is to copy and paste the commands GitHub suggests, so that you don't forget -u.

Using the same command, we can push any local branch to any remote copy of our project's repo. Just change the repo and branch name: git push -u remote_name branch_name.

Now let's head over to our browser and refresh the GitHub page. We will see all of our project files and commit history there.

Now we can continue developing our project and making new commits locally. To push our commits to the remote main branch, we just need to run git push. This time, we don't have to use the remote or branch name because we've already set main to track origin/main.

Pulling Content From a GitHub Repository With `git pull` and `git fetch`

We can do basic file editing and make commits within GitHub itself. For example, if we click the main.py file and then click the pencil icon at the top of the file, we can add another line of code and commit those changes to the remote main branch directly on GitHub.

Go ahead and add the statement print("Your Git Tutorial is Here...") to the end of main.py. Then go to the end of the page and click the Commit changes button. This makes a new commit on your remote repository.

This remote commit won't appear in your local commit history. To download it and update your local main branch, use the git pull command:

shell

$ git pull
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), 696 bytes | 174.00 KiB/s, done.
From github.com:USERNAME/sample_project
   be62476..605b6a7  main       -> origin/main
Updating be62476..605b6a7
Fast-forward
 main.py | 1 +
 1 file changed, 1 insertion(+)

Again, the command's output provides all the details about the operation. Note that git pull will download the remote branch and update the local branch in a single step.

If we want to download the remote branch without updating the local one, then we can use the git fetch command. This practice gives us the chance to review the changes and commit them to our local repo only if they look right.

For example, go ahead and update the remote copy of main.py by adding another statement like print("Let's go!!"). Commit the changes. Then get back to your local repo and run the following command:

shell

$ git fetch
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), 731 bytes | 243.00 KiB/s, done.
From github.com:USERNAME/sample_project
   605b6a7..ba489df  main       -> origin/main

This command downloaded the latest changes from origin/main to our local repo. Now we can compare the remote copy of main.py to the local copy. To do this, we can use the git diff command as follows:

shell

$ git diff main origin/main
diff --git a/main.py b/main.py
index be2aa66..4f0e7cf 100644
--- a/main.py
+++ b/main.py
@@ -1,3 +1,4 @@
 print('Hello, World!')
 print('Welcome to PythonGUIs!')
 print("Your Git Tutorial is Here...")
+print("Let's go!!")

In the command's output, you can see that the remote branch adds a line containing print("Let's go!!") to the end of main.py. This change looks good, so we can use git pull to commit the change automatically.

Exploring Alternatives to GitHub

While GitHub is the most popular public Git server and collaboration platform in use, it is far from being the only one. GitLab.com and BitBucket are popular commercial alternatives similar to GitHub. While they have paid plans, both offer free plans, with some restrictions, for individual users.

Although, if you would like to use a completely open-source platform instead, Codeberg might be a good option. It's a community-driven alternative with a focus on supporting Free Software. Therefore, in order to use Codeberg, your project needs to use a compatible open-source license.

Optionally, you can also run your own Git server. While you could just use barebones git for this, software such as GitLab Community Edition (CE) and Forgejo provide you with both the benefits of running your own server and the experience of using a service like GitHub.

Conclusion

By now, you're able to use Git and GitHub for version-controlling your Python projects. Git is a powerful tool that will make you much more efficient and productive, especially as the scale of your project grows over time.

While this guide introduced you to most of its basic concepts and common commands — including git init, git add, git commit, git branch, git merge, git push, and git pull — Git has many more commands and options that you can use to be even more productive. Now, you know enough to get up to speed with Git and GitHub in your Python development workflow.

Working With Classes in Python and PyQt — Understanding the Intricacies of Python Classes for GUI Development

2023-03-06T06:00:00+00:00

Python supports object-oriented programming (OOP) through classes, which allow you to bundle data and behavior in a single entity. Python classes allow you to quickly model concepts by creating representations of real objects that you can then use to organize your code.

Most of the currently available GUI frameworks for Python developers, such as PyQt, PySide, and Tkinter, rely on classes to provide apps, windows, widgets, and more. This means that you'll be actively using classes for designing and developing your GUI apps.

In this tutorial, you'll learn how OOP and classes work in Python. This knowledge will allow you to quickly grasp how GUI frameworks are internally organized, how they work, and how you can use their classes and APIs to create robust GUI applications.

Defining Classes in Python

Python classes are templates or blueprints that allow us to create objects through instantiation. These objects will contain data representing the object's state, and methods that will act on the data providing the object's behavior.

Instantiation is the process of creating instances of a class by calling the class constructor with appropriate arguments.

Attributes and methods make up what is known as the class interface or API. This interface allows us to operate on the objects without needing to understand their internal implementation and structure.

Alright, it is time to start creating our own classes. We'll start by defining a Color class with minimal functionality. To do that in Python, you'll use the class keyword followed by the class name. Then you provide the class body in the next indentation level:

python

>>> class Color:
...     pass
...

>>> red = Color()

>>> type(red)
<class '__main__.Color'>

In this example, we defined our Color class using the class keyword. This class is empty. It doesn't have attributes or methods. Its body only contains a pass statement, which is Python's way to do nothing.

Even though the class is minimal, it allows us to create instances by calling its constructor, Color(). So, red is an instance of Color. Now let's make our Color class more fun by adding some attributes.

Adding Class and Instance Attributes

Python classes allow you to add two types of attributes. You can have class and instance attributes. A class attribute belongs to its containing class. Its data is common to the class and all its instances. To access a class attribute, we can use either the class or any of its instances.

Let's now add a class attribute to our Color class. For example, let's say we need to keep note of how many instances of Color your code creates. Then you can have a color_count attribute:

python

>>> class Color:
...     color_count = 0
...     def __init__(self):
...         Color.color_count += 1
...

>>> red = Color()
>>> green = Color()

>>> Color.color_count
2
>>> red.color_count
2

Now Color has a class attribute called color_count that gets incremented every time we create a new instance. We can quickly access that attribute using either the class directly or one of its instances, like red.

To follow up with this example, say that we want to represent our Color objects using red, green, and blue attributes as part of the RGB color model. These attributes should have specific values for specific instances of the class. So, they should be instance attributes.

To add an instance attribute to a Python class, you must use the .__init__() special method, which we introduced in the previous code but didn't explain. This method works as the instance initializer because it allows you to provide initial values for instance attributes:

python

>>> class Color:
...     color_count = 0
...     def __init__(self, red, green, blue):
...         Color.color_count += 1
...         self.red = red
...         self.green = green
...         self.blue = blue
...

>>> red = Color(255, 0, 0)

>>> red.red
255
>>> red.green
0
>>> red.blue
0

>>> Color.red
Traceback (most recent call last):
    ...
AttributeError: type object 'Color' has no attribute 'red'

Cool! Now our Color class looks more useful. It has the usual class attributes and also three new instance attributes. Note that, unlike class attributes, instance attributes can't be accessed through the class itself. They're specific to a concrete instance.

There's something that jumps into sight in this new version of Color. What is the self argument in the definition of .__init__()? This argument holds a reference to the current instance. Using the name self to identify the current instance is a strong convention in Python.

We'll use self as the first or even the only argument to instance methods like .__init__(). Inside an instance method, we'll use self to access other methods and attributes defined in the class. To do that, we must prepend self to the name of the target attribute or method of the class.

For example, our class has an attribute .red that we can access using the syntax self.red inside the class. This will return the number stored under that name. From outside the class, you need to use a concrete instance instead of self.

Providing Behavior With Methods

A class bundles data (attributes) and behavior (methods) together in an object. You'll use the data to set the object's state and the methods to operate on that data or state.

Methods are just functions that we define inside a class. Like functions, methods can take arguments, return values, and perform different computations on an object's attributes. They allow us to make our objects usable.

In Python, we can define three types of methods in our classes:

Instance methods, which need the instance (self) as their first argument
Class methods, which take the class (cls) as their first argument
Static methods, which take neither the class nor the instance

Let's now talk about instance methods. Say that we need to get the attributes of our Color class as a tuple of numbers. In this case, we can add an .as_tuple() method like the following:

python

class Color:
    representation = "RGB"

    def __init__(self, red, green, blue):
        self.red = red
        self.green = green
        self.blue = blue

    def as_tuple(self):
        return self.red, self.green, self.blue

This new method is pretty straightforward. Since it's an instance method, it takes self as its first argument. Then it returns a tuple containing the attributes .red, .green, and .blue. Note how you need to use self to access the attributes of the current instance inside the class.

This method may be useful if you need to iterate over the RGB components of your color objects:

python

>>> red = Color(255, 0, 0)
>>> red.as_tuple()
(255, 0, 0)

>>> for level in red.as_tuple():
...     print(level)
...
255
0
0

Our as_tuple() method works great! It returns a tuple containing the RGB components of our color objects.

We can also add class methods to our Python classes. To do this, we need to use the @classmethod decorator as follows:

python

class Color:
    representation = "RGB"

    def __init__(self, red, green, blue):
        self.red = red
        self.green = green
        self.blue = blue

    def as_tuple(self):
        return self.red, self.green, self.blue

    @classmethod
    def from_tuple(cls, rbg):
        return cls(*rbg)

The from_tuple() class method takes a tuple object containing the RGB components of a desired color as an argument, creates a valid color object from it, and returns the object back to the caller:

python

>>> blue = Color.from_tuple((0, 0, 255))
>>> blue.as_tuple()
(0, 0, 255)

In this example, we use the Color class to access the class method from_tuple(). We can also access the method using a concrete instance of this class. However, in both cases, we'll get a completely new object.

Finally, Python classes can also have static methods that we can define with the @staticmethod decorator:

python

class Color:
    representation = "RGB"

    def __init__(self, red, green, blue):
        self.red = red
        self.green = green
        self.blue = blue

    def as_tuple(self):
        return self.red, self.green, self.blue

    @classmethod
    def from_tuple(cls, rbg):
        return cls(*rbg)

    @staticmethod
    def color_says(message):
        print(message)

Static methods don't operate either on the current instance self or the current class cls. These methods can work as independent functions. However, we typically put them inside a class when they are related to the class, and we need to have them accessible from the class and its instances.

Here's how the method works:

python

>>> Color.color_says("Hello from the Color class!")
Hello from the Color class!

>>> red = Color(255, 0, 0)
>>> red.color_says("Hello from the red instance!")
Hello from the red instance!

This method accepts a message and prints it on your screen. It works independently from the class or instance attributes. Note that you can call the method using the class or any of its instances.

Writing Getter and Setter Methods

Programming languages like Java and C++ rely heavily on setter and getter methods to retrieve and update the attributes of a class and its instances. These methods encapsulate an attribute allowing us to get and change its value without directly accessing the attribute itself.

For example, say that we have a Label class with a text attribute. We can make text a non-public attribute and provide getter and setter methods to manipulate the attributes according to our needs:

python

class Label:
    def __init__(self, text):
        self.set_text(text)

    def text(self):
        return self._text

    def set_text(self, value):
        self._text = str(value)

In this class, the text() method is the getter associated with the ._text attribute, while the set_text() method is the setter for ._text. Note how ._text is a non-public attribute. We know this because it has a leading underscore on its name.

The setter method calls str() to convert any input value into a string. Therefore, we can call this method with any type of object. It will convert any input argument into a string, as you will see in a moment.

If you come from programming languages like Java or C++, you need to know Python doesn't have the notion of private, protected, and public attributes. In Python, you'll use a naming convention to signal that an attribute is non-public. This convention consists of adding a leading underscore to the attribute's name. Note that this naming pattern only indicates that the attribute isn't intended to be used directly. It doesn't prevent direct access, though.

This class works as follows:

python

>>> label = Label("Python!")

>>> label.text()
'Python!'

>>> label.set_text("PyQt!")
>>> label.text()
'PyQt!'

>>> label.set_text(123)
>>> label.text()
'123'

In this example, we create an instance of Label. The original text is passed to the class constructor, Label(), which automatically calls __init__() to set the value of ._text by calling the setter method set_text(). You can use text() to access the label's text and set_text() to update it. Remember that any input will be converted into a string, as we can see in the final example above.

Note that the Label class above is just a toy example, don't confuse this class with similarly named classes from GUI frameworks like PyQt, PySide, and Tkinter.

The getter and setter pattern is pretty common in languages like Java and C++. Because PyQt and PySide are Python bindings to the Qt library, which is written in C++, you'll be using this pattern a lot in your Qt-based GUI apps. However, this pattern is less popular among Python developers. Instead, they use the @property decorator to hide attributes behind properties.

Using Python Properties Instead of Getters and Setters

Here's how most Python developers will write their Label class using the @property decorator:

python

class Label:
    def __init__(self, text):
        self.text = text

    @property
    def text(self):
        return self._text

    @text.setter
    def text(self, value):
        self._text = str(value)

This class defines .text as a property. This property has getter and setter methods. Python calls them automatically when we access the attribute or update its value in an assignment:

python

>>> label = Label("Python!")

>>> label.text
'Python!'

>>> label.text = "PyQt"
>>> label.text
'PyQt'

>>> label.text = 123
>>> label.text
'123'

Python properties allow you to add function behavior to your attributes while permitting you to use them as normal attributes instead of as methods.

Writing Special Methods (`str`, `repr`, and More)

Python supports many special methods, also known as dunder or magic methods, that are part of its class mechanism. We can identify these methods because their names start and end with a double underscore, which is the origin of their other name: dunder methods.

These methods accomplish different tasks in Python's class mechanism. They all have a common feature: Python calls them automatically depending on the operation we run.

For example, all Python objects are printable. We can print them to the screen using the print() function. Calling print() internally falls back to calling the target object's __str__() special method:

python

>>> label = Label("Python!")

>>> print(label)
<__main__.Label object at 0x10354efd0>

In this example, we've printed our label object. This action provides some information about the object and the memory address where it lives. However, the actual output is not very useful from the user's perspective.

Fortunately, we can improve this by providing our Label class with an appropriate __str__() method:

python

class Label:
    def __init__(self, text):
        self.text = text

    @property
    def text(self):
        return self._text

    @text.setter
    def text(self, value):
        self._text = str(value)

    def __str__(self):
        return self.text

The __str__() method must return a user-friendly string representation for our objects. In this case, when we print an instance of Label to the screen, the label's text will be displayed:

python

>>> label = Label("Python!")

>>> print(label)
Python!

As you can see, Python takes care of calling __str__() automatically when we use the print() function to display our instances of Label.

Another special method that belongs to Python's class mechanism is __repr__(). This method returns a developer-friendly string representation of a given object. Here, developer-friendly implies that the representation should allow a developer to recreate the object itself.

python

class Label:
    def __init__(self, text):
        self.text = text

    @property
    def text(self):
        return self._text

    @text.setter
    def text(self, value):
        self._text = str(value)

    def __str__(self):
        return self.text

    def __repr__(self):
        return f"{type(self).__name__}(text='{self.text}')"

The __repr__() method returns a string representation of the current object. This string differs from what __str__() returns:

python

>>> label = Label("Python!")
>>> label
Label(text='Python!')

Now when you access the instance in your REPL session, you get a string representation of the current object. You can copy and paste this representation to recreate the object in an appropriate environment.

Reusing Code With Class Inheritance

Inheritance is an advanced topic in object-oriented programming. It allows you to create hierarchies of classes where each subclass inherits all the attributes and behaviors from its parent class or classes. Arguably, code reuse is the primary use case of inheritance.

You code a base class with a given functionality and make that functionality available to its subclasses through inheritance. This way, you implement the functionality only once and reuse it in every subclass.

Python classes support single and multiple inheritance. For example, let's say we need to create a button class. This class needs .width and .height attributes that define its rectangular shape. The class also needs a label for displaying some informative text.

We can code this class from scratch, or we can use inheritance and reuse the code of our current Label class. Here's how to do this:

python

class Button(Label):
    def __init__(self, text, width, height):
        super().__init__(text)
        self.width = width
        self.height = height

    def __repr__(self):
        return (
            f"{type(self).__name__}"
            f"(text='{self.text}', "
            f"width={self.width}, "
            f"height={self.height})"
        )

To inherit from a parent class in Python, we need to list the parent class or classes in the subclass definition. To do this, we use a pair of parentheses and a comma-separated list of parent classes. If we use several parent classes, then we're using multiple inheritance, which can be challenging to reason about.

The first line in __init__() calls the __init__() method on the parent class to properly initialize its .text attribute. To do this, we use the built-in super() function. Then we define the .width and .height attributes, which are specific to our Button class. Finally, we provide a custom implementation of __repr__().

Here's how our Button class works:

python

>>> button = Button("Ok", 10, 5)

>>> button.text
'Ok'
>>> button.text = "Click Me!"
>>> button.text
'Click Me!'

>>> button.width
10
>>> button.height
5

>>> button
Button(text='Ok', width=10, height=5)
>>> print(button)
Click Me!

As you can conclude from this code, Button has inherited the .text attribute from Label. This attribute is completely functional. Our class has also inherited the __str__() method from Label. That's why we get the button's text when we print the instance.

Using Python Classes in PyQt and PySide GUI Apps

Everything we've learned so far about Python classes is the basis of our future work in GUI development. When it comes to working with PyQt, PySide, Tkinter, or any other GUI framework, we'll heavily rely on our knowledge of classes and OOP because most of them are based on classes and class hierarchies.

We'll now look at how to use inheritance to create some GUI-related classes. For example, when we create an application with PyQt or PySide, we usually have a main window. To create this window, we typically inherit from QMainWindow:

PyQt6
PySide6

python
from PyQt6.QtWidgets import QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()

python
from PySide6.QtWidgets import QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()

In the definition of our Window class, we use the QMainWindow class as the parent class. This tells Python that we want to define a class that inherits all the functionalities that QMainWindow provides.

We can continue adding attributes and methods to our Window class. Some of these attributes can be GUI widgets, such as labels, buttons, comboboxes, checkboxes, line edits, and many others. In PyQt, we can create all these GUI components using classes such as QLabel, QPushButton, QComboBox, QCheckBox, and QLineEdit.

All of them have their own sets of attributes and methods that we can use according to our specific needs when designing the GUI of a given application.

Summary of Python Class Concepts

As we've seen, Python allows us to write classes that work as templates that you can use to create concrete objects that bundle together data and behavior. The building blocks of Python classes are:

Attributes, which hold the data in a class
Methods, which provide the behaviors of a class

The attributes of a class define the class's data, while the methods provide the class's behaviors, which typically act on that data.

To better understand OOP and classes in Python, we should first discuss some terms that are commonly used in this aspect of Python development:

Classes are blueprints or templates for creating objects — just like a blueprint for creating a car, plane, house, or anything else. In programming, this blueprint will define the data (attributes) and behavior (methods) of the object and will allow us to create multiple objects of the same kind.
Objects or Instances are the realizations of a class. We can create objects from the blueprint provided by the class. For example, you can create John's car from a Car class.
Methods are functions defined within a class. They provide the behavior of an object of that class. For example, our Car class can have methods to start the engine, turn right and left, stop, and so on.
Attributes are properties of an object or class. We can think of attributes as variables defined in a class or object. Therefore, we can have:
- Class attributes, which are specific to a concrete class and common to all the instances of that class. You can access them either through the class or an object of that class. For example, if we're dealing with a single car manufacturer, then our Car class can have a manufacturer attribute that identifies it.
- Instance attributes, which are specific to a concrete instance. You can access them through the specific instance. For example, our Car class can have attributes to store properties such as the maximum speed, the number of passengers, the car's weight, and so on.
Instantiation is the process of creating an individual instance from a class. For example, we can create John's car, Jane's car, and Linda's car from our Car class through instantiation. In Python, this process runs through two steps:
1. Instance creation: Creates a new object and allocates memory for storing it.
2. Instance initialization: Initializes all the attributes of the current object with appropriate values.
Inheritance is a mechanism of code reuse that allows us to inherit attributes and methods from one or multiple existing classes. In this context, we'll hear terms like:
- Parent class: The class we're inheriting from. This class is also known as the superclass or base class. If we have one parent class, then we're using single inheritance. If we have more than one parent class, then we're using multiple inheritance.
- Child class: The class that inherits from a given parent. This class is also known as the subclass.

Don't feel frustrated or bad if you don't understand all these terms immediately. They'll become more familiar as you use them in your own Python code. Many of our GUI tutorials make use of some or all of these concepts.

Conclusion

Now you know the basics of Python classes. You also learned fundamental concepts of object-oriented programming, such as inheritance. You also learned that most GUI frameworks are heavily based on classes. Therefore knowing about classes will open the door to begin building your own GUI app using PyQt, PySide, Tkinter, or any other GUI framework for Python.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

How to Create a Custom Title Bar for a PyQt5 Window — Customize Your Python App's Title Bars

2023-02-18T06:00:00+00:00

In this tutorial, you will learn how to create custom title bars in PyQt. By the end of this tutorial, you will have the necessary knowledge to enhance your PyQt applications with personalized and (hopefully!) stylish title bars.

Creating Frameless Windows in PyQt

In PyQt, we can create a frameless window using the setWindowFlags() method available on all QWidget subclasses, including QMainWindow. We call this method, passing in the FramelessWindowHint flag, which lives in the Qt namespace under the WindowType enumeration.

Here's the code of a minimal PyQt app whose main window is frameless:

python

from PyQt5.QtCore import Qt
from PyQt5.QtWidgets import QApplication, QMainWindow

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()

If you run this app from your command line, you'll get the following window on your screen:

A frameless window in PyQt

As you can see, the app's main window doesn't have a title bar or any other decoration. It's only a gray rectangle on your screen.

Because the window has no buttons, you need to press Alt-F4 on Windows and Linux or Cmd+Q on macOS to close the app.

This isn't very helpful, of course, but we'll be adding back in our custom title bar shortly.

Setting Up the Main Window

Before creating our custom title bar, we'll finish the initialization of our app's main window, import some additional classes and create the window's central widget and layouts.

Here's the code update:

python

from PyQt5.QtCore import Qt
from PyQt5.QtWidgets import (
    QApplication,
    QLabel,
    QMainWindow,
    QVBoxLayout,
    QWidget,
)

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        central_widget = QWidget()
        self.title_bar = CustomTitleBar(self)

        work_space_layout = QVBoxLayout()
        work_space_layout.setContentsMargins(11, 11, 11, 11)
        work_space_layout.addWidget(QLabel("Hello, World!", self))

        centra_widget_layout = QVBoxLayout()
        centra_widget_layout.setContentsMargins(0, 0, 0, 0)
        centra_widget_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
        centra_widget_layout.addWidget(self.title_bar)
        centra_widget_layout.addLayout(work_space_layout)

        central_widget.setLayout(centra_widget_layout)
        self.setCentralWidget(central_widget)

# ...

That's it! We have all the boilerplate code we need for our window to work correctly. Now we're ready to write our custom title bar.

Creating a Custom Title Bar for a PyQt Window

python

from PyQt5.QtCore import QSize, Qt
from PyQt5.QtGui import QPalette
from PyQt5.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QStyle,
    QToolButton,
    QVBoxLayout,
    QWidget,
)

# ...

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        self.setAutoFillBackground(True)
        self.setBackgroundRole(QPalette.ColorRole.Highlight)
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)

The next line of code creates and initializes an instance attribute called initial_pos. We'll use this attribute later on when we deal with moving the window around our screen.

The final three lines of code allow us to create a layout for our title bar. Because the title bar should be horizontally oriented, we use a QHBoxLayout class to structure it.

The piece of code below deals with our window's title:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        # ...
        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setStyleSheet(
            """QLabel {
                   font-weight: bold;
                   border: 2px solid black;
                   border-radius: 12px;
                   margin: 2px;
                }
            """
        )
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        if title := parent.windowTitle():
            self.title.setText(title)
        title_bar_layout.addWidget(self.title)

Next, we center the title using the setAlignment() method with the Qt.AlignmentFlag.AlignCenter flag as an argument.

Here's the required code:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        # ...
        # Min button
        self.min_button = QToolButton(self)
        min_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMinButton
        )
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMaxButton
        )
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarCloseButton
        )
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarNormalButton
        )
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)

Now that we've created and tweaked the buttons, we must add them to our title bar. To do this, we can use the following for loop:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        # ...
        buttons = [
            self.min_button,
            self.normal_button,
            self.max_button,
            self.close_button,
        ]
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(28, 28))
            button.setStyleSheet(
                """QToolButton {
                        border: 2px solid white;
                        border-radius: 12px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

Next, we set a fixed size of 28 by 28 pixels for the three buttons using the setFixedSize() method with a QSize object as an argument.

A PyQt window with a custom title bar

We'll apply some nicer styles later, once we have the functionality in place! Keep reading.

In addition to this, if you try to move the window around your screen, you'll quickly notice a problem: it's impossible to move the window!

In the following sections, we'll write the necessary code to fix these issues and make our custom title bar fully functional. To kick things off, let's start by fixing the state issues.

Updating the Window's State

Here's the code that overrides the changeEvent() method:

python

from PyQt5.QtCore import QSize, Qt, QEvent
# ...

class MainWindow(QMainWindow):
    # ...

    def changeEvent(self, event):
        if event.type() == QEvent.Type.WindowStateChange:
            self.title_bar.window_state_changed(self.windowState())
        super().changeEvent(event)
        event.accept()

Here's the implementation of our window_state_changed() method in CustomTitleBar:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def window_state_changed(self, state):
        if state == Qt.WindowState.WindowMaximized:
            self.normal_button.setVisible(True)
            self.max_button.setVisible(False)
        else:
            self.normal_button.setVisible(False)
            self.max_button.setVisible(True)

This method takes a window's state as an argument. Depending on the value of the state parameter, we will show or hide the maximize and restore buttons.

Handling the Window's Movements

In particular, we need to override three mouse events:

mousePressEvent() will let us know when the user clicks on our custom title bar using the mouse's left button. This may indicate that the window movement should start.
mouseMoveEvent() will let us process window movement.
mouseReleaseEvent() will let us know when the user has released the mouse's left button so that we can stop moving the window.

Here's the code that overrides the mousePressEvent() method:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            self.initial_pos = event.pos()
        super().mousePressEvent(event)
        event.accept()

Next, we need to override the mouseMoveEvent() method. Here's the required code:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def mouseMoveEvent(self, event):
        if self.initial_pos is not None:
            delta = event.pos() - self.initial_pos
            self.window().move(
                self.window().x() + delta.x(),
                self.window().y() + delta.y(),
            )
        super().mouseMoveEvent(event)
        event.accept()

This if statement in mouseMoveEvent() checks if the initial_pos attribute is not None. If this condition is true, then the if code block executes because we have a valid initial position.

The first line in the if code block calculates the difference, or delta, between the current and initial mouse positions. To get the current position, we call the pos() method on the event object.

The following four lines update the position of our application's main window by adding the delta values to the current window position. The move() method does the hard work of moving the window.

Finally, we can complete the mouseReleaseEvent() method:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def mouseReleaseEvent(self, event):
        self.initial_pos = None
        super().mouseReleaseEvent(event)
        event.accept()

This method's implementation is pretty straightforward. Its purpose is to reset the initial position by setting it back to None when the mouse is released, indicating that the drag is complete.

The completed code for the custom title bar is shown below:

python

from PyQt5.QtCore import QEvent, QSize, Qt
from PyQt5.QtGui import QPalette
from PyQt5.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QStyle,
    QToolButton,
    QVBoxLayout,
    QWidget,
)

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        self.setAutoFillBackground(True)
        self.setBackgroundRole(QPalette.ColorRole.Highlight)
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)

        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setStyleSheet(
            """QLabel {
                   font-weight: bold;
                   border: 2px solid black;
                   border-radius: 12px;
                   margin: 2px;
                }
            """
        )
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        if title := parent.windowTitle():
            self.title.setText(title)
        title_bar_layout.addWidget(self.title)

        # Min button
        self.min_button = QToolButton(self)
        min_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMinButton,
        )
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMaxButton,
        )
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarCloseButton
        )
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarNormalButton
        )
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)
        # Add buttons
        buttons = [
            self.min_button,
            self.normal_button,
            self.max_button,
            self.close_button,
        ]
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(28, 28))
            button.setStyleSheet(
                """QToolButton {
                        border: 2px solid white;
                        border-radius: 12px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

    def window_state_changed(self, state):
        if state == Qt.WindowState.WindowMaximized:
            self.normal_button.setVisible(True)
            self.max_button.setVisible(False)
        else:
            self.normal_button.setVisible(False)
            self.max_button.setVisible(True)

    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            self.initial_pos = event.pos()
        super().mousePressEvent(event)
        event.accept()

    def mouseMoveEvent(self, event):
        if self.initial_pos is not None:
            delta = event.pos() - self.initial_pos
            self.window().move(
                self.window().x() + delta.x(),
                self.window().y() + delta.y(),
            )
        super().mouseMoveEvent(event)
        event.accept()

    def mouseReleaseEvent(self, event):
        self.initial_pos = None
        super().mouseReleaseEvent(event)
        event.accept()

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        central_widget = QWidget()
        self.title_bar = CustomTitleBar(self)

        work_space_layout = QVBoxLayout()
        work_space_layout.setContentsMargins(11, 11, 11, 11)
        work_space_layout.addWidget(QLabel("Hello, World!", self))

        central_widget_layout = QVBoxLayout()
        central_widget_layout.setContentsMargins(0, 0, 0, 0)
        central_widget_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
        central_widget_layout.addWidget(self.title_bar)
        central_widget_layout.addLayout(work_space_layout)

        central_widget.setLayout(central_widget_layout)
        self.setCentralWidget(central_widget)

    def changeEvent(self, event):
        if event.type() == QEvent.Type.WindowStateChange:
            self.title_bar.window_state_changed(self.windowState())
        super().changeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()

Making It a Little More Beautiful

In this section, we'll look at how we can reproduce the same effect in PyQt using a combination of stylesheets and icons. Below is a screenshot of the final result which we'll be building:

python

# ...
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
        # ...

python

#...
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        # ...
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
        self.setStyleSheet("background-color: gray; border-radius: 10px;")
#...

On our MainWindow class, we already have a central widget which contains our layout, so we can apply the styles there:

python

# ...

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        # ...
        central_widget = QWidget()
        # This container holds the window contents, so we can style it.
        central_widget.setObjectName("Container")
        central_widget.setStyleSheet(
            """#Container {
                    background: qlineargradient(x1:0 y1:0, x2:1 y2:1, stop:0 #051c2a stop:1 #44315f);
                    border-radius: 5px;
                }
            """
        )
        self.title_bar = CustomTitleBar(self)
        # ...

We've taken the existing central_widget object and assigned an object name to it. This is an ID which we can use to refer to the widget from QSS and apply our styles specifically to that widget.

With this style applied on our window, we have a nice gradient background with curved corners.

We don't need to set any flags or attributes on this widget because it is not a window. A QWidget object is transparent by default.

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        # self.setAutoFillBackground(True) # <-- remove
        # self.setBackgroundRole(QPalette.ColorRole.Highlight) # <-- remove
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)
        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.title.setStyleSheet(
            """QLabel {
                    text-transform: uppercase;
                    font-size: 10pt;
                    margin-left: 48px;
                    color: white;
                }
            """
        )

QSS is very similar to CSS, especially for text styling.

The margin-left: 48px is to compensate for the 3 × 16 px window icons on the right-hand side so the text aligns centrally.

python

from PyQt5.QtGui import QIcon
# ...
class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        # ...
        # Min button
        self.min_button = QToolButton(self)
        min_icon = QIcon()
        min_icon.addFile('min.svg')
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = QIcon()
        max_icon.addFile('max.svg')
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = QIcon()
        close_icon.addFile('close.svg') # Close has only a single state.
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = QIcon()
        normal_icon.addFile('normal.svg')
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)
        # ...

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        # ...
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(16, 16))
            button.setStyleSheet(
                """QToolButton {
                        border: none;
                        padding: 2px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

And that's it! With these changes, you can now run your application and you'll see a nice sleek modern-looking UI with unified title bar and custom controls:

The final result, showing our unified title bar and window design.

The complete code is shown below:

python

from PyQt5.QtCore import QEvent, QSize, Qt
from PyQt5.QtGui import QIcon
from PyQt5.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QToolButton,
    QVBoxLayout,
    QWidget,
)

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)
        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.title.setStyleSheet(
            """QLabel {
                    text-transform: uppercase;
                    font-size: 10pt;
                    margin-left: 48px;
                    color: white;
                }
            """
        )

        if title := parent.windowTitle():
            self.title.setText(title)
        title_bar_layout.addWidget(self.title)

        # Min button
        self.min_button = QToolButton(self)
        min_icon = QIcon()
        min_icon.addFile("min.svg")
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = QIcon()
        max_icon.addFile("max.svg")
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = QIcon()
        close_icon.addFile("close.svg")  # Close has only a single state.
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = QIcon()
        normal_icon.addFile("normal.svg")
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)
        # Add buttons
        buttons = [
            self.min_button,
            self.normal_button,
            self.max_button,
            self.close_button,
        ]
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(16, 16))
            button.setStyleSheet(
                """QToolButton {
                        border: none;
                        padding: 2px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

    def window_state_changed(self, state):
        if state == Qt.WindowState.WindowMaximized:
            self.normal_button.setVisible(True)
            self.max_button.setVisible(False)
        else:
            self.normal_button.setVisible(False)
            self.max_button.setVisible(True)

    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            self.initial_pos = event.pos()
        super().mousePressEvent(event)
        event.accept()

    def mouseMoveEvent(self, event):
        if self.initial_pos is not None:
            delta = event.pos() - self.initial_pos
            self.window().move(
                self.window().x() + delta.x(),
                self.window().y() + delta.y(),
            )
        super().mouseMoveEvent(event)
        event.accept()

    def mouseReleaseEvent(self, event):
        self.initial_pos = None
        super().mouseReleaseEvent(event)
        event.accept()

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
        central_widget = QWidget()
        # This container holds the window contents, so we can style it.
        central_widget.setObjectName("Container")
        central_widget.setStyleSheet(
            """#Container {
                    background: qlineargradient(x1:0 y1:0, x2:1 y2:1, stop:0 #051c2a stop:1 #44315f);
                    border-radius: 5px;
                }
            """
        )
        self.title_bar = CustomTitleBar(self)

        work_space_layout = QVBoxLayout()
        work_space_layout.setContentsMargins(11, 11, 11, 11)
        hello_label = QLabel("Hello, World!", self)
        hello_label.setStyleSheet("color: white;")
        work_space_layout.addWidget(hello_label)

        centra_widget_layout = QVBoxLayout()
        centra_widget_layout.setContentsMargins(0, 0, 0, 0)
        centra_widget_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
        centra_widget_layout.addWidget(self.title_bar)
        centra_widget_layout.addLayout(work_space_layout)

        central_widget.setLayout(centra_widget_layout)
        self.setCentralWidget(central_widget)

    def changeEvent(self, event):
        if event.type() == QEvent.Type.WindowStateChange:
            self.title_bar.window_state_changed(self.windowState())
        super().changeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()

Note that you've also set the color of the "Hello, World!" label to white so that it's visible on a dark background.

Conclusion

Now let your imagination run and transform your PyQt application's UX.

For an in-depth guide to building Python GUIs with PyQt5 see my book, Create GUI Applications with Python & Qt5.

Getting Started with VS Code for Python — Setting up a Development Environment for Python Programming

2022-09-21T09:00:00+00:00

Setting up a working development environment is the first step for any project. Your development environment setup will determine how easy it is to develop and maintain your projects over time. That makes it important to choose the right tools for your project. This article will guide you through how to set up Visual Studio Code (VS Code), a popular free-to-use, cross-platform code editor developed by Microsoft, for Python development.

Visual Studio Code is not to be confused with Visual Studio, which is a separate product also offered by Microsoft. Visual Studio is a fully-fledged IDE that is mainly geared towards Windows application development using C# and the .NET Framework.

Setting Up a Python Environment

In case you haven't already done this, Python needs to be installed on the development machine. You can do this by going to python.org and grabbing the specific installer for either Windows or macOS. Python is also available for installation via Microsoft Store on Windows devices.

Make sure that you select the option to Add Python to PATH during installation (via the installer).

If you are on Linux, you can check if Python is already installed on your machine by typing python3 --version in a terminal. If it returns an error, you need to install it from your distribution's repository. On Ubuntu/Debian, this can be done by typing sudo apt install python3. Both pip (or pip3) and venv are distributed as separate packages on Ubuntu/Debian and can also be installed by typing sudo apt install python3-pip python3-venv.

Installing Visual Studio Code and the Python Extension

First, head over to code.visualstudio.com and grab the installer for your specific platform.

If you are on a Raspberry Pi (with Raspberry Pi OS), you can also install VS Code by simply typing sudo apt install code. On Linux distributions that support Snaps, you can do it by typing sudo snap install code --classic.

Once VS Code is installed, head over to the Extensions tab in the sidebar on the left by clicking on it or by pressing CTRL+SHIFT+X. Search for the 'Python' extension published by Microsoft and click on Install.

The Extensions tab in the left-hand sidebar.

Using and Configuring VS Code for Python

Now that you have finished setting up VS Code, you can go ahead and create a new Python file. Remember that the Python extension only works if you open a .py file or have selected the language mode for the active file as Python.

To change the language mode for the active file, simply press CTRL+K once and then press M after releasing the previous keys. This kind of keyboard shortcut is called a chord in VS Code. You can see more of them by pressing CTRL+K CTRL+S (another chord).

The Python extension in VS Code allows you to directly run a Python file by clicking on the 'Play' button on the top-right corner of the editor (without having to type python file.py in the terminal).

You can also do it by pressing CTRL+SHIFT+P to open the Command Palette and running the > Python: Run File in Terminal command.

Finally, you can configure VS Code's settings by going to File > Preferences > Settings or by pressing CTRL+COMMA. In VS Code, each individual setting has a unique identifier which you can see by clicking on the cog wheel that appears to the left of each setting and clicking on 'Copy Setting ID'. This ID is what will be referred to while talking about a specific setting. You can also search for this ID in the search bar under Settings.

Configuring Python Linting and Formatting in VS Code

Linters make it easier to find errors and check the quality of your code. On the other hand, code formatters help keep the source code of your application compliant with PEP (Python Enhancement Proposal) standards, which make it easier for other developers to read your code and collaborate with you.

For VS Code to provide linting support for your Python projects, you must first install a preferred linter like flake8 or pylint.

pip install flake8

Then, go to Settings in VS Code and toggle the relevant setting (e.g. python.linting.flake8Enabled) for the Python extension depending on what you installed. You also need to make sure that python.linting.enabled is toggled on.

A similar process must be followed for code formatting. First, install something like autopep8 or black.

pip install autopep8

You then need to tell VS Code which formatter to use by modifying python.formatting.provider and toggle on editor.formatOnSave so that it works without manual intervention.

If pip warns that the installed modules aren't in your PATH, you may have to specify the path to their location in VS Code (under Settings). Follow the method described under Working With Virtual Environments to do that.

Now, when you create a new Python file, VS Code automatically gives you a list of Problems (CTRL+SHIFT+M) in your program and formats the code on saving the file.

Identified problems in the source code, along with a description and line/column numbers.

You can also find the location of identified problems from the source overview on the right hand, inside the scrollbar.

Working With Python Virtual Environments in VS Code

Virtual environments are a way of life for Python developers. Most Python projects require the installation of external packages and modules (via pip). Virtual environments allow you to separate one project's packages from your other projects, which may require a different version of those same packages. Hence, it allows all those projects to have the specific dependencies they require to work.

The Python extension makes it easier for you by automatically activating the desired virtual environment for the in-built terminal and Run Python File command after you set the path to the Python interpreter. By default, the path is set to use the system's Python installation (without a virtual environment).

To use a virtual environment for your project/workspace, you need to first make a new one by opening a terminal (View > Terminal) and typing python -m venv .venv. Then, you can set the default interpreter for that project by opening the Command Palette (CTRL+SHIFT+P) and selecting > Python: Select Interpreter.

You should now either close the terminal pane in VS Code and open a new one or type source .venv/bin/activate into the existing one to start using the virtual environment. Then, install the required packages for your project by typing pip install <package_name>.

VS Code, by default, looks for tools like linters and code formatters in the current Python environment. If you don't want to keep installing them over and over again for each new virtual environment you make (unless your project requires a specific version of that tool), you can specify the path to their location under Settings in VS Code.

flake8 - python.linting.flake8Path
autopep8 - python.formatting.autopep8Path

To find the global location of these packages on macOS and Linux, type which flake8 and which autopep8 in a terminal. If you are on Windows, you can use where <command_name>. Both these commands assume that flake8 and autopep8 are in your PATH.

Understanding VS Code Workspaces for Python Projects

VS Code has a concept of Workspaces. Each 'project folder' (or the root/top folder) is treated as a separate workspace. This allows you to have project-specific settings and enable/disable certain extensions for that workspace. It is also what allows VS Code to quickly recover the UI state (e.g. files that were previously kept open) when you open that workspace again.

In VS Code, each workspace (or folder) has to be 'trusted' before certain features like linters, autocomplete suggestions and the in-built terminal are allowed to work.

In the context of Python projects, if you tend to keep your virtual environments outside the workspace (where VS Code is unable to detect it), you can use this feature to set the default path to the Python interpreter for that workspace. To do that, first Open a Folder (CTRL+K CTRL+O) and then go to File > Preferences > Settings > Workspace to modify python.defaultInterpreterPath.

Setting the default interpreter path for the workspace.

In VS Code settings you can search for settings by name using the bar at the top.

You can also use this approach to do things like use a different linter for that workspace or disable the code formatter for it. The workspace-specific settings you change are saved in a .vscode folder inside that workspace, which you can share with others.

If VS Code is not recognizing Python libraries you are using in your code, double check the correct interpreter is being used. You can find which Python version you're using on the command line by running which python or which python3 on macOS/Linux, or where python or where python3 on Windows.

Using Git With VS Code for Python Projects

Using Version Control is required for developing applications. VS Code does have in-built support for Git but it is pretty barebones, not allowing much more than tracking changes that you have currently made and committing/pushing those changes once you are done.

For the best experience, it is recommended to use the GitLens extension. It lets you view your commit history, check who made the changes and much more. To set it up, you first need to have Git set up on your machine (go here) and then install GitLens from the Extensions tab in the sidebar on the left. You can now use those Git-related features by going to the Git tab in the sidebar (CTRL+SHIFT+G).

There are more Git-related extensions you could try as well, like Git History and GitLab Workflow. Give them a whirl too!

Community-Driven & Open Source Alternatives to VS Code

While VS Code is open source (MIT-licensed), the distributed versions include some Microsoft-specific proprietary modifications, such as telemetry (app tracking). If you would like to avoid this, there is also a community-driven distribution of Visual Studio Code called VSCodium that provides freely-licensed binaries without telemetry.

Due to legal restrictions, VSCodium is unable to use the official Visual Studio Marketplace for extensions. Instead, it uses a separate vendor neutral, open source marketplace called Open VSX Registry. It doesn't have every extension, especially proprietary ones, and some are not kept up-to-date but both the Python and GitLens extensions are available on it.

You can also use the open source Jedi language server for the Python extension, rather than the bundled Pylance language server/extension, by configuring the python.languageServer setting. You can then completely disable Pylance by going to the Extensions tab. Note that, if you are on VSCodium, Jedi is used by default (as Pylance is not available on Open VSX Registry) when you install the Python extension.

Conclusion

Having the right tools and making sure they're set up correctly will greatly simplify your Python development process. While VS Code starts as a simple code editor, it is flexible and extendable with plugins to suit your own preferred workflow. In this tutorial we've covered the basics of setting up your VS Code environment for Python, including installing the Python extension, configuring linting and formatting, working with virtual environments, and using Git. You should now be ready to start developing your own applications with Python!

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Plotting With PyQtGraph and PyQt6 — Create Custom Plots in PyQt6 With PyQtGraph

2024-02-19T06:00:00+00:00

One of the major fields where Python shines is in data science. For data exploration and cleaning, Python has many powerful tools, such as Pandas and Polars. For visualization, Python has Matplotlib.

When you're building GUI applications with PyQt, you can have access to all those tools directly from within your app. While it is possible to embed matplotlib plots in PyQt, the experience doesn't feel entirely native. So, for highly integrated plots, you may want to consider using the PyQtGraph library instead.

PyQtGraph is built on top of Qt's native QGraphicsScene, so it gives better drawing performance, particularly for real-time data visualization. It also provides interactivity and the ability to customize plots according to your needs.

In this tutorial, you'll learn the basics of creating plots with PyQtGraph. You'll also explore the different plot customization options, including background color, line colors, line type, axis labels, and more.

Installing PyQtGraph

To use PyQtGraph with PyQt6, you first need to install the library in your Python environment. You can do this using pip as follows:

$ python -m pip install pyqtgraph

Once the installation is complete, you will be able to import the module into your Python code. So, now you are ready to start creating plots.

Creating a PlotWidget Instance

In PyQtGraph, all plots use the PlotWidget class. This widget provides a canvas on which we can add and configure many types of plots. Under the hood, PlotWidget uses Qt's QGraphicsScene class, meaning that it's fast, efficient, and well-integrated with the rest of your app.

The code below shows a basic GUI app with a single PlotWidget in a QMainWindow:

python

import pyqtgraph as pg
from PyQt6 import QtWidgets

class MainWindow(QtWidgets.QMainWindow):
    def __init__(self):
        super().__init__()

        # Temperature vs time plot
        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)
        minutes = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
        temperature = [30, 32, 34, 32, 33, 31, 29, 32, 35, 30]
        self.plot_graph.plot(minutes, temperature)

app = QtWidgets.QApplication([])
main = MainWindow()
main.show()
app.exec()

In this short example, you create a PyQt app with a PlotWidget as its central widget. Then you create two lists of sample data for time and temperature. The final step to create the plot is to call the plot() methods with the data you want to visualize.

The first argument to plot() will be your x coordinate, while the second argument will be the y coordinate.

In all the examples in this tutorial, we import PyQtGraph using import pyqtgraph as pg. This is a common practice in PyQtGraph examples to keep things tidy and reduce typing.

If you run the above application, then you'll get the following window on your screen:

Basic PyQtGraph plot: Temperature vs time.

PyQtGraph's default plot style is quite basic — a black background with a thin (barely visible) white line. Fortunately, the library provides several options that will allow us to deeply customize our plots.

In the examples in this tutorial, we'll create the PyQtGraph widget in code. To learn how to embed PyQtGraph plots when using Qt Designer, check out Embedding custom widgets from Qt Designer.

In the following section, we'll learn about the options we have available in PyQtGraph to improve the appearance and usability of our plots.

Customizing PyQtGraph Plots

Because PyQtGraph uses Qt's QGraphicsScene to render the graphs, we have access to all the standard Qt line and shape styling options for use in plots. PyQtGraph provides an API for using these options to draw plots and manage the plot canvas.

Below, we'll explore the most common styling features that you'll need to create and customize your own plots with PyQtGraph.

Changing the Background Color

Beginning with the app skeleton above, we can change the background color by calling setBackground() on our PlotWidget instance, self.graphWidget. The code below sets the background to white by passing in the string "w":

python

from PyQt6 import QtWidgets

import pyqtgraph as pg

class MainWindow(QtWidgets.QMainWindow):
    def __init__(self):
        super().__init__()

        # Temperature vs time plot
        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)
        self.plot_graph.setBackground("w")
        minutes = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
        temperature = [30, 32, 34, 32, 33, 31, 29, 32, 35, 30]
        self.plot_graph.plot(minutes, temperature)

app = QtWidgets.QApplication([])
main = MainWindow()
main.show()
app.exec()

Calling setBackground() with "w" as an argument changes the background of your plot to white, as you can see in the following window:

PyQtGraph plot with a white background.

There are a number of colors available using single letters, as we did in the example above. They're based on the standard colors used in Matplotlib. Here are the most common codes:

Letter Code	Color
`"b"`	Blue
`"c"`	Cian
`"d"`	Grey
`"g"`	Green
`"k"`	Black
`"m"`	Magenta
`"r"`	Red
`"w"`	White
`"y"`	Yellow

In addition to these single-letter codes, we can create custom colors using the hexadecimal notation as a string:

python

self.plot_graph.setBackground("#bbccaa")  # Hex

We can also use RGB and RGBA values passed in as 3-value and 4-value tuples, respectively. We must use values in the range from 0 to 255:

python

self.plot_graph.setBackground((100, 50, 255))  # RGB each 0-255
self.plot_graph.setBackground((100, 50, 255, 25))  # RGBA (A = alpha opacity)

The first call to setBackground() takes a tuple representing an RGB color, while the second call takes a tuple representing an RGBA color.

We can also specify colors using Qt's QColor class if we prefer it:

python

from PyQt6 import QtGui
# ...

self.plot_graph.setBackground(QtGui.QColor(100, 50, 254, 25))

Using QColor can be useful when you're using specific QColor objects elsewhere in your application and want to reuse them in your plots. For example, say that your app has a custom window background color, and you want to use it in the plots as well. Then you can do something like the following:

python

color = self.palette().color(QtGui.QPalette.Window)
# ...

self.plot_graph.setBackground(color)

In the first line, you get the GUI's background color, while in the second line, you use that color for your plots.

Customizing Line Color, Width, and Style

Plot lines in PyQtGraph are drawn using the Qt QPen class. This gives us full control over line drawing, as we would have in any other QGraphicsScene drawing. To use a custom pen, you need to create a new QPen instance and pass it into the plot() method.

In the app below, we use a custom QPen object to change the line color to red:

python

from PyQt6 import QtWidgets

import pyqtgraph as pg

class MainWindow(QtWidgets.QMainWindow):
    def __init__(self):
        super().__init__()

        # Temperature vs time plot
        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)
        self.plot_graph.setBackground("w")
        pen = pg.mkPen(color=(255, 0, 0))
        time = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
        temperature = [30, 32, 34, 32, 33, 31, 29, 32, 35, 45]
        self.plot_graph.plot(time, temperature, pen=pen)

app = QtWidgets.QApplication([])
main = MainWindow()
main.show()
app.exec()

Here, we create a QPen object, passing in a 3-value tuple that defines an RGB red color. We could also define this color with the "r" code or with a QColor object. Then, we pass the pen to plot() with the pen argument.

PyQtGraph plot with a red plot line.

By tweaking the QPen object, we can change the appearance of the line. For example, you can change the line width in pixels and the style (dashed, dotted, etc.), using Qt's line styles.

Update the following lines of code in your app to create a red, dashed line with 5 pixels of width:

python

from PyQt6 import QtCore, QtWidgets
# ...

pen = pg.mkPen(color=(255, 0, 0), width=5, style=QtCore.Qt.DashLine)

The result of this code is shown below, giving a 5-pixel, dashed, red line:

PyQtGraph plot with a red, dashed, and 5-pixel line

You can use all other Qt's line styles, including Qt.SolidLine, Qt.DotLine, Qt.DashDotLine, and Qt.DashDotDotLine. Examples of each of these lines are shown in the image below:

Qt's line styles.

To learn more about Qt's line styles, check the documentation about pen styles. There, you'll find all you need to deeply customize the lines in your PyQtGraph plots.

Adding Line Markers

For many plots, it can be helpful to use point markers in addition or instead of lines on the plot. To draw a marker on your plot, pass the symbol you want to use as a marker when calling plot(). The following example uses the plus sign as a marker:

python

self.plot_graph.plot(hour, temperature, symbol="+")

In this line of code, you pass a plus sign to the symbol argument. This tells PyQtGraph to use that symbol as a marker for the points in your plot.

If you use a custom symbol, then you can also use the symbolSize, symbolBrush, and symbolPen arguments to further customize the marker.

The value passed as symbolBrush can be any color, or QBrush instance, while symbolPen can be any color or a QPen instance. The pen is used to draw the shape, while the brush is used for the fill.

Go ahead and update your app's code to use a blue marker of size 15, on a red line:

python

pen = pg.mkPen(color=(255, 0, 0))

self.plot_graph.plot(
    time,
    temperature,
    pen=pen,
    symbol="+",
    symbolSize=20,
    symbolBrush="b",
)

In this code, you pass a plus sign to the symbol argument. You also customize the marker size and color. The resulting plot looks something like this:

PyQtGraph plot with a plus sign as a point marker.

In addition to the + plot marker, PyQtGraph supports the markers shown in the table below:

Character	Marker Shape
`"o"`	Circle
`"s"`	Square
`"t"`	Triangle
`"d"`	Diamond
`"+"`	Plus
`"t1"`	Triangle pointing upwards
`"t2"`	Triangle pointing right side
`"t3"`	Triangle pointing left side
`"p"`	Pentagon
`"h"`	Hexagon
`"star"`	Star
`"x"`	Cross
`"arrow_up"`	Arrow Up
`"arrow_right"`	Arrow Right
`"arrow_down"`	Arrow Down
`"arrow_left"`	Arrow Left
`"crosshair"`	Crosshair

You can use any of these symbols as markers for your data points. If you have more specific marker requirements, then you can also use a QPainterPath object, which allows you to draw completely custom marker shapes.

Adding Plot Titles

Plot titles are important to provide context around what is shown on a given chart. In PyQtGraph, you can add a main plot title using the setTitle() method on the PlotWidget object. Your title can be a regular Python string:

python

self.plot_graph.setTitle("Temperature vs Time")

You can style your titles and change their font color and size by passing additional arguments to setTitle(). The code below sets the color to blue and the font size to 20 points:

python

self.plot_graph.setTitle("Temperature vs Time", color="b", size="20pt")

In this line of code, you set the title's font color to blue and the size to 20 points using the color and size arguments of setTitle().

You could've even used CSS style and basic HTML tag syntax if you prefer, although it's less readable:

python

self.plot_graph.setTitle(
    '<span style="color: blue; font-size: 20pt">Temperature vs Time</span>'
)

In this case, you use a span HTML tag to wrap the title and apply some CSS styles on top of it. The final result is the same as using the color and size arguments. Your plot will look like this:

PyQtGraph plot with title.

Your plot looks way better now. You can continue customizing it by adding informative labels to both axes.

Adding Axis Labels

When it comes to axis labels, we can use the setLabel() method to create them. This method requires two arguments, position and text.

python

self.plot_graph.setLabel("left", "Temperature (°C)")
self.plot_graph.setLabel("bottom", "Time (min)")

The position argument can be any one of "left", "right", "top", or "bottom". They define the position of the axis on which the text is placed. The second argument, text is the text you want to use for the label.

You can pass an optional style argument into the setLabel() method. In this case, you need to use valid CSS name-value pairs. To provide these CSS pairs, you can use a dictionary:

python

styles = {"color": "red", "font-size": "18px"}
self.plot_graph.setLabel("left", "Temperature (°C)", **styles)
self.plot_graph.setLabel("bottom", "Time (min)", **styles)

Here, you first create a dictionary containing CSS pairs. Then you pass this dictionary as an argument to the setLabel() method. Note that you need to use the dictionary unpacking operator to unpack the styles in the method call.

Again, you can use basic HTML syntax and CSS for the labels if you prefer:

python

self.plot_graph.setLabel(
    "left",
    '<span style="color: red; font-size: 18px">Temperature (°C)</span>'
)
self.plot_graph.setLabel(
    "bottom",
    '<span style="color: red; font-size: 18px">Time (min)</span>'
)

This time, you've passed the styles in a span HTML tag with appropriate CSS styles. In either case, your plot will look something like this:

PyQtGraph plot with axis labels.

Having axis labels highly improves the readability of your plots as you can see in the above example. So, it's a good practice that you should keep in mind when creating your plots.

Adding a Plot Legend

In addition to the axis labels and the plot title, you will often want to show a legend identifying what a given line represents. This feature is particularly important when you start adding multiple lines to a plot.

You can add a legend to a plot by calling the addLegend() method on the PlotWidget object. However, for this method to work, you need to provide a name for each line when calling plot().

The example below assigns the name "Temperature Sensor" to the plot() method. This name will be used to identify the line in the legend:

python

self.plot_graph.addLegend()
# ...
self.plot_graph.plot(
    time,
    temperature,
    name="Temperature Sensor",
    pen=pen,
    symbol="+",
    symbolSize=15,
    symbolBrush="b",
)

Note that you must call addLegend() before you call plot() for the legend to show up. Otherwise, the plot won't show the legend at all. Now your plot will look like the following:

PyQtGraph plot with legend.

The legend appears in the top left by default. If you would like to move it, you can drag and drop the legend elsewhere. You can also specify a default offset by passing a 2-value tuple to the offset parameter when calling the addLegend() method. This will allow you to specify a custom position for the legend.

Enabling a Background Grid

Adding a background grid can make your plots easier to read, particularly when you're trying to compare relative values against each other. You can turn on the background grid for your plot by calling the showGrid() method on your PlotWidget instance. The method takes two Boolean arguments, x and y:

python

self.plot_graph.showGrid(x=True, y=True)

In this call to the showGrid() method, you enable the grid lines in both dimensions x and y. Here's how the plot looks now:

PyQtGraph plot with grid.

You can toggle the x and y arguments independently, according to the dimension on which you want to enable the grid lines.

Setting the Axis Range

Sometimes, it can be useful to predefine the range of values that is visible on the plot or to lock the axis to a consistent range regardless of the data input. In PyQtGraph, you can do this using the setXRange() and setYRange() methods. They force the plot to only show data within the specified ranges.

Below, we set two ranges, one on each axis. The first argument is the minimum value, and the second is the maximum:

python

self.plot_graph.setXRange(1, 10)
self.plot_graph.setYRange(20, 40)

The first line of code sets the x-axis to show values between 1 and 10. The second line sets the y-axis to display values between 20 and 40. Here's how this changes the plot:

PyQtGraph plot with axis ranges

Now your plot looks more consistent. The axes show fixed scales that are specifically set for the possible range of input data.

An optional padding argument causes the range to be set larger than specified by the given fraction (this is between 0.02 and 0.1 by default, depending on the size of the ViewBox). If you want to remove this padding entirely, pass 0.

python

self.plot_graph.setXRange(5, 20, padding=0)
self.plot_graph.setYRange(30, 40, padding=0)

The complete code so far is shown below:

python

import sys

import pyqtgraph as pg
from PyQt6.QtWidgets import QApplication, QMainWindow

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)

        hour = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
        temperature = [30, 32, 34, 32, 33, 31, 29, 32, 35, 45]

        # Set background color to white
        self.plot_graph.setBackground('w')
        # Set title
        self.plot_graph.setTitle("Your Title Here", color="b", size="30pt")
        # Set axis labels
        styles = {"color": "#f00", "font-size": "20px"}
        self.plot_graph.setLabel("left", "Temperature (°C)", **styles)
        self.plot_graph.setLabel("bottom", "Hour (H)", **styles)
        # Add legend
        self.plot_graph.addLegend()
        # Show the grid
        self.plot_graph.showGrid(x=True, y=True)
        # Set range
        self.plot_graph.setXRange(0, 10, padding=0)
        self.plot_graph.setYRange(20, 55, padding=0)

        pen = pg.mkPen(color=(255, 0, 0))
        self.plot_graph.plot(hour, temperature, name="Sensor 1", pen=pen, symbol='+', symbolSize=30, symbolBrush='b')

app = QApplication(sys.argv)
main = MainWindow()
main.show()
app.exec_()

Plotting Multiple Lines on the Same Chart

It is common to have plots that involve more than one dependent variable. In PyQtGraph, you can plot multiple lines in a single chart by calling .plot() multiple times on the same PlotWidget instance.

In the following example, we plot temperature values from two different sensors. We use the same line style but change the line color. To avoid code repetition, we define a new plot_line() method on our window:

python

from PyQt6 import QtWidgets

import pyqtgraph as pg

class MainWindow(QtWidgets.QMainWindow):
    def __init__(self):
        super().__init__()

        # Temperature vs time plot
        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)
        self.plot_graph.setBackground("w")
        self.plot_graph.setTitle("Temperature vs Time", color="b", size="20pt")
        styles = {"color": "red", "font-size": "18px"}
        self.plot_graph.setLabel("left", "Temperature (°C)", **styles)
        self.plot_graph.setLabel("bottom", "Time (min)", **styles)
        self.plot_graph.addLegend()
        self.plot_graph.showGrid(x=True, y=True)
        self.plot_graph.setXRange(1, 10)
        self.plot_graph.setYRange(20, 40)
        minutes = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
        temperature_1 = [30, 32, 34, 32, 33, 31, 29, 32, 35, 30]
        temperature_2 = [32, 35, 40, 22, 38, 32, 27, 38, 32, 38]
        pen = pg.mkPen(color=(255, 0, 0))
        self.plot_line("Temperature Sensor 1", minutes, temperature_1, pen, "b")
        pen = pg.mkPen(color=(0, 0, 255))
        self.plot_line("Temperature Sensor 2", minutes, temperature_2, pen, "r")

    def plot_line(self, name, minutes, temperature, pen, brush):
        self.plot_graph.plot(
            minutes,
            temperature,
            name=name,
            pen=pen,
            symbol="+",
            symbolSize=15,
            symbolBrush=brush,
        )

app = QtWidgets.QApplication([])
main = MainWindow()
main.show()
app.exec()

The custom plot_line() method on the main window does the hard work. It accepts a name to set the line name for the plot legend. Then it takes the time and temperature arguments. The pen and brush arguments allow you to tweak other features of the lines.

To plot separate temperature values, we'll create a new list called temperature_2 and populate it with random numbers similar to our old temperature, which now is temperature_1. Here's how the plot looks now:

PyQtGraph plot with two lines.

You can play around with the plot_line() method, customizing the markers, line widths, colors, and other parameters.

Creating Real-Time Dynamic Plots

You can also create dynamic real-time plots with PyQtGraph. The PlotWidget can take new data and update the plot in real time without affecting other elements. To update a plot dynamically, we need a reference to the line object that the plot() method returns.

Once we have the reference to the plot line, we can call the setData() method on the line object to apply the new data. In the example below, we've adapted our temperature vs time plot to accept new temperature measures every minute. Note that we've set the timer to 300 milliseconds so that we don't have to wait an entire minute to see the updates:

python

from random import randint

from PyQt6 import QtCore, QtWidgets

import pyqtgraph as pg

class MainWindow(QtWidgets.QMainWindow):
    def __init__(self):
        super().__init__()

        # Temperature vs time dynamic plot
        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)
        self.plot_graph.setBackground("w")
        pen = pg.mkPen(color=(255, 0, 0))
        self.plot_graph.setTitle("Temperature vs Time", color="b", size="20pt")
        styles = {"color": "red", "font-size": "18px"}
        self.plot_graph.setLabel("left", "Temperature (°C)", **styles)
        self.plot_graph.setLabel("bottom", "Time (min)", **styles)
        self.plot_graph.addLegend()
        self.plot_graph.showGrid(x=True, y=True)
        self.plot_graph.setYRange(20, 40)
        self.time = list(range(10))
        self.temperature = [randint(20, 40) for _ in range(10)]
        # Get a line reference
        self.line = self.plot_graph.plot(
            self.time,
            self.temperature,
            name="Temperature Sensor",
            pen=pen,
            symbol="+",
            symbolSize=15,
            symbolBrush="b",
        )
        # Add a timer to simulate new temperature measurements
        self.timer = QTimer()
        self.timer.setInterval(300)
        self.timer.timeout.connect(self.update_plot)
        self.timer.start()

    def update_plot(self):
        self.time = self.time[1:]
        self.time.append(self.time[-1] + 1)
        self.temperature = self.temperature[1:]
        self.temperature.append(randint(20, 40))
        self.line.setData(self.time, self.temperature)

app = QtWidgets.QApplication([])
main = MainWindow()
main.show()
app.exec()

The first step to creating a dynamic plot is to get a reference to the plot line. In this example, we've used a QTimer object to set the measuring interval. We've connected the update_plot() method with the timer's timeout signal.

The`update_plot() method does the work of updating the data in every interval. If you run the app, then you will see a plot with random data scrolling to the left:

The time scale in the x-axis changes as the stream of data provides new values. You can replace the random data with your own real data. You can take the data from a live sensor readout, API, or from any other stream of data. PyQtGraph is performant enough to support multiple simultaneous dynamic plots using this technique.

Conclusion

In this tutorial, you've learned how to draw basic plots with PyQtGraph and customize plot components, such as lines, markers, titles, axis labels, and more. You now know how to create interactive, real-time data visualizations in your PyQt6 applications using PyQtGraph's PlotWidget.

For a complete overview of PyQtGraph methods and capabilities, see the PyQtGraph documentation. The PyQtGraph repository on Github also has a complete set of plot examples.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Plotting With Matplotlib and PyQt6 — Create PyQt6 plots with the popular Python plotting library

2022-08-04T07:01:00+00:00

In a previous tutorial we covered plotting in PyQt6 using PyQtGraph. PyQtGraph uses the Qt vector-based QGraphicsScene to draw plots and provides a great interface for interactive and high performance plotting.

However, there is another plotting library for Python which is used far more widely, and which offers a richer assortment of plots — Matplotlib. If you're migrating an existing data analysis tool to a Python GUI, or if you simply want to have access to the array of plot abilities that Matplotlib offers, then you'll want to know how to include Matplotlib plots within your application.

In this tutorial we'll cover how to embed Matplotlib plots in your PyQt applications

Many other Python libraries — such as seaborn and pandas— make use of the Matplotlib backend for plotting. These plots can be embedded in PyQt6 in the same way shown here, and the reference to the axes passed when plotting. There is a pandas example at the end of this tutorial.

Installing Matplotlib

The following examples assume you have Matplotlib installed. If not you can install it as normal using Pip, with the following —

pip install matplotlib

A Simple Example

The following minimal example sets up a Matplotlib canvas FigureCanvasQTAgg which creates the Figure and adds a single set of axes to it. This canvas object is also a QWidget and so can be embedded straight into an application as any other Qt widget.

python

import os
import sys

os.environ["QT_API"] = "PyQt6"

from PyQt6 import QtCore, QtWidgets
from matplotlib.backends.backend_qtagg import FigureCanvas
from matplotlib.figure import Figure


class MplCanvas(FigureCanvas):

    def __init__(self, parent=None, width=5, height=4, dpi=100):
        fig = Figure(figsize=(width, height), dpi=dpi)
        self.axes = fig.add_subplot(111)
        super().__init__(fig)


class MainWindow(QtWidgets.QMainWindow):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        # Create the maptlotlib FigureCanvas object,
        # which defines a single set of axes as self.axes.
        sc = MplCanvas(self, width=5, height=4, dpi=100)
        sc.axes.plot([0,1,2,3,4], [10,1,20,3,40])
        self.setCentralWidget(sc)

        self.show()


app = QtWidgets.QApplication(sys.argv)
w = MainWindow()
app.exec()

In this case we're adding our MplCanvas widget as the central widget on the window with .setCentralWidget(). This means it will take up the entirety of the window and resize together with it. The plotted data [0,1,2,3,4], [10,1,20,3,40] is provided as two lists of numbers (x and y respectively) as required by the .plot method.

Basic plot with embedded Matplotlib

Plot Controls

Plots from Matplotlib displayed in PyQt6 are actually rendered as simple (bitmap) images by the Agg backend. The FigureCanvasQTAgg class wraps this backend and displays the resulting image on a Qt widget. The effect of this architecture is that Qt is unaware of the positions of lines and other plot elements — only the x, y coordinates of any clicks and mouse movements over the widget.

However, support for handling Qt mouse events and transforming them into interactions on the plot is built into Matplotlib. This can be controlled through a custom toolbar which can be added to your applications alongside the plot. In this section we'll look at adding these controls so we can zoom, pan and get data from embedded Matplotlib plots.

The complete code, importing the toolbar widget NavigationToolbar2QT and adding it to the interface within a QVBoxLayout, is shown below —

python

import os
import sys

os.environ["QT_API"] = "PyQt6"

from PyQt6 import QtCore, QtGui, QtWidgets

from matplotlib.backends.backend_qtagg import FigureCanvas
from matplotlib.backends.backend_qtagg import NavigationToolbar2QT as NavigationToolbar
from matplotlib.figure import Figure


class MplCanvas(FigureCanvasQTAgg):

    def __init__(self, parent=None, width=5, height=4, dpi=100):
        fig = Figure(figsize=(width, height), dpi=dpi)
        self.axes = fig.add_subplot(111)
        super().__init__(fig)


class MainWindow(QtWidgets.QMainWindow):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        sc = MplCanvas(self, width=5, height=4, dpi=100)
        sc.axes.plot([0,1,2,3,4], [10,1,20,3,40])

        # Create toolbar, passing canvas as first parament, parent (self, the MainWindow) as second.
        toolbar = NavigationToolbar(sc, self)

        layout = QtWidgets.QVBoxLayout()
        layout.addWidget(toolbar)
        layout.addWidget(sc)

        # Create a placeholder widget to hold our toolbar and canvas.
        widget = QtWidgets.QWidget()
        widget.setLayout(layout)
        self.setCentralWidget(widget)

        self.show()


app = QtWidgets.QApplication(sys.argv)
w = MainWindow()
app.exec()

We'll step through the changes.

First we import the toolbar widget from matplotlib.backends.backend_qt5agg.NavigationToolbar2QT renaming it with the simpler name NavigationToolbar. We create an instance of the toolbar by calling NavigationToolbar with two parameters, first the canvas object sc and then the parent for the toolbar, in this case our MainWindow object self. Passing in the canvas links the created toolbar to it, allowing it to be controlled. The resulting toolbar object is stored in the variable toolbar.

We need to add two widgets to the window, one above the other, so we use a QVBoxLayout. First we add our toolbar widget toolbar and then the canvas widget sc to this layout. Finally, we set this layout onto our simple widget layout container which is set as the central widget for the window.

Running the above code will produce the following window layout, showing the plot at the bottom and the controls on top as a toolbar.

Matplotlib plot with Toolbar

The buttons provided by NavigationToolbar2QT allow the following actions —

Home, Back/Forward, Pan & Zoom which are used to navigate through the plots. The Back/Forward buttons can step backwards and forwards through navigation steps, for example zooming in and then clicking Back will return to the previous zoom. Home returns to the initial state of the plot.
Plot margin/position configuration which can adjust the plot within the window.
Axis/curve style editor, where you can modify plot titles and axes scales, along with setting plot line colours and line styles. The colour selection uses the platform-default colour picker, allowing any available colours to be selected.
Save, to save the resulting figure as an image (all Matplotlib supported formats).

A few of these configuration settings are shown below.

Matplotlib figure options

Matplotlib curves figure options

For more information on navigating and configuring Matplotlib plots, take a look at the official Matplotlib toolbar documentation.

Updating Plots

Quite often in applications you'll want to update the data shown in plots, whether in response to input from the user or updated data from an API. There are two ways to update plots in Matplotlib, either

clearing and redrawing the canvas (simpler, but slower) or,
by keeping a reference to the plotted line and updating the data.

If performance is important to your app it is recommended you do the latter, but the first is simpler.

Clear and Redraw

We start with the simple clear-and-redraw method first below —

python

import sys
import os
import random

os.environ["QT_API"] = "PyQt6"

from PyQt6 import QtCore, QtWidgets
from matplotlib.backends.backend_qtagg import FigureCanvas
from matplotlib.figure import Figure


class MplCanvas(FigureCanvas):

    def __init__(self, parent=None, width=5, height=4, dpi=100):
        fig = Figure(figsize=(width, height), dpi=dpi)
        self.axes = fig.add_subplot(111)
        super().__init__(fig)


class MainWindow(QtWidgets.QMainWindow):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.canvas = MplCanvas(self, width=5, height=4, dpi=100)
        self.setCentralWidget(self.canvas)

        n_data = 50
        self.xdata = list(range(n_data))
        self.ydata = [random.randint(0, 10) for i in range(n_data)]
        self.update_plot()

        self.show()

        # Setup a timer to trigger the redraw by calling update_plot.
        self.timer = QtCore.QTimer()
        self.timer.setInterval(100)
        self.timer.timeout.connect(self.update_plot)
        self.timer.start()

    def update_plot(self):
        # Drop off the first y element, append a new one.
        self.ydata = self.ydata[1:] + [random.randint(0, 10)]
        self.canvas.axes.cla()  # Clear the canvas.
        self.canvas.axes.plot(self.xdata, self.ydata, 'r')
        # Trigger the canvas to update and redraw.
        self.canvas.draw()


app = QtWidgets.QApplication(sys.argv)
w = MainWindow()
app.exec()

In this example we've moved the plotting to a update_plot method to keep it self-contained. In this method we take our ydata array and drop off the first value with [1:] then append a new random integer between 0 and 10. This has the effect of scrolling the data to the left.

To redraw we simply call axes.cla() to clear the axes (the entire canvas) and the axes.plot(…) to re-plot the data, including the updated values. The resulting canvas is then redrawn to the widget by calling canvas.draw().

The update_plot method is called every 100 msec using a QTimer. The clear-and-refresh method is fast enough to keep a plot updated at this rate, but as we'll see shortly, falters as the speed increases.

In-place Redraw

The changes required to update the plotted lines in-place are fairly minimal, requiring only an addition variable to store and retrieve the reference to the plotted line. The updated MainWindow code is shown below.

python

class MainWindow(QtWidgets.QMainWindow):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.canvas = MplCanvas(self, width=5, height=4, dpi=100)
        self.setCentralWidget(self.canvas)

        n_data = 50
        self.xdata = list(range(n_data))
        self.ydata = [random.randint(0, 10) for i in range(n_data)]

        # We need to store a reference to the plotted line
        # somewhere, so we can apply the new data to it.
        self._plot_ref = None
        self.update_plot()

        self.show()

        # Setup a timer to trigger the redraw by calling update_plot.
        self.timer = QtCore.QTimer()
        self.timer.setInterval(100)
        self.timer.timeout.connect(self.update_plot)
        self.timer.start()

    def update_plot(self):
        # Drop off the first y element, append a new one.
        self.ydata = self.ydata[1:] + [random.randint(0, 10)]

        # Note: we no longer need to clear the axis.
        if self._plot_ref is None:
            # First time we have no plot reference, so do a normal plot.
            # .plot returns a list of line <reference>s, as we're
            # only getting one we can take the first element.
            plot_refs = self.canvas.axes.plot(self.xdata, self.ydata, 'r')
            self._plot_ref = plot_refs[0]
        else:
            # We have a reference, we can use it to update the data for that line.
            self._plot_ref.set_ydata(self.ydata)

        # Trigger the canvas to update and redraw.
        self.canvas.draw()

First, we need a variable to hold a reference to the plotted line we want to update, which here we're calling _plot_ref. We initialize self._plot_ref with None so we can check its value later to determine if the line has already been drawn — if the value is still None we have not yet drawn the line.

T> If you were drawing multiple lines you would probably want to use a list or dict data structure to store the multiple references and keep track of which is which.

Finally, we update the ydata data as we did before, rotating it to the left and appending a new random value. Then we either —

if self._plotref is None (i.e. we have not yet drawn the line) draw the line and store the reference in self._plot_ref, or
update the line in place by calling self._plot_ref.set_ydata(self.ydata)

We obtain a reference to the plotted when calling .plot. However .plot returns a list (to support cases where a single .plot call can draw more than one line). In our case we're only plotting a single line, so we simply want the first element in that list – a single Line2D object. To get this single value into our variable we can assign to a temporary variable plot_refs and then assign the first element to our self._plot_ref variable.

python

plot_refs = self.canvas.axes.plot(self.xdata, self.ydata, 'r')
self._plot_ref = plot_refs[0]

You could also use tuple-unpacking, picking off the first (and only) element in the list with —

python

self._plot_ref, = self.canvas.axes.plot(self.xdata, self.ydata, 'r')

If you run the resulting code, there will be no noticeable difference in performance between this and the previous method at this speed. However if you attempt to update the plot faster (e.g. down to every 10 msec) you'll start to notice that clearing the plot and re-drawing takes longer, and the updates do not keep up with the timer. We can compare the two versions below —

Both using 100 msec timer, clear-and-redraw on the left, update-in-place on the right.

Both using 10 msec timer, clear-and-redraw on the left, update-in-place on the right.

Whether this performance difference is enough to matter in your application depends on what you're building, and should be weighed against the added complication of keeping and managing the references to plotted lines.

Embedding Plots from Pandas

Pandas is a Python package focused on working with table (data frames) and series data structures, which is particularly useful for data analysis workflows. It comes with built-in support for plotting with Matplotlib and here we'll take a quick look at how to embed these plots into PyQt6. With this you will be able to start building PyQt6 data-analysis applications built around Pandas.

The examples in this section require Pandas to be installed. If you don't already have it, you can install it using Pip:

pip install pandas

Pandas plotting functions are directly accessible from the DataFrame objects. The function signature is quite complex, giving a lot of options to control how the plots will be drawn.

python

DataFrame.plot(
    x=None, y=None, kind='line', ax=None, subplots=False,
    sharex=None, sharey=False, layout=None, figsize=None,
    use_index=True, title=None, grid=None, legend=True, style=None,
    logx=False, logy=False, loglog=False, xticks=None, yticks=None,
    xlim=None, ylim=None, rot=None, fontsize=None, colormap=None,
    table=False, yerr=None, xerr=None, secondary_y=False,
    sort_columns=False, **kwargs
)

The parameter we're most interested in is ax which allows us to pass in our own matplotlib.Axes instance on which Pandas will plot the DataFrame.

python

import os
import sys

os.environ["QT_API"] = "PyQt6"


from PyQt6 import QtCore, QtWidgets

from matplotlib.backends.backend_qtagg import FigureCanvas
from matplotlib.figure import Figure

import pandas as pd


class MplCanvas(FigureCanvasQTAgg):

    def __init__(self, parent=None, width=5, height=4, dpi=100):
        fig = Figure(figsize=(width, height), dpi=dpi)
        self.axes = fig.add_subplot(111)
        super().__init__(fig)


class MainWindow(QtWidgets.QMainWindow):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        # Create the maptlotlib FigureCanvas object,
        # which defines a single set of axes as self.axes.
        sc = MplCanvas(self, width=5, height=4, dpi=100)

        # Create our pandas DataFrame with some simple
        # data and headers.
        df = pd.DataFrame([
           [0, 10], [5, 15], [2, 20], [15, 25], [4, 10],
        ], columns=['A', 'B'])

        # plot the pandas DataFrame, passing in the
        # matplotlib Canvas axes.
        df.plot(ax=sc.axes)

        self.setCentralWidget(sc)
        self.show()


app = QtWidgets.QApplication(sys.argv)
w = MainWindow()
app.exec()

The key step here is passing the canvas axes in when calling the plot method on the DataFrame on the line df.plot(ax=sc.axes). You can use this same pattern to update the plot any time, although bear in mind that Pandas clears and redraws the entire canvas, meaning that it is not ideal for high performance plotting.

The resulting plot generated through Pandas is shown below —

Pandas plot embedded in PyQt6

Just as before, you can add the Matplotlib toolbar and control support to plots generated using Pandas, allowing you to zoom/pan and modify them live. The following code combines our earlier toolbar example with the Pandas example.

python

import os
import sys

os.environ["QT_API"] = "PyQt6"

from PyQt6 import QtCore, QtWidgets

from matplotlib.backends.backend_qtagg import FigureCanvas
from matplotlib.backends.backend_qtagg import NavigationToolbar2QT as NavigationToolbar
from matplotlib.figure import Figure

import pandas as pd


class MplCanvas(FigureCanvasQTAgg):

    def __init__(self, parent=None, width=5, height=4, dpi=100):
        fig = Figure(figsize=(width, height), dpi=dpi)
        self.axes = fig.add_subplot(111)
        super().__init__(fig)


class MainWindow(QtWidgets.QMainWindow):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        # Create the maptlotlib FigureCanvas object,
        # which defines a single set of axes as self.axes.
        sc = MplCanvas(self, width=5, height=4, dpi=100)

        # Create our pandas DataFrame with some simple
        # data and headers.
        df = pd.DataFrame([
           [0, 10], [5, 15], [2, 20], [15, 25], [4, 10],
        ], columns=['A', 'B'])

        # plot the pandas DataFrame, passing in the
        # matplotlib Canvas axes.
        df.plot(ax=sc.axes)

        # Create toolbar, passing canvas as first parament, parent (self, the MainWindow) as second.
        toolbar = NavigationToolbar(sc, self)

        layout = QtWidgets.QVBoxLayout()
        layout.addWidget(toolbar)
        layout.addWidget(sc)

        # Create a placeholder widget to hold our toolbar and canvas.
        widget = QtWidgets.QWidget()
        widget.setLayout(layout)
        self.setCentralWidget(widget)
        self.show()


app = QtWidgets.QApplication(sys.argv)
w = MainWindow()
app.exec()

Running this you should see the following window, showing a Pandas plot embedded in PyQt6 alongside the Matplotlib toolbar.

Pandas plot with Matplotlib toolbar

What's Next

In this tutorial we looked at how you can embed Matplotlib plots in your PyQt6 applications. Being able to use Matplotlib plots in your applications allows you to create custom data analysis and visualization tools from Python.

Matplotlib is a huge library and too big to cover in detail here. If you're not familiar with Matplotlib plotting and want to give it a try, take a look at the documentation and example plots to see what is possible. If you are familiar with it you should now be able to put those skills to work in your PyQt6 apps!

For a more in-depth guide to building complete applications with PyQt6, take a look at our PyQt6 tutorial. You might also want to explore how to create your first app with PyQt6 to get started with the fundamentals.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Plotting With Matplotlib and PySide6 — Create PySide6 plots with the popular Python plotting library

2022-07-11T21:01:00+00:00

In a previous tutorial we covered plotting in PySide using PyQtGraph. PyQtGraph uses the Qt vector-based QGraphicsScene to draw plots and provides a great interface for interactive and high performance plotting.

In this tutorial we'll cover how to embed Matplotlib plots in your PySide6 applications

Many other Python libraries — such as seaborn and pandas— make use of the Matplotlib backend for plotting. These plots can be embedded in PySide in the same way shown here, and the reference to the axes passed when plotting. There is a pandas example at the end of this tutorial.

Installing Matplotlib

The following examples assume you have Matplotlib installed. If not you can install it as normal using Pip, with the following —

pip install matplotlib

A Simple Example

python

import os
import sys

os.environ["QT_API"] = "PySide6"

from PySide6.QtWidgets import QMainWindow, QApplication

from matplotlib.backends.backend_qtagg import FigureCanvas
from matplotlib.figure import Figure


class MplCanvas(FigureCanvas):

    def __init__(self, parent=None, width=5, height=4, dpi=100):
        fig = Figure(figsize=(width, height), dpi=dpi)
        self.axes = fig.add_subplot(111)
        super().__init__(fig)


class MainWindow(QMainWindow):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        # Create the maptlotlib FigureCanvas object,
        # which defines a single set of axes as self.axes.
        sc = MplCanvas(self, width=5, height=4, dpi=100)
        sc.axes.plot([0,1,2,3,4], [10,1,20,3,40])
        self.setCentralWidget(sc)

        self.show()


app = QApplication(sys.argv)
w = MainWindow()
app.exec()

Basic plot with embedded Matplotlib

Plot Controls

Plots from Matplotlib displayed in PySide are actually rendered as simple (bitmap) images by the Agg backend. The FigureCanvasQTAgg class wraps this backend and displays the resulting image on a Qt widget. The effect of this architecture is that Qt is unaware of the positions of lines and other plot elements — only the x, y coordinates of any clicks and mouse movements over the widget.

The complete code, importing the toolbar widget NavigationToolbar2QT and adding it to the interface within a QVBoxLayout, is shown below —

python

import os
import sys

os.environ["QT_API"] = "PySide6"

from PySide6.QtWidgets import QMainWindow, QVBoxLayout, QWidget, QApplication

from matplotlib.backends.backend_qtagg import FigureCanvas
from matplotlib.backends.backend_qtagg import NavigationToolbar2QT as NavigationToolbar
from matplotlib.figure import Figure


class MplCanvas(FigureCanvas):

    def __init__(self, parent=None, width=5, height=4, dpi=100):
        fig = Figure(figsize=(width, height), dpi=dpi)
        self.axes = fig.add_subplot(111)
        super().__init__(fig)


class MainWindow(QMainWindow):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        sc = MplCanvas(self, width=5, height=4, dpi=100)
        sc.axes.plot([0,1,2,3,4], [10,1,20,3,40])

        # Create toolbar, passing canvas as first parament, parent (self, the MainWindow) as second.
        toolbar = NavigationToolbar(sc, self)

        layout = QVBoxLayout()
        layout.addWidget(toolbar)
        layout.addWidget(sc)

        # Create a placeholder widget to hold our toolbar and canvas.
        widget = QWidget()
        widget.setLayout(layout)
        self.setCentralWidget(widget)

        self.show()


app = QApplication(sys.argv)
w = MainWindow()
app.exec()

We'll step through the changes.

Running the above code will produce the following window layout, showing the plot at the bottom and the controls on top as a toolbar.

Matplotlib plot with Toolbar

The buttons provided by NavigationToolbar2QT allow the following actions —

Home, Back/Forward, Pan & Zoom which are used to navigate through the plots. The Back/Forward buttons can step backwards and forwards through navigation steps, for example zooming in and then clicking Back will return to the previous zoom. Home returns to the initial state of the plot.
Plot margin/position configuration which can adjust the plot within the window.
Axis/curve style editor, where you can modify plot titles and axes scales, along with setting plot line colours and line styles. The colour selection uses the platform-default colour picker, allowing any available colours to be selected.
Save, to save the resulting figure as an image (all Matplotlib supported formats).

A few of these configuration settings are shown below.

Matplotlib figure options

Matplotlib curves figure options

For more information on navigating and configuring Matplotlib plots, take a look at the official Matplotlib toolbar documentation.

Updating Plots

clearing and redrawing the canvas (simpler, but slower) or,
by keeping a reference to the plotted line and updating the data.

If performance is important to your app it is recommended you do the latter, but the first is simpler.

Clear and Redraw

We start with the simple clear-and-redraw method first below —

python

import os
import sys
import random

os.environ["QT_API"] = "PySide6"

from PySide6.QtWidgets import QMainWindow, QApplication
from PySide6.QtCore import QTimer

from matplotlib.backends.backend_qtagg import FigureCanvas
from matplotlib.figure import Figure


class MplCanvas(FigureCanvas):

    def __init__(self, parent=None, width=5, height=4, dpi=100):
        fig = Figure(figsize=(width, height), dpi=dpi)
        self.axes = fig.add_subplot(111)
        super().__init__(fig)


class MainWindow(QMainWindow):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.canvas = MplCanvas(self, width=5, height=4, dpi=100)
        self.setCentralWidget(self.canvas)

        n_data = 50
        self.xdata = list(range(n_data))
        self.ydata = [random.randint(0, 10) for i in range(n_data)]
        self.update_plot()

        self.show()

        # Setup a timer to trigger the redraw by calling update_plot.
        self.timer = QTimer()
        self.timer.setInterval(100)
        self.timer.timeout.connect(self.update_plot)
        self.timer.start()

    def update_plot(self):
        # Drop off the first y element, append a new one.
        self.ydata = self.ydata[1:] + [random.randint(0, 10)]
        self.canvas.axes.cla()  # Clear the canvas.
        self.canvas.axes.plot(self.xdata, self.ydata, 'r')
        # Trigger the canvas to update and redraw.
        self.canvas.draw()


app = QApplication(sys.argv)
w = MainWindow()
app.exec()

The update_plot method is called every 100 msec using a QTimer. The clear-and-refresh method is fast enough to keep a plot updated at this rate, but as we'll see shortly, falters as the speed increases.

In-place Redraw

python

class MainWindow(QMainWindow):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.canvas = MplCanvas(self, width=5, height=4, dpi=100)
        self.setCentralWidget(self.canvas)

        n_data = 50
        self.xdata = list(range(n_data))
        self.ydata = [random.randint(0, 10) for i in range(n_data)]

        # We need to store a reference to the plotted line
        # somewhere, so we can apply the new data to it.
        self._plot_ref = None
        self.update_plot()

        self.show()

        # Setup a timer to trigger the redraw by calling update_plot.
        self.timer = QTimer()
        self.timer.setInterval(100)
        self.timer.timeout.connect(self.update_plot)
        self.timer.start()

    def update_plot(self):
        # Drop off the first y element, append a new one.
        self.ydata = self.ydata[1:] + [random.randint(0, 10)]

        # Note: we no longer need to clear the axis.
        if self._plot_ref is None:
            # First time we have no plot reference, so do a normal plot.
            # .plot returns a list of line <reference>s, as we're
            # only getting one we can take the first element.
            plot_refs = self.canvas.axes.plot(self.xdata, self.ydata, 'r')
            self._plot_ref = plot_refs[0]
        else:
            # We have a reference, we can use it to update the data for that line.
            self._plot_ref.set_ydata(self.ydata)

        # Trigger the canvas to update and redraw.
        self.canvas.draw()

T> If you were drawing multiple lines you would probably want to use a list or dict data structure to store the multiple references and keep track of which is which.

Finally, we update the ydata data as we did before, rotating it to the left and appending a new random value. Then we either —

if self._plotref is None (i.e. we have not yet drawn the line) draw the line and store the reference in self._plot_ref, or
update the line in place by calling self._plot_ref.set_ydata(self.ydata)

python

plot_refs = self.canvas.axes.plot(self.xdata, self.ydata, 'r')
self._plot_ref = plot_refs[0]

You could also use tuple-unpacking, picking off the first (and only) element in the list with —

python

self._plot_ref, = self.canvas.axes.plot(self.xdata, self.ydata, 'r')

Both using 100 msec timer, clear-and-redraw on the left, update-in-place on the right.

Both using 10 msec timer, clear-and-redraw on the left, update-in-place on the right.

Embedding Plots from Pandas

Pandas is a Python package focused on working with table (data frames) and series data structures, which is particularly useful for data analysis workflows. It comes with built-in support for plotting with Matplotlib and here we'll take a quick look at how to embed these plots into PySide. With this you will be able to start building PySide data-analysis applications built around Pandas.

The examples in this section require Pandas to be installed. If you don't already have it, you can install it using Pip:

pip install pandas

Pandas plotting functions are directly accessible from the DataFrame objects. The function signature is quite complex, giving a lot of options to control how the plots will be drawn.

python

DataFrame.plot(
    x=None, y=None, kind='line', ax=None, subplots=False,
    sharex=None, sharey=False, layout=None, figsize=None,
    use_index=True, title=None, grid=None, legend=True, style=None,
    logx=False, logy=False, loglog=False, xticks=None, yticks=None,
    xlim=None, ylim=None, rot=None, fontsize=None, colormap=None,
    table=False, yerr=None, xerr=None, secondary_y=False,
    sort_columns=False, **kwargs
)

The parameter we're most interested in is ax which allows us to pass in our own matplotlib.Axes instance on which Pandas will plot the DataFrame.

python

import os
import sys

os.environ["QT_API"] = "PySide6"


from PySide6.QtWidgets import QMainWindow, QApplication

from matplotlib.backends.backend_qtagg import FigureCanvas
from matplotlib.figure import Figure

import pandas as pd


class MplCanvas(FigureCanvas):

    def __init__(self, parent=None, width=5, height=4, dpi=100):
        fig = Figure(figsize=(width, height), dpi=dpi)
        self.axes = fig.add_subplot(111)
        super().__init__(fig)


class MainWindow(QMainWindow):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        # Create the maptlotlib FigureCanvas object,
        # which defines a single set of axes as self.axes.
        sc = MplCanvas(self, width=5, height=4, dpi=100)

        # Create our pandas DataFrame with some simple
        # data and headers.
        df = pd.DataFrame([
           [0, 10], [5, 15], [2, 20], [15, 25], [4, 10],
        ], columns=['A', 'B'])

        # plot the pandas DataFrame, passing in the
        # matplotlib Canvas axes.
        df.plot(ax=sc.axes)

        self.setCentralWidget(sc)
        self.show()


app = QApplication(sys.argv)
w = MainWindow()
app.exec()

The resulting plot generated through Pandas is shown below —

Pandas plot embedded in PySide

python

import os
import sys

os.environ["QT_API"] = "PySide6"

from PySide6.QtWidgets import QMainWindow, QApplication, QVBoxLayout, QWidget

from matplotlib.backends.backend_qtagg import FigureCanvas
from matplotlib.backends.backend_qtagg import NavigationToolbar2QT as NavigationToolbar
from matplotlib.figure import Figure

import pandas as pd


class MplCanvas(FigureCanvas):

    def __init__(self, parent=None, width=5, height=4, dpi=100):
        fig = Figure(figsize=(width, height), dpi=dpi)
        self.axes = fig.add_subplot(111)
        super().__init__(fig)


class MainWindow(QMainWindow):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        # Create the maptlotlib FigureCanvas object,
        # which defines a single set of axes as self.axes.
        sc = MplCanvas(self, width=5, height=4, dpi=100)

        # Create our pandas DataFrame with some simple
        # data and headers.
        df = pd.DataFrame([
           [0, 10], [5, 15], [2, 20], [15, 25], [4, 10],
        ], columns=['A', 'B'])

        # plot the pandas DataFrame, passing in the
        # matplotlib Canvas axes.
        df.plot(ax=sc.axes)

        # Create toolbar, passing canvas as first parament, parent (self, the MainWindow) as second.
        toolbar = NavigationToolbar(sc, self)

        layout = QVBoxLayout()
        layout.addWidget(toolbar)
        layout.addWidget(sc)

        # Create a placeholder widget to hold our toolbar and canvas.
        widget = QWidget()
        widget.setLayout(layout)
        self.setCentralWidget(widget)
        self.show()


app = QApplication(sys.argv)
w = MainWindow()
app.exec()

Running this you should see the following window, showing a Pandas plot embedded in PySide alongside the Matplotlib toolbar.

Pandas plot with Matplotlib toolbar

What's Next

In this tutorial we looked at how you can embed Matplotlib plots in your PySide applications. Being able to use Matplotlib plots in your applications allows you to create custom data analysis and visualization tools from Python.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Plotting With PyQtGraph and PySide6 — Create custom plots in PySide6 with PyQtGraph

2022-07-01T13:10:00+00:00

One of the major strengths of Python is in exploratory data science and visualization, using tools such as Pandas, numpy, sklearn for data analysis and matplotlib plotting. Building GUI applications with PySide6 gives you access to all these Python tools directly from within your app, allowing you to build complex data-driven apps and interactive dashboards.

While it is possible to embed matplotlib plots in PySide6 the experience does not feel entirely native. For simple and highly interactive plots you may want to consider using PyQtGraph instead. PyQtGraph is built on top of Qt's native QGraphicsScene giving better drawing performance, particularly for live data, as well as providing interactivity and the ability to easily customize plots with Qt graphics widgets.

In this tutorial we'll walk through the first steps of creating a plot widget with PyQtGraph and then demonstrate plot customization using line colours, line type, axis labels, background colour and plotting multiple lines.

Installing PyQtGraph

To be able to use PyQtGraph with PySide6 you first need to install the package to your Python environment. You can do this as normal using pip.

pip install pyqtgraph

Once the installation is complete you should be able to import the module as normal.

Creating a PyQtGraph PlotWidget

In PyQtGraph all plots are created using the PlotWidget widget. This widget provides a contained canvas on which plots of any type can be added and configured. Under the hood, this plot widget uses Qt native QGraphicsScene meaning it fast and efficient yet simple to integrate with the rest of your app. You can create a PlotWidget as for any other widget.

The basic template app, with a single PlotWidget in a QMainWindow is shown below.

In the following examples we'll create the PyQtGraph widget in code. Want to know how to embed PyQtGraph when using Qt Designer? See Embedding custom widgets from Qt Designer

python

from PySide6.QtWidgets import QApplication, QMainWindow
import pyqtgraph as pg
import sys

class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()

        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)

        hour = [1,2,3,4,5,6,7,8,9,10]
        temperature = [30,32,34,32,33,31,29,32,35,45]

        # plot data: x, y values
        self.plot_graph.plot(hour, temperature)


app = QApplication(sys.argv)
w = MainWindow()
w.show()
app.exec()

In all our examples below we import PyQtGraph using import pyqtgraph as pg. This is a common convention in PyQtGraph examples to keep things tidy & reduce typing. You can import and use it as import pyqtgraph if you prefer.

The custom PyQtGraph widget showing dummy data.

The default plot style of PyQtGraph is quite bare — a black background with a thin (barely visible) white line. In the next section we'll look at what options we have available to us in PyQtGraph to improve the appearance and usability of our plots.

Styling PyQtGraph Plots

PyQtGraph uses Qt's QGraphicsScene to render the graphs. This gives us access to all the standard Qt line and shape styling options for use in plots. However, PyQtGraph provides an API for using these to draw plots and manage the plot canvas.

Below we'll go through the most common styling features you'll need to create and customize your own plots.

Background Colour

Beginning with the app skeleton above, we can change the background colour by calling .setBackground on our PlotWidget instance (in self.plot_graph). The code below will set the background to white, by passing in the string 'w'.

python

self.plot_graph.setBackground('w')

You can set (and update) the background colour of the plot at any time.

python

from PySide6.QtWidgets import QMainWindow, QApplication
import pyqtgraph as pg
import sys


class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()

        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)

        hour = [1,2,3,4,5,6,7,8,9,10]
        temperature = [30,32,34,32,33,31,29,32,35,45]

        self.plot_graph.setBackground('w')
        self.plot_graph.plot(hour, temperature)


app = QApplication(sys.argv)
main = MainWindow()
main.show()
app.exec()

Change PyQtGraph Plot Background to White

There are a number of simple colours available using single letters, based on the standard colours used in matplotlib. They're pretty unsurprising -- r is red, b is blue -- except that 'k' is used for black. In addition to these single letter codes, you can also set more complex colours using hex notation eg. #672922 as a string.

python

self.plot_graph.setBackground('#672922')         # hex

RGB and RGBA values can be passed in as a 3-tuple or 4-tuple respectively, using values 0-255.

python

self.plot_graph.setBackground((100,50,255))      # RGB each 0-255
self.plot_graph.setBackground((100,50,255,25))   # RGBA (A = alpha opacity)

Lastly, you can also specify colours using Qt's QColor type directly.

python

from PySide6 import QtGui  # Place this at the top of your file.
self.plot_graph.setBackground(QtGui.QColor(100,50,254,25))

This can be useful if you're using specific QColor objects elsewhere in your application, or to set your plot background to the default GUI background colour.

python

color = self.palette().color(QtGui.QPalette.Window)  # Get the default window background,
self.plot_graph.setBackground(color)

Line Colour, Width & Style

Lines in PyQtGraph are drawn using standard Qt QPen types. This gives you the same full control over line drawing as you would have in any other QGraphicsScene drawing. To use a pen to plot a line, you simply create a new QPen instance and pass it into the plot method.

Below we create a QPen object, passing in a 3-tuple of int values specifying an RGB value (of full red). We could also define this by passing 'r', or a QColor object. Then we pass this into plot with the pen parameter.

python

pen = pg.mkPen(color=(255, 0, 0))
self.plot_graph.plot(hour, temperature, pen=pen)

The complete code is shown below.

python

from PySide6.QtWidgets import QApplication, QMainWindow
import pyqtgraph as pg
import sys


class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()

        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)

        hour = [1,2,3,4,5,6,7,8,9,10]
        temperature = [30,32,34,32,33,31,29,32,35,45]

        self.plot_graph.setBackground('w')

        pen = pg.mkPen(color=(255,  0,  0))
        self.plot_graph.plot(hour, temperature, pen=pen)


app = QApplication(sys.argv)
main = MainWindow()
main.show()
app.exec()

Changing Line Colour

By changing the QPen object we can change the appearance of the line, including both line width in pixels and style (dashed, dotted, etc.) using standard Qt line styles. For example, the following example creates a 15px width dashed line in red.

python

from PySide6 import QtCore  # Place this at the top of your file.
pen = pg.mkPen(color=(255, 0,  0), width=15, style=QtCore.Qt.DashLine)

The result is shown below, giving a 15px dashed red line.

Changing Line Width and Style

The standard Qt line styles can all be used, including Qt.SolidLine, Qt.DashLine, Qt.DotLine, Qt.DashDotLine and Qt.DashDotDotLine. Examples of each of these lines are shown in the image below, and you can read more in the Qt Documentation.

Qt Line Types

Line Markers (Symbols)

For many plots it can be helpful to place markers in addition or instead of lines on the plot. To draw a marker on the plot, pass the symbol to use as a marker when calling .plot as shown below.

python

self.plot_graph.plot(hour, temperature, symbol='+')

In addition to symbol you can also pass in symbolSize, symbolBrush and symbolPen parameters. The value passed as symbolBrush can be any colour, or QBrush type, while symbolPen can be passed any colour or a QPen instance. The pen is used to draw the outline of the shape, while brush is used for the fill.

For example the below code will give a blue cross marker of size 30, on a thick red line.

python

pen = pg.mkPen(color=(255, 0, 0), width=15, style=QtCore.Qt.DashLine)
self.plot_graph.plot(hour, temperature, pen=pen, symbol='+', symbolSize=30, symbolBrush=('b'))

Adding Symbols on Line

In addition to the + plot marker, PyQtGraph supports the following standard markers shown in the table below:

Character	Marker Shape
`"o"`	Circle
`"s"`	Square
`"t"`	Triangle
`"d"`	Diamond
`"+"`	Plus
`"t1"`	Triangle pointing upwards
`"t2"`	Triangle pointing right side
`"t3"`	Triangle pointing left side
`"p"`	Pentagon
`"h"`	Hexagon
`"star"`	Star
`"x"`	Cross
`"arrow_up"`	Arrow Up
`"arrow_right"`	Arrow Right
`"arrow_down"`	Arrow Down
`"arrow_left"`	Arrow Left
`"crosshair"`	Crosshair

Adding Plot Titles

Chart titles are important to provide context to what is shown on a given chart. In PyQtGraph you can add a main plot title using the setTitle() method on the PlotWidget, passing in your title string.

python

self.plot_graph.setTitle("Your Title Here")

You can apply text styles, including colours, font sizes and weights to your titles (and any other labels in PyQtGraph) by passing additional arguments. The available style arguments are shown below.

The code below sets the color to blue with a font size of 30px.

python

self.plot_graph.setTitle("Your Title Here", color="b", size="30pt")

You can also style your headers with HTML tag syntax if you prefer, although it's less readable.

python

self.plot_graph.setTitle("<span style=\"color:blue;font-size:30pt\">Your Title Here</span>")

Adding Chart Title

Adding Axis Labels

Similar to titles, we can use the setLabel() method to create our axis titles. This requires two parameters, position and text. The position can be any one of 'left,'right','top','bottom' which describe the position of the axis on which the text is placed. The 2nd parameter text is the text you want to use for the label.

You can pass additional style parameters into the method. These differ slightly than for the title, in that they need to be valid CSS name-value pairs. For example, the size is now font-size. Because the name font-size has a hyphen in it, you cannot pass it directly as a parameter, but must use the **dictionary method.

python

styles = {'color':'red', 'font-size':'20px'}
self.plot_graph.setLabel('left', 'Temperature (°C)', **styles)
self.plot_graph.setLabel('bottom', 'Hour (H)', **styles)

These also support HTML syntax for styling if you prefer.

python

self.plot_graph.setLabel('left', "<span style=\"color:red;font-size:20px\">Temperature (°C)</span>")
self.plot_graph.setLabel('bottom', "<span style=\"color:red;font-size:20px\">Hour (H)</span>")

Add Axis Labels

Adding a Legend

In addition to the axis and plot titles you will often want to show a legend identifying what a given line represents. This is particularly important when you start adding multiple lines to a plot. Adding a legend to a plot can be accomplished by calling .addLegend on the PlotWidget, however before this will work you need to provide a name for each line when calling .plot().

The example below assigns a name "Sensor 1" to the line we are plotting with .plot(). This name will be used to identify the line in the legend.

python

self.plot_graph.plot(hour, temperature, name = "Sensor 1",  pen = NewPen, symbol='+', symbolSize=30, symbolBrush=('b'))
self.plot_graph.addLegend()

Add Legend

The legend appears in the top left by default. If you would like to move it, you can easily drag and drop the legend elsewhere. You can also specify a default offset by passing a 2-tuple to the offset parameter when creating the legend.

Adding a Background Grid

Adding a background grid can make your plots easier to read, particularly when trying to compare relative x & y values against each other. You can turn on a background grid for your plot by calling .showGrid on your PlotWidget. You can toggle x and y grids independently.

The following with create the grid for both the X and Y axis.

python

self.plot_graph.showGrid(x=True, y=True)

Add Grid

Setting Axis Limits

Sometimes it can be useful to restrict the range of data which is visible on the plot, or to lock the axis to a consistent range regardless of the data input (e.g. a known min-max range). In PyQtGraph this can be done using the .setXRange() and .setYRange() methods. These force the plot to only show data within the specified ranges on each axis.

Below we set two ranges, one on each axis. The 1st argument is the minimum value and the 2nd is the maximum.

python

self.plot_graph.setXRange(5, 20)
self.plot_graph.setYRange(30, 40)

A optional padding argument causes the range to be set larger than specified by the specified fraction (this between 0.02 and 0.1 by default, depending on the size of the ViewBox). If you want to remove this padding entirely, pass 0.

python

self.plot_graph.setXRange(5, 20, padding=0)
self.plot_graph.setYRange(30, 40, padding=0)

The complete code so far is shown below:

python

from PySide6.QtWidgets import QApplication, QMainWindow
import pyqtgraph as pg
import sys


class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()

        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)

        hour = [1,2,3,4,5,6,7,8,9,10]
        temperature = [30,32,34,32,33,31,29,32,35,45]

        #Add Background colour to white
        self.plot_graph.setBackground('w')
        # Add Title
        self.plot_graph.setTitle("Your Title Here", color="b", size="30pt")
        # Add Axis Labels
        styles = {"color": "#f00", "font-size": "20px"}
        self.plot_graph.setLabel("left", "Temperature (°C)", **styles)
        self.plot_graph.setLabel("bottom", "Hour (H)", **styles)
        #Add legend
        self.plot_graph.addLegend()
        #Add grid
        self.plot_graph.showGrid(x=True, y=True)
        #Set Range
        self.plot_graph.setXRange(0, 10, padding=0)
        self.plot_graph.setYRange(20, 55, padding=0)

        pen = pg.mkPen(color=(255, 0, 0))
        self.plot_graph.plot(hour, temperature, name="Sensor 1",  pen=pen, symbol='+', symbolSize=30, symbolBrush=('b'))


app = QApplication(sys.argv)
main = MainWindow()
main.show()
app.exec()

Set Axis Range

Plotting Multiple Lines

It is common for plots to involve more than one line. In PyQtGraph this is as simple as calling .plot() multiple times on the same PlotWidget. In the following example we're going to plot two lines of similar data, using the same line styles, thicknesses etc. for each, but changing the line colour.

To simplify this we can create our own custom plot method on our MainWindow. This accepts x and y parameters to plot, the name of the line (for the legend) and a colour. We use the colour for both the line and marker colour.

python

    def plot(self, x, y, plotname, color):
        pen = pg.mkPen(color=color)
        self.plot_graph.plot(x, y, name=plotname, pen=pen, symbol='+', symbolSize=30, symbolBrush=(color))

To plot separate lines we'll create a new array called temperature_2 and populate it with random numbers similar to temperature (now temperature_1). Plotting these alongside each other allows us to compare them together.

Now, you can call plot function twice and this will generate 2 lines on the plot.

python

self.plot(hour, temperature_1, "Sensor1", 'r')
self.plot(hour, temperature_2, "Sensor2", 'b')

python

from PySide6.QtWidgets import QApplication, QMainWindow
import pyqtgraph as pg
import sys


class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()

        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)

        hour = [1,2,3,4,5,6,7,8,9,10]
        temperature_1 = [30,32,34,32,33,31,29,32,35,45]
        temperature_2 = [50,35,44,22,38,32,27,38,32,44]

        #Add Background colour to white
        self.plot_graph.setBackground('w')
        # Add Title
        self.plot_graph.setTitle("Your Title Here", color="b", size="30pt")
        # Add Axis Labels
        styles = {"color": "#f00", "font-size": "20px"}
        self.plot_graph.setLabel("left", "Temperature (°C)", **styles)
        self.plot_graph.setLabel("bottom", "Hour (H)", **styles)
        #Add legend
        self.plot_graph.addLegend()
        #Add grid
        self.plot_graph.showGrid(x=True, y=True)
        #Set Range
        self.plot_graph.setXRange(0, 10, padding=0)
        self.plot_graph.setYRange(20, 55, padding=0)

        self.plot(hour, temperature_1, "Sensor1", 'r')
        self.plot(hour, temperature_2, "Sensor2", 'b')

    def plot(self, x, y, plotname, color):
        pen = pg.mkPen(color=color)
        self.plot_graph.plot(x, y, name=plotname, pen=pen, symbol='+', symbolSize=30, symbolBrush=(color))


app = QApplication(sys.argv)
main = MainWindow()
main.show()
app.exec()

2 Line Graph

Play around with this function, customising your markers, line widths, colours and other parameters.

Clearing the Plot

Finally, sometimes you might want to clear and refresh the plot periodically. You can easily do that by calling .clear().

python

self.plot_graph.clear()

This will remove the lines from the plot but keep all other attributes the same.

Real-Time Plot Updates

While you can simply clear the plot and redraw all your elements again, this means Qt has to destroy and recreate all your QGraphicsScene objects. For small or simple plots this is probably not noticeable, but if you want to create high-performance streaming plots it is much better to update the data in place. PyQtGraph takes the new data and updates the plotted line to match without affecting any other elements in the plot.

To update a line we need a reference to the line object. This reference is returned when first creating the line using .plot and we can simply store this in a variable. Note that this is a reference to the line not to the plot.

python

my_line_ref = plot_graph.plot(x, y)

Once we have the reference, updating the plot is simply a case of calling .setData on the reference to apply the new data. In the example below we've taken our simple plot demo and expanded it to take a reference to the line.

python

from PySide6.QtWidgets import QApplication, QMainWindow
from PySide6.QtCore import QTimer
import pyqtgraph as pg
import sys
from random import randint

class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()

        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)

        self.x = list(range(100))  # 100 time points
        self.y = [randint(0,100) for _ in range(100)]  # 100 data points

        self.plot_graph.setBackground('w')

        pen = pg.mkPen(color=(255, 0, 0))
        self.data_line =  self.plot_graph.plot(self.x, self.y, pen=pen)



app = QApplication(sys.argv)
w = MainWindow()
w.show()
sys.exit(app.exec())

We're going to update our data every 50ms, although PyQtGraph can plot data much more quickly than this it can get hard to watch! To do this we define a Qt timer, and set it to call a custom method update_plot_data where we'll change the data. We define this timer in the __init__ block so it is automatically started. Add the following to the window class:

python

        # ... init continued ...
        self.timer = QTimer()
        self.timer.setInterval(50)
        self.timer.timeout.connect(self.update_plot_data)
        self.timer.start()

    def update_plot_data(self):

        self.x = self.x[1:]  # Remove the first y element.
        self.x.append(self.x[-1] + 1)  # Add a new value 1 higher than the last.

        self.y = self.y[1:]  # Remove the first
        self.y.append( randint(0,100))  # Add a new random value.

        self.data_line.setData(self.x, self.y)  # Update the data.

If you run the app you will see a plot with random data scrolling rapidly to the left, with the X values also updating and scrolling in time, as if streaming data. You can replace the random data with your own real data, taken for example from a live sensor readout or API. PyQtGraph is performant enough to support multiple simultaneous plots using this method.

The complete code is shown below.

python

from PySide6.QtWidgets import QApplication, QMainWindow
from PySide6.QtCore import QTimer
import pyqtgraph as pg
import sys
from random import randint

class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()

        self.plot_graph = pg.PlotWidget()
        self.setCentralWidget(self.plot_graph)

        self.x = list(range(100))  # 100 time points
        self.y = [randint(0,100) for _ in range(100)]  # 100 data points

        self.plot_graph.setBackground('w')

        pen = pg.mkPen(color=(255, 0, 0))
        self.data_line =  self.plot_graph.plot(self.x, self.y, pen=pen)

        self.timer = QTimer()
        self.timer.setInterval(50)
        self.timer.timeout.connect(self.update_plot_data)
        self.timer.start()

    def update_plot_data(self):

        self.x = self.x[1:]  # Remove the first y element.
        self.x.append(self.x[-1] + 1)  # Add a new value 1 higher than the last.

        self.y = self.y[1:]  # Remove the first
        self.y.append( randint(0,100))  # Add a new random value.

        self.data_line.setData(self.x, self.y)  # Update the data.

app = QApplication(sys.argv)
main = MainWindow()
main.show()
app.exec()

Conclusion

In this tutorial we've discovered how to use PyQtGraph to draw plots in PySide6 applications and customize lines, markers, titles, axis labels and legends. We also covered how to update plots in real time for live data visualization. For a complete overview of PyQtGraph methods and capabilities see the PyQtGraph Documentation & API Reference. The PyQtGraph repository on Github also has complete set of more complex example plots in Plotting.py (shown below).

PyQtGraph Repo Example (Plotting.py)

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Python GUIs - tutorials

Getting Started With Flet for GUI Development — Your First Steps With the Flet Library for Desktop and Web Python GUIs

What Is Flet? A Cross-Platform Python GUI Framework

Installing Flet

Writing Your First Flet GUI App

Exploring Flet Controls (Widgets)

Flet Button Controls

Input and Selection Controls

Navigation Controls

Information Display Controls

Dialogs, Alerts, and Panels

Laying Out Your GUI With Flet Layouts

Handling Events and Callbacks in Flet

Conclusion

Getting Started With NiceGUI for Web UI Development in Python — Your First Steps With the NiceGUI Library for Web UI Development

Installing NiceGUI

Writing Your First NiceGUI App in Python

Exploring NiceGUI Graphical Elements

Text Elements

Control Elements

Data Elements

Audiovisual Elements

Laying Out Pages in NiceGUI

Handling Events and Actions in NiceGUI

Conclusion

Getting Started With DearPyGui for GUI Development — Your First Steps With the DearPyGui Library for Desktop Python GUIs

What Is DearPyGui?

Installing DearPyGui

Writing Your First DearPyGui Application

Exploring DearPyGui Widgets

Laying Out Your DearPyGui Interface

Handling Events with DearPyGui Callbacks

Creating Plots and Charts with DearPyGui

Conclusion

Kivy's Complex Widgets — Learn How to Use Kivy's Complex UX Widgets in Your Apps

Writing an Outline Kivy App

Providing Option Selections With the Kivy Spinner Widget

Providing Options With the Kivy DropDown List Widget

Accessing Files With the Kivy FileChooser Widget

Building Quick Dialogs With the Kivy Popup Widget

Creating Contextual Popups With the Kivy Bubble Widget

Displaying Large Data Sets With the Kivy RecycleView Widget

Building Tabbed UIs With the Kivy TabbedPanel Widget

Allowing User Input With the Kivy VKeyboard Widget

Conclusion

Getting Started with Streamlit — Build your first Streamlit app and explore some basic features

Installing Streamlit

Adding Titles, Headings, and Paragraphs in Streamlit

Adding a Title

Adding Headings

Adding Paragraphs

Adding Interactive Buttons to a Streamlit App

Basic Button

Download Button

Radio Buttons for Options

Adding a Slider to Your Streamlit App

Adding a Dropdown Menu in Streamlit

Adding a Sidebar in Streamlit

Building a Simple Data Dashboard with Streamlit

Tkinter Widgets — A walkthrough of Tkinter's basic widgets

A Quick Demo

Label

Button

Checkbutton

Combobox

Listbox

Entry

Spinbox

Scale

Conclusion

Getting Started With PyCharm for Python GUI Development — The Python-Specific Integrated Development Environment

Install Python

Install PyCharm

Create a New PyQt6 Project in PyCharm

Get Familiar With PyCharm's Interface

Window Header

Editor

Sidebar and Tool Windows

Status Bar

Install PyQt6 in PyCharm

Providing Option Selections With the Kivy `Spinner` Widget

Providing Options With the Kivy `DropDown` List Widget

Accessing Files With the Kivy `FileChooser` Widget

Building Quick Dialogs With the Kivy `Popup` Widget

Creating Contextual Popups With the Kivy `Bubble` Widget

Displaying Large Data Sets With the Kivy `RecycleView` Widget

Building Tabbed UIs With the Kivy `TabbedPanel` Widget

Allowing User Input With the Kivy `VKeyboard` Widget

`Label`

`Button`

`Checkbutton`

`Combobox`

`Listbox`

`Entry`

`Spinbox`

`Scale`

Creating a Simple `QGraphicsScene`

Adding a `QGraphicsView` to a PySide6 Layout

Displaying a Logo With the Kivy `Image` Widget

Displaying Text With the Kivy `Label` Widget

Collecting Text Input Data With the Kivy `TextInput` Widget

Using the Kivy `CheckBox` Widget

Using the Kivy `ToggleButton` Widget

Using the Kivy `Switch` Widget

Creating a `Button` Widget in Kivy

Adding a `ProgressBar` Widget in Kivy

The Kivy `Video` Widget

The Kivy `Slider` Widget

Creating a Simple `QGraphicsScene`

Adding a `QGraphicsView` to a PyQt6 Layout

Create a Python Virtual Environment With `venv`