Chapter 4 Window Information Functions

Chapter 4: Window Information Functions 4章 ウィンドウ情報関数

ディスプレイをXサーバに接続し、ウィンドウを作成した後、 次のXlibウィンドウ情報関数を使う事ができる。

ウィンドウ情報を得る

Xlibはウィンドウツリー、ウィンドウの現在の属性、ウィンドウの現在の座標、 現在のポインタ座標についての情報を取得するための関数を与える。 ウィンドウマネージャにより最も頻繁に使われるので これらの関数は全て、ウィンドウがまだ存在するかどうかを示す値を返す。

与えられたウィンドウに対する、親ウィンドウ、子ウィンドウのリスト、 子ウィンドウの数を得るには、 XQueryTree を使う。

Status XQueryTree(display, w, root_return, parent_return, children_return, nchildren_return)
Display *display;
Window w;
Window *root_return;
Window *parent_return;
Window **children_return;
unsigned int *nchildren_return;
display
Xサーバへの接続を指定。
w
子ウィンドウ、ルートウィンドウ、親ウィンドウ、子ウィンドウの数を求めたいウィンドウを指定。
root_return
ルートウィンドウが返される。
parent_return
親ウィンドウが返される。
children_return
子ウィンドウのリストが返される。
nchildren_return
子ウィンドウの数が返される。

関数 XQueryTreeは指定したウィンドウに対して、ルートウィンドウのID, 親ウィンドウのID, 子ウィンドウのリストへのポインタ(子ウィンドウが無い場合には NULL)、 このリスト中の子ウィンドウの数を返す。 ウィンドウのリストは、最も奥のウィンドウから最も手前のウィンドウへの順で、 現在重なっている順番に作られる。 XQueryTreeは問い合わせに失敗した場合にゼロを返し、成功の場合にはゼロでない値を返す。 不要になった NULL でない子ウィンドウのリストを解放するときには XFree を使うこと。

XQueryTreeはエラー BadWindowを起こす事がある。

与えられたウィンドウの現在の属性を得るには、 XGetWindowAttributes を使う。

Status XGetWindowAttributes(display, w, window_attributes_return)
Display *display;
Window w;
XWindowAttributes *window_attributes_return;
display
Xサーバへの接続を指定。
w
子ウィンドウ、ルートウィンドウ、親ウィンドウ、子ウィンドウの数を求めたい対象のウィンドウを指定。
window_attributes_return
XWindowAttributes構造体の指定したウィンドウ属性値が返される

The XGetWindowAttributesfunction returns the current attributes for the specified window to an XWindowAttributesstructure.

typedef struct {
	int x, y;	/* ウィンドウの位置 */ 
	int width, height;	/* ウィンドウの幅と高さ */ 
	int border_width;	/* ウィンドウの境界幅 */ 
	int depth;	/* ウィンドウの深さ */ 
	Visual *visual;	/* 対応するビジュアル構造体 */ 
	Window root;	/* ウィンドウがあるスクリーンのルートウィンドウ */ 
	int class;	/* InputOutput, InputOnly*/
	int bit_gravity;	/* ビットの gravity 値のうちの1つ */ 
	int win_gravity;	/* ウィンドウの gravity 値のうちの1つ */ 
	int backing_store;	/* NotUseful, WhenMapped, Always */
	unsigned long backing_planes;	/* 可能ならば保存されるプレーン */ 
	unsigned long backing_pixel;	/* プレーンの復元に使われる値 */ 
	Bool save_under;	/* 真偽値。ビットを保存するかどうか */ 
	Colormap colormap;	/* ウィンドウに対応するカラーマップ */ 
	Bool map_installed;	/* 真偽値。現在カラーマップはインストールされているかどうか */ 
	int map_state;	/* IsUnmapped, IsUnviewable, IsViewable */
	long all_event_masks;	/* クライアント全てが注目しているイベントの集合 */ 
	long your_event_mask;	/* 自分自身のイベントマスク */ 
	long do_not_propagate_mask;	/* 伝播させないイベントの集合 */ 
	Bool override_redirect;	/* override-redirect を示す真偽値 */ 
	Screen *screen;	/* 正しいスクリーンへのバックポインタ */ 
} XWindowAttributes;

