[gnome-builder/wip/chergert/merge-shortcuts] doc: update more keytheme documentation

[Christian Hergert <chergert src gnome org>]

commit 224a3540807b2c98f01c5370133f8d44840a6e17
Author: Christian Hergert <chergert redhat com>
Date:   Thu May 25 17:41:01 2017 -0700

    doc: update more keytheme documentation
    
    Some of this still needs to be implemented, but starting from how the
    application developers will use it seems prudent.

 doc/plugins/keybindings.rst |  139 ++++++++++++++++++++++++++++++++++++-------
 1 files changed, 118 insertions(+), 21 deletions(-)
---
diff --git a/doc/plugins/keybindings.rst b/doc/plugins/keybindings.rst
index 3370c78..6da9dc4 100644
--- a/doc/plugins/keybindings.rst
+++ b/doc/plugins/keybindings.rst
@@ -1,39 +1,132 @@
-#######################
-Registering Keybindings
-#######################
+##################
+Keyboard Shortcuts
+##################
 
-Defining a Shortcut
-===================
+Builder's powerful shortcut engine provides the ability for simple shortcuts, complex chords, shortcut 
themes, and user overrides.
+To support this, it is important to understand where to register the necessary information for your 
shortcuts to give users maximum flexibility.
 
-Shortcuts in Builder are defined similar to Gtk with the exception that you may define multiple keys 
separted by the | character.
+Accelerators
+============
 
-To define a keyboard shortcut for the combination of Control and C you would use ``<Control>c``.
-Modifiers such as ``Control``, ``Super``, ``Hyper``, ``Alt``, ``Primary``, and ``Shift`` are kept within XML 
style tags.
+Accelerator is the term we use for defining which keys need to be pressed for a shortcut.
+Shortcuts in Builder are defined similar to Gtk with the exception that you may define multiple keys 
separted by the | (pipe) character.
 
-.. note:: Use ``<Primary>`` instead of ``<Control>`` if you want the command key to be used on macOS™.
-
-
-Shortcut Examples
------------------
-
-The following are examples of properly defined shortcuts.
+To define a keyboard shortcut for the combination of ``Control`` and ``C`` use ``<Control>c``.
+Modifiers such as ``Control``, ``Super``, ``Hyper``, ``Alt``, ``Primary``, and ``Shift`` are placed within 
XML-style element tags.
 
 .. code-block:: xml
+   :caption: A list of properly formatted shortcut accelerators
 
    <Primary>c
    <Control><Shift>p
    <Control><Alt>n
    <Super>k
+   <Shift>Page_Up
    <Alt>1
    <Shift>comma
    <Shift>plus
    <Control>x|<Control>c
 
-For more essoteric keys, the name should match the nickname from the ``GDK_Key_`` enumeration.
-See ``gdkkeysyms.h`` for the various definitions.
+.. tip:: Use ``Primary`` instead of ``Control`` if you'd like ``Command`` to be used on macOS™.
+
+Some key names are not obvious.
+Refer to ``gdk/gdkkeysyms.h`` for their name.
+For example, ``grave`` is the name for ``GDK_KEY_grave``.
+
+.. tip:: You may find the ``xev`` program useful to locate the name of a key.
+
+Registering a Shortcut
+----------------------
+
+Shortcuts should be registered with the ``IdeShortcutManager`` in your ``GObjectClass.class_init`` function.
+This allows both the user and shortcut themes to override the accelerator.
+
+.. code-block:: c
+
+   static void
+   my_widget_class_init (MyWidget *widget)
+   {
+      /* ... */
+
+      ide_shortcut_manager_add_command (NULL,
+                                        "org.gnome.builder.commands.my-command",
+                                        "<Primary><Shift>z",
+                                        _("Shorctuts Window Page"),
+                                        _("Shortcuts Window Group"),
+                                        _("Shortcut Title"),
+                                        _("Shortcut Description if necessary"));
+   }
+
+Now we need to enable our shortcut controller to handle our registered command 
``org.gnome.builder.commands.my-command``.
+We just want to focus our widget when this command occurs, so we will dispatch the ``grab-focus`` signal.
+You may want to connect other signals, actions, or callbacks in your code.
+
+.. code-block:: c
+
+   static void
+   my_widget_init (MyWidget *widget)
+   {
+     /* ... */
+
+     IdeShortcutController *controller = ide_shortcut_controller_find (GTK_WIDGET (self));
+
+     /* If you want to activate a signal */
+     ide_shortcut_controller_add_command_signal (controller,
+                                                 "org.gnome.builder.commands.my-command",
+                                                 "grab-focus", 0);
+
+     /* If instead you want to activate a GAction */
+     ide_shortcut_controller_add_command_action (controller,
+                                                 "org.gnome.builder.commands.my-command",
+                                                 "build-manager.build");
+
+     /* Or just a callback instead */
+     ide_shortcut_controller_add_command_callback (controller,
+                                                   "org.gnome.builder.commands.my-command",
+                                                   (GtkCallback) my_callback_func,
+                                                   user_data,
+                                                   destroy_notify);
+   }
+
+
+Extending a Shortcut Theme
+==========================
 
