GDK/GTK Signal Handling Notes
I recently tried my hands at implementing motion event support for canvas widgets in Toga on Linux, which uses GTK3 as its GUI back end. In the process I had learn to navigate GDK's event handling mechanics and documentation. This post is a summary of notes I made during the process.
### Basics
GTK widgets general signals, which you can be notified of if you connect() to the widget by specifying
1. the name of the signal
2. callback to invoke when the event occurs
### Event Names
To find out what signals a widget emits you naturally look at the widget's documentation, e.g. for [DrawingArea](https://docs.gtk.org/gtk4/class.DrawingArea.html). However you will quickly realise not *all* signals are listed. The list does not include signals such as "draw" which is mentioned in [python-gtk-3](https://athenajc.gitbooks.io/python-gtk-3-api/content/gtk-group/gtkdrawingarea.html)'s documentation. The actual list of inherited signals can only be seen in the [documentation for Widget](https://docs.gtk.org/gtk3/class.Widget.html#signals). Why the disparity? No idea.
### Event Mask
Not that widgets do not emit all possible signals, there is an [EventMask](https://docs.gtk.org/gdk3/enum.EventType.html) bitfield that determines which signals a widget will emit. It is not enough to simply connect() to a signal - you must also enable those events you wish to receive if not enabled by default via gtk_widget_add_event(). Note that the relationship between signal names defined and the event-mask required is not explicitly defined. It comes down to guessing the how they are related and trial and error.