Back

プロパティ関数

アトム
XInternAtom文字列に関連付けられたアトム識別子を返す
XInternAtoms複数のアトム識別子を取得
XGetAtomNameアトムに関連付けられた名前を返す
XGetAtomNamesアトムに関連付けられた名前を複数個返す
プロパティ
XGetWindowPropertyウィンドウのプロパティを取得
XListPropertiesウィンドウに定義されているプロパティのリストを返す
XChangePropertyプロパティのデータを変更
XRotateWindowPropertiesプロパティの値を回転する
XDeletePropertyプロパティを削除
セレクション
XSetSelectionOwner指定セレクションの所有者を変更する
XGetSelectionOwnerセレクションの所有者を返す
XConvertSelectionセレクションから指定ターゲットのデータを要求
テキストプロパティ
struct XTextPropertyテキストプロパティ構造体
XmbTextListToTextProperty
XwcTextListToTextProperty
Xutf8TextListToTextProperty		文字列のリストを XTextProperty に変換
XmbTextPropertyToTextList
XwcTextPropertyToTextList
Xutf8TextPropertyToTextList		XTextProperty を文字列のリストに変換
XFreeStringList
XwcFreeStringList		文字列のリストを解放
XDefaultStringテキスト変換のデフォルトの文字列を返す
XStringListToTextProperty文字列のリストを STRING 型の XTextProperty に変換
XTextPropertyToStringListSTRING 型の XTextProperty を文字列リストに変換
XSetTextPropertyウィンドウのプロパティにテキストプロパティをセット
XGetTextPropertyウィンドウからテキストプロパティを読み込み
アトム
Atom XInternAtom(Display *display, char *atom_name, Bool only_if_exists);
指定された文字列に関連付けられたアトム識別子を返します。
アトム名がホストポータブル文字エンコーディングでない場合、結果は実装に依存します。
大文字と小文字は区別されます。

アトムは、クライアントの接続が閉じられた後でも、定義されたままの状態になります。
X サーバーへの最後の接続が閉じられた場合のみ、未定義になります。
only_if_exists
False の場合、アトムが存在しない場合は、作成される。
True の場合、存在しない場合は None が返る。
戻り値
アトム識別子。None で定義されていない。
Status XInternAtoms(Display *display, char **names, int count, Bool only_if_exists, Atom *atoms_return);
指定された名前に関連付けられたアトム識別子を、複数個返します。
names
文字列の配列
count
数
atoms_return
ここに結果が入る
戻り値
全ての名前に対してアトムが返された場合、０以外。一つでもアトムが返されなかった場合、０。
char *XGetAtomName(Display *display, Atom atom);
指定されたアトムに関連付けられた名前を返します。
サーバーから返されたデータがラテンポータブル文字エンコーディングである場合、返される文字列はホストポータブル文字エンコーディングになります。
それ以外の場合、結果は実装に依存します。

Error: BadAtom
戻り値
確保されたポインタ。XFree() で解放する。
Status XGetAtomNames(Display *display, Atom *atoms, int count, char **names_return);
アトムに関連付けられた名前を複数個返す
atoms
アトムの配列
count
数
names_return
count 個の char * の配列を用意して、そのポインタを渡す。
各文字列ごとにポインタがセットされるので、配列のそれぞれの文字列は XFree() で解放する。
戻り値
全てのアトムに対して名前が返された場合、０以外。一つでも返されなかった場合、０。
プロパティ
int XGetWindowProperty(Display *display, Window w, Atom property, long long_offset, long 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);
ウィンドウのプロパティを読み込む。

指定プロパティがウィンドウに存在しない場合、actual_type_return = None、actual_format_return = 0, bytes_after_return = 0, nitems_return = 0 になる。この場合、delete 引数は無視される。

指定プロパティが存在するが、タイプが一致しない場合、actual_type_return = 実際のタイプ、actual_format_return = 実際のプロパティ形式、bytes_after_return = プロパティ長 (常にバイト単位)、nitems_return = 0 になる。また、delete 引数は無視される。

指定プロパティが存在し、req_type = AnyPropertyType または、プロパティタイプが一致する場合、actual_type_return = 実際のタイプ、actual_format_return = 実際のプロパティ形式、bytes_after_return と nitems_return は以下の計算で返す。

N = データの長さ (バイト単位)
I = 4 * long_offset
T = N - I
L = min(T, 4 * long_length)
A = N - (I + L)

