lindocs

freedesktop.org / Standards / systemtray-spec

システムトレイプロトコル仕様書

Havoc Pennington

hp@redhat.com

Version 0.1

概要

「システムトレイ」は、アプリケーションを実行した時に、 小さなアイコンを表示できる X 画面上のアプリケーションです。 Windows XP はこの機能を「通知領域」と呼びます。 *1 KDE にインスパイアされ、この仕様書では「システムトレイ」という用語を使用します。

UI の立場では、十分に発達した「アプレット」が、 恒久的なドック・パネル機能に使われる一方、システムトレイは、 特殊な状態を示す一時的なアイコンを表示するのに通常使用します。 たとえば、システムトレイアイコンが、新しいメールが届いたり、 インスタントメッセージが入ってきといったことを、 ユーザがわかるように現れることになります。

基本的な考えは、通知領域にアイコンを作成するほうが、 ダイアログをポップアップするよりうるさくないということです。 しかしこれは気がつきにくくなるということでもあります。 そのため Windows XP には、トレイアイコンに小さなメッセージバルーンを ポップアップする機能が追加されました。 (ユーザは隠れたレジストリ設定によって、この機能を無効にできます) この仕様書でもバルーン機能をサポートします。

定義

システムトレイ (System tray)
システムトレイは、与えられた画面上の特殊なマネージャセレクションを所有し、 コンテナウィンドウを提供する X クライアントです。
セレクションオーナーウィンドウ (Selection owner window)
セレクションオーナーウィンドウは、 (XGetSelectionOwner?()/XSetSelectionOwner?() 内のような) マネージャセレクションを所有するシステムトレイに属するウィンドウです。 これがシステムトレイアイコンを含むウィンドウと、 おそらく同じウィンドウではないことに注意してください。
トレイアイコン (Tray icon)
トレイアイコンはシステムトレイに組み込まれるウィンドウです。

システムトレイの位置

スタートアップにおいて、 システムトレイは _NET_SYSTEM_TRAY_Sn と呼ばれるマネージャセレクションを得なければなりません。 ここで n はトレイが使用したい画面番号です。 マネージャセレクション用の規約は ICCCM で定義されます。

マネージャセレクションが失われた場合、 セレクションオーナーウィンドウが破棄されるため、 通常、システムトレイが提供する、 ユーザ可視ウィンドウのうちのどれとも同じにはなりません。

セレクションの取得に失敗したり、セレクションを失うシステムトレイは、 別のシステムトレイが実行中であると見なすべきで、 セレクションオーナーにトレイアイコンを扱わせる必要があります。

システムトレイにアイコンを提供したいアプリケーションは、 マネージャセレクションのオーナーウィンドウの要求により、 最初にシステムトレイに配置するべきです。 マネージャセレクションにオーナーがいない場合、 クライアントは、システムトレイがいつ現われるか通知されるために、 ICCCM に記述された方法 (MANAGER クライアントメッセージを待つ) を使用するかもしれません。

オペコードメッセージ

トレイアイコンはシステムトレイへ「オペコード」を送信できます。 これは NoEventMask? や _NET_SYSTEM_TRAY_OPCODE, フォーマット 32 で送られた X クライアントメッセージです。 メッセージの最初のデータフィールドは、タイムスタンプ (有効なら現在のイベントのタイムスタンプ。そうでなければ現在の時間) です。 2 番目のデータフィールドは、以下のようなメッセージのオペコードを表す整数です。

#define SYSTEM_TRAY_REQUEST_DOCK    0
#define SYSTEM_TRAY_BEGIN_MESSAGE   1
#define SYSTEM_TRAY_CANCEL_MESSAGE  2

3 番目のデータフィールドの内容は、 送られるメッセージタイプに依存します。 特定のメッセージで未使用の場合、常に 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 仕様書の "client" や "plug" 側をサポートしなければなりません。 XEMBED はクロスツールキットウィジット組込用のプロトコルです。

ドッキングプロセスの始めには、トレイアイコンアプリケーションが、 クライアントメッセージイベントを、“オペコードメッセージ” で述べたように、マネージャセレクションオーナーウィンドウに送信します。 このイベントには SYSTEM_TRAY_REQUEST_DOCK オペコードを含まなければなりませんし、 xclient.data.l[2] には、 ドッキングするトレイアイコンの X ウィンドウ ID を含まなければなりません。

この時点で、XEMBED 仕様書の中で説明される 「組込ライフサイクル」が始まります。 XEMBED 仕様書では、組み込むアプリケーションが 組み込まれるトレイアイコンとどのように通信するか、 また、組み込み・ 組み込まれ関係がどのように終了されるか説明しています。

トレイアイコンは、 システムトレイによって任意のサイズに割り当てられるかもしれません。 また、任意のサイズが有効になるよう最善を尽くすべきです。

トレイアイコンのヒント

システムトレイが、 気の利いたユーザインターフェイスを提供する助けとなるように、 トレイアイコンは以下のヒントを設定するべきです。 システムトレイがトレイアイコンを参照する必要がある場合、 その名前とアイコンのヒントが使用されます。 例えば、システムトレイは、トレイアイコンのリストを示し、 ユーザが並び替えたり、プロパティの変更をしたりできるでしょう。

