XGetWindowProperty

Section: XLIB FUNCTIONS (3X11)
Updated: Release 6.3
Index xjman/web INDEX
 

名前


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

書式

int XGetWindowProperty(display, w, property, long_offset, long_length, delete, req_type,

                        actual_type_returnactual_format_returnnitems_returnbytes_after_return

                        prop_return)

      Display *display;

      Window w;

      Atom property;

      long long_offsetlong_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 propertytype;

      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


 

Index

名前
書式
引き数
説明
返り値
関連項目

This document was created by man2html, using the manual pages.
Time: 15:55:47 GMT, February 12, 2001