diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 27 | ||||
| -rw-r--r-- | doc/config.xsl | 6 | ||||
| -rw-r--r-- | doc/dbus-interface.xml | 479 | ||||
| -rw-r--r-- | doc/docbook.css | 18 | ||||
| -rw-r--r-- | doc/mate-screensaver.xml.in | 23 |
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> |