/GTK 4.0

Event propagation

The function which initially receives input events on the GTK side is responsible for a number of tasks.

  1. Find the widget which got the event.

  2. Generate crossing (i.e. enter and leave) events when the focus or hover location change from one widget to another.

  3. Send the event to widgets.

An event is propagated down and up the widget hierarchy in three phases (see GtkPropagationPhase) towards a target widget.

Figure 14. Event propagation phases

Event propagation phases

For key events, the top-level window gets a first shot at activating mnemonics and accelerators. If that does not consume the events, the target widget for event propagation is window’s current focus widget (see gtk_window_get_focus()).

For pointer events, the target widget is determined by picking the widget at the events coordinates (see gtk_widget_pick()).

In the first phase (the capture phase) the event is delivered to each widget from the top-most (the top-level GtkWindow or grab widget) down to the target GtkWidget. Event controllers that are attached with GTK_PHASE_CAPTURE get a chance to react to the event.

After the capture phase, the widget that was intended to be the destination of the event will run event controllers attached to it with GTK_PHASE_TARGET. This is known as the target phase, and only happens on that widget.

In the last phase (the bubble phase), the event is delivered to each widget from the target to the top-most, and event controllers attached with GTK_PHASE_BUBBLE are run.

Events are not delivered to a widget which is insensitive or unmapped.

Any time during the propagation phase, a controller may indicate that a received event was consumed and propagation should therefore be stopped. If gestures are used, this may happen when the gesture claims the event touch sequence (or the pointer events) for its own. See the gesture states section below to learn more about gestures and sequences.

© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.