x, y メンバには、ウィンドウの左上外側の隅の座標が、 原点に対する相対座標でセットされる。 width, height メンバには、境界を含まないウィンドウ内部のサイズがセットされる。 border_width メンバには、ウィンドウの幅のピクセル数がセットされる。 depth メンバにはウィンドウの深さ(つまり、 オブジェクトのピクセルごとのビット数)がセットされる。 visual メンバはスクリーンの対応する Visual構造体へのポインタである。 root メンバには、このウィンドウがあるスクリーンのルートウィンドウがセットされる。 class メンバにはウィンドウのクラスがセットされる。 これは InputOutputInputOnly のいずれかである。

bit_gravity メンバにはウィンドウの bit gravity 値がセットされる。 これは以下のいずれかである:

ForgetGravity EastGravity
NorthWestGravity SouthWestGravity
NorthGravity SouthGravity
NorthEastGravity SouthEastGravity
WestGravity StaticGravity
CenterGravity

win_gravity メンバにはウィンドウの window gravity 値がセットされる。 これは以下のいずれかである:

UnmapGravity EastGravity
NorthWestGravity SouthWestGravity
NorthGravity SouthGravity
NorthEastGravity SouthEastGravity
WestGravity StaticGravity
CenterGravity

gravityについての追加的な情報は 3.2.3節を参照

backing_store メンバは、ウィンドウの内容をどのように保持すべきか指定する。 この値は、 WhenMapped ,Always ,NotUseful のいずれかである。 backing_planes メンバは、バッキングストアやセーブアンダーで保存しなければならない 動的なデータを、ウィンドウのどのビットプレーンが保持するのか指示する (ビットに1をセットする)。 backing_pixel メンバは、backing_planes にセットされていないプレーンでどの値を 使用するかを示す。

save_under メンバには TrueFalse がセットされる。 colormap メンバには指定したウィンドウのカラーマップがセットされる。 このメンバの取る値はカラーマップの ID か None である。 map_installed メンバはカラーマップが現在インストールされているかどうかを示す。 このメンバの取る値は、 TrueFalse である。 map_state メンバはウィンドウの状態を示し、 IsUnmapped ,IsUnviewable ,IsViewable のいずれかの値を取る。 IsUnviewableは、そのウィンドウ自体はマップされているが祖先ウィンドウにマップ されていないものがある場合に使用される。

all_event_masks メンバは、そのウィンドウ上で選択しているイベントマスクを全ての クライアントについてビットごとの論理和を取ったものである。 your_event_mask メンバは問い合わせをしたクライアントが選択している全ての イベントマスクの論理和を取ったものである。 do_not_propagate_mask メンバは、伝播してはならないイベントの集合について ビットごとの論理和を取ったものである。

override_redirect メンバは、このウィンドウがウィンドウ構成の制御を無視する かどうかを指定する。このメンバの取る値は TrueFalse である。 このメンバが True ならば、ウィンドウマネージャはそのウィンドウを無視すべきである。

screen メンバには、正しいスクリーンを指すバックポインタを与えるスクリーンへの ポインタがセットされる。 これにより、ルートウィンドウのフィールドを使ったループでマッチするフィールドを 探すことなく、容易にスクリーン情報を取得することができる。

XGetWindowAttributesはエラー BadDrawableBadWindowを起こすことがある。

与えられたdrawableの現在の座標を得るには、 XGetGeometry を使う。

Status XGetGeometry(display, d, root_return, x_return, y_return, width_return,
height_return, border_width_return, depth_return)
Display *display;
Drawable d;
Window *root_return;
int *x_return, *y_return;
unsigned int *width_return, *height_return;
unsigned int *border_width_return;
unsigned int *depth_return;
display
Xサーバへの接続を指定。
d
ドロウアブルを指定。これはウィンドウかピックスマップである。
root_return
ルートウィンドウを返す。
x_return

y_return
ドロウアブルの位置を定義する x, y 座標が返される。 ウィンドウの場合、この座標は親ウィンドウの原点に対する相対座標であり、 左上外側の隅を示す。 ピックスマップの場合は、x, y 座標は常にゼロである。
width_return

height_return
ドロウアブルのディメンジョン(幅と高さ)が返される。 ウィンドウの場合、これらのディメンションはサイズの内側であり、境界線 を含まない。
border_width_return
境界の幅のピクセル数が返される。 ドロウアブルがピクスマップなら、ゼロを返す。
depth_return
ドロウアブルの深さが返される(オブジェクトのピクセルごとのビット数)。

