The Tor Browser: widget/nsIIdleService.idl@b8a032363ba2

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

     1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-

     2  *

     3  * This Source Code Form is subject to the terms of the Mozilla Public

     4  * License, v. 2.0. If a copy of the MPL was not distributed with this

     5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

     7 #include "nsISupports.idl"

     8 interface nsIObserver;

    10 /**

    11  * This interface lets you monitor how long the user has been 'idle',

    12  * i.e. not used their mouse or keyboard. You can get the idle time directly,

    13  * but in most cases you will want to register an observer for a predefined

    14  * interval. The observer will get an 'idle' notification when the user is idle

    15  * for that interval (or longer), and receive an 'active' notification when the

    16  * user starts using their computer again.

    17  */

    19 [scriptable, uuid(cc52f19a-63ae-4a1c-9cc3-e79eace0b471)]

    20 interface nsIIdleService : nsISupports

    21 {

    22     /**

    23      * The amount of time in milliseconds that has passed

    24      * since the last user activity.

    25      *

    26      * If we do not have a valid idle time to report, 0 is returned

    27      * (this can happen if the user never interacted with the browser

    28      * at all, and if we are also unable to poll for idle time manually).

    29      */

    30     readonly attribute unsigned long idleTime;

    32     /**

    33      * Add an observer to be notified when the user idles for some period of

    34      * time, and when they get back from that.

    35      *

    36      * @param observer the observer to be notified

    37      * @param time the amount of time in seconds the user should be idle before

    38      *             the observer should be notified.

    39      *

    40      * @note

    41      * The subject of the notification the observer will get is always the

    42      * nsIIdleService itself.

    43      * When the user goes idle, the observer topic is "idle" and when he gets

    44      * back, the observer topic is "active".

    45      * The data param for the notification contains the current user idle time.

    46      *

    47      * @note

    48      * You can add the same observer twice.

    49      * @note

    50      * Most implementations need to poll the OS for idle info themselves,

    51      * meaning your notifications could arrive with a delay up to the length

    52      * of the polling interval in that implementation.

    53      * Current implementations use a delay of 5 seconds.

    54      */

    55     void addIdleObserver(in nsIObserver observer, in unsigned long time);

    57     /**

    58      * Remove an observer registered with addIdleObserver.

    59      * @param observer the observer that needs to be removed.

    60      * @param time the amount of time they were listening for.

    61      * @note

    62      * Removing an observer will remove it once, for the idle time you specify.

    63      * If you have added an observer multiple times, you will need to remove it

    64      * just as many times.

    65      */

    66     void removeIdleObserver(in nsIObserver observer, in unsigned long time);

    67 };

    69 %{C++

    70     /**

    71      * Observer topic notification for idle window: OBSERVER_TOPIC_IDLE.

    72      * Observer topic notification for active window: OBSERVER_TOPIC_ACTIVE.

    73      */

    75     #define OBSERVER_TOPIC_IDLE "idle"

    76     #define OBSERVER_TOPIC_ACTIVE "active"

    77     #define OBSERVER_TOPIC_IDLE_DAILY "idle-daily"

    78 %}

The Tor Browser / file revision