Building Desktop Applications with GTK 4 and Qt 6 — an open source book about writing desktop applications in Python, and the technologies around them: drawing, printing, multimedia, D-Bus, embedded web content, translation and packaging.
Read it online at https://python-desktop-handbook.majorsilence.com/, or download the PDF.
It began as PyGTK Notebook, one person's notes on PyGTK and GTK 2. That edition is in the git history; this one is rewritten from it.
Part I — GTK 4 with PyGObject — is complete, and targets the GNOME 50 stack: GTK 4.22, libadwaita 1.9, PyGObject 3.56, Wayland only. Part II, covering the same ground with Qt 6 and PySide6, is not written yet.
| Path | What it is |
|---|---|
_chapters/ |
The book. One Markdown file per chapter — this is the source of truth. |
images/, examples/ |
Figures and the runnable sample programs the text refers to. |
_layouts/, assets/, index.md, _config.yml |
The Jekyll site. |
tools/build-pdf.sh |
Builds the PDF from _chapters/ via pandoc + LaTeX. |
tools/smoke-test.py |
Starts every example and shuts it down again. |
examples/gtk4/testing/ |
The testing chapter's application and its pytest suite. |
tools/make-figures.sh |
Regenerates the figures that examples draw. |
tools/make-screenshots.py |
Regenerates the screenshots of the examples' windows. |
tools/lyx2md.py |
The one-shot LyX → Markdown migration, kept for reference. |
pygtk-notebook-latest.lyx |
The retired LyX source. No longer edited. |
Chapters are plain Markdown with a small amount of Jekyll front matter:
---
layout: chapter
title: "Cairo"
number: 3
---Add appendix: true for back matter and unnumbered: true for pages that
should not get a chapter number. Body headings start at ##; the # level is
generated from title.
Two conventions are worth knowing:
- Cross references are ordinary relative links —
[Glade 3](02-more-pygtk.html#sec-glade-3). The PDF build rewrites them into internal document anchors, so one form works in both outputs. - Image sizing uses a kramdown attribute list —
{: width="50%"}. The PDF build translates it to pandoc's syntax.
An image alone in a paragraph becomes a numbered figure in the PDF, with its alt text as the caption.
bundle install
make serve # http://127.0.0.1:4000Needs pandoc and a LaTeX installation:
sudo apt-get install pandoc texlive-xetex texlive-fonts-recommended texlive-latex-extra
make pdf # -> build/python-desktop-notebook.pdfThe PDF keeps the shape the LyX original had: book class, 10pt, two-sided,
20.95 × 27.31 cm paper, parts and numbered chapters with an appendix, a table of
contents and a list of figures.
Every listing in the book is a file under examples/, and every one of them is
started and shut down again on each build:
dbus-run-session -- xvfb-run -a python3 tools/smoke-test.py examples/gtk4It catches import errors, renamed methods, signals that no longer exist and anything that raises while the first window is built — including exceptions inside a signal handler, which GTK otherwise prints and swallows.
The testing chapter's example has a real pytest suite, and it runs on each build:
make testThat builds a --system-site-packages virtual environment, because PyGObject
comes from the distribution and a plain venv cannot see it.
Nothing in this book is a hand-taken screenshot. Illustrations that an example draws are regenerated by running it, and the pictures of windows are captured from the examples themselves:
make figures # Cairo output, and a page of a generated PDF
make screenshots # the examples' own windowsThe screenshots are rendered through each window's own GskRenderer, so they
need no window manager and work under Xvfb. tools/make-screenshots.py holds a
manifest saying which examples to capture, and can put a window into a more
interesting state first — filling in an entry, pressing a button, or running the
whole thing under a different language.
.github/workflows/pages.yml smoke-tests the examples, builds and validates the
packaging example with Meson, builds the PDF, builds the site, copies the PDF
into it, and deploys the result to GitHub Pages on every push to main. Enable
it under Settings → Pages → Build and deployment → GitHub Actions.
The site is served from python-desktop-handbook.majorsilence.com. For a
workflow deployment the domain is the one recorded in Settings → Pages →
Custom domain; the CNAME file keeps it if the repository ever goes back to
publishing from a branch.
Corrections, examples and modernization are all welcome — open an issue or a pull request.
Book text is licensed under CC BY-SA 4.0. Sample code is released under the MIT license.
Editions up to 0.13 released their text under CC BY-SA 3.0 and their sample code under the LGPL v3; copies distributed under those terms keep them.