Skip to content

Latest commit

 

History

History
271 lines (152 loc) · 6.45 KB

messageDisplay.rst

File metadata and controls

271 lines (152 loc) · 6.45 KB
Raw

≡ messageDisplay API

≡ Related examples on Github

messageDisplay API

A message can be displayed in either a 3-pane tab, a tab of its own, or in a window of its own. All are referenced by tabId in this API. Display windows are considered to have exactly one tab, which has limited functionality compared to tabs from the main window.

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

Note

The permission messagesRead is required to use messenger.messageDisplay.*.

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

Functions

getDisplayedMessage([tabId])

.. api-section-annotation-hack::

Gets the currently displayed message in the specified tab (even if the tab itself is currently not visible), or the currently active tab. It returns null if no messages are displayed, or if multiple messages are displayed.

.. api-header::
   :label: Parameters


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



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


   .. api-member::
      :type: :ref:`messages.MessageHeader` or null


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


.. api-header::
   :label: Required permissions

   - :permission:`messagesRead`

getDisplayedMessages([tabId])

.. api-section-annotation-hack:: -- [Added in TB 81, backported to TB 78.4.0]

Gets an array of the currently displayed messages in the specified tab (even if the tab itself is currently not visible), or the currently active tab. The array is empty if no messages are displayed.

.. api-header::
   :label: Parameters


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



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


   .. api-member::
      :type: array of :ref:`messages.MessageHeader`


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


.. api-header::
   :label: Required permissions

   - :permission:`messagesRead`

open(openProperties)

.. api-section-annotation-hack:: -- [Added in TB 102]

Opens a message in a new tab or in a new window.

.. api-header::
   :label: Parameters


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

      Settings for opening the message. Exactly one of messageId, headerMessageId or file must be specified.

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

         Whether the new tab should become the active tab in the window. Only applicable to messages opened in tabs.


      .. api-member::
         :name: [``file``]
         :type: (`File <https://developer.mozilla.org/en-US/docs/Web/API/File>`__, optional)

         The DOM file object of a message to be opened.


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

         The headerMessageId of a message to be opened. Will throw an *ExtensionError*, if the provided :value:`headerMessageId` is unknown or invalid. Not supported for external messages.


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

         Where to open the message. If not specified, the users preference is honoured.

         Supported values:

         .. api-member::
            :name: :value:`tab`

         .. api-member::
            :name: :value:`window`


      .. api-member::
         :name: [``messageId``]
         :type: (:ref:`messages.MessageId`, optional)

         The id of a message to be opened. Will throw an *ExtensionError*, if the provided :value:`messageId` is unknown or invalid.


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

         The id of the window, where the new tab should be created. Defaults to the current window. Only applicable to messages opened in tabs.




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


   .. api-member::
      :type: :ref:`tabs.Tab`


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


.. api-header::
   :label: Required permissions

   - :permission:`messagesRead`


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

Events

onMessageDisplayed

.. api-section-annotation-hack::

Fired when a message is displayed, whether in a 3-pane tab, a message tab, or a message window.

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


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

      A function that will be called when this event occurs.



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


   .. api-member::
      :name: ``tab``
      :type: (:ref:`tabs.Tab`)


   .. api-member::
      :name: ``message``
      :type: (:ref:`messages.MessageHeader`)



.. api-header::
   :label: Required permissions

   - :permission:`messagesRead`

onMessagesDisplayed

.. api-section-annotation-hack:: -- [Added in TB 81, backported to TB 78.4.0]

Fired when either a single message is displayed or when multiple messages are displayed, whether in a 3-pane tab, a message tab, or a message window.

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


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

      A function that will be called when this event occurs.



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


   .. api-member::
      :name: ``tab``
      :type: (:ref:`tabs.Tab`)


   .. api-member::
      :name: ``messages``
      :type: (array of :ref:`messages.MessageHeader`)



.. api-header::
   :label: Required permissions

   - :permission:`messagesRead`