名前¶

XGetWindowProperty, XListProperties, XChangeProperty, XRotateWindowProperties, XDeleteProperty - ウィンドウのプロパティの取得と変更を行なう

書式¶

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; Atom *XListProperties( display, w, num_prop_return)
Display * display;
Window w;
int * num_prop_return; 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; XRotateWindowProperties( display, w, properties, num_prop, npositions)
Display * display;
Window w;
Atom properties[];
int num_prop;
int npositions; XDeleteProperty( display, w, property)
Display * display;
Window w;
Atom property;

引き数¶

actual_format_return

プロパティの実際のフォーマットが返される。

actual_type_return

プロパティの実際のタイプを定義するアトム識別子が返される。

bytes_after_return

プロパティの一部だけ読み込んだ場合、残りのバイト数が返される。

data

プロパティのデータを指定する。

delete

プロパティを削除するかどうか決定する真偽値を指定する。

display

X サーバへの接続を指定する。

format

データを 8ビット、16ビット、32ビットいずれの単位のリストとみなすかを 指定する。 8, 16, 32 を指定できる。 この情報により、X サーバは必要に応じてバイト交換を正しく行うことができ る。 フォーマットが 16ビットか32ビットの場合には、 XChangeProperty の呼び出しの際にはデータへのポインタを (unsigned char *) にキャストし なければならない。

long_length

取得するデータの32ビット倍で長さを指定する。

long_offset

データが取り込まれる、指定したプロパティ内のオフセット(32ビット単位)を 指定する。

mode

操作のモードを指定する。 PropModeReplace, PropModePrepend, PropModeAppend のいずれかを指定できる。

nelements

指定したデータフォーマットの要素数を指定する。

nitems_return

prop_return に格納された 8ビット、16ビット、32ビットのアイテムの実際の 数が返される。

num_prop

プロパティの配列の長さを指定する。

num_prop_return

プロパティの配列の長さが返される。

npositions

ローテーションの量を指定する。

prop_return

指定したフォーマットのデータが返される。

property

プロパティ名を指定する。

properties

ローテートさせるプロパティの配列を指定する。

req_type

プロパティのタイプに対応するアトム識別子か AnyPropertyType を指定する。

type

プロパティの型を指定する。 X サーバは型の解釈は行わないが、後で XGetWindowProperty を呼び出したアプリケーションにこの型をそのまま返す。

w

プロパティの取得、変更、ローテート、削除を行うウィンドウを指定する。

説明¶

関数 XGetWindowProperty はプロパティの実際のタイプ、プロパティの実際のフォーマット、転送される 8ビット、16ビット、32ビットのアイテム数、プロパティに残っている読み込 むべきバイト数、データへのポインタを返す。 XGetWindowProperty は値を返す引き数に対して以下のように値を設定する。

•

指定したウィンドウに対する指定したプロパティが存在しない場合、 XGetWindowProperty は actual_type_return に None を返し、actual_format_return と bytes_after_return に 0 を返す。 引き数 nitems_return は空になる。 この場合には引き数 delete は無視される。

•

指定したプロパティは存在するが指定したタイプに一致しない場合、 XGetWindowProperty は actual_type_return に実際のプロパティのタイプ、 actual_format_return に実際のプロパティのフォーマット(決して 0 にはな らない)、bytes_after_return にプロパティのバイト長 (actual_format_return が16または32であっても)を返す。 この場合も引き数 delete は無視される。 引き数 nitems_return は空である。

•

指定したプロパティが存在し、かつ、引き数 req_type に AnyPropertyType を指定するか指定したタイプが実際のプロパティと一致した場合は、 XGetWindowProperty は actual_type_return に実際のプロパティのタイプ、actual_format_return に 実際のプロパティのフォーマット(決して 0 にならない)を返す。 また、以下で定義する値を bytes_after_return と nitems_return に返す。

 	N = 格納されているプロパティの実際のバイト長
 	     (フォーマットが16または32の場合も含む)
	I = 4 * long_offset
	T = N - I
	L = MINIMUM(T, 4 * long_length)
	A = N - (I + L)
    

返される値は(0 から数えて) I 番目のバイトから始まり、長さは L バイト である。 long_offset の値により L が負の値になった場合、エラー BadValue となる。 bytes_after_return の値は A である。これは格納されているプロパティ内に 残っていてまだ読んでいないバイト数である。

