added module

1 files changed, 342 insertions, 0 deletions

diff --git a/systemtray/systemtray-spec.xml b/systemtray/systemtray-spec.xml
new file mode 100644
index 0000000..b5f1568
--- /dev/null
+++ b/systemtray/systemtray-spec.xml
@@ -0,0 +1,342 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<article id="index">
+  <articleinfo>
+    <title>System Tray Protocol Specification</title>
+    <releaseinfo>Version 0.1</releaseinfo>
+    <date>19 September 2002</date>
+    <authorgroup>
+      <author>
+	<firstname>Havoc</firstname>
+	<surname>Pennington</surname>
+	<affiliation>
+	  <address>
+	    <email>hp@redhat.com</email>
+	  </address>
+	</affiliation>
+      </author>
+    </authorgroup>
+  </articleinfo>
+
+  <sect1 id="overview">
+    <title>Overview</title>
+    <para>
+     The "system tray" is an application running on a given X screen
+     that can display small icons provided by running
+     applications. Windows XP calls this feature the "notification area."
+     <footnote><para>According to the MSDN documentation for the
+     <literal>Shell_NotifyIcon()</literal> function,
+     "The taskbar notification area is sometimes erroneously called
+     the 'tray.'" So presumably "notification area" is the official
+     term on Windows. Parts of the docs also call it the "status
+     area."</para></footnote> Inspired by KDE, this specification 
+     uses the term "system tray."
+    </para>
+    <para>
+     From a UI standpoint, the system tray is normally used for
+     transient icons that indicate some special state, while
+     full-blown "applets" are used for permanent dock/panel
+     features. For example, a system tray icon might appear to tell
+     the user that they have new mail, or have an incoming instant
+     message, or something along those lines.
+    </para>
+    <para>
+     The basic idea is that creating an icon in the notification 
+     area is less annoying than popping up a dialog. However it's 
+     also harder to notice, so Windows XP adds a feature allowing
+     tray icons to pop up small message balloons. (Users can disable
+     these via a hidden registry setting.) This specification 
+     also supports the balloon feature.
+    </para>
+  </sect1>
+
+  <sect1 id="definitions">
+    <title>Definitions</title>
+    <variablelist>
+      <varlistentry>
+	<term>System tray</term>
+	<listitem>
+	  <para>
+            The system tray is an X client which owns a special 
+            manager selection on a given screen and provides
+            container windows.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Selection owner window</term>
+	<listitem>
+	  <para>
+            The selection owner window is the window belonging to the
+            System Tray that owns the manager selection (as in
+            <literal>XGetSelectionOwner()</literal>/<literal>XSetSelectionOwner()</literal>.
+            Note that this probably is not the same window that's used 
+            to contain the system tray icons.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Tray icon</term>
+	<listitem>
+	  <para>
+            The tray icon is a window to be embedded in the
+            system tray.
+	  </para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </sect1>
+
+  <sect1 id="locating">
+    <title>Locating the system tray</title>
+    <para>
+      On startup, the system tray must acquire a manager selection
+      called <literal>_NET_SYSTEM_TRAY_Sn</literal>, replacing
+      <literal>n</literal> with the screen number the tray wants to
+      use. The conventions for manager selections are defined in the 
+      ICCCM.
+    </para>
+    <para>
+      Because the selection owner window should be destroyed when the
+      manager selection is lost, normally the selection owner window
+      will not be the same as any of the user-visible windows provided
+      by the system tray.
+    </para>
+    <para>
+      A system tray that fails to get the selection or loses the 
+      selection should assume that another system tray is running, 
+      and let the selection owner handle tray icons.
+    </para>
+    <para>
+      An application wishing to provide an icon to the system tray
+      should first locate the system tray by requesting the owner
+      window of the manager selection. If the manager selection has no
+      owner, clients may use the method described in the ICCCM
+      (watching for a <literal>MANAGER</literal> client message) to be
+      notified when a system tray appears. 
+    </para>
+  </sect1>
+
+  <sect1 id="messages">
+    <title>Opcode messages</title>
+      <para>
+        Tray icons can send "opcodes" to 
+        the system tray. These are X client messages, sent with
+        <literal>NoEventMask</literal>, a
+        <literal>message_type</literal> of
+        <literal>_NET_SYSTEM_TRAY_OPCODE</literal>, and format 32. 
+        The first data field in the message is a timestamp (the stamp
+        of the current event, if available, otherwise CurrentTime).
+        The second data field is an integer indicating the op code 
+        of the message:
+         <programlisting>
+#define SYSTEM_TRAY_REQUEST_DOCK    0
+#define SYSTEM_TRAY_BEGIN_MESSAGE   1
+#define SYSTEM_TRAY_CANCEL_MESSAGE  2
+         </programlisting>
+        The content remaining three data fields depends on the type of
+        message being sent. If they are unused by a particular
+        message, they should always be set to 0.
+      </para>
+      <para> 
+        Here is an example of how to send a client message:
+      <programlisting><!--
+-->#include &lt;X11/Xlib.h&gt;
+
+void send_message(
+     Display* dpy, /* display */
+     Window w,     /* sender (tray icon window) */
+     long message, /* message opcode */
+     long data1    /* message data 1 */
+     long data2    /* message data 2 */
+     long data3    /* message data 3 */
+){
+    XEvent ev;
+  
+    memset(&amp;ev, 0, sizeof(ev));
+    ev.xclient.type = ClientMessage;
+    ev.xclient.window = w;
+    ev.xclient.message_type = XInternAtom (dpy, "_NET_SYSTEM_TRAY_OPCODE", False );
+    ev.xclient.format = 32;
+    ev.xclient.data.l[0] = x_time;
+    ev.xclient.data.l[1] = message;
+    ev.xclient.data.l[2] = data1;
+    ev.xclient.data.l[3] = data2;
+    ev.xclient.data.l[4] = data3;
+
+    trap_errors();
+    XSendEvent(dpy, w, False, NoEventMask, &amp;ev);
+    XSync(dpy, False);
+    if (untrap_errors()) {
+	/* Handle failure */
+    }
+}<!--
+    --></programlisting>
+
+     </para>
+
+  </sect1>
+
+  <sect1 id="docking">
+    <title>Docking a tray icon</title>
+    <para>
+      A tray icon must support the "client" or "plug" side of the
+      XEMBED specification. XEMBED is a protocol for cross-toolkit
+      widget embedding.
+    </para>
+    <para>
+      To begin the docking process, the tray icon application sends
+      a client message event to the manager selection owner window, 
+      as described in <xref linkend="messages"/>. This event 
+      should contain the <literal>SYSTEM_TRAY_REQUEST_DOCK</literal>
+      opcode, <literal>xclient.data.l[2]</literal> should contain 
+      the X window ID of the tray icon to be docked.
+    </para>
+    <para>
+      At this point the "embedding life cycle" explained in the XEMBED
+      specification begins. The XEMBED specification explains how the 
+      embedding application will interact with the embedded tray 
+      icon, and how the embedder/embedded relationship may be ended.
+    </para>
+    <para>
+      Tray icons may be assigned any size by the system tray, and 
+      should do their best to cope with any size effectively.
+    </para>
+  </sect1>
+
+  <sect1 id="hints">
+    <title>Tray icon hints</title>
+    <para>
+     Tray icons should set the following hints to help the system 
+     tray provide a nice user interface. The name and icon hints 
+     are used if the system tray needs to refer to a tray icon;
+     for example, the system tray may present a list of tray 
+     icons and let the user reorder them or change their properties.
+    </para>
+
+    <sect2><title>_NET_WM_NAME</title>
+      <programlisting><![CDATA[
+_NET_WM_NAME, UTF8_STRING
+]]></programlisting>
+	<para>
+         This hint should be set as it would be for a normal toplevel
+         window, as defined in the Extended Window Manager Hints
+         Specification (EWMH).  The hint MUST be in UTF-8 encoding. It
+         provides a human-readable, localized name for the tray icon.
+	</para>
+    </sect2>
+
+    <sect2><title>WM_CLASS</title>
+      <programlisting><![CDATA[
+WM_CLASS, STRING
+]]></programlisting>
+	<para>
+         This hint should be set as it would be for a normal toplevel
+         window, as defined in the ICCCM. The system tray can use it
+         to distinguish different kinds of tray icon. This is useful
+         for example if the system tray wants to save and restore the
+         positions of the icons in the tray.
+	</para>
+    </sect2>
+
+	<sect2>
+		<title>_NET_WM_ICON</title>
+		<programlisting><![CDATA[
+_NET_WM_ICON CARDINAL[][2+n]/32
+]]></programlisting>
+		<para>
+         This hint should be set as it would be for a normal toplevel
+         window, as defined in the Extended Window Manager Hints
+         Specification (EWMH). See that specification for the format
+         of the icon data.
+		</para>
+	</sect2>
+
+  </sect1>
+
+  <sect1 id="balloon">
+    <title>Balloon messages</title>
+    <para>
+      Tray icons may ask the system tray to display a balloon message 
+      to the user. The system tray coordinates balloon messages 
+      to ensure that they have a consistent look-and-feel, and to 
+      avoid displaying multiple balloon messages at once.
+    </para>
+    <para>
+      A balloon message is a short text message to be displayed to 
+      the user. The message may have a timeout; if so, the message
+      will be taken down after the timeout expires. Messages are
+      displayed in a queue, as only one can appear at a time; 
+      if a message has a timeout, the timer begins when the message
+      is first displayed. Users may be allowed to close messages at
+      any time, and may be allowed to disable all message display.
+    </para>
+    <para>
+      System trays may display balloon messages in any way they 
+      see fit; for example, instead of popping up a balloon, they 
+      could choose to put a special indicator around icons with 
+      pending messages, and display the message on mouseover.
+    </para>
+    <para>
+      Balloon messages are sent from the tray icon to the system tray
+      selection owner window as a series of client messages. The first
+      client message is an opcode message, and contains the usual timestamp,
+      and the op code <literal>SYSTEM_TRAY_BEGIN_MESSAGE</literal>.
+      <literal>xclient.data.l[2]</literal> contains the timeout in
+      thousandths of a second or zero for infinite timeout,
+      <literal>xclient.data.l[3]</literal> contains the length 
+      of the message string in bytes, not including any nul bytes, and 
+      <literal>xclient.data.l[4]</literal> contains an ID number
+      for the message. This ID number should never be reused by 
+      the same tray icon. (The simplest way to generate the ID number 
+      is to increment it with each message sent.)
+    </para>
+    <para>
+      Following the <literal>SYSTEM_TRAY_BEGIN_MESSAGE</literal>
+      op code, the tray icon should send a series of client messages
+      with a <literal>message_type</literal> of
+      <literal>_NET_SYSTEM_TRAY_MESSAGE_DATA</literal>. These client
+      messages must have their <literal>window</literal> field set 
+      to the window ID of the tray icon, and have a
+      <literal>format</literal> of 8.
+    </para>
+    <para>
+      Each <literal>_NET_SYSTEM_TRAY_MESSAGE_DATA</literal> message
+      contains 20 bytes of the message string, up to the length given 
+      in the <literal>SYSTEM_TRAY_BEGIN_MESSAGE</literal> opcode.
+      If the message string is zero-length, then no messages need be
+      sent beyond the <literal>SYSTEM_TRAY_BEGIN_MESSAGE</literal>. 
+      A terminating nul byte should never be sent.
+    </para>
+    <para>
+      System trays may receive portions of messages from several 
+      tray icons at once, so are required to reassemble the messages
+      based on the window ID of the tray icon.
+    </para>
+    <para>
+      The tray icon may wish to cancel a previously-sent balloon
+      message. To do so, it sends a
+      <literal>SYSTEM_TRAY_CANCEL_MESSAGE</literal> opcode with
+      <literal>data.l[2]</literal> set to the ID number of the message
+      to cancel.
+    </para>
+  </sect1>
+
+  <appendix id="changes">
+    <title>Change history</title>
+    <formalpara>
+      <title>Version 0.1, 20 April 2002, Havoc Pennington</title>    
+      <para>
+	<itemizedlist>
+	  <listitem>
+	    <para>
+              Created initial draft.
+	    </para>
+	  </listitem>
+	</itemizedlist>
+      </para>
+    </formalpara>
+  </appendix>
+</article>