Gtk4-tutorial: a beginner's C guide to GTK 4 built around one small editor

One running example carries the whole curriculum

ToshioCP/Gtk4-tutorial is a tutorial on writing C programs with the GTK library, aimed at beginners, with the contents deliberately limited to the basics. That constraint is what shapes it. Instead of covering the library by topic, the tutorial builds one application, a simple editor called tfe for Text File Editor, and introduces concepts as the editor needs them.

The README explains the naming too. Now that GTK 4 is widely used, GTK usually means GTK 4, so the tutorial says GTK except where the version has to be named explicitly.

The structure runs to 36 sections in three blocks. Sections 3 to 26 cover the basics with the tfe example, which is where the application shape comes from: GtkApplication and GtkApplicationWindow, widgets, strings and memory management, defining a final class, GtkBuilder and UI files, the build system, instance initialisation and destruction, GLib error handling, finishing the custom object implementation, file dialogs and the GIO asynchronous model, menus and actions, stateful actions, a UI file for menu and action entries, GtkPopoverMenuBar and GtkMenuButton, managing the application, creating TfeWindow, handling unsaved text, accelerators, CSS and Pango, GtkFontDialogButton with CSS updates, and GSettings.

Sections 27 to 30 cover GtkDrawingArea, then 31 covers drag and drop, and sections 32 to 36 cover the list model and the list view, including GtkListView, GtkGridView, GtkColumnView, GtkExpression and GtkSignalListItemFactory.

For a beginner, a working editor beats an inventory of widgets, because each concept arrives attached to a reason it exists.

The order is deliberate: GObject and actions before anything else

Reading the table of contents tells you the author's view of what a GTK programmer must understand first, and it is not the widget catalogue.

Section 8 is Defining a Final Class, section 11 is Instance Initialization and Destruction, and section 13 is Completing the custom object implementation. Those three sit before the first menubar, and they only make sense if you accept the object system underneath GTK. The README makes the same point from the other side: GObject is the base of GTK, so it is important for developers to understand it as well as GTK, and the author runs a separate GObject tutorial for that.

Actions come next, in sections 16, 17 and 18, covering menus and actions, stateful actions, and a UI file for menu and action entries. The application is managed in section 20, then the editor window is created in section 21 and unsaved text is handled in section 22.

The payoff of that ordering shows up in the later sections. CSS and Pango in section 24, the font dialog and CSS updates in section 25 and GSettings in section 26 all assume the reader can already navigate a codebase organised around custom objects and actions, so the sections build on each other rather than repeat each other.

A reader who arrives from another GUI toolkit will notice the emphasis on the application object and on declarative UI files. That is the shape of modern GTK, and the tutorial front-loads it.

Only src is editable, and rake regenerates the rest

The repository is a documentation toolchain as much as a tutorial, and its contribution rules are strict about where edits go.

The instruction is explicit: when submitting a pull request, ensure that you only modify the files in the src directory, and do not modify the files under the gfm or html directories directly. Those two directories hold generated GFM, GitHub Flavoured Markdown, and HTML files.

After changing source files, you regenerate the derived files. The command for GFM is `bundle exec rake`, and the production HTML build is `G4T_ENV=production bundle exec rake html`. The README points at the Author Guide at gfm/author_guide.md for the details of how the source files are written.

The same rake toolchain produces the downloadable editions. For HTML, the command is `bundle exec rake html`, and there is a development variant spelled `G4T_ENV=developmnt bundle exec rake html` for a local serve. For PDF, the command is `bundle exec rake pdf`, and the finished PDF is committed into the pdf directory in the repository, which is where people who want the offline format get it.

The supporting files explain what the toolchain needs. There is a Gemfile and a Gemfile.lock for the Ruby dependencies, a .ruby-version file pinning the interpreter, a Rakefile holding the tasks, a mise.toml for tool version management, and a path_manager.rb. The lib, bin, data, docs and test directories sit alongside them, with the test directory holding the checks for the build tooling itself.

The GitHub Pages edition is the one the author recommends reading

The README opens by pointing readers away from the repository and towards the published site, saying the GitHub Pages site is available and that it is more readable than this repository.

The site is at the repository homepage address, toshiocp.github.io/Gtk4-tutorial, and it is the HTML version of the tutorial. The latest version of the tutorial lives in the GitHub repository, and the README says you can read it directly without downloading anything. So there are two ways in: a browsable web edition and a downloadable PDF in the pdf directory, and the repository itself is the source rather than the reading experience.

