widget/nsIUserIdleService.idl

   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/. */
   6
   7 #include "nsISupports.idl"
   8 interface nsIObserver;
   9
  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  */
  18
  19 [scriptable, uuid(cc52f19a-63ae-4a1c-9cc3-e79eace0b471)]
  20 interface nsIUserIdleService : 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;
  31
  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      * nsIUserIdleService 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);
  56
  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
  68     /**
  69      * If true, the idle service is temporarily disabled, and all idle events
  70      * will be ignored.
  71      *
  72      * This should only be used in automation.
  73      */
  74     attribute boolean disabled;
  75 };
  76
  77 %{C++
  78     /**
  79      * Observer topic notification for idle window: OBSERVER_TOPIC_IDLE.
  80      * Observer topic notification for active window: OBSERVER_TOPIC_ACTIVE.
  81      */
  82
  83     #define OBSERVER_TOPIC_IDLE "idle"
  84     #define OBSERVER_TOPIC_ACTIVE "active"
  85     #define OBSERVER_TOPIC_IDLE_DAILY "idle-daily"
  86 %}