GNOME Bugzilla – Bug 744054
Clarify documentation for event propagation and handling
Last modified: 2015-02-19 12:49:49 UTC
GTK+’s documentation for how events are triggered, propagated through the widget hierarchy, and how event masks interact with them to determine which widgets receive an event, is hard to find and opaque to new developers. It would be great if we could write a conceptual overview of event handling, using the material currently on https://developer.gnome.org/gtk3/unstable/gtk3-General.html https://developer.gnome.org/gtk3/unstable/GtkWidget.html#gtk-widget-set-events and cross-link it from all the relevant places. We should make sure that it’s clear exactly when a user should call gtk_widget_add_events() — do they assume internal knowledge of what events a widget handles already, or do they just go ahead and add everything they ever expect the widget to handle (which I guess would involve calling gtk_widget_add_events(my_gtk_button, GDK_BUTTON_PRESS_MASK), which is a bit silly; but there are other cases which are less obvious).
Like this: https://developer.gnome.org/gtk3/stable/chap-input-handling.html you mean ?
(In reply to comment #1) > Like this: https://developer.gnome.org/gtk3/stable/chap-input-handling.html you > mean ? Yeah, pretty much. Perhaps we could: • Add ‘event’ to the page title to make it easier to find. • Add a section on event masks, since they are only briefly touched in the ‘touch events’ section. • Link to it from the GtkWidget event mask functions and GdkEventMask documentation. How would you feel about that? I can try and come up with a patch if you’re happy with it.
(In reply to Philip Withnall from comment #2) > How would you feel about that? I can try and come up with a patch if you’re > happy with it. Hard to say if I'm happy with it before seeing the patch... but lets just say I'm happy with the suggestion.
Created attachment 297086 [details] [review] gtk: Remove documentation references to the GTK_NO_WINDOW flag It has been removed entirely, and replaced by gtk_widget_get_has_window().
Created attachment 297087 [details] [review] docs: Mention events in the input handling documentation title Make it a little easier to find these docs when searching for ‘event’.
Created attachment 297088 [details] [review] docs: Expand input handling documentation to cover event masks Also try and clarify a few things about event propagation. Move input-handling.xml into gtk-doc’s expand_content_files variable so it automatically links to widget documentation. Add links from gtk_widget_add_events() and friends to the new documentation.
Created attachment 297089 [details] [review] docs: Add extra symbol links to input handling documentation Cross-reference to the API documentation more consistently.
Review of attachment 297086 [details] [review]: sure
Review of attachment 297087 [details] [review]: Not sure I fully agree with input and events being two separate things, but ok
Review of attachment 297089 [details] [review]: easy to do too much with cross-references, but I guess this is still ok
Review of attachment 297088 [details] [review]: Thanks Philip for tackling this :). Very nice additions overall, I've only got some minor changes/suggestions ::: docs/reference/gtk/input-handling.xml @@ +101,3 @@ + + <para> + When a GDK backend produces an event, it is tied to a #GdkDevice and a Probably better to clarify "input event" @@ +116,3 @@ + event’s #GdkWindow. If this #GtkWidget is a child of the grab widget, the + event is propagated to the child — this is the basis for propagating + events within modal dialogues. "dialogs" for consistence? is there even a british vs american english preference? :). Feel free to ignore me. @@ +122,3 @@ + An event is propagated to a widget using gtk_propagate_event(). + Propagation differs between event types: key events (%GDK_KEY_PRESS, + %GDK_KEY_RELEASE) are delivered to the top-level #GtkWindow; other events It might be worth to mention gtk_window_propagate_key_event(), and how key events bubble from the focus widget. @@ +123,3 @@ + Propagation differs between event types: key events (%GDK_KEY_PRESS, + %GDK_KEY_RELEASE) are delivered to the top-level #GtkWindow; other events + are propagated down and up the widget hierarchy in two phases. That's 3 phases. Conceptually, GtkWidget::event is part of the bubbling phase, might be mentioned as such on the paragraph below. @@ +184,3 @@ + <para> + If a widget is windowless (gtk_widget_get_has_window() returns %FALSE), it + must be placed inside a #GtkEventBox to receive events, and an appropriate Many widgets achieve this through GDK_INPUT_ONLY windows, not sure if this is something we want to explain too much in detail here.
Created attachment 297253 [details] [review] fixup! docs: Expand input handling documentation to cover event masks
Review of attachment 297253 [details] [review]: Looks great! please commit together with the other patch :)
Great, all merged. Thanks for the fast reviews! Attachment 297086 [details] pushed as b397dd0 - gtk: Remove documentation references to the GTK_NO_WINDOW flag Attachment 297087 [details] pushed as 668d5d8 - docs: Mention events in the input handling documentation title Attachment 297088 [details] pushed as 09bb109 - docs: Expand input handling documentation to cover event masks Attachment 297089 [details] pushed as 8b4863f - docs: Add extra symbol links to input handling documentation