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 |
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:
- 1/a: he already knows the concepts and just want to figure how to implement well known things with gtk4
- 1/b: he is new to GUI programming and is learning basic concepts with gtk4
A twin-aspect of this is another two choices, normally correlating with the above:
- 2/a: he already has a clear vision/plan on what gtk4 needs to do for his app, and/or he even has an already existing, working application that needs a (new) GUI
- 2/b: he has no idea about how the GUI should look like and wants to get inspired
Orthogonally to that, there's another scale with these two extremes on how the application relates to GUI in general:
- 3/a: the application wants to do something useful and GUI is merely an interface, a secondary thing; GUI tailored to fit the functionality
- 3/b: GUI is the central thing, designed first, any functionality is added later, sort of as pulled in by the GUI
There are two, mutually exclusive approaches to examples or demo code:
- minimal: each example tries to be as small as possible, demonstrating a single feature
- inspiring: each example tries to be a complete showcase of a bigger area, combining many fancy features
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:
- gtk4-demo-application
- gtk4-widget-factory
- gtk4-demo
- examples/
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:
- a minimal, plain C version that makes it easy to understand how to create it
- an inspiring, .ui/css/g-resources version that shows off all cool side-features of the widget
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.