The GTK+ Input Handling Model 3 GTK Library The GTK+ Input Handling Model GTK+ input handling in detail This chapter describes in detail how GTK+ handles input. If you are interested in what happens to translate a key press or mouse motion of the users into a change of a GTK+ widget, you should read this chapter. This knowledge will also be useful if you decide to implement your own widgets. The most basic input devices that every computer user has interacted with are keyboards and mice; beyond these, GTK+ supports touchpads, touchscreens and more exotic input devices such as graphics tablets. Inside GTK+, every such input device is represented by a #GdkDevice object. To simplify dealing with the variability between these input devices, GTK+ has a concept of master and slave devices. The concrete physical devices that have many different characteristics (mice may have 2 or 3 or 8 buttons, keyboards have different layouts and may or may not have a separate number block, etc) are represented as slave devices. Each slave device is associated with a virtual master device. Master devices always come in pointer/keyboard pairs - you can think of such a pair as a 'seat'. GTK+ widgets generally deal with the master devices, and thus can be used with any pointing device or keyboard. When a user interacts with an input device (e.g. moves a mouse or presses a key on the keyboard), GTK+ receives events from the windowing system. These are typically directed at a specific window - for pointer events, the window under the pointer (grabs complicate this), for keyboard events, the window with the keyboard focus. GDK translates these raw windowing system events into #GdkEvents. Typical input events are: GdkEventButton GdkEventMotion GdkEventCrossing GdkEventKey GdkEventFocus GdkEventTouch When GTK+ is initialized, it sets up an event handler function with gdk_event_handler_set(), which receives all of these input events (as well as others, for instance window management related events). When GTK+ receives an event, it determines the target widget that it is directed to. Unless grabs are involved, this is done by finding the widget to which the window of the event belongs. The event is then propagated from the toplevel window down to the target widget. In this phase, which is known as the “capture” phase, gestures that are attached with GTK_PHASE_CAPTURE get a chance to react to the event. Next, the appropriate event signal is emitted for the event in question, e.g. “motion-notify-event”. Handling these signals was the primary way to handle input in GTK+ widgets before gestures were introduced. The signals are emitted from the target widget up to the toplevel, until a signal handler indicates that it has handled the event, by returning GDK_EVENT_STOP. The default handlers for the event signals send the event to gestures that are attached with GTK_PHASE_TARGET. Therefore, gestures in the ”target” phase are only used if the widget does not have its own event handlers, or takes care to chain up to the default handlers. After calling the event handlers, in the so-called ”bubble” phase, gestures that are attached with GTK_PHASE_BUBBLE get a chance to react to the event.