≡ idle API
Hint
The idle API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.
Use the browser.idle API to detect when the machine's idle state changes.
.. rst-class:: api-main-section
The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.
Hint
Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.
.. api-member:: :name: :permission:`idle` :refid: idle-permission-idle :refname: idle Grant access to some or all methods of the idle API.
.. rst-class:: api-permission-info
Note
The permission idle is required to use messenger.idle.*.
.. rst-class:: api-main-section
.. api-section-annotation-hack:: -- [Added in TB 45]
Returns "idle" if the user has not generated any input for a specified number of seconds, or "active" otherwise.
Note
Before version 51, Thunderbird always reports 'active'. After version 51, Thunderbird reports 'active' or 'idle' as appropriate.
.. api-header::
:label: Parameters
.. _idle.query^state.detection^interval^in^seconds:
.. api-member::
:name: ``detectionIntervalInSeconds``
:refid: idle-query-state-detection-interval-in-seconds
:refname: detectionIntervalInSeconds
:type: (integer)
The system is considered idle if detectionIntervalInSeconds seconds have elapsed since the last user input detected.
.. api-header::
:label: Return type (`Promise`_)
.. _idle.query^state.returns:
.. api-member::
:refid: idle-query-state-returns
:refname: _returns
:type: :ref:`idle.^idle^state`
.. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
.. api-header:: :label: Required permissions - :permission:`idle`
.. api-section-annotation-hack:: -- [Added in TB 51]
Sets the interval, in seconds, used to determine when the system is in an idle state for onStateChanged events. The default interval is 60 seconds.
.. api-header::
:label: Parameters
.. _idle.set^detection^interval.interval^in^seconds:
.. api-member::
:name: ``intervalInSeconds``
:refid: idle-set-detection-interval-interval-in-seconds
:refname: intervalInSeconds
:type: (integer)
Threshold, in seconds, used to determine when the system is in an idle state.
.. api-header:: :label: Required permissions - :permission:`idle`
.. rst-class:: api-main-section
.. api-section-annotation-hack:: -- [Added in TB 51]
Fired when the system changes to an active or idle state. The event fires with "idle" if the the user has not generated any input for a specified number of seconds, and "active" when the user generates input on an idle system.
.. api-header::
:label: Parameters for onStateChanged.addListener(listener)
.. _idle.on^state^changed.listener(new^state):
.. api-member::
:name: ``listener(newState)``
:refid: idle-on-state-changed-listener-new-state
:refname: listener(newState)
A function that will be called when this event occurs.
.. api-header::
:label: Parameters passed to the listener function
.. _idle.on^state^changed.new^state:
.. api-member::
:name: ``newState``
:refid: idle-on-state-changed-new-state
:refname: newState
:type: (:ref:`idle.^idle^state`)
.. api-header:: :label: Required permissions - :permission:`idle`
.. rst-class:: api-main-section
.. api-section-annotation-hack:: -- [Added in TB 45]
.. api-header::
:label: `string`
.. container:: api-member-node
.. container:: api-member-description-only
Supported values:
.. _idle.^idle^state.active:
.. api-member::
:name: :value:`active`
:refid: idle-idle-state-active
:refname: active
.. _idle.^idle^state.idle:
.. api-member::
:name: :value:`idle`
:refid: idle-idle-state-idle
:refname: idle