I am trying to get started with GTK, but I find the documentation for signals (https://developer.gnome.org/gobject/stable/signal.html) hard to understand.
It seems as there is a difference between a "signal" and an "event". For example, the documentation for the "event"-signal for a Widget (https://developer.gnome.org/gtk3/stable/GtkWidget.html#GtkWidget-event) says
The GTK+ main loop will emit three signals for each GDK event delivered to a widget: one generic ::event signal, another, more specific, signal that matches the type of event delivered (e.g. “key-press-event”) and finally a generic “event-after” signal.
So it seems to me, that GDK uses "events", whereas GTK+ uses "signals". Maybe events are just packed into signals, or the other way around? Or are they completely different things?
My understanding of the above quote:
When a key is pressed, then a GDK-event is fired. This GDK-event calls a callback function of the widget (which is not for the programmer to interfer with). The callback function then in turn emits the three signals ::event, key-press-event and event-after, one after the other. As a programmer I can intercept these signals by writing callback functions. If the callback for the first ::event signal returns TRUE, then the second key-press-event signal is not fired, otherwise it is. The third event-after signal is always fired.
Is my understanding correct?
Furthermore, in the docs, sometimes signals are prepended by a double colon (::event) and sometimes they are not (key-press-event and event-after). What is the difference? What is the meaning of the double colon?
it's just nomenclature.
signals, in GObject, are just fancy ways to calling named lists of functions; each time an instance "emits" a signal, the GSignal machinery will look at all the callbacks connected to that particular signal, and call them sequentially until either one of these conditions is satisfied:
all signals emitted by GDK or GTK+ (as well as any other GObject-based library) work exactly in that way.
events, in GDK, are structures related to windowing system events, like a button press, a key release, a pointer crossing the window boundaries, a change in the window hierarchy, and so on and so forth. the only interaction you generally have with GDK events happen in specific signals on the GtkWidget types. as a convention (though it does not always apply) the signals that have a GdkEvent structure have an -event suffix, like button-press-event, or key-release-event, or enter-notify-event, or window-state-event. again, those are GObject signals, and their only specialization is having a GdkEvent as an argument.
as for the double colon: the full specification of a signal is made of the type that declares it, e.g. GtkWidget, and the signal name, e.g. button-press-event, separated by a double colon, e.g. GtkWidget::button-press-event. the ::button-press-event notation is just a documentation shorthand, signifying that the speaker is referring to the button-press-event signal.