1XmbTextListToTextProperty(3)    XLIB FUNCTIONS    XmbTextListToTextProperty(3)
2
3
4

NAME

6       XmbTextListToTextProperty,  XwcTextListToTextProperty, Xutf8TextListTo‐
7       TextProperty,   XmbTextPropertyToTextList,   XwcTextPropertyToTextList,
8       Xutf8TextPropertyToTextList,  XwcFreeStringList,  XDefaultString - con‐
9       vert text lists and text property structures
10

SYNTAX

12       int XmbTextListToTextProperty(Display *display, char **list, int count,
13              XICCEncodingStyle style, XTextProperty *text_prop_return);
14
15       int  XwcTextListToTextProperty(Display  *display,  wchar_t  **list, int
16              count,       XICCEncodingStyle       style,        XTextProperty
17              *text_prop_return);
18
19       int  Xutf8TextListToTextProperty(Display  *display,  char  **list,  int
20              count,       XICCEncodingStyle       style,        XTextProperty
21              *text_prop_return);
22
23       int  XmbTextPropertyToTextList(Display  *display, _Xconst XTextProperty
24              *text_prop, char ***list_return, int *count_return);
25
26       int XwcTextPropertyToTextList(Display *display,  _Xconst  XTextProperty
27              *text_prop, wchar_t ***list_return, int *count_return);
28
29       int Xutf8TextPropertyToTextList(Display *display, _Xconst XTextProperty
30              *text_prop, char ***list_return, int *count_return);
31
32       void XwcFreeStringList(wchar_t **list);
33
34       char *XDefaultString(void)
35

ARGUMENTS

37       display   Specifies the connection to the X server.
38
39       list      Specifies a list of null-terminated character strings.
40
41       count     Specifies the number of strings specified.
42
43       style     Specifies the manner in which the property is encoded.
44
45       text_prop_return
46                 Returns the XTextProperty structure.
47
48       text_prop Specifies the XTextProperty structure to be used.
49
50       list_return
51                 Returns a list of null-terminated character strings.
52
53       count_return
54                 Returns the number of strings.
55
56       list      Specifies the list of strings to be freed.
57

DESCRIPTION

