系统托盘协议规范（基于Xwindow的桌面环境）

原文地址：http://standards.freedesktop.org/systemtray-spec/systemtray-spec-0.2.html

                系统托盘协议规范（基于Xwindow的桌面环境）

                        Havoc Pennington    <hp@redhat.com>;
                        中文翻译：赵青风    <qingfeng18@yahoo.com.cn>;

版本 0.2

目录

一、概述
二、定义
三、定位系统托盘
四、操作码消息
五、进驻显示托盘图标
六、托盘图标提示
七、托盘管理提示
八、消息菜单
九、附注
十、译者注



一、概述
        “系统托盘”是一个在X屏幕上显示应用程序提供的小图标的系统应用。WindowsXP将此特性命名为"通告区域"。[1]借鉴于KDE本规范使用“系统托盘”作为标准术语。
        从用户的观点来看，当成熟的小应用程序使用持久的嵌入特性时，系统托盘通常用暂时的图标来显示程序的状态。例如，一个系统托盘图标可能要通知用户收到一封邮件，或者有一条短消息，或者其它类似的事情。
        基本的想法是，在提示区域显示一个图标比弹出一个对话框更容易让人接受。然而提醒用户还是比较困难的，因此WindowsXP添加了一个允许托盘图标弹出消息菜单的特性（用户可通过隐含的系统注册设置禁用此功能）。本规范支持弹出消息菜单的特性。

二、定义
        系统托盘        ：系统托盘是一个在给定的屏幕上拥有专门管理者选择区并且提供容器窗口的X客户端。
        选择区拥有者窗口：选择区拥有者窗口是拥有管理者选择区的系统托盘附属窗口（如同在函数XGetSelectionOwner()/XSetSelectionOwner()中用到的）。注意它可能不是那个用于包容系统托盘图标的窗口。
        托盘图标        ：托盘图标是一个被嵌入到系统托盘中的窗口。
        
三、定位系统托盘
        启动时，系统托盘必须获得一个称为“_NET_SYSTEM_TRAY_Sn”的管理者选择区，用托盘将使用的屏幕号数值替换“n”值。在ICCCM中定义了关于管理者选择区的约定。
        在管理者选择区退出时，选择区拥有者窗口将被释放，因此通常地，选择区拥有者窗口与任何系统托盘提供的可见窗口都不相同。
        如果系统托盘不能够得到选择区或者失去了选择区，那么将被认为是另外一个系统托盘启动并获得此选择区并关联了对托盘图标的操作。
        应用程序希望提供一个图标给系统托盘，那么选择区管理者的拥有者窗口将要求首先定位系统托盘。如果管理者选择区没有拥有者，客户端可以使用ICCCM 描述的方法（查阅关于MANAGER的客户通信消息）在系统托盘出现时被通报。

四、操作码消息
        托盘图标能发送"opcodes"给系统托盘。这些是X客户端消息，以NoEventMask掩码、_NET_SYSTEM_TRAY_OPCODE消息类型、32位格式发送。消息中的第一个数据字段是时间戳（可用时值为当前事件的标志，否则是X全局变量的当前时间[CurrentTime]）。消息中的第二个数据字段是此消息的整型操作码值：
        #define SYSTEM_TRAY_REQUEST_DOCK    0
        #define SYSTEM_TRAY_BEGIN_MESSAGE   1
        #define SYSTEM_TRAY_CANCEL_MESSAGE  2
        消息数据中保留的三个数据段值由所发送的消息类型决定。如果不使用详细的消息，应该将它们置为0值。下面是一个怎样发送客户消息的样例：

#include <X11/Xlib.h>;

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(&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, &ev);
    XSync(dpy, False);
    if (untrap_errors()) {
        /* Handle failure */
    }
}

五、进驻显示托盘图标
        托盘图标必须支持“XEMBED”规范的“客户端”或“插件”部分。XEMBED是一个嵌入式窗口小部件交叉工具包协议。
        在开始进驻时，托盘图标程序发送一条客户消息事件给管理者选择区拥有者窗口，就像是在“操作码消息”段描述的那样。这个事件应该包含SYSTEM_TRAY_REQUEST_DOCK操作码，数据字段xclient.data.l[2]应该包含将要进驻的托盘图标的X窗口ID。
        这里指出XEMBED规范最初时解释的“嵌入生命周期”。XEMBED规范解释了嵌入式程序怎样与嵌入的托盘图标相互作用，以及怎样结束这种嵌入关系。托盘图标可能被系统图标设置成任意的尺寸，同时它们应该能够尽可能的适应任何尺寸。

