XmbTextListToTextProperty(3X11)

名前
XmbTextListToTextProperty, XwcTextListToTextProperty, Xutf8TextListToTextProperty, XmbTextPropertyToTextList, XwcTextPropertyToTextList, Xutf8TextPropertyToTextList, XwcFreeStringList, XDefaultString - テキストリストとテキストプロパティ構造体を相互に変換する

書式
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
    構造体が返される。

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

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

count_return
    文字列 の数が返される。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

構造体
構造体の内容を示す。

typedef struct {
    unsigned char *value;    /* プロパティのデータ */
    Atom encoding;    /* プロパティのタイプ */
    int format;    /* 8, 16, 32 のいずれか */
     unsigned long nitems;    /* value 内の要素数 */
} XTextProperty;

構造体の内容を示す。

#define |  | -1
#define |  | -2
#define |  | -3
typedef enum {
    XStringStyle,    /* STRING */
    XCompoundTextStyle,    /* COMPOUND_TEXT */
    XTextStyle,    /* 所有者のエンコーディングの文字列 (現在のロケール) */
    XStdICCTextStyle,    /* STRING, さもなくば COMPOUND_TEXT */
    XUTF8StringStyle    /* UTF8_STRING */
} XICCEncodingStyle;

関連項目
XSetTextProperty(3X11), XStringListToTextProperty(3X11)
Xlib - C Language X Interface