59       The    XmbTextListToTextProperty,     XwcTextListToTextProperty     and
60       Xutf8TextListToTextProperty  functions  set the specified XTextProperty
61       value to a set of null-separated elements representing  the  concatena‐
62       tion  of the specified list of null-terminated text strings.  The input
63       text strings must be given in the current  locale  encoding  (for  Xmb‐
64       TextListToTextProperty  and  XwcTextListToTextProperty),  or  in  UTF-8
65       encoding (for Xutf8TextListToTextProperty).
66
67       The functions set the encoding field of text_prop_return to an Atom for
68       the  specified  display naming the encoding determined by the specified
69       style and convert the specified text list to this encoding for  storage
70       in  the  text_prop_return  value  field.   If the style XStringStyle or
71       XCompoundTextStyle is specified, this encoding  is  “STRING”  or  “COM‐
72       POUND_TEXT”, respectively.  If the style XUTF8StringStyle is specified,
73       this encoding is “UTF8_STRING”.  (This is an  extension  introduced  by
74       The  XFree86  Project,  Inc.,  in their 4.0.2 release.  Its presence is
75       indicated by the macro X_HAVE_UTF8_STRING.)  If the style XTextStyle is
76       specified, this encoding is the encoding of the current locale.  If the
77       style XStdICCTextStyle is specified, this encoding is “STRING”  if  the
78       text  is  fully  convertible  to STRING, else “COMPOUND_TEXT”.  A final
79       terminating null byte is stored at  the  end  of  the  value  field  of
80       text_prop_return but is not included in the nitems member.
81
82       If insufficient memory is available for the new value string, the func‐
83       tions return XNoMemory.  If the current locale is  not  supported,  the
84       functions  return  XLocaleNotSupported.   In both of these error cases,
85       the functions do not set text_prop_return.
86
87       To determine if the functions are guaranteed not to return  XLocaleNot‐
88       Supported, use XSupportsLocale.
89
90       If  the  supplied text is not fully convertible to the specified encod‐
91       ing, the functions return the number of unconvertible characters.  Each
92       unconvertible  character  is converted to an implementation-defined and
93       encoding-specific default string.  Otherwise, the functions return Suc‐
94       cess.   Note that full convertibility to all styles except XStringStyle
95       is guaranteed.
96
97       To free the storage for the value field, use XFree.
98
99       The    XmbTextPropertyToTextList,     XwcTextPropertyToTextList     and
100       Xutf8TextPropertyToTextList  functions  return  a  list of text strings
101       representing the null-separated elements of the specified XTextProperty
102       structure.   The  returned strings are encoded using the current locale
103       encoding (for XmbTextPropertyToTextList and  XwcTextPropertyToTextList)
104       or  in  UTF-8 (for Xutf8TextPropertyToTextList).  The data in text_prop
105       must be format 8.
106
107       Multiple elements of the property (for example, the strings in  a  dis‐
108       joint  text  selection)  are separated by a null byte.  The contents of
109       the property are not required to be  null-terminated;  any  terminating
110       null should not be included in text_prop.nitems.
111
112       If insufficient memory is available for the list and its elements, Xmb‐
113       TextPropertyToTextList, XwcTextPropertyToTextList and  Xutf8TextProper‐
114       tyToTextList return XNoMemory.  If the current locale is not supported,
115       the functions return XLocaleNotSupported.  Otherwise, if  the  encoding
116       field  of  text_prop  is not convertible to the encoding of the current
117       locale,  the  functions  return  XConverterNotFound.    For   supported
118       locales,   existence   of   a  converter  from  COMPOUND_TEXT,  STRING,
119       UTF8_STRING or the encoding of the  current  locale  is  guaranteed  if
120       XSupportsLocale  returns  True  for  the current locale (but the actual
121       text may contain unconvertible characters).  Conversion of other encod‐
122       ings  is  implementation-dependent.   In  all of these error cases, the
123       functions do not set any return values.
124
125       Otherwise,  XmbTextPropertyToTextList,  XwcTextPropertyToTextList   and
126       Xutf8TextPropertyToTextList  return  the  list  of null-terminated text
127       strings to list_return and the number of text strings to count_return.
128
129       If the value field of text_prop is not fully convertible to the  encod‐
130       ing  of  the  current locale, the functions return the number of uncon‐
131       vertible characters.  Each unconvertible character is  converted  to  a
132       string  in  the  current locale that is specific to the current locale.
133       To obtain the value of this  string,  use  XDefaultString.   Otherwise,
134       XmbTextPropertyToTextList, XwcTextPropertyToTextList and Xutf8TextProp‐
135       ertyToTextList return Success.
136
137       To free the storage for the list and  its  contents  returned  by  Xmb‐
138       TextPropertyToTextList      or     Xutf8TextPropertyToTextList,     use
139       XFreeStringList.  To free the storage for the  list  and  its  contents
140       returned by XwcTextPropertyToTextList, use XwcFreeStringList.
141
142       The XwcFreeStringList function frees memory allocated by XwcTextProper‐
143       tyToTextList.
144
145       The XDefaultString function returns the default string used by Xlib for
146       text  conversion  (for  example,  in  XmbTextPropertyToTextList).   The
147       default string is the string in the current locale that is output  when
148       an  unconvertible  character  is  found during text conversion.  If the
149       string returned by XDefaultString is the empty string (""), no  charac‐
150       ter  is  output  in the converted text.  XDefaultString does not return
151       NULL.
152
153       The string returned by XDefaultString is  independent  of  the  default
154       string  for  text  drawing;  see  XCreateFontSet  to obtain the default
155       string for an XFontSet.
156
157       The behavior when an invalid codepoint is supplied to any Xlib function
158       is undefined.
159
160       The returned string is null-terminated.  It is owned by Xlib and should
161       not be modified or freed by the client.  It may be freed after the cur‐
162       rent locale is changed.  Until freed, it will not be modified by Xlib.
163
164       The   functions  Xutf8TextListToTextProperty  and  Xutf8TextPropertyTo‐
165       TextList are extensions introduced by The  XFree86  Project,  Inc.,  in
166       their  4.0.2  release.   Their  presence  is  indicated  by  the  macro
167       X_HAVE_UTF8_STRING.
168

STRUCTURES

170       The XTextProperty structure contains:
171
172       typedef struct {
173               unsigned char *value;   /* property data */
174               Atom encoding;  /* type of property */
175               int format;     /* 8, 16, or 32 */
176               unsigned long nitems;   /* number of items in value */
177       } XTextProperty;
178
179       The XICCEncodingStyle structure contains:
180
181       #define   XNoMemory              -1
182       #define   XLocaleNotSupported    -2
183       #define   XConverterNotFound     -3
184       typedef enum {
185               XStringStyle,           /* STRING */
186               XCompoundTextStyle,     /* COMPOUND_TEXT */
187               XTextStyle,             /* text in owner's encoding (current locale) */
188               XStdICCTextStyle,       /* STRING, else COMPOUND_TEXT */
189               XUTF8StringStyle        /* UTF8_STRING */
190       } XICCEncodingStyle;
191

SEE ALSO

193       XSetTextProperty(3), XStringListToTextProperty(3)
194       Xlib - C Language X Interface
195
196
197
198X Version 11                     libX11 1.6.12    XmbTextListToTextProperty(3)
Impressum