六、托盘图标提示
        托盘图标应该设置下面的提示属性以帮助系统托盘提供一个良好的用户接口。如果系统托盘需要提到一个托盘图标，那么就要用到名字提示属性和图标提示属性；例如，系统托盘可以呈现一个托盘图标列表来让用户重新排列它们或者修改它们的属性。
        _NET_WM_NAME提示属性应该被设置以用于一个正常的上层窗口，就像在窗口管理提示属性规范扩展中定义的那样。提示属性必须用UTF-8编码，它提供了本地可读的托盘图标名字。
        WM_CLASS提示属性应该被设置以用于一个正常的上层窗口，就像在ICCCM协议中定义的那样。系统托盘通过它区分不同种类的托盘图标。这是非常有用的，例如在系统托盘想保留或恢复图标在托盘中的位置时。_NET_WM_ICON提示属性应该被设置以用于一个正常的上层窗口，就像在窗口管理提示属性规范扩展中定义的那样。图标数据格式请查阅该规范。

七、托盘管理提示
        托盘管理者应该在选择区拥有者窗口上设置_NET_SYSTEM_TRAY_ORIENTATION提示属性。
        #define _NET_SYSTEM_TRAY_ORIENTATION_HORZ 0
        #define _NET_SYSTEM_TRAY_ORIENTATION_VERT 1
        托盘管理者应该设置属性来说明当前托盘的排列方向。托盘图标可以通过这个提示属性来维持图标的长宽比以及显示图标内的内容。

八、消息菜单
        托盘图标可以要求系统托盘显示一个消息菜单给用户。系统托盘匹配的消息菜单保证它们整体的视觉和谐效果，并且避免同时显示多个消息菜单。
        消息菜单时显示给用户的简短文字信息；这个消息可以有一个超时时间，这样在超时时消息将被记载。消息可以通过队列显示，但同一时间只能能够有一个在显示；若果消息有超时时间，在消息显示时将启动计时。用户可能被允许在任何时间关掉消息或者禁用消息。
        系统托盘可以在他们定制的任何方式下显示消息菜单；例如，它们可以选择另外一种方式来代替弹出消息菜单：在图标周围放置特别的指示器，当鼠标移动到此时显示消息菜单。
        托盘图标将消息菜单作为一系列客户消息发送给系统托盘选择区拥有者窗口。第一条消息是操作码信息包含常用的时间戳和操作码SYSTEM_TRAY_BEGIN_MESSAGE。xclient.data.l[2]包含微秒计量数值的超时时间，或者在无限超时时是0值；xclient.data.l[3]包含字节计量数值的消息字符串长度，但不包含空字节；and xclient.data.l[4]包含此消息的ID值。这个ID值不能被同一个托盘图标再生。（产生ID值的最简单方式是每次发送消息时增加它的值。）在SYSTEM_TRAY_BEGIN_MESSAGE操作码之后，托盘图标应该发送一系列_NET_SYSTEM_TRAY_MESSAGE_DATA类型的客户消息。客户消息必须有8位格式的窗口字段，并设置托盘图标的窗口ID。
        每一个_NET_SYSTEM_TRAY_MESSAGE_DATA消息包含20字节的字符信息，等于SYSTEM_TRAY_BEGIN_MESSAGE操作码中的长度值。如果消息字符串长度为0，那么在SYSTEM_TRAY_BEGIN_MESSAGE中不需要发送消息。不应该发送终结空字符。
        系统托盘可能立刻从几个托盘图标收到部分消息，因此必须依据托盘图标窗口ID重新集合消息。
        托盘图标可能希望取消先前发送弹出菜单消息。为达到此目的，可以发送一个设置data.l[2]为ID号的SYSTEM_TRAY_CANCEL_MESSAGE操作码消息。

九、附注
        A. 发展历史
                0.2版本，2004年11月23日，Mark McLoughlin.
                        添加 _NET_SYSTEM_TRAY_ORIENTATION 提示属性。
                0.1版本，2002年4月20日，Havoc Pennington.
                        创建初始草稿。

十、译者注
        此规范为基于X的桌面系统而要通用实现托盘状态栏显示应用程序图标而制定的。因此规范中的术语和描述都需要对基本的X编程有一定了解才能更好的理解。特别是X的机制。规范是希望在现有的X桌面环境概念及方式不变的情况下，添加扩展属性且大家共同遵守而达到通用性和功能性。与X的现有规范相类似，规范只是一个发展中的协议，可扩展性较强，利于向后兼容，并希望在现有的X框架内解决问题。

[1] 根据MSDN关于Shell_NotifyIcon()函数的文档，“任务栏通告区域有时被错误的称为托盘”，因此大概“通告区域” 是Windows上的正式术语。此文档在局部称此为“状态区域”。