_NET_WM_NAME

_NET_WM_NAME, UTF8_STRING

拡張ウィンドウマネージャヒント仕様書 (EWMH) で定義されているように、 通常のトップレベルウィンドウと同様に、 このヒントがセットされるべきです。 ヒントは UTF-8 エンコードでなければなりません。 これはトレイアイコンの、可読性のあるローカライズされた名前を提供します。

WM_CLASS

WM_CLASS, STRING

ICCCM に定義されているように、 通常のトップレベルウィンドウと同様に、 このヒントがセットされるべきです。 システムトレイは、異なる種類のトレイアイコンを識別するのに これを使用できます。 これは例えば、システムトレイが、 トレイ内のアイコンの位置を保存したり復元したりする場合などに便利です。

_NET_WM_ICON

_NET_WM_ICON CARDINAL[][2+n]/32

拡張ウィンドウマネージャヒント仕様書 (EWMH) で定義されているように、 通常のトップレベルウィンドウと同様に、 このヒントがセットされるべきです。 アイコンデータのフォーマットはその仕様書をご覧ください。


バルーンメッセージ

トレイアイコンは、バルーンメッセージを表示するよう システムトレイに問い合わせることがあります。 システムトレイは、バルーンメッセージが一貫したルック・アンド・フィールを持つことを保証し、 同時に複数のバルーンメッセージを表示しないよう調整を行います。

バルーンメッセージは、ユーザに表示する短いテキストメッセージです。 メッセージにはタイムアウトがあってもかまいません。 タイムアウトの時間が経過したら、メッセージを消すことになります。 メッセージはキューの順に、一度にひとつしか表示されません。 メッセージにタイムアウトがある場合、 最初に表示したときからタイマーが動き始めます。 ユーザはいつでもメッセージを閉じることができ、 またメッセージの表示をすべて無効にすることもできます。

システムトレイは、いずれかの方法で、 バルーンメッセージを表示するのが適当だと思います。 例えば、ポップアップバルーンの代わりに、 メッセージをアイコンの周りの特殊表示部に出力するよう選択できますし、 マウスを上にかざした時に表示することもできます。

バルーンメッセージは、トレイアイコンから、 システムトレイセレクションオーナウィンドウへ、 クライアントメッセージの列として送られます。 最初のクライアントメッセージはオペコードメッセージで、 通常タイムスタンプと SYSTEM_TRAY_BEGIN_MESSAGE オペコードを含んでいます。 xclient.data.l[2] は 1/1000 秒単位のタイムアウトか、 タイムアウトが無限となる 0 を格納しています。 xclient.data.l[3] は、 メッセージ文字列の長さをバイト単位で格納しています。 xclient.data.l[4] は、 メッセージの ID 番号を格納しています。 この ID 番号は、同じトレイアイコンでは決して再利用されません。 (ID 番号を生成する最も単純な方法は、 それぞれのメッセージが送られるたびに増加させていくことです)

SYSTEM_TRAY_BEGIN_MESSAGE オペコードに続いて、 トレイアイコンは _NET_SYSTEM_TRAY_MESSAGE_DATA の message_type である、 クライアントメッセージの列を送ります。 これらのクライアントメッセージは、 トレイアイコンのウィンドウ ID を割り当てる window フィールドを持たねばなりませんし、 また、8 つの format を持たねばなりません。

SYSTEM_TRAY_BEGIN_MESSAGE オペコードで与えられる長さになるまで、 それぞれ _NET_SYSTEM_TRAY_MESSAGE_DATA メッセージは、 20 バイトのメッセージ文字列を含んでいます。 メッセージ文字列の長さが 0 の場合、 SYSTEM_TRAY_BEGIN_MESSAGE 越しに送られるメッセージはありません。 終端のヌルバイトが送られることはありません。

システムトレイはメッセージの一部を、 いくつものトレイアイコンから一度に受け取れます。 これはトレイアイコンの ウィンドウ ID を基に、 メッセージを再構築する必要があるからです。

トレイアイコンは、前に送ったメッセージをキャンセルするかもしれません。 そのためには、SYSTEM_TRAY_CANCEL_MESSAGE オペコードを data.l[2] にキャンセルするメッセージの ID 番号をセットして送ってください。

更新履歴

Version 0.1, 20 April 2002, Havoc Pennington.

  • Created initial draft.

日本語訳について

「Linuxデスクトップ市場制覇のためには」スレの有志による各種ドキュメントの日本語訳です。

原文は http://freedesktop.org/Standards/systemtray-spec にあります。

コメント


メニュー

freedesktop.org

最新の20件

2016-05-13
  • freedesktop.org/Standards/systemtray-spec
2015-05-03 2013-11-16 2010-03-26 2006-09-22 2004-09-22

人気の10件

  • counter: 985
  • today: 1
  • yesterday: 0
  • online: 1

*1 Shell_NotifyIcon?() 関数の MSDN 文書によると、『タスクバー通知領域は時々誤って「トレイ」と呼ばれます。』とあります。おそらく Windows の公式用語では「通知領域」です。この文書では「ステータスエリア」とも呼びます。