For upstream reference, the README sends you to the GTK API Reference at docs.gtk.org and the GNOME Developer Documentation Website, and notes that both of those sites were opened in August 2021. That detail matters more than it looks: a tutorial written against a GTK 4 world of 2021 will have drifted from the current API, and the upstream references are the places to check when a call signature in the tutorial no longer matches what you see in your headers.

The example code is stated to have been tested on GTK version 4.22.4. That gives you a concrete version to check against when something in the text disagrees with your local installation.

An unstable tutorial that asks for bug reports anyway

The contribution section is unusually candid. The README states that this tutorial is still under development and unstable, and that even though the example codes have been tested on GTK version 4.22.4, bugs may still exist.

Bugs can be reported through GitHub issues, and updated files can be posted as a pull request. Questions and feedback are also welcome on the issue tracker, and the README describes them as invaluable for improving the tutorial.

That combination, an acknowledged unstable state plus a request for corrections, is the honest way to run a long teaching project. Thirty-six sections of C code against a moving toolkit will drift, and a tutorial that pretended otherwise would be less useful, not more.

There is also a testing dimension that belongs in the picture, because the repository is a working project rather than a folder of Markdown. Alongside the prose there are data, lib, bin and test directories, and the Rakefile drives both the document generation and the checks, which means the tutorial's own tooling is exercised when you run the build.

One structural constraint is worth knowing before you contribute: the src directory is the only editable area, so a fix to a generated HTML file will be rejected. The workflow is edit the source, regenerate, then open the pull request with the regenerated files included.

Two licences, one for the prose and one for the code

The repository metadata does not record a standard licence, and the README explains where the terms actually live: the licence of this repository is written in Section 1, at gfm/sec1.md.

The summary given there is short and split by artefact. GFDL1.3 applies to the documents, and GPL3 applies to the programs. That is a sensible split for a tutorial, since the prose and the example code are separately reusable: a reader can quote and adapt the text under the GNU Free Documentation License, while the C examples carry the GPL terms of the GNU General Public License.

The practical consequence is that the example programs are the part with copyleft obligations. If you take a chunk of tfe code into a project of your own, the GPL terms travel with it, while the surrounding explanations can be reused more freely. As always, the licence text itself is the authority on what any of this permits, and this is not legal advice.

The LGPL and GPL distinction does not apply here, since the README names GPL3 for the programs rather than the LGPL, which is worth noticing for anyone who assumed the looser terms of a typical GTK-adjacent example.

The API reference and the GObject tutorial as the alternatives

There is a real alternative to this tutorial, and the README names it twice: the GTK API Reference and the GNOME Developer Documentation Website, plus the author's separate GObject tutorial.

The difference in approach is what each one optimises for. The API reference is exhaustive and alphabetical. It tells you every parameter of every widget, which is exactly what you need when you already know what you are looking for and only need the signature or the property list. It tells you nothing about why you would reach for that call.

The tutorial is a narrative with a running example. It gives you an order, which for a beginner is the entire value, because the GTK surface is large enough that browsing the reference without direction is disorienting. The trade-off is coverage and currency: the tutorial says its contents are limited to the basics, and it was written against a 2021 view of GTK 4, so it will not cover the newer parts of the toolkit.

The GObject tutorial is the third option, and it addresses the one area this one explicitly defers. If you are comfortable with the object system already, you can use Gtk4-tutorial for the widget and application layer and read GObject separately, rather than working through both in sequence.

One more constraint applies to all of them. This is a C tutorial. There is no Python or JavaScript variant in this repository, and the build tooling for the documents is Ruby, so anyone coming from a scripting language has two new things to learn rather than one.

Editorial conclusion

Gtk4-tutorial fits a C developer who knows the language but has never written a GTK application, and it fits a reader who prefers one worked example over an API reference, since the tfe editor carries the reader from a bare window to drawing, drag and drop and list views. It does not fit developers working in another language, and it does not fit people who want a complete GTK reference, since the README states the contents are limited to the basics and points to the upstream API reference for that. Before you rely on it, check the section you need against the table of contents, read the licence note in gfm/sec1.md, and remember that the README describes the tutorial as still under development and unstable, with example code tested against GTK 4.22.4.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. ToshioCP/Gtk4-tutorial on GitHub