-You can also figure this out using the ``xev`` command and pressing the key you are interested in.
-The ``xev`` program will print the name of the key.
+All Builder users are using a shortcut theme to some degree.
+The default shortcuts are also mapped via the ``default`` shortcut theme.
+Therefore, your plugin may want to support different key themes slightly differently.
+
+For example, you might want a different shortcut for the ``emacs`` theme than the ``default`` or ``vim`` 
shortcut theme.
+
+To do this, add a new ``themename.keytheme`` file to your plugins ``GResources`` in the ``keybindings`` 
direction.
+This should be something similar to ``/opt/gnome/builder/plugins/my-plugin/keybindings/default.keytheme``.
+Builder will automatically load and merge these keytheme extensions into the matching keytheme.
+
+.. code-block:: xml
+   :caption: Extending the ``default.keytheme``
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <theme name="default">
+     <shortcut accelerator="<Control><Shift>r"
+                   command="org.gnome.builder.commands.my-command"/>
+   </theme>
+
+If you want to extend shortcuts only when focused within a certain widget type, use a ``<context>`` to 
define the widget focus.
+Note that some key themes have more complex "modal" contexts (such as Vim).
+
+.. code-block:: xml
+   :caption: Extending the ``default.keytheme`` for a given widget type
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <theme name="default">
+
+     <!-- Only map command when focused in an GtkEntry -->
+     <context name="GtkEntry">
+       <shortcut accelerator="<Control><Shift>r"
+                     command="org.gnome.builder.commands.my-command"/>
+     </context>
+
+   </theme>
 
 
 Creating a Shortcut Theme
@@ -51,14 +144,17 @@ Builder also support multi-press "chords" familiar to Emacs users.
    :caption: Save this to ``gedit.keytheme``
 
    <?xml version="1.0" encoding="UTF-8"?>
-   <theme>
-     <property name="name">gedit</property>
+   <theme name="gedit">
      <property name="title">Gedit</property>
      <property name="subtitle">Emulates the Gedit text editor</property>
 
      <!-- Keythemes support both &lt; &gt; < and > -->
      <shortcut accelerator="<control>q" action="app.quit"/>
 
+     <!-- Only actions and commands can be activated outside of a context.
+          Signals require a context as they must be attached to a widget. -->
+     <shortcut accelerator="<Primary>c" command="org.gnome.builder.commands.my-command"/>
+
      <!-- You can set accelerators for widgets by using their name for the context -->
      <context name="GtkEntry">
        <!-- signal="select-all" activates the GtkEntry::select-all signal -->
@@ -70,6 +166,7 @@ Builder also support multi-press "chords" familiar to Emacs users.
            <param>chars</param>
            <param>1</param>
          </signal>
+
        </shortcut>
      </context>