返される値は、プロパティの I byte から始まり、バイト長は L である。
bytes_after_return は A であり、格納されたプロパティの末尾の未読バイト数を示す。

delete が True で bytes_after_return が 0 の場合、プロパティを削除し、PropertyNotify イベントを生成します。
property
プロパティのアトム
long_offset
プロパティ内のオフセット位置を、4byte 単位で指定
long_length
取得するデータの長さを 4byte 単位で指定。
実際より大きなサイズを指定しても良い。
delete
True で、すべて読み込んだ後にプロパティを削除する。
req_type
プロパティ値のタイプのアトム。
AnyPropertyType を指定した場合、任意のタイプ。
actual_type_return
実際のプロパティタイプのアトムが入る
actual_format_return
実際のプロパティのフォーマットが入る
nitems_return
prop_return に格納されている数が入る (8 = 1byte, 16 = 2byte, 32 = 4byte 単位)
bytes_after_return
残りのバイト数
prop_return
確保されたデータのポインタが入る。XFree() で解放する。
format = 8 の場合、char 配列。
format = 16 の場合、short 配列。
format = 32 の場合、long 配列として扱われる。

文字列が常にヌル文字で終われるように、データ長が 0 であっても、常に +1byte 余分に確保して、終端に０をセットする。
戻り値
Success で正常に実行された
Atom *XListProperties(Display *display, Window w, int *num_prop_return);
指定されたウィンドウに定義されているプロパティの、アトム配列へのポインタを返す。
num_prop_return
プロパティの数が入る
戻り値
確保されたアトム配列のポインタ。XFree() で解放する。
プロパティがない場合は NULL。
XChangeProperty(Display *display, Window w, Atom property, Atom type, int format, int mode, unsigned char *data, int nelements);
指定プロパティのデータを変更し、PropertyNotify イベントを生成させます。

プロパティは、明示的にプロパティが削除されるか、ウィンドウが破棄されるまで、またはサーバーがリセットされるまで、残ります。
プロパティの値の最大サイズはサーバーに依存し、サーバーが使用可能なメモリの量に応じて、動的に変化する可能性があります。(容量が足りない場合は BadAlloc エラーとなります)

※XOrg の実装においては、最大 XMaxRequestSize() のサイズまでしか対応しておらず、それ以上のサイズは分割して設定する必要がある (XExtendedMaxRequestSize のサイズには対応していない)。
type
プロパティタイプのアトム。
X サーバーは型を解釈しません。XGetWindowProperty を呼び出したアプリケーションに対して、この型を返します。
format
8,16,32 のいずれか。
mode
操作モード。
PropModeReplace: 以前の値を破棄し、新しいデータに置き換える。
PropModePrepend: 既存のデータの前に挿入。
PropModeAppend: 既存のデータの後に追加。

挿入/追加の場合、タイプとフォーマットは一致する必要があります。
プロパティが未定義の場合は、置き換えに等しくなります。
data
プロパティのデータ。
format = 8 なら char 配列、format = 16 なら short 配列、format = 32 なら long 配列。
nelements
データの個数
XRotateWindowProperties(Display *display, Window w, Atom properties[], int num_prop, int npositions);
ウィンドウ上のプロパティの値を回転し、各プロパティごとに PropertyNotify イベントを生成させます。

配列内のプロパティが、その順番でリング状につながっているとみなされ、各プロパティの値を、指定方向と個数分、回転させます。

リスト内に同じアトムが複数回出現する場合、または、そのプロパティがウィンドウに定義されていない場合は、BadMatch エラーが発生します。
BadAtom または BadMatch エラーが発生した場合、プロパティは変更されません。
properties
プロパティのアトムの配列
num_prop
プロパティの数
npositions
回転する量。正で右、負で左方向。
XDeleteProperty(Display *display, Window w, Atom property);
指定されたプロパティが、指定されたウィンドウで定義されている場合にのみ、指定されたプロパティを削除します。
プロパティが存在しない場合を除いて、PropertyNotify イベントを生成します。
セレクション
XSetSelectionOwner(Display *display, Atom selection, Window owner, Time time);
指定されたセレクションの所有者と最終変更時刻を変更する。

指定された時刻が、指定されたセレクションの現在の最終変更時刻よりも早い場合、または、現在の X サーバー時刻よりも遅い場合は効果がありません。
それ以外の場合、最終変更時刻は指定された時刻に設定され、CurrentTime は現在のサーバー時刻に置き換えられます。

