GNOME.org
 

[gtk/wip/matthiasc/shortcut-2] docs: Update the overview input chapter

commit de80fb01565ac10b88dd3b4f2bb180773698c249
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Mar 24 16:11:07 2020 -0400

    docs: Update the overview input chapter
    
    Update the wording around events to reflect current
    usage, and add information about shortcuts and the
    shortcut controller.

 docs/reference/gtk/input-handling.xml | 158 +++++++++++++++-------------------
 1 file changed, 71 insertions(+), 87 deletions(-)
---
diff --git a/docs/reference/gtk/input-handling.xml b/docs/reference/gtk/input-handling.xml
index cc6d7f0db2..4399d04325 100644
--- a/docs/reference/gtk/input-handling.xml
+++ b/docs/reference/gtk/input-handling.xml
@@ -63,25 +63,19 @@
      GDK translates these raw windowing system events into #GdkEvents.
      Typical input events are:
      <simplelist>
-       <member>#GdkEventButton</member>
-       <member>#GdkEventMotion</member>
-       <member>#GdkEventCrossing</member>
-       <member>#GdkEventKey</member>
-       <member>#GdkEventFocus</member>
-       <member>#GdkEventTouch</member>
+       <member>button clicks</member>
+       <member>pointer motion</member>
+       <member>key presses</member>
+       <member>focus changes</member>
+       <member>touch events</member>
      </simplelist>
+     These are all represented as #GdkEvents, but you can differentiate
+     between different events by looking at their type, using
+     gdk_event_get_event_type().
     </para>
     <para>
-      Additionally, GDK/GTK synthesizes other signals to let know whether
-      grabs (system-wide or in-app) are taking input away:
-      <simplelist>
-       <member>#GdkEventGrabBroken</member>
-       <member>#GtkWidget::grab-notify</member>
-      </simplelist>
-    </para>
-    <para>
-      When GTK creates a GdkSurface, it connects to the ::event signal
-      on it, which receives all of these input events. Surfaces have
+      When GTK creates a GdkSurface, it connects to the #GdkSurface::event
+      signal on it, which receives all of these input events. Surfaces have
       have signals and properties, e.g. to deal with window management
       related events.
     </para>
@@ -96,14 +90,11 @@
     </para>
     <orderedlist>
       <listitem><para>
-        Compress enter/leave notify events. If the event passed build an
-        enter/leave pair together with the next event (peeked from GDK), both
-        events are thrown away. This is to avoid a backlog of (de-)highlighting
-        widgets crossed by the pointer.
+        Find the widget which got the event.
       </para></listitem>
       <listitem><para>
-        Find the widget which got the event. If the widget can’t be determined
-        the event is thrown away unless it belongs to a INCR transaction.
+        Generate crossing (i.e. enter and leave) events when the focus or hover
+        location change from one widget to another.
       </para></listitem>
       <listitem><para>
         Then the event is pushed onto a stack so you can query the currently
@@ -137,24 +128,6 @@
       </para></listitem>
     </orderedlist>
 
