Skip to content

Latest commit

 

History

History
333 lines (187 loc) · 7.03 KB

commands.rst

File metadata and controls

333 lines (187 loc) · 7.03 KB
Raw

commands API

The commands API is more or less the same as the Firefox commands API and allows to define key shortcuts to trigger certain actions.

Use the commands API to add keyboard shortcuts that trigger actions in your extension, for example opening one of the action popups or sending a command to the extension.

.. rst-class:: api-main-section

Manifest file properties

.. api-member::
   :name: [``commands``]
   :type: (object, optional)

   A *dictionary object* defining one or more commands as *name-value* pairs, the *name* being the name of the command and the *value* being a :ref:`commands.CommandsShortcut`. The *name* may also be one of the following built-in special shortcuts:

    * :value:`_execute_browser_action`

    * :value:`_execute_compose_action`

    * :value:`_execute_message_display_action`

   Example:

   .. literalinclude:: includes/commands/manifest.json
     :language: JSON




.. rst-class:: api-permission-info

Note

A manifest entry named commands is required to use messenger.commands.*.

.. rst-class:: api-main-section

Functions

getAll()

.. api-section-annotation-hack::

Returns all the registered extension commands for this extension and their shortcut (if active).

.. api-header::
   :label: Return type (`Promise`_)


   .. api-member::
      :type: array of :ref:`commands.Command`


   .. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

reset(name)

.. api-section-annotation-hack::

Reset a command's details to what is specified in the manifest.

.. api-header::
   :label: Parameters


   .. api-member::
      :name: ``name``
      :type: (string)

      The name of the command.

update(detail)

.. api-section-annotation-hack::

Update the details of an already defined command.

.. api-header::
   :label: Parameters


   .. api-member::
      :name: ``detail``
      :type: (object)

      The new details for the command.

      .. api-member::
         :name: ``name``
         :type: (string)

         The name of the command.


      .. api-member::
         :name: [``description``]
         :type: (string, optional)

         The description for the command.


      .. api-member::
         :name: [``shortcut``]
         :type: (string, optional)

         An empty string to clear the shortcut, or a string matching the format defined by the `MDN page of the commands API <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands#shortcut_values>`__  to set a new shortcut key. If the string does not match this format, the function throws an error.




.. rst-class:: api-main-section

Events

onChanged

.. api-section-annotation-hack::

Fired when a registered command's shortcut is changed.

.. api-header::
   :label: Parameters for onChanged.addListener(listener)


   .. api-member::
      :name: ``listener(changeInfo)``

      A function that will be called when this event occurs.



.. api-header::
   :label: Parameters passed to the listener function


   .. api-member::
      :name: ``changeInfo``
      :type: (object)

      .. api-member::
         :name: ``name``
         :type: (string)

         The name of the shortcut.


      .. api-member::
         :name: ``newShortcut``
         :type: (string)

         The new shortcut active for this command, or blank if not active.


      .. api-member::
         :name: ``oldShortcut``
         :type: (string)

         The old shortcut which is no longer active for this command, or blank if the shortcut was previously inactive.

onCommand

.. api-section-annotation-hack::

Fired when a registered command is activated using a keyboard shortcut. This is a user input event handler. For asynchronous listeners some restrictions apply.

.. api-header::
   :label: Parameters for onCommand.addListener(listener)


   .. api-member::
      :name: ``listener(command, tab)``

      A function that will be called when this event occurs.



.. api-header::
   :label: Parameters passed to the listener function


   .. api-member::
      :name: ``command``
      :type: (string)


   .. api-member::
      :name: ``tab``
      :type: (:ref:`tabs.Tab`)
      :annotation: -- [Added in TB 106]

      The details of the active tab while the command occurred.



.. rst-class:: api-main-section

Types

Command

.. api-section-annotation-hack::


.. api-header::
   :label: object


   .. api-member::
      :name: [``description``]
      :type: (string, optional)

      The Extension Command description


   .. api-member::
      :name: [``name``]
      :type: (string, optional)

      The name of the Extension Command


   .. api-member::
      :name: [``shortcut``]
      :type: (string, optional)

      The shortcut active for this command, or blank if not active.

CommandsShortcut

.. api-section-annotation-hack::


.. api-header::
   :label: object


   .. api-member::
      :name: [``description``]
      :type: (string, optional)


   .. api-member::
      :name: [``suggested_key``]
      :type: (object, optional)

      .. api-member::
         :name: [``default``]
         :type: (:ref:`commands.KeyName`, optional)

         Default key combination.


      .. api-member::
         :name: [``linux``]
         :type: (:ref:`commands.KeyName`, optional)

         Key combination on Linux.


      .. api-member::
         :name: [``mac``]
         :type: (:ref:`commands.KeyName`, optional)

         Key combination on Mac.


      .. api-member::
         :name: [``windows``]
         :type: (:ref:`commands.KeyName`, optional)

         Key combination on Windows.

KeyName

.. api-section-annotation-hack::

Definition of a shortcut, for example Alt+F5. The string must match the shortcut format as defined by the MDN page of the commands API.

.. api-header::
   :label: string