関数 XGetGeometryはドロウアブルの現在のジオメトリとルートウィンドウを返す。 ドロウアブルのジオメトリは、x, y 座標、幅と高さ、境界の幅、深さを持つ。 These are described in the argument list. これらは引き数リストに記述される。 この関数にクラスが InputOnly であるウィンドウを渡すことは正しい指定である。

XGetGeometryはエラー BadDrawableを起こすことがある。

Translating Screen Coordinates

アプリケーションは時々あるウィンドウの座標空間から他のウィンドウの座標空間に 変換したり、ポインティングデバイスがあるウィンドウを決定したりする必要がある。 XTranslateCoordinatesXQueryPointerはこれらの操作を行いXサーバに尋ねることでこれらの要求 (そして全ての競合状態を無視する)に応える。

あるウィンドウでの座標を他のウィンドウの座標に変換するには、 XTranslateCoordinates を使う。

Bool XTranslateCoordinates(display, src_w, dest_w, src_x, src_y, dest_x_return,
dest_y_return, child_return)
Display *display;
Window src_w, dest_w;
int src_x, src_y;
int *dest_x_return, *dest_y_return;
Window *child_return;
display
Xサーバへの接続を指定。
src_w
ソースウィンドウを指定。
dest_w
対象ウィンドウを指定。
src_x

src_y
ソースウィンドウ内部での x, y 座標を指定。
dest_x_return

dest_y_return
対象ウィンドウ内部での x, y 座標が返される。
child_return
座標が対象ウィンドウのマップされている子ウィンドウに含まれる場合、 その子ウィンドウが返される。

XTranslateCoordinatesTrue を返した場合、 この関数はソースウィンドウの原点に対する src_x, src_y 座標を受け取り、 この座標を対象ウィンドウの原点に対する dest_x_return, dest_y_return として返す。 XTranslateCoordinatesFalse を返した場合、 src_w と dest_w は異なるウィンドウ上にあり、 dest_x_return と dest_y_return にはゼロがセットされる。 もし、座標が ウィンドウ dest_w のマップされている子ウィンドウに 含まれている場合、その子ウィンドウが chile_return に返される。 そうでなければ chile_return には None がセットされる。

XTranslateCoordinatesはエラー BadWindow を起こすことがある。

ポインタのスクリーン座標を得たり、指定したウィンドウに対する相対座標で ポインタ座標を決定するには、 XQueryPointer を使う。

Bool XQueryPointer(display, w, root_return, child_return, root_x_return, root_y_return,
win_x_return, win_y_return, mask_return)
Display *display;
Window w;
Window *root_return, *child_return;
int *root_x_return, *root_y_return;
int *win_x_return, *win_y_return;
unsigned int *mask_return;
display
Xサーバへの接続を指定。
w
ウィンドウを指定。
root_return
ポインタを含むルートウィンドウが返される。
child_return
もしポインタが子ウィンドウの内部にあれば、そのウィンドウが返される。
root_x_return

root_y_return
ルートウィンドウの原点に対する相対座標でポインタの座標が返される。
win_x_return

win_y_return
指定したウィンドウに対する相対座標でポインタの座標が返される。
mask_return
モディファイアキーとポインタのボタンの現在の状態が返される。

関数 XQueryPointerはポインタが論理的に存在するルートウィンドウおよび ポインタのルートウィンドウの原点からの相対座標を返す。 XQueryPointerFalse を返した場合、ポインタは指定したウィンドウと同じスクリーン上には存在しない。 このとき、 XQueryPointerは child_return に Noneをセットし、win_x_return と win_y_return にゼロをセットする。 XQueryPointerTrue , を返した場合、win_x_return と win_y_return に返されるポインタの 座標は指定したウィンドウの原点に対する相対座標である。 この場合、 XQueryPointerはポインタを含む子ウィンドウがあればこれを child_return に返し、 そうでなければ Noneを child_return に返す。

XQueryPointerはキーボードのボタンとモディファイアキーの現在の論理的状態を mask_return に返す。 この関数は mask_return にボタンやモディファイアキーのビットマスクの ビットごとの論理和をセットし、現在のマウスボタンと モディファイアキーの状態にマッチさせる。

デバイスの処理がフリーズされた場合、 デバイスの論理的な状態(Xlibを通じて見られるような)は物理的な状態 に遅れることに注意する。(12.1節を参照)

XQueryPointerはエラー BadWindow を起こすことがある。

Properties and Atoms

