XGetWindowProperty(3X11)

名前
 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ビットの場合には、 の呼び出しの際にはデータへのポインタを (unsigned char *) にキャストし なければならない。

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

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

mode
    操作のモードを指定する。 のいずれかを指定できる。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

•   指定したプロパティが存在し、かつ、引き数 req_type に を指定するか指定したタイプが実際のプロパティと一致した場合は、 は 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 が負の値になった場合、エラー となる。 bytes_after_return の値は A である。これは格納されているプロパティ内に 残っていてまだ読んでいないバイト数である。

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

は常に prop_return に追加の1バイトを割り当て、そこに 0 を設定する。 文字からなる簡単なプロパティを、使用前に別の文字列にコピーする必要 がないようにするためである。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

返り値

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

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

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

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

関連項目
XFree(3X11), XInternAtom(3X11)
Xlib - C Language X Interface