mozilla

Revision 92912 of nsIIdleService

  • Revision slug: XPCOM_Interface_Reference/nsIIdleService
  • Revision title: nsIIdleService
  • Revision id: 92912
  • Created:
  • Creator: trevorh
  • Is current revision? No
  • Comment Update to use IFSummary, minor cleanup; 175 words added, 102 words removed; page display name reset to default

Revision Content

{{ IFSummary("widget/public/nsIIdleService.idl", "nsISupports", "Scriptable", "1.9", "The idle service lets you monitor how long the user has been 'idle', that is they have not used their mouse or keyboard.", "1.9") }}

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 a 'back' notification when the user starts using their computer again.

Currently nsIIdleService implementations exist for Windows, Mac OS X, and Linux (via XScreenSaver).

Implemented by: @mozilla.org/widget/idleservice;1. To create an instance, use:

var idleService = Components.classes["@mozilla.org/widget/idleservice;1"]
                  .getService(Components.interfaces.nsIIdleService);

Method overview

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

Attributes

Attribute Type Description
idleTime unsigned long The amount of time in milliseconds that has passed since the last user activity. Can be 0 if there is no valid idle time to report (this can happen if the user never interacted with the browser at all, and if we are unable to poll for idle time manually). Read only.

Methods

addIdleObserver()

Add an observer to be notified when the user idles for some period of time, and when they get back from that.

  • 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 they get back, the observer topic is 'back'. The data parameter for the notification contains the current user idle time.
  • You can add the same observer twice.
  • 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.

{{ gecko_minversion_note("1.9.2", "Starting in Gecko 1.9.2, there is a once a day notification sent out if the user remains idle for an extended period: 'idle-daily'. The data parameter for the notification contains the current user idle time.") }}

void addIdleObserver(
  in nsIObserver observer,
  in unsigned long time
);
Parameters
observer
The {{ interface("nsIObserver") }} to be notified.
time
The amount of time in seconds the user should be idle before the observer should be notified.

removeIdleObserver()

Remove an observer registered with {{ manch("addIdleObserver") }}.

{{ 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
);
Parameters
observer
The {{ interface("nsIObserver") }} to be removed.
time
The amount of time they were listening for.

Example

Example 1

var idleService = Components.classes["@mozilla.org/widget/idleservice;1"]
                  .getService(Components.interfaces.nsIIdleService)
setTimeout(function() { alert(idleService.idleTime) }, 1000)
// if you don't use the mouse or the keyboard after running this snippet,
// you'll see a number around 1000 alerted.

Example 2

var idleService = Components.classes["@mozilla.org/widget/idleservice;1"]
                  .getService(Components.interfaces.nsIIdleService)
var idleObserver = {
  observe: function(subject, topic, data) {
    alert("topic: " + topic + "\ndata: " + data);
  }
};
idleService.addIdleObserver(idleObserver, 60); // one minute
// ...
// Don't forget to remove the observer using removeIdleObserver!
idleService.removeIdleObserver(idleObserver, 60);

Interwiki Language Links

{{ languages( { "ja": "ja/NsIIdleService", "pt": "pt/NsIIdleService" } ) }}

Revision Source

<p>{{ IFSummary("widget/public/nsIIdleService.idl", "nsISupports", "Scriptable", "1.9", "The idle service lets you monitor how long the user has been 'idle', that is they have not used their mouse or keyboard.", "1.9") }}</p>
<p>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 a 'back' notification when the user starts using their computer again.</p>
<p>Currently <code>nsIIdleService</code> implementations exist for Windows, Mac OS X, and Linux (via XScreenSaver).</p>
<p>Implemented by: <code>@mozilla.org/widget/idleservice;1</code>. To create an instance, use:</p>
<pre class="eval">var idleService = Components.classes["@mozilla.org/widget/idleservice;1"]
                  .getService(Components.interfaces.nsIIdleService);
</pre>
<h2 name="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>void <a href="#addIdleObserver()">addIdleObserver</a>(in nsIObserver observer, in unsigned long time);</code></td> </tr> <tr> <td><code>void <a href="#removeIdleObserver()">removeIdleObserver</a>(in nsIObserver observer, in unsigned long time);</code></td> </tr> </tbody>
</table>
<h2 name="Attributes">Attributes</h2>
<table class="standard-table"> <tbody> <tr> <td class="header">Attribute</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>idleTime</code></td> <td><code><a href="/en/unsigned_long" title="en/unsigned long">unsigned long</a></code></td> <td>The amount of time in milliseconds that has passed since the last user activity. Can be 0 if there is no valid idle time to report (this can happen if the user never interacted with the browser at all, and if we are unable to poll for idle time manually). <strong>Read only.</strong></td> </tr> </tbody>
</table>
<h2 name="Methods">Methods</h2>
<h3 name="addIdleObserver()">addIdleObserver()</h3>
<p>Add an observer to be notified when the user idles for some period of time, and when they get back from that.</p>
<ul> <li>The subject of the notification the observer will get is always the <code>nsIIdleService</code> itself. When the user goes idle, the observer topic is 'idle' and when they get back, the observer topic is 'back'. The data parameter for the notification contains the current user idle time.</li> <li>You can add the same observer twice.</li> <li>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.</li>
</ul>
<p>{{ gecko_minversion_note("1.9.2", "Starting in Gecko 1.9.2, there is a once a day notification sent out if the user remains idle for an extended period: 'idle-daily'. The data parameter for the notification contains the current user idle time.") }}</p>
<pre class="eval">void addIdleObserver(
  in nsIObserver observer,
  in unsigned long time
);
</pre>
<h6 name="Parameters">Parameters</h6>
<dl> <dt><code>observer</code></dt> <dd>The {{ interface("nsIObserver") }} to be notified.</dd> <dt><code>time</code></dt> <dd>The amount of time in seconds the user should be idle before the observer should be notified.</dd>
</dl>
<h3 name="removeIdleObserver()">removeIdleObserver()</h3>
<p>Remove an observer registered with {{ manch("addIdleObserver") }}.</p>
<p>{{ 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.") }}</p>
<pre class="eval">void removeIdleObserver(
  in nsIObserver observer,
  in unsigned long time
);
</pre>
<h6 name="Parameters">Parameters</h6>
<dl> <dt><code>observer</code></dt> <dd>The {{ interface("nsIObserver") }} to be removed.</dd> <dt><code>time</code></dt> <dd>The amount of time they were listening for.</dd>
</dl>
<h2 name="Example">Example</h2>
<h4 name="Example_1">Example 1</h4>
<pre class="brush: js">var idleService = Components.classes["@mozilla.org/widget/idleservice;1"]
                  .getService(Components.interfaces.nsIIdleService)
setTimeout(function() { alert(idleService.idleTime) }, 1000)
// if you don't use the mouse or the keyboard after running this snippet,
// you'll see a number around 1000 alerted.
</pre>
<h4 name="Example_2">Example 2</h4>
<pre class="brush: js">var idleService = Components.classes["@mozilla.org/widget/idleservice;1"]
                  .getService(Components.interfaces.nsIIdleService)
var idleObserver = {
  observe: function(subject, topic, data) {
    alert("topic: " + topic + "\ndata: " + data);
  }
};
idleService.addIdleObserver(idleObserver, 60); // one minute
// ...
// Don't forget to remove the observer using removeIdleObserver!
idleService.removeIdleObserver(idleObserver, 60);
</pre>
<p><span class="comment">Interwiki Language Links</span></p>
<p>{{ languages( { "ja": "ja/NsIIdleService", "pt": "pt/NsIIdleService" } ) }}</p>
Revert to this revision