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  *text_prop_re‐
17              turn);
18
19       int  Xutf8TextListToTextProperty(Display  *display,  char  **list,  int
20              count,  XICCEncodingStyle  style,  XTextProperty  *text_prop_re‐
21              turn);
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 en‐
65       coding (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 in‐
75       dicated 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  lo‐
118       cales, existence of a converter from COMPOUND_TEXT, STRING, UTF8_STRING
119       or the encoding of the current locale is guaranteed if  XSupportsLocale
120       returns  True  for  the current locale (but the actual text may contain
121       unconvertible characters).  Conversion of other encodings is  implemen‐
122       tation-dependent.   In  all  of these error cases, the functions do not
123       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 re‐
140       turned 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 de‐
147       fault string is the string in the current locale that is output when an
148       unconvertible character is found during text conversion.  If the string
149       returned by XDefaultString is the empty string (""),  no  character  is
150       output in the converted text.  XDefaultString does not return NULL.
151
152       The  string  returned  by  XDefaultString is independent of the default
153       string for text drawing;  see  XCreateFontSet  to  obtain  the  default
154       string for an XFontSet.
155
156       The behavior when an invalid codepoint is supplied to any Xlib function
157       is undefined.
158
159       The returned string is null-terminated.  It is owned by Xlib and should
160       not be modified or freed by the client.  It may be freed after the cur‐
161       rent locale is changed.  Until freed, it will not be modified by Xlib.
162
163       The  functions  Xutf8TextListToTextProperty  and   Xutf8TextPropertyTo‐
164       TextList  are  extensions  introduced  by The XFree86 Project, Inc., in
165       their  4.0.2  release.   Their  presence  is  indicated  by  the  macro
166       X_HAVE_UTF8_STRING.
167

STRUCTURES

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

SEE ALSO

195       XSetTextProperty(3), XStringListToTextProperty(3)
196       Xlib - C Language X Interface
197
198
199
200X Version 11                     libX11 1.7.0     XmbTextListToTextProperty(3)
Impressum