-    <para>
-      When a GDK backend produces an input event, it is tied to a #GdkDevice and
-      a #GdkSurface, which in turn represents a windowing system surface in the
-      backend. If a widget has grabbed the current input device, or all input
-      devices, the event is propagated to that #GtkWidget. Otherwise, it is
-      propagated to the the #GtkRoot which owns the #GdkSurface receiving the event.
-    </para>
-
-    <para>
-      Grabs are implemented for each input device, and globally. A grab for a
-      specific input device (gtk_device_grab_add()), is sent events in
-      preference to a global grab (gtk_grab_add()). Input grabs only have effect
-      within the #GtkWindowGroup containing the #GtkWidget which registered the
-      event’s #GdkSurface. 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 dialogs.
-    </para>
-
     <para>
       An event is propagated down and up the widget hierarchy in three phases
       (see #GtkPropagationPhase) towards a target widget.
@@ -220,70 +193,74 @@
   </refsect2>
 
   <refsect2>
-    <title>Grabs</title>
+    <title>Keyboard input</title>
 
     <para>
-      Grabs are a method to claim all input events from a device,
-      they happen either implicitly on pointer and touch devices,
-      or explicitly. Implicit grabs happen on user interaction, when
-      a #GdkEventButtonPress happens, all events from then on, until
-      after the corresponding #GdkEventButtonRelease, will be reported
-      to the widget that got the first event. Likewise, on touch events,
-      every #GdkEventSequence will deliver only events to the widget
-      that received its %GDK_TOUCH_BEGIN event.
+      Every #GtkWindow maintains a single focus location (in the
+      #GtkWindow:focus-widget property). The focus widget is the target
+      widget for key events sent to the window. Only widgets which have
+      #GtkWidget:can-focus set to %TRUE can become the focus. Typically
+      these are input controls such as entries or text fields, but e.g.
+      buttons can take the focus too.
     </para>
 
     <para>
-      Explicit grabs happen programatically (both activation and
-      deactivation), and can be either system-wide (GDK grabs) or
-      application-wide (GTK grabs). On the windowing platforms that
-      support it, GDK grabs will prevent any interaction with any other
-      application/window/widget than the grabbing one, whereas GTK grabs
-      will be effective only within the application (across all its
-      windows), still allowing for interaction with other applications.
+      Input widgets can be given the focus by clicking on them, but focus
+      can also be moved around with certain key events (this is known as
+      “keyboard navigation”). GTK reserves the Tab key to move the focus
+      to the next location, and Shift-Tab to move it back to the previous
+      one. In addition many containers allow “directional navigation” with
+      the arrow keys.
     </para>
 
     <para>
-      But one important aspect of grabs is that they may potentially
-      happen at any point somewhere else, even while the pointer/touch
-      device is already grabbed. This makes it necessary for widgets to
-      handle the cancellation of any ongoing interaction. Depending on
-      whether a GTK or GDK grab is causing this, the widget will
-      respectively receive a #GtkWidget::grab-notify signal, or a
-      #GdkEventGrabBroken event.
+      Many widgets can be “activated” to trigger and action. E.g., you can
+      activate a button or switch by clicking on them, but you can also
+      activate them with the keyboard, by using the Enter or Space keys.
     </para>
 
     <para>
-      On gestures, these signals are handled automatically, causing the
-      gesture to cancel all tracked pointer/touch events, and signal
-      the end of recognition.
+      Apart from keyboard navigation, activation and directly typing into
+      entries or text views, GTK widgets can use key events for activating
+      “shortcuts”. Shortcuts generally act as a quick way to move the focus
+      around or to activate a widget that does not currently have the focus.
     </para>
-  </refsect2>
-
-  <refsect2>
-    <title>Keyboard input</title>
 
     <para>
-      Every #GtkWindow maintains a single focus location (in
-      the ::focus-widget property). The focus widget is the
-      target widget for key events sent to the window. Only
-      widgets which have ::can-focus set to %TRUE can become
-      the focus. Typically these are input controls such as
-      entries or text fields, but e.g. buttons can take the
-      focus too.
+      GTK has traditionally supported different kinds of shortcuts:
+      <variablelist>
+        <varlistentry>
+          <term>Mnmemonics</term>
+          <listitem><para>
+            Mnemonics are usually triggered using Alt as a modifier for a letter.
+            They are used in places where a label is associated with a control,
+            and are indicated by underlining the letter in the label. As a special
+            case, inside menus (i.e. inside #GtkPopoverMenu), mnemonics can be
+            trigered without the modifier.
+          </para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Key bindings</term>
+          <listitem><para>
+            Key bindings are specific to individual widgets, such as Ctrl-C or
+            Ctrl-V in an entry copy to or paste from the clipboard. They are only
+            triggered when the widget has focus.
+          </para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>Accelerators</term>
+          <listitem><para>
+            Accelerators are any other shortcuts that can be activated regardless
+            of where the focus is, and typically trigger global actions, such as
+            Ctrl-Q to quit an application.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
     </para>
-
     <para>
-      Input widgets can be given the focus by clicking on them,
-      but focus can also be moved around with certain key
-      events (this is known as “keyboard navigation”). GTK
-      reserves the Tab key to move the focus to the next location,
-      and Shift-Tab to move it back to the previous one. In addition
-      many containers allow “directional navigation” with the
-      arrow keys.
+      Under the hood, all shortcuts are represented as instances of #GtkShortcut,
+      and they are managed by #GtkShortcutController.
     </para>
-
-    <!-- mnemonics, accelerators, bindings -->
   </refsect2>
 
   <refsect2 id="event-controllers-and-gestures">
@@ -330,6 +307,13 @@
        </member>
       </simplelist>
     </para>
+
+    <para>
+      Shortcuts are handled by #GtkShortcutController, which is
+      a complex event handler that can either activate shortcuts
+      itself, or propagate them to another controller, depending
+      on its #GtkShortcutController:scope.
+    </para>
   </refsect2>
 
   <refsect2>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]