プロパティは名前づけられ、型付されたデータの集合である。 ウィンドウシステムは事前に定義されたプロパティの組を持つ。 (例えば、ウィンドウの名前、サイズのヒント等)、そしてユーザは 他の任意の情報を定義したり、ウィンドウにこれらを関連づける。 それぞれのプロパティは名前を持ち、 その名前はISO Latin-1文字列である。 それぞれに名付けられたプロパティに対して、 ユニークなID(アトム)がこれに関連づけられる。 プロパティはまた型(例えば、文字列や整数値)を持つ。 これらの型は使っているアトムに示され、任意の新しい型を定義できる。 一つの型のみを持つデータは単一のプロパティー名に関連づけられる。 クライアントはウィンドウに関連づけられたプロパティを保存したり、検索 したりできる。 効率の理由から、 アトムは文字列がよく使われる。 XInternAtomはプロパティ名に対するアトムを得るために使われる。

プロパティはまたいくつかの可能な形式のうちいずれかで蓄えられる。 Xサーバは8 bit,16 bit,32 bitとして情報を蓄える。 これはXサーバにクライアントが望むバイトオーダーでデータを蓄える事を許す。

Note: もっと複雑な型のプロパティを定義するなら、 その型を自分でエンコード、デコードしなければならない。 このプロパティがポータブルなら、これらの関数は注意深く書かれるべきである。 ライブラリの拡張をどのように書くかについてのもっと多くの情報は Appendix Cを参照すること。
プロパティの型はアトムにより定義され、そのアトムは この型の枠組みにおいて自由に拡張可能である。

いくつかのプロパティ名は一般に使われる関数においてサーバで 事前に定義される。 これらのプロパティに対するアトムは <X11/Xatom.h >で定義されている。 ユーザシンボルと名前が衝突するのを避けるために、 それぞれのアトムに対する #define 名はプリフィクス XA_ を持つ。 これらの事前に定義されたプロパティで蓄えられた多くの情報を得たり、 セットしたりする関数の説明については、 14章を参照すること。

コアのプロトコルはこれらのプロパティ名における解釈を押しつけない。 しかし、この解釈は他のXコンソーシアム標準で指定される。 例えば、クライアント間通信規約マニュアルや \IX論理フォント描画規約\fPなどである。

アプリケーション間で他の情報をやりとりするためにプロパティを使う ことができる。 この節で示されている関数はアプリケーションで新しいプロパティを定義したり、 ユニークなアトムIDを得ることを許す。

全ての特定のアトムはそれぞれの名前空間内であるクライアントの解釈 を持つけれども、 アトムはプロトコル内で5つの対象となる名前空間で起こる。

組み込まれているセレクションプロパティ名には 次のものがある。

PRIMARY
SECONDARY

組み込まれているプロパティ名は次の ものがある。

CUT_BUFFER0 RESOURCE_MANAGER
CUT_BUFFER1 WM_CLASS
CUT_BUFFER2 WM_CLIENT_MACHINE
CUT_BUFFER3 WM_COLORMAP_WINDOWS
CUT_BUFFER4 WM_COMMAND
CUT_BUFFER5 WM_HINTS
CUT_BUFFER6 WM_ICON_NAME
CUT_BUFFER7 WM_ICON_SIZE
RGB_BEST_MAP WM_NAME
RGB_BLUE_MAP WM_NORMAL_HINTS
RGB_DEFAULT_MAP WM_PROTOCOLS
RGB_GRAY_MAP WM_STATE
RGB_GREEN_MAP WM_TRANSIENT_FOR
RGB_RED_MAP WM_ZOOM_HINTS

組み込まれているプロパティ型は次の ものがある。

ARC POINT
ATOM RGB_COLOR_MAP
BITMAP RECTANGLE
CARDINAL STRING
COLORMAP VISUALID
CURSOR WINDOW
DRAWABLE WM_HINTS
FONT WM_SIZE_HINTS
INTEGER PIXMAP

組み込まれているフォントプロパティ名は次のもの がある。

MIN_SPACE STRIKEOUT_DESCENT
NORM_SPACE STRIKEOUT_ASCENT
MAX_SPACE ITALIC_ANGLE
END_SPACE X_HEIGHT
SUPERSCRIPT_X QUAD_WIDTH
SUPERSCRIPT_Y WEIGHT
SUBSCRIPT_X POINT_SIZE
SUBSCRIPT_Y RESOLUTION
UNDERLINE_POSITION COPYRIGHT
UNDERLINE_THICKNESS NOTICE
FONT_NAME FAMILY_NAME
FULL_NAME CAP_HEIGHT

