2 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
3 .\" Copyright \(co 2000 The XFree86 Project, Inc.
5 .\" Permission is hereby granted, free of charge, to any person obtaining
6 .\" a copy of this software and associated documentation files (the
7 .\" "Software"), to deal in the Software without restriction, including
8 .\" without limitation the rights to use, copy, modify, merge, publish,
9 .\" distribute, sublicense, and/or sell copies of the Software, and to
10 .\" permit persons to whom the Software is furnished to do so, subject to
11 .\" the following conditions:
13 .\" The above copyright notice and this permission notice shall be included
14 .\" in all copies or substantial portions of the Software.
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
20 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22 .\" OTHER DEALINGS IN THE SOFTWARE.
24 .\" Except as contained in this notice, the name of the X Consortium shall
25 .\" not be used in advertising or otherwise to promote the sale, use or
26 .\" other dealings in this Software without prior written authorization
27 .\" from the X Consortium.
29 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
30 .\" Digital Equipment Corporation
32 .\" Portions Copyright \(co 1990, 1991 by
35 .\" Permission to use, copy, modify and distribute this documentation for
36 .\" any purpose and without fee is hereby granted, provided that the above
37 .\" copyright notice appears in all copies and that both that copyright notice
38 .\" and this permission notice appear in all copies, and that the names of
39 .\" Digital and Tektronix not be used in in advertising or publicity pertaining
40 .\" to this documentation without specific, written prior permission.
41 .\" Digital and Tektronix makes no representations about the suitability
42 .\" of this documentation for any purpose.
43 .\" It is provided ``as is'' without express or implied warranty.
46 .ds xT X Toolkit Intrinsics \- C Language Interface
47 .ds xW Athena X Widgets \- C Language X Toolkit Interface
48 .ds xL Xlib \- C Language X Interface
49 .ds xC Inter-Client Communication Conventions Manual
56 .\".if \\n(VS>=40 .vs \\n(VSu
57 .\".if \\n(VS<=39 .vs \\n(VSp
80 .de IN \" send an index entry to the stderr
87 .\" choose appropriate monospace font
88 .\" the imagen conditional, 480,
89 .\" may be changed to L if LB is too
90 .\" heavy for your eyes...
92 .ie "\\*(.T"480" .ft L
93 .el .ie "\\*(.T"300" .ft L
94 .el .ie "\\*(.T"202" .ft PO
95 .el .ie "\\*(.T"aps" .ft CW
98 .ie \\n(VS>40 .vs \\n(VSu
106 .ie t \\$1\fB\^\\$2\^\fR\\$3
107 .el \\$1\fI\^\\$2\^\fP\\$3
110 .ie t \fB\^\\$1\^\fR\\$2
111 .el \fI\^\\$1\^\fP\\$2
114 .ie t <\fB\\$1\fR>\\$2
120 .if \\n(.$>$1 .if !'\\$2'C' .ds NO \\$2
121 .if \\n(.$ .if !'\\$1'C' .ds NO \\$1
135 . \" Note End -- doug kraft 3/85
145 .TH XmbTextListToTextProperty __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
147 XmbTextListToTextProperty, XwcTextListToTextProperty, Xutf8TextListToTextProperty, XmbTextPropertyToTextList, XwcTextPropertyToTextList, Xutf8TextPropertyToTextList, XwcFreeStringList, XDefaultString \- convert text lists and text property structures
150 int XmbTextListToTextProperty\^(\^Display *\fIdisplay\fP\^, char
151 **\fIlist\fP\^, int \fIcount\fP\^, XICCEncodingStyle \fIstyle\fP\^,
152 XTextProperty *\fItext_prop_return\fP\^);
154 int XwcTextListToTextProperty\^(\^Display *\fIdisplay\fP\^, wchar_t
155 **\fIlist\fP\^, int \fIcount\fP\^, XICCEncodingStyle \fIstyle\fP\^,
156 XTextProperty *\fItext_prop_return\fP\^);
158 int Xutf8TextListToTextProperty\^(\^Display *\fIdisplay\fP\^, char
159 **\fIlist\fP\^, int \fIcount\fP\^, XICCEncodingStyle \fIstyle\fP\^,
160 XTextProperty *\fItext_prop_return\fP\^);
162 int XmbTextPropertyToTextList\^(\^Display *\fIdisplay\fP\^, XTextProperty
163 *\fItext_prop\fP\^, char ***\fIlist_return\fP\^, int *\fIcount_return\fP\^);
165 int XwcTextPropertyToTextList\^(\^Display *\fIdisplay\fP\^, XTextProperty
166 *\fItext_prop\fP\^, wchar_t ***\fIlist_return\fP\^, int
167 *\fIcount_return\fP\^);
169 int Xutf8TextPropertyToTextList\^(\^Display *\fIdisplay\fP\^, XTextProperty
170 *\fItext_prop\fP\^, char ***\fIlist_return\fP\^, int *\fIcount_return\fP\^);
172 void XwcFreeStringList\^(\^wchar_t **\fIlist\fP\^);
174 char *XDefaultString\^(void)
177 Specifies the connection to the X server.
179 Specifies a list of null-terminated character strings.
181 Specifies the number of strings specified.
183 Specifies the manner in which the property is encoded.
184 .IP \fItext_prop_return\fP 1i
188 .IP \fItext_prop\fP 1i
191 structure to be used.
192 .IP \fIlist_return\fP 1i
193 Returns a list of null-terminated character strings.
195 .IP \fIcount_return\fP 1i
196 Returns the number of \*(Cn.
198 Specifies the list of strings to be freed.
201 .ZN XmbTextListToTextProperty ,
202 .ZN XwcTextListToTextProperty
204 .ZN Xutf8TextListToTextProperty
205 functions set the specified
207 value to a set of null-separated elements representing the concatenation
208 of the specified list of null-terminated text strings. The input text
209 strings must be given in the current locale encoding (for
210 .ZN XmbTextListToTextProperty
212 .ZN XwcTextListToTextProperty ),
213 or in UTF-8 encoding (for
214 .ZN Xutf8TextListToTextProperty ).
216 The functions set the encoding field of text_prop_return to an
218 for the specified display
219 naming the encoding determined by the specified style
220 and convert the specified text list to this encoding for storage in
221 the text_prop_return value field.
225 .ZN XCompoundTextStyle
227 this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
231 this encoding is ``UTF8_STRING''.
232 (This is an extension introduced by The XFree86 Project, Inc. in their 4.0.2
233 release. Its presence is indicated by the macro
234 .ZN X_HAVE_UTF8_STRING .)
238 this encoding is the encoding of the current locale.
242 this encoding is ``STRING'' if the text is fully convertible to STRING,
243 else ``COMPOUND_TEXT''.
244 A final terminating null byte is stored at the end of the value field
245 of text_prop_return but is not included in the nitems member.
247 If insufficient memory is available for the new value string,
250 If the current locale is not supported,
252 .ZN XLocaleNotSupported .
253 In both of these error cases,
254 the functions do not set text_prop_return.
256 To determine if the functions are guaranteed not to return
257 .ZN XLocaleNotSupported ,
259 .ZN XSupportsLocale .
261 If the supplied text is not fully convertible to the specified encoding,
262 the functions return the number of unconvertible characters.
263 Each unconvertible character is converted to an implementation-defined and
264 encoding-specific default string.
265 Otherwise, the functions return
267 Note that full convertibility to all styles except
271 To free the storage for the value field, use
275 .ZN XmbTextPropertyToTextList ,
276 .ZN XwcTextPropertyToTextList
278 .ZN Xutf8TextPropertyToTextList
279 functions return a list of text strings representing the
280 null-separated elements of the specified
282 structure. The returned strings are encoded using the current locale encoding
284 .ZN XmbTextPropertyToTextList
286 .ZN XwcTextPropertyToTextList )
288 .ZN Xutf8TextPropertyToTextList ).
289 The data in text_prop must be format 8.
291 Multiple elements of the property (for example, the strings in a disjoint
292 text selection) are separated by a null byte.
293 The contents of the property are not required to be null-terminated;
294 any terminating null should not be included in text_prop.nitems.
296 If insufficient memory is available for the list and its elements,
297 .ZN XmbTextPropertyToTextList ,
298 .ZN XwcTextPropertyToTextList
300 .ZN Xutf8TextPropertyToTextList
303 If the current locale is not supported,
305 .ZN XLocaleNotSupported .
306 Otherwise, if the encoding field of text_prop is not convertible
307 to the encoding of the current locale,
309 .ZN XConverterNotFound .
310 For supported locales,
311 existence of a converter from COMPOUND_TEXT, STRING, UTF8_STRING
312 or the encoding of the current locale is guaranteed if
316 for the current locale (but the actual text
317 may contain unconvertible characters).
318 Conversion of other encodings is implementation-dependent.
319 In all of these error cases,
320 the functions do not set any return values.
323 .ZN XmbTextPropertyToTextList ,
324 .ZN XwcTextPropertyToTextList
326 .ZN Xutf8TextPropertyToTextList
327 return the list of null-terminated text strings to list_return
328 and the number of text strings to count_return.
330 If the value field of text_prop is not fully convertible to the
331 encoding of the current locale,
332 the functions return the number of unconvertible characters.
333 Each unconvertible character is converted to a string in the
334 current locale that is specific to the current locale.
335 To obtain the value of this string,
339 .ZN XmbTextPropertyToTextList ,
340 .ZN XwcTextPropertyToTextList
342 .ZN Xutf8TextPropertyToTextList
346 To free the storage for the list and its contents returned by
347 .ZN XmbTextPropertyToTextList
349 .ZN Xutf8TextPropertyToTextList ,
351 .ZN XFreeStringList .
352 To free the storage for the list and its contents returned by
353 .ZN XwcTextPropertyToTextList ,
355 .ZN XwcFreeStringList .
358 .ZN XwcFreeStringList
359 function frees memory allocated by
360 .ZN XwcTextPropertyToTextList .
364 function returns the default string used by Xlib for text conversion
366 .ZN XmbTextPropertyToTextList ).
367 The default string is the string in the current locale that is output
368 when an unconvertible character is found during text conversion.
369 If the string returned by
371 is the empty string ("\^"),
372 no character is output in the converted text.
374 does not return NULL.
376 The string returned by
378 is independent of the default string for text drawing;
381 to obtain the default string for an
384 The behavior when an invalid codepoint is supplied to any Xlib function is
387 The returned string is null-terminated.
388 It is owned by Xlib and should not be modified or freed by the client.
389 It may be freed after the current locale is changed.
390 Until freed, it will not be modified by Xlib.
393 .ZN Xutf8TextListToTextProperty
395 .ZN Xutf8TextPropertyToTextList
396 are extensions introduced by The XFree86 Project, Inc. in their 4.0.2
397 release. Their presence is
398 indicated by the macro
399 .ZN X_HAVE_UTF8_STRING .
409 unsigned char *value; /\&* property data */
410 Atom encoding; /\&* type of property */
411 int format; /\&* 8, 16, or 32 */
412 unsigned long nitems; /\&* number of items in value */
417 .ZN XICCEncodingStyle
421 lw(.5i) lw(2i) lw(2.5i).
432 .ZN XLocaleNotSupported
439 .ZN XConverterNotFound
448 XStringStyle, /\&* STRING */
449 XCompoundTextStyle, /\&* COMPOUND_TEXT */
450 XTextStyle, /\&* text in owner's encoding (current locale) */
451 XStdICCTextStyle, /\&* STRING, else COMPOUND_TEXT */
452 XUTF8StringStyle /\&* UTF8_STRING */
456 XSetTextProperty(__libmansuffix__),
457 XStringListToTextProperty(__libmansuffix__)