書式

int XmbTextListToTextProperty(display, list, count, style, text_prop_return)

      Display *display;

      char **list;

      int count;

      XICCEncodingStyle style;

      XTextProperty *text_prop_return;

int XwcTextListToTextProperty(display, list, count, style, text_prop_return)

      Display *display;

      wchar_t **list;

      int count;

      XICCEncodingStyle style;

      XTextProperty *text_prop_return;

int Xutf8TextListToTextProperty(display, list, count, style, text_prop_return)

      Display *display;

      char **list;

      int count;

      XICCEncodingStyle style;

      XTextProperty *text_prop_return;

int XmbTextPropertyToTextList(display, text_prop, list_return, count_return)

      Display *display;

      XTextProperty *text_prop;

      char ***list_return;

      int *count_return;

int XwcTextPropertyToTextList(display, text_prop, list_return, count_return)

      Display *display;

      XTextProperty *text_prop;

      wchar_t ***list_return;

      int *count_return;

int Xutf8TextPropertyToTextList(display, text_prop, list_return, count_return)

      Display *display;

      XTextProperty *text_prop;

      char ***list_return;

      int *count_return;

void XwcFreeStringList(list)

      wchar_t **list;

char *XDefaultString()

引き数

display

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

list

NULL 文字で終わる文字列のリストを指定する。

count

指定した文字列の数を指定する。

style

プロパティをエンコードする方法を指定する。

text_prop_return

XTextProperty 構造体が返される。

text_prop

使用する XTextProperty 構造体を指定する。

list_return

NULL 文字で終わる文字列のリストが返される。

count_return

文字列 の数が返される。

list

解放する文字列のリストを指定する。

説明

関数 XmbTextListToTextProperty, XwcTextListToTextProperty, Xutf8TextListToTextProperty は指定した XTextProperty の値として NULL 文字で区切られた要素からなる集合を設定する。ここで設定 する集合は、NULL 文字で終わるテキスト文字列からなる指定したリストを結 合したものである。 入力するテキストは現在のロケールのエンコーディング( XmbTextListToTextProperty および XwcTextListToTextProperty の場合)または UTF-8 エンコーディング( Xutf8TextListToTextProperty の場合)で与えなければならない。

これらの関数は text_prop_return の encoding フィールドに、指定した ディスプレイに対する Atom を設定する。この Atom は指定したスタイルから決まるエンコーディングを示す。 これらの関数は次に、指定したテキストリストをこのエンコーディングに変換 して text_prop_return フィールドに入れる。 スタイルに XStringStyle あるいは XCompoundTextStyle が指定された場合は、このエンコーディングはそれぞれ ``STRING'' か ``COMPOUND_TEXT'' となる。 スタイルに XUTF8StringStyle が指定された場合は、エンコーディングは ``UTF8_STRING'' となる(これは XFree86 4.0.2 で導入された XFree86 独自の拡張である。これが使えるかど うかはマクロ X_HAVE_UTF8_STRING で判定できる)。 スタイルに XTextStyle が指定された場合には、エンコーディングは現在のロケールのエンコーディン グとなる。 スタイルに XStdICCTextStyle が指示された場合、テキストが完全に STRING に変換可能であれば エンコーディングは ``STRING'' に、そうでなければ ``COMPOUND_TEXT'' に なる。 終端の NULL バイトは text_prop_return の value フィールドの末尾に 格納されるが、これは nitems のメンバの数には含められない。

新しい文字列(XTextProperty の value フィールド)に割り当てるメモリが十 分にない場合、関数は XNoMemory を返す。 現在のロケールがサポートされていない場合、関数は XLocaleNotSupported を返す。 どちらのエラーの場合も、関数は text_prop_return に値を設定しない。

関数が XLocaleNotSupported を返さないかどうかを確実に知るためには、関数 XSupportsLocale を利用すること。

与えられたテキストの全てが指定されたエンコーディングに変換可能でない場 合、関数は変換できない文字の数を返す。 変換できない文字はそれぞれ実装定義かつエンコーディング特有のデフォルト 文字列に変換される。 上記以外の場合には、関数は Success を返す。 XStringStyle を除く全てのスタイルに対しては、テキストを完全に変換できることが保証さ れている点に注意すること。

XTextProperty 構造体の value フィールドのメモリを解放するには、 XFree を使用すること。

