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
- the name of the signal
- 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. 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's documentation. The actual list of inherited signals can only be seen in the documentation for Widget. Why the disparity? No idea.
Event Mask
Not that widgets do not emit all possible signals, there is an EventMask 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.