所有者ウィンドウが None として指定されている場合、所有者なしになります。
それ以外の場合、セレクションの所有者は、リクエストを実行したクライアントになります。
新しい所有者 (None 含む) が、セレクションの現在の所有者と同じではなく、現在の所有者が None でない場合、現在の所有者に SelectionClear イベントが送信されます。

セレクションの所有者であるクライアントが、後で終了した場合 (つまり、接続が閉じられた場合)、または、指定した所有者ウィンドウが後で破棄された場合、セレクションの所有者は自動的に None に戻りますが、最終変更時刻は影響を受けません。
selection アトムは X サーバーによって解釈されません。

セレクションは X サーバーに対してグローバルです。
selection
セレクションのアトム
owner
セレクションの所有者。None でなし。
time
タイムスタンプまたは CurrentTime
Window XGetSelectionOwner(Display *display, Atom selection);
指定されたセレクションを現在所有しているウィンドウの ID を返します。
selection が指定されていない場合、None を返します。
None が返された場合、所有者は存在しません。
XConvertSelection(Display *display, Atom selection, Atom target, Atom property, Window requestor, Time time);
指定されたセレクションから、指定されたターゲットタイプに変換することを要求します。

所有者がいる場合、X サーバーはその所有者に SelectionRequest イベントを送信します。
所有者が存在しない場合、X サーバーは、property = None を指定して、要求元に SelectionNotify イベントを生成します。

どちらのイベントにおいても、引数は変更されずに渡されます。
target
ターゲットのアトム
property
プロパティ名。
None の場合、所有者が任意のプロパティを選択する。
requestor
要求者
time
タイムスタンプまたは CurrentTime
テキストプロパティ
typedef struct {
    unsigned char *value;
    Atom encoding;
    int format;
    unsigned long nitems;
} XTextProperty;
"TEXT" タイプのプロパティの多くでは、さまざまなタイプと形式が使用できます。
これらのプロパティに格納されるデータは、単純な NULL 終了文字列ではないため、XTextProperty 構造体を使用して、テキストのエンコード、タイプ、長さ、およびその値を記述します。
value
テキストデータ。複数個の場合は、ヌル区切り。
encoding
データのタイプ
format
8,16,32
nitems
データの個数
int XmbTextListToTextProperty(Display *display, char **list, int count, XICCEncodingStyle style, XTextProperty *text_prop_return);
int XwcTextListToTextProperty(Display *display, wchar_t **list, int count, XICCEncodingStyle style, XTextProperty *text_prop_return);
int Xutf8TextListToTextProperty(Display *display, char **list, int count, XICCEncodingStyle style, XTextProperty *text_prop_return);

typedef enum {
    XStringStyle,         // STRING (ラテン文字)
    XCompoundTextStyle,   // COMPOUND_TEXT (マルチエンコーディング)
    XTextStyle,           // 現在のロケール
    XStdICCTextStyle,     // STRING, 変換できなければ COMPOUND_TEXT
    XUTF8StringStyle      // UTF8_STRING (XFree86 による拡張)
} XICCEncodingStyle;

#define XNoMemory           -1
#define XLocaleNotSupported -2
#define XConverterNotFound  -3
文字列のリストを、単一の XTextProperty に変換します。

Xutf8 は、XFree86 (4.0.2) による拡張。
list
文字列のリスト。
ヌル文字で終わる文字列のポインタの配列。
count
文字列の個数
style
変換後のエンコーディング
text_prop_return
結果が入る。value データは、XFree() で解放する。
変換できない各文字は、実装定義およびエンコード固有のデフォルト文字列に変換されます。
XStringStyle を除くすべてのスタイルへは、完全な変換が保証されている。
戻り値
完全に変換できた場合 Success。
指定されたエンコーディングに完全に変換できない場合、変換できない文字の数を返します。
XNoMemory でメモリが足りない。
XLocaleNotSupported で、現在のロケールがサポートされていない (XSupportsLocale() で判定可能)。
int XmbTextPropertyToTextList(Display *display, XTextProperty *text_prop, char ***list_return, int *count_return);
int XwcTextPropertyToTextList(Display *display, XTextProperty *text_prop, wchar_t ***list_return, int *count_return);
int Xutf8TextPropertyToTextList(Display *display, const XTextProperty *text_prop, char ***list_return, int *count_return);
XTextProperty を文字列のリストに変換します。
text_prop のデータは format = 8 である必要があります。