関数 XmbTextPropertyToTextList, XwcTextPropertyToTextList, Xutf8TextPropertyToTextList は、与えられた XTextProperty 構造体が持つ要素(NULL 文字で区切られている)を表すテキスト文字列の リストを返す。 返される文字列のエンコーディングは現在のロケールのエンコーディング( XmbTextPropertyToTextList および XwcTextPropertyToTextList の場合)または UTF-8 ( Xutf8TextPropertyToTextList の場合)である。 text_prop 内のデータはフォーマット 8 でなければならない。

プロパティの複数の要素(例えば、ばらばらのテキストセレクション文字列)は NULL バイトで区切られる。 プロパティの内容は NULL で終わる必要はない。 終端の NULL 文字は text_prop.nitems に含まれてはならない。

リストとその要素に割り当てる十分なメモリがない場合、関数 XmbTextPropertyToTextList, XwcTextPropertyToTextList, Xutf8TextPropertyToTextList は XNoMemory を返す。 現在のロケールがサポートされていない場合、関数は XLocaleNotSupported を返す。 それ以外の場合、もし text_prop の encoding フィールドを現在のロケール のエンコーディングに変換することができなければ、関数は XConverterNotFound を返す。 サポートされているロケールに対しては、 XSupportsLocale が現在のロケールに対して True を返すのであれば、 COMPOUND_TEXT, STRING, UTF8_STRING, 現在のロケールのエンコーディング からのコンバータの存在が保証される(ただし、実際のテキストは変換不可能 な文字を含むかもしれない)。 他のエンコーディングとの変換については実装依存である。 以上のいずれのエラーの場合も関数は返り値を設定しない。

それ以外の場合には、 XmbTextPropertyToTextList, XwcTextPropertyToTextList, Xutf8TextPropertyToTextList は list_return に NULL 文字で終わるテキスト文字列のリストを返し、 count_return にテキスト文字列の数を返す。

もし、text_prop の value フィールドを現在のロケールのエンコーディング に完全には変換できない場合には、関数は変換できない文字の数を返す。 変換できないそれぞれの文字は、現在のロケールに含まれ、かつ 現在のロケールに特有の文字列に変換される。 この文字列の値を得るには XDefaultString を使用する。 それ以外の場合、 XmbTextPropertyToTextList, XwcTextPropertyToTextList, Xutf8TextPropertyToTextList は Success を返す。

XmbTextPropertyToTextList や Xutf8TextPropertyToTextList が返したリストとその内容のためのメモリを解放するには XFreeStringList を使用する。 XwcTextPropertyToTextList が返したリストとその内容のためのメモリを解放するには XwcFreeStringList を使用する。

関数 XwcFreeStringList は、 XwcTextPropertyToTextList によって割り当てられたメモリを解放する。

関数 XDefaultString は Xlib が(例えば、 XmbTextPropertyToTextList で)テキスト変換に用いるデフォルト文字列を返す。 デフォルト文字列は現在のロケールの文字列であり、テキスト変換中に変換で きない文字が現れたときに出力される。 XDefaultString が返す文字列が空文字列("")である場合、変換されたテキストには何も出力 されない。 XDefaultString は NULL を返さない。

XDefaultString が返す文字列は、テキスト描画のデフォルト文字列とは独立である。 XFontSet に対するデフォルト文字列を得たい場合は XCreateFontSet の項を参照すること。

undefined. Xlib の全ての関数は、不正な文字コードが与えられたときの動作は未定義で ある。

返される文字列は NULL 文字で終わる。 これは Xlib が所有しているので、クライアントは変更や解放をしてはならない。 これは現在のロケールが変更された後に解放される。 解放されるまでは、Xlib によって変更されることはない。

関数 Xutf8TextListToTextProperty および Xutf8TextPropertyToTextList は XFree86 4.0.2 から導入された XFree86 独自の拡張である。この関数が あるかどうかはマクロ X_HAVE_UTF8_STRING で判定できる。

構造体

XTextProperty 構造体の内容を示す。

typedef struct {
     unsigned char *value;
     Atom encoding;      
     int format;         
     unsigned long nitems;
} XTextProperty;

XICCEncodingStyle 構造体の内容を示す。

#define	XNoMemory	-1
#define	XLocaleNotSupported	-2
#define	XConverterNotFound	-3

typedef enum {
     XStringStyle,       
     XCompoundTextStyle, 
     XTextStyle,         
     XStdICCTextStyle,   
     XUTF8StringStyle    
} XICCEncodingStyle;