フォントプロパティについてのより多くの情報に関しては 8.5節を参照すること。

与えられた名前に対するアトムを得るには、 XInternAtom を使う。

Atom XInternAtom(display, atom_name, only_if_exists)
Display *display;
char *atom_name;
Bool only_if_exists;
display
Xサーバへの接続を指定。
atom_name
取得しようとしているアトムに対応する名前を指定。
only_if_exists
アトムを生成しなければならないかどうかを示す真偽値を指定。

関数 XInternAtomは指定した atom_name 文字列に対応するアトムの識別子を返す。 only_if_exists が False ならば、 アトムが存在しない場合には新しく生成される。 したがって、 XInternAtomは常に None を返すことになる。 アトム名のエンコーディングがホストポータブル文字エンコーディングでない場合、 実行結果は実装依存である。 大文字と小文字は区別される。 したがって、``thing'', ``Thing'', ``thinG'' は全て異なるアトムとして区別される。 クライアントの接続が閉じた後であっても、アトムは定義されたまま残る。 アトムが未定義にされるのは、X サーバへの最後の接続が閉じられた時である。

XInternAtomはエラー BadAlloc, BadValue を起こすことがある。

名前の配列に対応するアトムを得るには、 XInternAtoms を使う。

Status XInternAtoms(display, names, count, only_if_exists, atoms_return)
Display *display;
char **names;
int count;
Bool only_if_exists;
Atom *atoms_return;
display
Xサーバへの接続を指定。
names
アトム名の配列を指定。
count
配列中にあるアトムの数を指定。
only_if_exists
アトムを生成しなければならないかどうかを示す真偽値を指定。
atoms_return
アトムが返される。

関数 XInternAtomsは指定した名前の配列に対応するアトム識別子の配列を返す。 アトムは呼び出し側が与える配列 atoms_return に格納される。 この関数の呼び出しは、それぞれの名前を使って only_if_exists を指定した XInternAtomを順に呼び出すことと同等である。 しかし、この関数を使えばクライアントと X サーバ間のプロトコル交換の 回数を最小化することができる。

この関数は、全ての名前に対してアトムが返された場合にゼロでない 値を返し、 そうでない場合にはゼロを返す。

XInternAtomsはエラー BadAlloc, BadValue を起こすことがある。

与えられたアトム識別子に対応するアトム名を返すには、 XGetAtomName を使う。

char *XGetAtomName(display, atom)
Display *display;
Atom atom;
display
Xサーバに対する接続を指定。
atom
取得しようとしているプロパティ名に対するアトムを指定。

関数 XGetAtomNameは指定したアトムに対応する名前を返す。 サーバが返すデータのエンコーディングが Latin ポータブル文字エンコーディングであれば、 関数が返す文字列のエンコーディングはホストポータブル文字エンコーディングである。 そうでない場合の結果は実装依存である。 返された文字列を解放するには XFree を用いること。

XGetAtomNameはエラー BadAtom を起こすことがある。

アトム識別子の配列に対応するアトム名を返すには、 XGetAtomNames を使う。

Status XGetAtomNames(display, atoms, count, names_return)
Display *display;
Atom *atoms;
int count;
char **names_return;
display
Xサーバへの接続を指定。
atoms
アトムの配列を指定。
count
配列中にあるアトムの数を指定。
names_return
アトム名を返す。

関数 XGetAtomNamesは指定したアトムの配列に対応する名前の配列を返す。 名前は呼び出し側が与える配列 names_return に格納される。 この関数を呼ぶことは、それぞれのアトムについて XGetAtomNameを順に呼ぶことと等価である。 しかし、この関数を使えば、クライアントと X サーバの間のプロトコル交換の 回数を最小化することができる。

の関数は、全てのアトムに対する名前を返すことができる場合は ゼロでない値を返し、 そうでない場合はゼロを返す。

XGetAtomNamesはエラー BadAtom を起こすことがある。

Obtaining and Changing Window Properties

全てのウィンドウにプロパティリストを取り付ける事ができる。 それぞれのプロパティは名前、型、値を持つ。(4.3節を参照すること) 値は8bit,16bit,32bit単位の配列であり、 これらの値の解釈はクライアントに任させる。型 charis used to represent 8-bit quantities, the type は8bit単位に対して使われ、型 shortは16bit単位に対して使われ、型 longは32bit単位に対して使われる。

