:right-sidebar: True

ShortcutController
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: ShortcutController(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gtk.EventController`, :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gio.ListModel`, :class:`~gi.repository.Gtk.Buildable`



``GtkShortcutController`` is an event controller that manages shortcuts.

Most common shortcuts are using this controller implicitly, e.g. by
adding a mnemonic underline to a :obj:`~gi.repository.Gtk.Label`, or by installing a key
binding using :obj:`~gi.repository.Gtk.WidgetClass.add_binding`, or by adding accelerators
to global actions using :obj:`~gi.repository.Gtk.Application.set_accels_for_action`.

But it is possible to create your own shortcut controller, and add
shortcuts to it.

``GtkShortcutController`` implements :obj:`~gi.repository.Gio.ListModel` for querying the
shortcuts that have been added to it.

GtkShortcutController as GtkBuildable
-------------------------------------

``GtkShortcutController``'s can be created in :obj:`~gi.repository.Gtk.Builder` ui files, to set up
shortcuts in the same place as the widgets.

An example of a UI definition fragment with ``GtkShortcutController``:

.. code-block::
   :dedent:

     <object class='GtkButton'>
       <child>
         <object class='GtkShortcutController'>
           <property name='scope'>managed</property>
           <child>
             <object class='GtkShortcut'>
               <property name='trigger'>&lt;Control&gt;k</property>
               <property name='action'>activate</property>
             </object>
           </child>
         </object>
       </child>
     </object>


This example creates a :obj:`~gi.repository.Gtk.ActivateAction` for triggering the
``activate`` signal of the :obj:`~gi.repository.Gtk.Button`. See :obj:`~gi.repository.Gtk.ShortcutAction.parse_string`
for the syntax for other kinds of :obj:`~gi.repository.Gtk.ShortcutAction`. See
:obj:`~gi.repository.Gtk.ShortcutTrigger.parse_string` to learn more about the syntax
for triggers.



Constructors
------------

.. rst-class:: interim-class

.. class:: ShortcutController
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.EventController

      Creates a new shortcut controller.










   .. classmethod:: new_for_model(model: ~gi.repository.Gio.ListModel) -> ~gi.repository.Gtk.EventController

      Creates a new shortcut controller that takes its shortcuts from
      the given list model.

      A controller created by this function does not let you add or
      remove individual shortcuts using the shortcut controller api,
      but you can change the contents of the model.







      :param model: a ``GListModel`` containing shortcuts









Methods
-------

.. rst-class:: interim-class

.. class:: ShortcutController
   :no-index:


   .. method:: add_shortcut(shortcut: ~gi.repository.Gtk.Shortcut) -> None

      Adds ``shortcut`` to the list of shortcuts handled by ``self``.

      If this controller uses an external shortcut list, this
      function does nothing.







      :param shortcut: a ``GtkShortcut``





   .. method:: get_mnemonics_modifiers() -> ~gi.repository.Gdk.ModifierType

      Gets the mnemonics modifiers for when this controller activates its shortcuts.










   .. method:: get_scope() -> ~gi.repository.Gtk.ShortcutScope

      Gets the scope for when this controller activates its shortcuts.

      See :obj:`~gi.repository.Gtk.ShortcutController.set_scope` for details.










   .. method:: remove_shortcut(shortcut: ~gi.repository.Gtk.Shortcut) -> None

      Removes ``shortcut`` from the list of shortcuts handled by ``self``.

      If ``shortcut`` had not been added to ``controller`` or this controller
      uses an external shortcut list, this function does nothing.







      :param shortcut: a ``GtkShortcut``





   .. method:: set_mnemonics_modifiers(modifiers: ~gi.repository.Gdk.ModifierType) -> None

      Sets the controller to use the given modifier for mnemonics.

      The mnemonics modifiers determines which modifiers need to be pressed to allow
      activation of shortcuts with mnemonics triggers.

      GTK normally uses the Alt modifier for mnemonics, except in ``GtkPopoverMenu``'s,
      where mnemonics can be triggered without any modifiers. It should be very
      rarely necessary to change this, and doing so is likely to interfere with
      other shortcuts.

      This value is only relevant for local shortcut controllers. Global and managed
      shortcut controllers will have their shortcuts activated from other places which
      have their own modifiers for activating mnemonics.







      :param modifiers: the new mnemonics_modifiers to use





   .. method:: set_scope(scope: ~gi.repository.Gtk.ShortcutScope) -> None

      Sets the controller to have the given ``scope``.

      The scope allows shortcuts to be activated outside of the normal
      event propagation. In particular, it allows installing global
      keyboard shortcuts that can be activated even when a widget does
      not have focus.

      With :const:`~gi.repository.Gtk.ShortcutScope.LOCAL`, shortcuts will only be activated
      when the widget has focus.







      :param scope: the new scope to use









Properties
----------

.. rst-class:: interim-class

.. class:: ShortcutController
   :no-index:
   

   .. attribute:: props.item_type
      :type: type

      The type of items. See :obj:`~gi.repository.Gio.ListModel.get_item_type`.



      .. versionadded:: 4.8





   .. attribute:: props.mnemonic_modifiers
      :type: ~gi.repository.Gdk.ModifierType

      The modifiers that need to be pressed to allow mnemonics activation.







   .. attribute:: props.model
      :type: ~gi.repository.Gio.ListModel

      A list model to take shortcuts from.







   .. attribute:: props.n_items
      :type: int

      The number of items. See :obj:`~gi.repository.Gio.ListModel.get_n_items`.



      .. versionadded:: 4.8





   .. attribute:: props.scope
      :type: ~gi.repository.Gtk.ShortcutScope

      What scope the shortcuts will be handled in.