summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am27
-rw-r--r--doc/config.xsl6
-rw-r--r--doc/dbus-interface.xml479
-rw-r--r--doc/docbook.css18
-rw-r--r--doc/mate-screensaver.xml.in23
5 files changed, 553 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..a8851b7
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,27 @@
+NULL =
+
+SPEC_XML_FILES = \
+ mate-screensaver.xml \
+ dbus-interface.xml \
+ $(NULL)
+
+if DOCBOOK_DOCS_ENABLED
+
+htmldocdir = $(DOCDIR)/spec
+htmldoc_DATA = mate-screensaver.html
+
+mate-screensaver.html : dbus-interface.xml
+ $(XMLTO) html-nochunks -m config.xsl mate-screensaver.xml
+
+endif # DOCBOOK_DOCS_ENABLED
+
+EXTRA_DIST = \
+ mate-screensaver.xml.in \
+ config.xsl \
+ docbook.css \
+ $(SPEC_XML_FILES)
+ $(NULL)
+
+clean-local:
+ rm -f *~
+ rm -f mate-screensaver.html
diff --git a/doc/config.xsl b/doc/config.xsl
new file mode 100644
index 0000000..7aa9def
--- /dev/null
+++ b/doc/config.xsl
@@ -0,0 +1,6 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ version="1.0">
+ <xsl:param name="html.stylesheet" select="'docbook.css'"/>
+</xsl:stylesheet>
diff --git a/doc/dbus-interface.xml b/doc/dbus-interface.xml
new file mode 100644
index 0000000..d245bf1
--- /dev/null
+++ b/doc/dbus-interface.xml
@@ -0,0 +1,479 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+
+<chapter id="dbus-interface">
+ <title>DBUS Interface</title>
+ <para>
+ This API is currently unstable and is likely to change in the future.
+ </para>
+
+ <sect1 id="gs-intro">
+ <title>Introduction</title>
+ <para>
+ MATE Screensaver exposes a DBUS API for programs to obtain information about
+ the screensaver state and to interact with the screensaver in limited ways.
+ </para>
+ <para>
+ The following constants are used to uniquely refer to the MateScreensaver
+ object when making DBUS method calls:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>DBUS Service:</entry>
+ <entry><literal>org.mate.ScreenSaver</literal></entry>
+ </row>
+ <row>
+ <entry>DBUS Object Path:</entry>
+ <entry><literal>/org/mate/ScreenSaver</literal></entry>
+ </row>
+ <row>
+ <entry>DBUS Interface:</entry>
+ <entry><literal>org.mate.ScreenSaver</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect1>
+
+ <sect1 id="gs-methods">
+ <title>Methods</title>
+ <para>
+ These are the DBUS methods.
+ </para>
+
+ <sect2 id="gs-method-Lock">
+ <title>
+ <literal>Lock</literal>
+ </title>
+ <para>
+ Request that the screen be locked. This bypasses all Inhibit requests.
+ </para>
+ </sect2>
+
+ <sect2 id="gs-method-Cycle">
+ <title>
+ <literal>Cycle</literal>
+ </title>
+ <para>
+ Request that the screen saver theme be restarted and, if applicable,
+ switch to the next one in the list.
+ </para>
+ </sect2>
+
+ <sect2 id="gs-method-SimulateUserActivity">
+ <title>
+ <literal>SimulateUserActivity</literal>
+ </title>
+ <para>
+ Simulate user activity. If the screensaver is activated this
+ will attempt to deactivate and authentication will be
+ requested if necessary. If the screensaver is not activated
+ then the idle timers will be reset.
+ </para>
+ </sect2>
+
+ <sect2 id="gs-method-Inhibit">
+ <title>
+ <literal>Inhibit</literal>
+ </title>
+ <para>
+ Request that saving the screen due to system idleness be blocked until
+ UnInhibit is called or the calling process exits.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Direction</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>in</entry>
+ <entry>string</entry>
+ <entry>the application name, e.g. "totem"</entry>
+ </row>
+ <row>
+ <entry>in</entry>
+ <entry>string</entry>
+ <entry>the localized reason to inhibit, e.g. "playing movie"</entry>
+ </row>
+ <row>
+ <entry>out</entry>
+ <entry>unsigned integer</entry>
+ <entry>the cookie</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ A cookie is a random, unique, non-zero UINT32 used to identify the inhibit request.
+ </para>
+ </sect2>
+
+ <sect2 id="gs-method-UnInhibit">
+ <title>
+ <literal>UnInhibit</literal>
+ </title>
+ <para>
+ Cancel a previous call to Inhibit() identified by the cookie.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Direction</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>in</entry>
+ <entry>unsigned integer</entry>
+ <entry>the cookie</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="gs-method-Throttle">
+ <title>
+ <literal>Throttle</literal>
+ </title>
+ <para>
+ Request that running themes while the screensaver is active be blocked
+ until UnThrottle is called or the calling process exits.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Direction</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>in</entry>
+ <entry>string</entry>
+ <entry>the application name, e.g. "mate-power-manager"</entry>
+ </row>
+ <row>
+ <entry>in</entry>
+ <entry>string</entry>
+ <entry>the localized reason to inhibit, e.g. "on battery power"</entry>
+ </row>
+ <row>
+ <entry>out</entry>
+ <entry>unsigned integer</entry>
+ <entry>the cookie</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ A cookie is a random, unique, non-zero UINT32 used to identify the throttle request.
+ </para>
+ </sect2>
+
+ <sect2 id="gs-method-UnThrottle">
+ <title>
+ <literal>UnThrottle</literal>
+ </title>
+ <para>
+ Cancel a previous call to Throttle() identified by the cookie.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Direction</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>in</entry>
+ <entry>unsigned integer</entry>
+ <entry>the cookie</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="gs-method-SetActive">
+ <title>
+ <literal>SetActive</literal>
+ </title>
+ <para>
+ Request a change in the state of the screensaver.
+ Set to TRUE to request that the screensaver activate.
+ Active means that the screensaver has blanked the screen and may run a
+ graphical theme. This does not necessary mean that the screen is locked.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Direction</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>in</entry>
+ <entry>boolean</entry>
+ <entry>TRUE to request activation, FALSE to request deactivation</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="gs-method-GetActive">
+ <title>
+ <literal>GetActive</literal>
+ </title>
+ <para>
+ Returns the value of the current state of activity. See SetActive().
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Direction</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>out</entry>
+ <entry>boolean</entry>
+ <entry>Activation state</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="gs-method-GetActiveTime">
+ <title>
+ <literal>GetActiveTime</literal>
+ </title>
+ <para>
+ Returns the number of seconds that the screensaver has been active.
+ Returns zero if the screensaver is not active.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Direction</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>out</entry>
+ <entry>unsigned integer</entry>
+ <entry>Active time in seconds</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="gs-method-GetSessionIdle">
+ <title>
+ <literal>GetSessionIdle</literal>
+ </title>
+ <para>
+ Returns the value of the current state of session idleness.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Direction</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>out</entry>
+ <entry>boolean</entry>
+ <entry>If the session is idle</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="gs-method-GetSessionIdleTime">
+ <title>
+ <literal>GetSessionIdleTime</literal>
+ </title>
+ <para>
+ Returns the number of seconds that the session has been idle.
+ Returns zero if the session is not idle.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Direction</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>out</entry>
+ <entry>unsigned integer</entry>
+ <entry>Idle time in seconds</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+ </sect1>
+
+ <sect1 id="gs-signals">
+ <title>Signals</title>
+ <para>
+ These are the DBUS signals.
+ </para>
+
+ <sect2 id="gs-signal-ActiveChanged">
+ <title>
+ <literal>ActiveChanged</literal>
+ </title>
+ <para>
+ See method GetActive().
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Direction</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>out</entry>
+ <entry>boolean</entry>
+ <entry>Returns the value of the current state of activity.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="gs-signal-SessionIdleChanged">
+ <title>
+ <literal>SessionIdleChanged</literal>
+ </title>
+ <para>
+ See method GetActive().
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Direction</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>out</entry>
+ <entry>boolean</entry>
+ <entry>Returns the value of the current state of activity.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="gs-signal-AuthenticationRequestBegin">
+ <title>
+ <literal>AuthenticationRequestBegin</literal>
+ </title>
+ <para>
+ Emitted before an authentication request
+ </para>
+ </sect2>
+
+ <sect2 id="gs-signal-AuthenticationRequestEnd">
+ <title>
+ <literal>AuthenticationRequestEnd</literal>
+ </title>
+ <para>
+ Emitted after an authentication request
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="gs-examples">
+ <title>Examples</title>
+ <para>
+ You can get the number of seconds the screensaver has been active by
+ running the following:
+ </para>
+ <screen>
+dbus-send --session \
+ --dest=org.mate.ScreenSaver \
+ --type=method_call \
+ --print-reply \
+ --reply-timeout=20000 \
+ /org/mate/ScreenSaver \
+ org.mate.ScreenSaver.GetSessionIdleTime
+ </screen>
+ <para>
+ You can activate the screensaver like so:
+ </para>
+ <screen>
+dbus-send --session \
+ --dest=org.mate.ScreenSaver \
+ --type=method_call \
+ --print-reply \
+ --reply-timeout=20000 \
+ /org/mate/ScreenSaver \
+ org.mate.ScreenSaver.SetActive \
+ boolean:true
+ </screen>
+
+ <para>
+ You can monitor screensaver changes:
+ </para>
+ <screen>
+dbus-monitor --session \
+ "type='signal',interface='org.mate.ScreenSaver'"
+ </screen>
+
+ <para>
+ Or watch for a specific screensaver signal:
+ </para>
+ <screen>
+dbus-monitor --session \
+ "type='signal',interface='org.mate.ScreenSaver',member='SessionIdleChanged'"
+ </screen>
+ </sect1>
+
+</chapter>
diff --git a/doc/docbook.css b/doc/docbook.css
new file mode 100644
index 0000000..9a0e72a
--- /dev/null
+++ b/doc/docbook.css
@@ -0,0 +1,18 @@
+body {
+ font-family: luxi sans,sans-serif;
+}
+
+table {
+ border: solid 1pt;
+ border-collapse: collapse;
+}
+
+th {
+ background: #eeeeee;
+ padding: 5px;
+}
+
+td {
+ border: solid 1pt;
+ padding: 5px;
+}
diff --git a/doc/mate-screensaver.xml.in b/doc/mate-screensaver.xml.in
new file mode 100644
index 0000000..51a747a
--- /dev/null
+++ b/doc/mate-screensaver.xml.in
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<book id="index">
+ <bookinfo>
+ <title>MATE Screensaver @VERSION@ Documentation</title>
+ <releaseinfo>Version @VERSION@</releaseinfo>
+ <date>6 June, 2006</date>
+ <authorgroup>
+ <author>
+ <firstname>William Jon</firstname>
+ <surname>McCann</surname>
+ <affiliation>
+ <address>
+ <email>[email protected]</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+ </bookinfo>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dbus-interface.xml" />
+
+</book>