Xlibはウィンドウプロパティを変更、更新、置き換えることが できる関数を与える。 加えて、XLibはクライアント間通信のためのユーティリティ関数を与える。 (14節を参照すること)

与えれたウィンドウのプロパティの型、フォーマット、値を得るには、 XGetWindowProperty を使う。

int XGetWindowProperty(display, w, property, long_offset, long_length, delete, req_type,
actual_type_return, actual_format_return, nitems_return, bytes_after_return,
prop_return)
Display *display;
Window w;
Atom property;
long long_offset, long_length;
Bool delete;
Atom req_type;
Atom *actual_type_return;
int *actual_format_return;
unsigned long *nitems_return;
unsigned long *bytes_after_return;
unsigned char **prop_return;
display
Xサーバへの接続を指定。
w
子ウィンドウ、ルートウィンドウ、親ウィンドウ、子ウィンドウの数を求めたいウィンドウを指定。
property
プロパティ名を指定。
long_offset
データが取り込まれる、指定したプロパティ内のオフセット(32ビット単位)を指定。
long_length
取得するデータの32ビット倍で長さを指定。
delete
プロパティを削除するかどうか決定する真偽値を指定。
req_type
プロパティのタイプに対応するアトム識別子か AnyPropertyType を指定。
actual_type_return
プロパティの実際のタイプを定義するアトム識別子が返される。
actual_format_return
プロパティの実際のフォーマットが返される。
nitems_return
prop_return に格納された 8ビット、16ビット、32ビットのアイテムの 実際の数が返される。
bytes_after_return
プロパティの一部だけ読み込んだ場合、残りのバイト数が返される。
prop_return
指定したフォーマットのデータが返される。

関数 XGetWindowPropertythe number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining to be read in the property; and a pointer to the data actually returned. はプロパティの実際のタイプ、プロパティの実際のフォーマット、転送される 8ビット、 16ビット、32ビットのアイテム数、プロパティに残っている読み込むべきバイト数、 データへのポインタを返す。 XGetWindowPropertyは値を返す引き数に対して以下のように値をセットする。

返されたフォーマットが8ならば、返されたデータは charの配列として表現されている。 返されたフォーマットが16ならば、返されたデータは shortの配列として表現されており、要素を得るにはその型にキャストしなければならない。 返されたフォーマットが32ならば、返されたデータは longの配列として表現されており、要素を得るにはその型にキャストし なければならない。

XGetWindowPropertyは常に prop_return に追加の1バイトをアロケートし (たとえプロパティの長さがゼロでも)、 そこにゼロをセットする。 文字からなる簡単なプロパティを、使用前に別の文字列にコピーする 必要がないようにするためである。

delete が True で bytes_after_return がゼロならば、 XGetWindowPropertyはプロパティをウィンドウから削除し、 そのウィンドウ上に PropertyNotify イベントを生成する。

この関数は正常に実行された場合、 Successを返す。 得られたデータを解放するには XFree を使用すること。

XGetWindowPropertyはエラー BadAtom ,BadValue ,BadWindow を起こすことがある。

与えられたウィンドウのプロパティリストを得るには、 XListProperties を使う。

Atom *XListProperties(display, w, num_prop_return)
Display *display;
Window w;
int *num_prop_return;
display
Xサーバへの接続を指定。
w
プロパティリストの取得を行うウィンドウを指定。
num_prop_return
プロパティの配列の長さが返される。

関数 XListPropertiesは指定されたウィンドウに対して定義されているアトムプロパティの配列への ポインタを返す。プロパティが見つからなかった場合には NULL を返す。 この関数がアロケートしたメモリを解放するには XFree を使うこと。

XListPropertiesはエラー BadWindow を起こすことがある。

与えられたウィンドウのプロパティを変更するには、 XChangeProperty を使う。

XChangeProperty(display, w, property, type, format, mode, data, nelements)
Display *display;
Window w;
Atom property, type;
int format;
int mode;
unsigned char *data;
int nelements;
display
Xサーバへの接続を指定。
w
プロパティリストの取得を行うウィンドウを指定。
property
プロパティ名を指定。
type
プロパティのタイプを指定。 X サーバはこのタイプの解釈は行わないが、後で XGetWindowProperty を呼び出したアプリケーションにそのタイプをそのまま返す。
format
データを 8ビット、16ビット、32ビットいずれの単位のリストとみなすかを指定。 8, 16, 32 を指定できる。 この情報により、X サーバは必要に応じてバイト交換を正しく行うこと ができる。 フォーマットが 16ビットか32ビットの場合には、 XChangeProperty の呼び出しの際にはデータへのポインタを (unsigned char *) に キャストしなければならない。
mode
操作のモードを指定。 PropModeReplace ,PropModePrepend ,PropModeAppend のいずれかを指定できる。
data
プロパティのデータを指定。
nelements
指定したデータフォーマットの要素数を指定。