返されたフォーマットが8ならば、返されたデータは char の配列として表現されている。 返されたフォーマットが16ならば、返されたデータは short の配列として表現されており、要素を得るにはその型にキャストしなければな らない。 返されたフォーマットが32ならば、返されたデータは long の配列として表現されており、要素を得るにはその型にキャストしなければな らない。 XGetWindowProperty XGetWindowProperty は常に prop_return に追加の1バイトを割り当て、そこに 0 を設定する。 文字からなる簡単なプロパティを、使用前に別の文字列にコピーする必要 がないようにするためである。 delete が True で bytes_after_return が 0 ならば、 XGetWindowProperty はプロパティをウィンドウから削除し、そのウィンドウ上に PropertyNotify イベントを生成する。 この関数は正常に実行された場合、 Success を返す。 得られたデータを解放するには XFree を使用すること。 XGetWindowProperty はエラー BadAtom, BadValue, BadWindow を起こすことがある。 関数 XListProperties は指定されたウィンドウに対して定義されているアトムプロパティの配列への ポインタを返す。プロパティが見つからなかった場合には NULL を返す。 この関数が割り当てたメモリを解放するには XFree を使うこと。 XListProperties はエラー BadWindow を起こすことがある。 関数 XChangeProperty は指定されたウィンドウのプロパティを変更し、 そのウィンドウ上の PropertyNotify イベントを X サーバに生成させる。 XChangeProperty は以下の動作を行う。

•

引き数 mode が PropModeReplace ならば、 XChangeProperty は以前のプロパティ値を破棄し、新しいデータを格納する。

•

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

指定したフォーマットが8ならば、プロパティのデータは char 型の配列でなければならない。 指定したフォーマットが16ならば、プロパティのデータは short 型の配列でなければならない。 指定したフォーマットが32ならば、プロパティのデータは long 型の配列でなければならない。 プロパティの存続期間は、格納を行ったクライアントとは結びつけられない。 プロパティは明示的に削除されるか、ウィンドウが破壊されるか、サーバが再 設定するまで残る。 X サーバへの接続が切れた際の挙動については、2.6 章を参照すること。 プロパティの最大サイズはサーバに依存し、これはサーバが利用可能なメモリ 量によって動的に変わることもある。 (十分なメモリが確保できない場合はエラー BadAlloc となる。) XChangeProperty はエラー BadAlloc, BadAtom, BadMatch, BadValue, BadWindow を起こすことがある。 関数 XRotateWindowProperties を使うと、ウィンドウのプロパティをローテートさせることができる。また、 この関数はX サーバに PropertyNotify イベントを生成させる。 プロパティの配列内のプロパティ名に 0 から始まる番号を付け、リスト中に num_prop 個のプロパティ名があるものとすると、プロパティ名 I に対応する 値はプロパティ名 (I + npositions) mod N に対応する値となる(I の値は 0 か N-1 まで)。 この関数の効果は、状態をプロパティ名の仮想的なリングの周りで npositions 分の位置だけローテートさせることである(npositions が正なら ば右周りで、負ならば左回り)。 npositions mod N が 0 でなければ、X サーバは 配列中に列挙されている順に各プロパティに対する PropertyNotify イベントを生成する。 1つのアトムがリスト中に2度以上現われた場合とウィンドウに対してその名前 のプロパティが定義されていない場合には、エラー BadMatch となる。 エラー BadAtom あるいは BadMatch が起きた場合、プロパティは変更されない。 XRotateWindowProperties はエラー BadAtom, BadMatch, BadWindow を起こすことがある。 関数 XDeleteProperty は指定したプロパティが指定したウィンドウに対して定義されている場合に限 ってこのプロパティを削除し、そのウィンドウ上での PropertyNotify イベントを X サーバに生成させる。 XDeleteProperty はエラー BadAtom、 BadWindow を起こすことがある。

返り値¶

BadAlloc

要求されたリソースやサーバメモリの割り当てにサーバが失敗した。

BadAtom

引き数 Atom の値が、定義されている Atom を指していない。

BadValue

指定された数値に、リクエストの許容範囲を越えているものがある。引き数に対 して特定の範囲が指定されていなければ、引き数の型で定義されている全ての範 囲が許される。選択肢として定義されている引き数はこのエラーを起こすことが ある。

BadWindow

引き数 Window の値が、定義されている Window を指していない。

関連項目¶

XFree(3X11), XInternAtom(3X11) Xlib - C Language X Interface