プロパティの複数の要素は、NULL バイトで区切られます。
プロパティの内容は NULL で終了する必要はありません。
終端の null を nitems に含めないでください。

サポートされているロケールでは、XSupportsLocale() が現在のロケールに対して True を返す場合、COMPOUND_TEXT、STRING、または現在のロケールのエンコーディングからのコンバーターの存在が保証されます (ただし、実際のテキストには変換できない文字が含まれている可能性があります)。
他のエンコーディングの変換は実装に依存します。これらのエラーの場合はいずれも、関数は戻り値を設定しません。
list_return
ヌル文字で終わる文字列のリストが確保されて、返る。
XFreeStringList または XwcFreeStringList を使って解放する。
変換できない各文字は、現在のロケールに固有の現在のロケールの文字列に変換されます。この文字列の値を取得するには、XDefaultString を使用します。
count_return
リストの数が入る
戻り値
完全に変換できた場合 Success。
現在のエンコーディングに完全に変換できない場合、変換できない文字の数を返します。
XNoMemory でメモリが足りない。
XLocaleNotSupported で、現在のロケールがサポートされていない。
XTextProperty::encoding が現在のロケールのエンコーディングに変換できない場合、XConverterNotFound を返す。
void XFreeStringList(char **list);
void XwcFreeStringList(wchar_t **list);
文字列のリストを解放
char *XDefaultString(void);
Xlib がテキスト変換に使用するデフォルトの文字列 (XmbTextPropertyToTextList など) を返します。
デフォルトの文字列は、テキスト変換中に変換できない文字が見つかったときに出力される現在のロケールの文字列です。
XDefaultString によって返された文字列が空の文字列 ("") の場合、変換されたテキストには文字は出力されません。
XDefaultString は NULL を返しません。

XDefaultString によって返される文字列は、テキスト描画のデフォルトの文字列から独立しています。
XFontSet のデフォルト文字列を取得するには、XCreateFontSet を参照してください。

無効なコードポイントが Xlib 関数に指定された場合の動作は未定義です。

返される文字列は null で終了します。
これは Xlib によって所有されており、クライアントによって変更または解放されるべきではありません。
現在のロケールが変更された後に解放される可能性があります。
解放されるまで、Xlib によって変更されることはありません。
Status XStringListToTextProperty(char **list, int count, XTextProperty *text_prop_return);
文字列のリストを STRING 型 (format = 8) の XTextProperty に変換する。
余分な null バイト (nitems メンバーには含まれない) が、text_prop_return の value フィールドの最後に格納されます。
文字列は (検証なしで) STRING エンコーディングであると想定されます。
value フィールドのストレージを解放するには、XFree を使用します。
戻り値
新しい値文字列に使用できるメモリが不十分な場合、XTextProperty 構造体にフィールドを設定せず、ゼロを返します。
それ以外の場合は、ゼロ以外を返します。
Status XTextPropertyToStringList(XTextProperty *text_prop, char ***list_return, int *count_return);
STRING 型の XTextProperty を文字列リストに変換する。
text_prop のデータは、STRING 型、format = 8 である必要があります。

プロパティの複数の要素は、NULL (エンコード 0) で区切られます。
プロパティの内容は null で終了しません。
リストとその内容用のストレージを解放するには、XFreeStringList を使用します。
戻り値
リストとその要素に使用できるメモリが不十分な場合、戻り値を設定せず、ゼロを返します。
それ以外の場合は、ゼロ以外のステータスを返します。
void XSetTextProperty(Display *display, Window w, XTextProperty *text_prop, Atom property);
指定されたウィンドウの既存の指定されたプロパティを、指定された XTextProperty 構造体のデータで置き換え。
プロパティがまだ存在しない場合、XSetTextProperty は指定されたウィンドウにプロパティを設定します。
Status XGetTextProperty(Display *display, Window w, XTextProperty *text_prop_return, Atom property);
指定されたプロパティをウィンドウから読み取り、XTextProperty 構造体にデータを格納します。
null を含む追加バイト (nitems メンバーには含まれない) が、text_prop_return の値フィールドの最後に格納されます。
プロパティのエンコードとテキストとしてのデータの特定の解釈は、呼び出し元のアプリケーションに任されます。
指定されたプロパティがウィンドウに存在しない場合、すべての値が 0 になる。
戻り値
０以外で成功。それ以外の場合は、０