Managing Keyboard Shortcuts
===========================

Certain actions and key events in the UI can be defined with custom keyboard
shortcuts using a configuration file stored in a user's Katana folder:
:file:`$HOME/.katana/shortcuts.xml`.

Not all keyboard shortcuts can be customized. A list of modifiable keyboard
shortcuts can be viewed in the :kat:ui:`Keyboard Shortcuts` tab, along with
their default assignments. Keyboard shortcuts can be customized in tabs that
make use of the Keyboard Shortcuts Manager, including new custom tabs.

The configuration file can be used to override the default keyboard shortcuts
of actions and key events that are registered with Katana's Keyboard Shortcut
Manager, for example:

.. code-block:: xml

    <shortcuts>
        <shortcut id="430f81d33d338680a0c64ae9ea311cd7"
                  name="SceneGraphView.ExpandBranchesToAssembly"
                  shortcut="A"></shortcut>
    </shortcuts>

The ID of a keyboard shortcut element is assigned by the user that registers
the action or key event.  It is a hash based on the original name of the action
or key event. While the name of an action or key event may change, the ID
remains the same for future versions of Katana. This ensures that the
correspondence of custom keyboard shortcuts to the respective actions or key
events remain the same, even if names change.

From the :kat:ui:`Keyboard Shortcuts` tab, you can copy an XML representation
of an item in the keyboard shortcuts tree to the clipboard by right-clicking
the item and choosing :kat:ui:`Copy as XML`. Pasting such an XML representation
into the :file:`shortcuts.xml` file allows you to override the default assigned
keyboard shortcut.

.. note::

    The ``name`` attribute of a shortcut XML element only appears for
    readability, making it easy to identify the action or key event to which
    the shortcut has been assigned. The names in the :file:`shortcuts.xml` file
    are not updated automatically when names of actions or key events are
    changed in the application.

`KeyboardShortcutManager`
-------------------------

The :mod:`UI4.App.KeyboardShortcutManager` Python module can be used to
register action callbacks to which keyboard shortcuts can be assigned.

It covers the following areas of the UI:

* The buttons next to the main menu in Katana's main application window:

  * Shelf Scripts
  * Flush Caches
  * Toggle Scene Graph Implicit Resolvers
  * Render Only Selected Objects
  * Auto-key All

* The :kat:ui:`Scene Graph` tab
* The table of objects in GafferThree nodes that are edited in the
  :kat:ui:`Parameters` tab
* Custom tab plug-ins that derive from :mod:`UI4.Tabs.BaseTab`

.. automodule:: UI4.App.KeyboardShortcutManager.KeyboardShortcutManager
.. autoclass:: UI4.App.KeyboardShortcutManager.KeyboardShortcutItem.KeyboardShortcutItem
.. autoclass:: UI4.App.KeyboardShortcutManager.KeyboardShortcutManagerMixin.KeyboardShortcutManagerMixin
.. autoclass:: UI4.App.KeyboardShortcutManager.KeyboardShortcutModel.KeyboardShortcutModel
.. autoclass:: UI4.App.KeyboardShortcutManager.ManagedAction.ManagedAction