first commit

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>