関数 XChangePropertyは指定されたウィンドウのプロパティを変更し、 そのウィンドウ上の PropertyNotifyイベントを X サーバに生成させる。 XChangePropertyは以下の動作を行う。

指定したフォーマットが8ならば、プロパティのデータは char型の配列でなければならない。 指定したフォーマットが16ならば、プロパティのデータは short型の配列でなければならない。 指定したフォーマットが32ならば、プロパティのデータは long型の配列でなければならない。

プロパティの存続期間は、格納を行ったクライアントとは結びつけられない。 プロパティは明示的に削除されるか、ウィンドウが破壊されるか、 サーバが再設定するまで残る。 X サーバへの接続が切れた際の挙動については、2.6 章を参照すること。 プロパティの最大サイズはサーバに依存し、これはサーバが利用可能な メモリ量によって動的に変わることもある。 (十分なメモリが確保できない場合はエラー BadAllocとなる。)

XChangePropertyはエラー BadAlloc ,BadAtom ,BadMatch ,BadValue ,BadWindow を起こすことがある。

ウィンドウのプロパティリストをローケートするには、 XRotateWindowProperties を使う。

XRotateWindowProperties(display, w, properties, num_prop, npositions)
Display *display;
Window w;
Atom properties[];
int num_prop;
int npositions;
display
Xサーバへの接続を指定。
w
ウィンドウを指定。
properties
ローテートさせるプロパティの配列を指定。
num_prop
プロパティの配列の長さを指定。
npositions
ローテーションの量を指定。

関数 XRotateWindowPropertiesを使うと、ウィンドウのプロパティをローテートさせることができる。 また、この関数はX サーバに PropertyNotifyイベントを生成させる。 プロパティの配列内のプロパティ名にゼロから始まる番号を付け、 リスト中に num_prop 個のプロパティ名があるものとすると、 プロパティ名 I に対応する値はプロパティ名 (I + npositions) mod N に対応する値となる(I の値はゼロか N-1 まで)。 この関数の効果は、状態をプロパティ名の仮想的なリングの周りで npositions 分の位置だけローテートさせることである(npositions が正ならば 右周りで、負ならば左回り)。 npositions mod N がゼロでなければ、 X サーバは配列中に列挙されている順に 各プロパティに対する PropertyNotifyイベントを生成する。 1つのアトムがリスト中に2度以上現われた場合とウィンドウに対して その名前のプロパティが定義されていない場合には、 エラー BadMatch となる。 エラー BadAtom あるいは BadMatch が起きた場合、プロパティは 変更されない。

XRotateWindowPropertiesはエラー BadAtom ,BadMatch ,BadWindow を起こすことがある。

与えられたウィンドウのプロパティを削除するには、 XDeleteProperty を使う。

XDeleteProperty(display, w, property)
Display *display;
Window w;
Atom property;
display
Xサーバへの接続を指定。
w
プロパティリストの取得を行うウィンドウを指定。
property
プロパティ名を指定。

関数 XDeleteProperty指定したプロパティが指定したウィンドウに対して定義されている 場合に限ってこのプロパティを削除し、 そのウィンドウ上での PropertyNotifyイベントを X サーバに生成させる。

XDeletePropertycan generate BadAtomand BadWindow errors.

Selections

セレクションはアプリケーションによりデータ交換を行う一つの方法である。 プロパティのメカニズムを使う事により、 アプリケーションは任意のタイプのデータを交換でき、データのタイプを を取り決める事ができる。 セレクションは動的なタイプを使った間接的なプロパティと考えられる。 これはむしろXサーバに蓄えられるプロパティであり、 プロパティは特定のクライアントにより保持される。(所有者) セレクションは特定のウィンドウのサブ階層や特定のクライアントの組にプライベイト であるというよりも本質的にグローバルである。(ユーザに属すると考えられるが クライアントにより保持されている)

