X11

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 メンバにはウィンドウのクラスがセットされる。これは InputOutputと InputOnly のいずれかである。

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

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

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

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

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

与えられた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

アプリケーションは時々あるウィンドウの座標空間から他のウィンドウの座標空間に変換したり、ポインティングデバイスがあるウィンドウを決定したりする必要がある。 XTranslateCoordinatesと XQueryPointerはこれらの操作を行い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

座標が対象ウィンドウのマップされている子ウィンドウに含まれる場合、その子ウィンドウが返される。

XTranslateCoordinatesが True を返した場合、この関数はソースウィンドウの原点に対する src_x, src_y 座標を受け取り、この座標を対象ウィンドウの原点に対する dest_x_return, dest_y_return として返す。 XTranslateCoordinatesが False を返した場合、 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はポインタが論理的に存在するルートウィンドウおよびポインタのルートウィンドウの原点からの相対座標を返す。 XQueryPointerが False を返した場合、ポインタは指定したウィンドウと同じスクリーン上には存在しない。このとき、 XQueryPointerは child_return に Noneをセットし、win_x_return と win_y_return にゼロをセットする。 XQueryPointerが True , を返した場合、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つの対象となる名前空間で起こる。

セレクション
プロパティ名
プロパティタイプ
フォントプロパティ
ClientMessage イベントのタイプ(Xサーバに組み込まれていない)

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

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は値を返す引き数に対して以下のように値をセットする。

指定したウィンドウに対する指定したプロパティが存在しない場合、 XGetWindowProperty actual_type_return に Noneを返し、actual_format_return と bytes_after_return にゼロを返す。引き数 nitems_return は空になる。この場合には引き数 delete は無視される。
指定したプロパティは存在するが指定したタイプに一致しない場合、 XGetWindowProperty は actual_type_return に実際のプロパティのタイプ、 actual_format_return に実際のプロパティのフォーマット(決してゼロにはならない)、 bytes_after_return にプロパティのバイト長 (actual_format_return が 16または32であっても)を返す。この場合も引き数 delete は無視される。引き数 nitems_return は空である。
指定したプロパティが存在し、かつ、引き数 req_type に AnyPropertyType を指定するか指定したタイプが実際のプロパティと一致した場合は、 XGetWindowProperty は actual_type_return に実際のプロパティのタイプ、actual_format_return に実際のプロパティのフォーマット(決してゼロにならない)を返す。また、以下で定義する値を bytes_after_return と nitems_return に返す。 .IP .nf N = 格納されているプロパティの実際のバイト長 (フォーマットが16または32の場合も含む) I = 4 * long_offset T = N - I L = MINIMUM(T, 4 * long_length) A = N - (I + L) .fi .IP 返される値は(ゼロから数えて) I 番目のバイトから始まり、長さは L バイトである。 long_offset の値により L が負の値になった場合、エラー BadValueとなる。 bytes_after_return の値は A である。これは格納されているプロパティ内に残っていてまだ読んでいないバイト数である。

返されたフォーマットが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は以下の動作を行う。

引き数 mode が PropModeReplace ならば、 XChangePropertyは以前のプロパティ値を破棄し、新しいデータを格納する。
mode が PropModePrependならば、 XChangePropertyは現在あるデータの先頭に指定したデータを挿入し、 mode が PropModeAppendならば、現在あるデータの末尾に指定したデータを挿入する。タイプとフォーマットは現在あるプロパティ値と一致していなければならず、そうでない場合にはエラー BadMatchとなる。プロパティが定義されていない場合、これは正しいタイプとフォーマットで定義された、長さゼロのデータとして扱われる。

指定したフォーマットが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は、指定したセレクションが指定した型に変換されることを要求する。

指定したセレクションに所有者がいる場合、X サーバは SelectionRequestをその所有者に送る。
指定されたセレクションの所有者がいない場合、 X サーバはプロパティに SelectionNotifyを設定して None イベントを要求者に送る。

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

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

目次に戻る

ForgetGravity	EastGravity
NorthWestGravity	SouthWestGravity
NorthGravity	SouthGravity
NorthEastGravity	SouthEastGravity
WestGravity	StaticGravity
CenterGravity

UnmapGravity	EastGravity
NorthWestGravity	SouthWestGravity
NorthGravity	SouthGravity
NorthEastGravity	SouthEastGravity
WestGravity	StaticGravity
CenterGravity

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