名称

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プロパティを削除するか否かを決定するブール値を指定します。

displayX サーバへのコネクションを指定します。

formatデータを 8 ビットのリストとしてみなすか、または 16 ビットあるいは 32 ビットのリストとしてみなすかを指定します。 8、16、および 32 という値を使用できます。 この情報により、 X サーバは必要に応じて適切にバイトスワップを行う ことができます。 フォーマットが 16 ビットまたは 32 ビットであれば、 XChangeProperty へのコールでデータポインタを (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 は、return 引数を次のように設定します。

•指定されたウィンドウについて指定されたプロパティが存在しない場合、 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 引数は空です。

•指定されたプロパティが存在し、 AnyPropertyType を req_type 引数に割り当てるか、または指定された型が実際のプロパティの 型と一致する場合、 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)

返された値は、プロパティ中のバイトインデックスで始まり、 バイト長は L です。 long_offset の値によって L が負となる場合、 BadValue エラーが生じます。 bytes_after_return の値は A であり、 ストアされたプロパティの残りの未読取りバイト数を与えます。 XGetWindowProperty は、必ず、 pop_return で余分に 1 バイトを割り当て、 文字からなる単純なプロパティを使用前に他の文字列にコピーしなくて すむよう、 ASCII ナルに設定します。 delete が True で、bytes_after_return が 0 であれば、 XGetWindowProperty は、ウィンドウからプロパティを削除し、ウィンドウに対し PropertyNotify イベントを発生します。 この関数は、適切に実行された場合、 Success を返します。 この結果のデータを解放するには、 XFree を使用します。 XGetWindowProperty は、 BadAtom、 BadValue および BadWindow エラーを生じることがあります。 XListProperties 関数は、指定されたウィンドウのため定義されるアトムプロパティの 配列へのポインタを返すか、またはいかなるプロパティもなければ NULL を 返します。 この関数によって割り当てられたメモリを解放するには、 XFree を使用します。 XListProperties は、 BadWindow エラーを生じることがあります。 XChangeProperty 関数は指定されたウィンドウのプロパティを変更し、 X サーバがこのウィンドウで PropertyNotify イベントを発生します。 XChangeProperty は、以下を行います。

•モードが PropModeReplace であれば、 XChangeProperty は前のプロパティ値を捨て、新しいデータをストアします。

•モードが PropModePrepend または PropModeAppend であれば、 XChangeProperty は、指定されたデータを既存のデータの前かまたは既存のデータの終りに挿入します。 型とフォーマットは、既存のプロパティ値と一致しなければなりません。 さもなければ BadMatch エラーが生じます。 プロパティが未定義であれば、 長さが 0 のデータを含む正しい型とフォーマットで定義されたとみなされます。 プロパティのライフタイムは、登録するクライアントには影響されません。 明示的に削除するか、ウィンドウが破壊されるかまたはサーバが リセットするまで、プロパティは残ります。 X サーバへのコネクションがクローズされた場合に何が起こるかについては、 第 2.5 節を参照してください。 プロパティの最大サイズは、サーバ依存であり、サーバが利用できるメモリ 量に応じて動的に変わることがあります （スペースが不十分であれば、 BadAlloc エラーが生じます）。 XChangeProperty は、 BadAlloc、 BadAtom、 BadMatch、 BadValue および BadWindow エラーを生じることがあります。 XRotateWindowProperties 関数により、ウィンドウでプロパティをローテートでき、 X サーバは PropertyNotify イベントを発生します。 プロパティ配列中のプロパティ名が 0 から番号付けされるものとみなし、 またリスト中に num_prop で示される数のプロパティ名がある場合、 0 から N − 1 までのすべての I について、プロパティ名 I の値は、 プロパティ名 (I + npositions) mod N の値となります。 この結果、プロパティ名の仮想リング上を（npositions が正なら右、 npositions が負なら左に） npositions だけ状態をローテートしたことに なります。 npositions mod N が 0 以外であれば、 X サーバは、各プロパティについて 配列でリストされている順に PropertyNotify イベントを発生します。 アトムがリスト中で 2 回以上生じるか、またはウィンドウについてその名前の いかなるプロパティも定義されなければ、 BadMatch エラーが生じます。 BadAtom または BadMatch エラーが生じた場合、 いかなるプロパティも変更されません。 XRotateWindowProperties は、 BadAtom、 BadMatch および BadWindow エラーを生じることがあります。 XDeleteProperty 関数は、指定されたウィンドウでプロパティが定義されている場合にだけ 指定されたプロパティを削除し、 もしプロパティが存在しなければ、 X サーバがウィンドウで PropertyNotify イベントを発生します。 XDeleteProperty は、 BadAtom および BadWindow エラーを生じることがあります。

診断

BadAlloc サーバが、要求されたリソースまたはサーバメモリの割当てに失敗した。

BadAtom Atom 引数の値が、定義された Atom を指さない。

BadValue ある数値が許容範囲を超えた。 引数の値の範囲が明示されない限り、引数のタイプによって決まる最大の 範囲まで指定可能です。 選択形式の引数も、このエラーを生じることがあります。

BadWindow
Window 引数の値が定義されたウィンドウを指さない。

関連事項

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

NEWS-OSRelease 4.1C