Xlibはセレクションの変換をセットしたり、得たり、要求したりするのに使う 関数を与える。 これによりアプリケーションは現在のセレクションの考えを実装できる。 また、アプリケーションがもはやセレクションを所有しなくなった時、通知が アプリケーションに送られる事が要求される。 セレクションをサポートするアプリケーションはしばしば現在のセレクションを 反転表示させる。 そして、他のアプリケーションがセレクションを取得した時、アプリケーション がセレクションを反転表示しないように通達される。

クライアントがセレクションの内容を尋ねる時、 セレクションのターゲットタイプを指定する。 このターゲットタイプは送信された内容の再描画を制御するのに使われる。 例えば、セレクションが「ユーザが最後にクリックしたもの」であり、 それが現在、画像である場合、ターゲットタイプは 画像の内容がXYフォーマット、Zフォーマットのどちらで送るべきか指定するかも知れない。

ターゲットタイプは送られた内容のクラスを制御するのにも使われる。 例えば、 パラグラフセクションの「見ため」(フォント、線の間隔、ぎざぎざ、等の前面)を尋ねて、 テキストのパラグラフを尋ねない。 ターゲットタイプは他の目的にも使われる。 プロトコルは解釈は制約しない。

セレクションの所有者をセットするには、 XSetSelectionOwner を使う。

XSetSelectionOwner(display, selection, owner, time)
Display *display;
Atom selection;
Window owner;
Time time;
display
X サーバへの接続を指定。
selection
セレクションアトムを指定。
owner
指定されたセレクションアトムの所有者を指定。 ウィンドウか None を渡すことができる。
time
時間を指定。 タイムスタンプか CurrentTime を渡すことができる。

関数 XSetSelectionOwnerは、指定したセレクションの所有者と最終更新時間を変更する。 指定した時間が、指定したセレクションの現在の最終更新時間よりも 早い場合や X サーバの現在時刻よりも遅い場合には、 この関数は何もしない。 そうでない場合には、最終更新時間は指定された時間にセットされ、 CurrentTimeはXサーバの現在時刻に置き換えられる。 所有者のウィンドウに None が指定された場合には、 セレクションの所有者は None(つまり所有者無し)となる。 そうでない場合、セレクションの所有者は要求を行ったクライアントになる。

もし新しい所有者(クライアントか None )が、現在のセレクション所有者と異なり、かつ現在の所有者が None ,でなければ、現在の所有者には SelectionClear イベントが送られる。 セレクションの所有者になっているクライアントが後で終了した (つまり接続が閉じた)か、リクエストで指定された所有者の ウィンドウが後で破棄された場合には、 セレクションの所有者は自動的に None に戻るが、最終更新時間はこの影響を受けない。 セレクションのアトムは X サーバには解釈されない。 XGetSelectionOwnerは所有者のウィンドウを返すが、これは SelectionRequestおよび SelectionClearイベントで通知される。 セレクションは X サーバにおいて大域的に扱われる。

XSetSelectionOwnerはエラー BadAtomあるいは BadWindow を起こすことがある。

セレクションの所有者を返すには、 XGetSelectionOwner を使う。

Window XGetSelectionOwner(display, selection)
Display *display;
Atom selection;
display
Xサーバへの接続を指定。
selection
返したい所有者のセレクションアトムを指定。

関数 XGetSelectionOwnerは、指定したセレクションを現在所有しているウィンドウに関連づけられた ウィンドウIDを返す。 セレクションが指定されていない場合には、関数は定数 None を返す。 もし Noneが返された場合、 セレクションの所有者はいない。

XGetSelectionOwnerはエラー BadAtom を起こすことがある。

セレクションの変換を要求するには、 XConvertSelection を使う。

XConvertSelection(display, selection, target, property, requestor, time)
Display *display;
Atom selection, target;
Atom property;
Window requestor;
Time time;
display
Xサーバへの接続を指定。
selection
セレクションアトムを指定。
target
ターゲットのアトムを指定。
property
プロパティ名を指定。 None を渡すこともできる。
requestor
要求者を指定。
time
時間を指定。 タイムスタンプか CurrentTime を渡すことができる。

XConvertSelectionは、指定したセレクションが指定した型に変換されることを要求する。

引き数はいずれのイベントでも変更されずに送られる。 予め定義されているアトムとしては PRIMARY と SECONDARY の2つがある。

XConvertSelectionはエラー BadAtom, BadWindow を起こすことがある。


目次に戻る