pcb-rnd knowledge pool


GTK4 rant: demo/example code

gtk4r_demos by Tibor 'Igor2' Palinkas on 2021-12-02

Tags: insight, gtk4, rant, doc, example, demo

node source



Abstract: n/a

  This rant is part of a series.

minimal vs. inspiring

When one starts to use gtk4, and looks at example code or demo porgrams, there are basically two possibilities:

A twin-aspect of this is another two choices, normally correlating with the above:

Orthogonally to that, there's another scale with these two extremes on how the application relates to GUI in general:

There are two, mutually exclusive approaches to examples or demo code:

It's clear that 1/a, 2/a and 3/a work best with minimal examples, while inspiring examples are more efficient for 1/b, 2/b, 3/b.

The three main sets of examples coming with gtk4 are:

This could mean we have both minimal and inspiring examples. But unfortunately that's not the case. All three fall in the inspiring category. The demo application is smallish, but has a menu system, toolbars, about box... So not far from being a minimal application, but definitely bigger than minimal. but even if it was minimal, it's only an application example.

The widget factory tries to demonstrate a lot of widgets, but unfortunately all bundled. It's a large, 2k sloc main source but also uses .ui files, icon graphics, xml, css, etc. So it is definitely on the inspiring side, not on the minimal side.

gtk4-demo is similar: it has different example programs for different topics, but most of these demos are more about showing off how cool gtk is than concentrating on what's the easiest way to start using a widget.

Finally, examples/ is a well built tutorial that consists of a series of sources. Unfortunately these also grow big rather fast and the small ones cover only a small portion of the search space.

So majority of the demos/examples shipped with gtk4 are inspiring and not minimal. In an ideal world the API doc for each widget class would have a minimal example on how that widget is used most typically. Trickier function calls would have an example showing what they are used for in practice. All these done in the minimal manner. I'd definitely have a few minimal examples on how custom widgets are developed.

librnd demos

Before I started to work on the gtk4 HID, I spent some time reading the gtk4 docs and writing minimal demos. These demos are available in librnd svn: svn://svn.repo.hu/librnd/work/gtk4 . They are mostly single-widget demos with a few bigger ones acting as single-feature demo for a topic librnd needs.

It would have helped me a lot if gtk4 came with such demos. Taking a single-widget demo like that and experimenting with the code is often the most efficient way to figure how the API works.

.ui files, css

In gtk4-demo some of the examples are relatively simple, single .c projects. What I've found particularly annoying is that many examples use .ui files or even .css instead of going for the simplest, single-C setup.

This is a conflict of interests between */a and */b again: a programmer who goes for 3/b and writes a gtk4-only app, an .ui file is probably the better choice. So it's good if there is an example on how to do things with the .ui way. But when showing a single widget, not having it in a single source C file and mixing in .ui just makes it harder to experiment with.

Or in an ideal world every widget example would have two variants:

pcb-rnd aspects

For similar reasons in pcb-rnd scripting rosetta stone examples I decided to start with simple, single-feature scripts written in many different scripting languages. Instead of showing off how cool complex things can be done from scripts, I tried to show how easy it is to script pcb-rnd. The in-many-languages part helps the user spending his time on understanding what the script is doing, in his favorite language, and not getting distracted by the syntax of a new-to-him scripting language.

Only the last few scripts are more complex, to show how basic features can be combined.

Cuvoodoo's pcb-rnd "getting started" tutorial video is also a good example: it is very close to the minimal starter pack in using the GUI, not getting distracted into cool, advanced features or 10 alternatives on doing each step.