.. _org.freedesktop.portal.GlobalShortcuts:

======================================
 Global Shortcuts
======================================

-----------
Description
-----------

.. _org.freedesktop.portal.GlobalShortcuts Description:





.. _org.freedesktop.portal.GlobalShortcuts Properties:

----------
Properties
----------

.. _org.freedesktop.portal.GlobalShortcuts:version:

org.freedesktop.portal.GlobalShortcuts:version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    version readable u




.. _org.freedesktop.portal.GlobalShortcuts Methods:

-------
Methods
-------

.. _org.freedesktop.portal.GlobalShortcuts.CreateSession:

org.freedesktop.portal.GlobalShortcuts.CreateSession
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    CreateSession (
      IN options a{sv},
      OUT handle o
    )



Creates a global shortcuts session.

Supported keys in the ``options`` vardict include:

* ``handle_token`` (``s``)

  A string that will be used as the last element of the ``handle``. Must be a valid
  object path element. See the org.freedesktop.portal.Request documentation for
  more information about the ``handle``.

* ``session_handle_token`` (``s``)

  A string that will be used as the last element of the session handle. Must be a valid
  object path element. See the org.freedesktop.portal.Session documentation for
  more information about the session handle.

The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:

* ``session_handle`` (``s``)

  The session handle. An object path for the
  org.freedesktop.portal.Session object representing the created
  session.

  .. note::
    The ``session_handle`` is an object path that was erroneously implemented
    as ``s``. For backwards compatibility it will remain this type.



options
  Vardict with optional further information

handle
  Object path for the :ref:`org.freedesktop.portal.Request` object representing this call



.. _org.freedesktop.portal.GlobalShortcuts.BindShortcuts:

org.freedesktop.portal.GlobalShortcuts.BindShortcuts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    BindShortcuts (
      IN session_handle o,
      IN shortcuts a(sa{sv}),
      IN parent_window s,
      IN options a{sv},
      OUT request_handle o
    )



Bind the shortcuts. This will typically result the portal presenting a
dialog showing the shortcuts and allowing users to configure the shortcuts.
An application can only attempt bind shortcuts of a session once.

Each element of the ``shortcuts`` array is a tuple composed of a shortcut id,
and a vardict with the following keys:

* ``description`` (``s``)

  User-readable text describing what the shortcut does.

* ``preferred_trigger`` (``s``)

  The preferred shortcut trigger, defined as described by the
  `shortcuts XDG specification <https://specifications.freedesktop.org/shortcuts-spec/latest/>`__.
  Optional.

Supported keys in the ``options`` vardict include:

* ``handle_token`` (``s``)

  A string that will be used as the last element of the
  ``handle``. Must be a valid object path element. See the
  :ref:`org.freedesktop.portal.Request` documentation for more
  information about the ``handle``.

The following results get returned via the ref::`org.freedesktop.portal.Request::Response` signal:

* ``shortcuts`` (``a(sa{sv})``)

  The list of shortcuts which were bound. This is a subset of the
  shortcuts which were passed in from the ``shortcuts`` variable of this
  method (this includes the set of all shortcuts and the empty set).
  The keys they may contain are described below, and are different from
  the keys in the ``shortcuts`` variable of this method.

Each element of the ``shortcuts`` array returned by the
:ref:`org.freedesktop.portal.Request::Response` signal is a tuple composed of
a shortcut id, and a vardict with the following keys:

* ``description`` (``s``)

  User-readable text describing what the shortcut does.

* ``trigger_description`` (``s``)

  User-readable text describing how to trigger the shortcut for the
  client to render.



session_handle
  Object path for the :ref:`org.freedesktop.portal.Session` object representing the session

shortcuts
  The list of shortcuts to bind

parent_window
  Identifier for the application window, see :doc:`window-identifiers`

options
  Vardict with optional further information

request_handle
  Object path for the :ref:`org.freedesktop.portal.Request` object representing this call



.. _org.freedesktop.portal.GlobalShortcuts.ListShortcuts:

org.freedesktop.portal.GlobalShortcuts.ListShortcuts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    ListShortcuts (
      IN session_handle o,
      IN options a{sv},
      OUT request_handle o
    )



Lists all shortcuts.

Supported keys in the ``options`` vardict include:

* ``handle_token`` (``s``)

  A string that will be used as the last element of the
  ``handle``. Must be a valid object path element. See the
  :ref:`org.freedesktop.portal.Request` documentation for more
  information about the ``handle``.

The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:

* ``shortcuts`` (``a(sa{sv})``)

  A list of shortcuts.

  See the :ref:`org.freedesktop.portal.Request::Response` signal of the
  `org.freedesktop.portal.GlobalShortcuts.BindShortcuts`_ method for
  the list of supported properties of shortcuts.



session_handle
  Object path for the :ref:`org.freedesktop.portal.Session` object representing the session

options
  Vardict with optional further information

request_handle
  


.. _org.freedesktop.portal.GlobalShortcuts Signals:

-------
Signals
-------

.. _org.freedesktop.portal.GlobalShortcuts::Activated:

org.freedesktop.portal.GlobalShortcuts::Activated
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Activated (
      session_handle o,
      shortcut_id s,
      timestamp t,
      options a{sv}
    )



Notifies about a shortcut becoming active.



session_handle
  Session that requested the shortcut

shortcut_id
  the application-provided ID for the notification

timestamp
  the time of activation with millisecond granularity, with an undefined base.

options
  Vardict with optional further information



.. _org.freedesktop.portal.GlobalShortcuts::Deactivated:

org.freedesktop.portal.GlobalShortcuts::Deactivated
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Deactivated (
      session_handle o,
      shortcut_id s,
      timestamp t,
      options a{sv}
    )



Notifies that a shortcut is not active anymore.



session_handle
  Session that requested the shortcut

shortcut_id
  the application-provided ID for the notification

timestamp
  the time of deactivation with millisecond granularity, with an undefined base.

options
  Vardict with optional further information



.. _org.freedesktop.portal.GlobalShortcuts::ShortcutsChanged:

org.freedesktop.portal.GlobalShortcuts::ShortcutsChanged
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    ShortcutsChanged (
      session_handle o,
      shortcuts a(sa{sv})
    )



Indicates that the information associated with some of the shortcuts has changed.

See the :ref:`org.freedesktop.portal.Request::Response` signal of the
`org.freedesktop.portal.GlobalShortcuts.BindShortcuts`_ method for the
list of supported properties of shortcuts.



session_handle
  Session that requested the shortcut

shortcuts
  The different shortcuts that have been registered. See org.freedesktop.portal.GlobalShortcuts.


