widget/nsIIdleService.idl
author Noemi Erli <nerli@mozilla.com>
Tue, 26 Feb 2019 03:43:12 +0200
changeset 461110 3c030119c0dcf447dd1afe7165b2d6846a0bc7f0
parent 459451 1c6224158f64ae4291133faa56f538413092ff98
child 475212 020c8c871c0d3b3920fe95935cfef06501976c0f
permissions -rw-r--r--
Backed out 10 changesets (bug 1505871) for wrench bustages CLOSED TREE Backed out changeset 045ab0ec3613 (bug 1505871) Backed out changeset 6486435a048d (bug 1505871) Backed out changeset 9be871042749 (bug 1505871) Backed out changeset 0007feaf988d (bug 1505871) Backed out changeset 3cb8fb01e77e (bug 1505871) Backed out changeset 2fff213d97e3 (bug 1505871) Backed out changeset 1ad20d485eca (bug 1505871) Backed out changeset 0fd8742fa662 (bug 1505871) Backed out changeset 1899600a7985 (bug 1505871) Backed out changeset f9578d20e54e (bug 1505871)

/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
interface nsIObserver;

/**
 * This interface lets you monitor how long the user has been 'idle',
 * i.e. not used their mouse or keyboard. You can get the idle time directly,
 * but in most cases you will want to register an observer for a predefined
 * interval. The observer will get an 'idle' notification when the user is idle
 * for that interval (or longer), and receive an 'active' notification when the
 * user starts using their computer again.
 */

[scriptable, uuid(cc52f19a-63ae-4a1c-9cc3-e79eace0b471)]
interface nsIIdleService : nsISupports
{
    /**
     * The amount of time in milliseconds that has passed
     * since the last user activity.
     *
     * If we do not have a valid idle time to report, 0 is returned
     * (this can happen if the user never interacted with the browser
     * at all, and if we are also unable to poll for idle time manually).
     */
    readonly attribute unsigned long idleTime;

    /**
     * Add an observer to be notified when the user idles for some period of
     * time, and when they get back from that.
     *
     * @param observer the observer to be notified
     * @param time the amount of time in seconds the user should be idle before
     *             the observer should be notified.
     *
     * @note
     * The subject of the notification the observer will get is always the
     * nsIIdleService itself.
     * When the user goes idle, the observer topic is "idle" and when he gets
     * back, the observer topic is "active".
     * The data param for the notification contains the current user idle time.
     *
     * @note
     * You can add the same observer twice.
     * @note
     * Most implementations need to poll the OS for idle info themselves,
     * meaning your notifications could arrive with a delay up to the length
     * of the polling interval in that implementation.
     * Current implementations use a delay of 5 seconds.
     */
    void addIdleObserver(in nsIObserver observer, in unsigned long time);

    /**
     * Remove an observer registered with addIdleObserver.
     * @param observer the observer that needs to be removed.
     * @param time the amount of time they were listening for.
     * @note
     * Removing an observer will remove it once, for the idle time you specify. 
     * If you have added an observer multiple times, you will need to remove it
     * just as many times.
     */
    void removeIdleObserver(in nsIObserver observer, in unsigned long time);

    /**
     * If true, the idle service is temporarily disabled, and all idle events
     * will be ignored.
     *
     * This should only be used in automation.
     */
    attribute boolean disabled;
};

%{C++  
    /**
     * Observer topic notification for idle window: OBSERVER_TOPIC_IDLE.
     * Observer topic notification for active window: OBSERVER_TOPIC_ACTIVE.
     */
    
    #define OBSERVER_TOPIC_IDLE "idle"
    #define OBSERVER_TOPIC_ACTIVE "active"
    #define OBSERVER_TOPIC_IDLE_DAILY "idle-daily"
%}