man/XmbTextListToTextProperty.man

   1 '\" t
   2 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
   3 .\" Copyright \(co 2000  The XFree86 Project, Inc.
   4 .\"
   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:
  12 .\"
  13 .\" The above copyright notice and this permission notice shall be included
  14 .\" in all copies or substantial portions of the Software.
  15 .\"
  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.
  23 .\"
  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.
  28 .\"
  29 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
  30 .\" Digital Equipment Corporation
  31 .\"
  32 .\" Portions Copyright \(co 1990, 1991 by
  33 .\" Tektronix, Inc.
  34 .\"
  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.
  44 .\"
  45 .\"
  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
  50 .na
  51 .de Ds
  52 .nf
  53 .\\$1D \\$2 \\$1
  54 .ft 1
  55 .\".ps \\n(PS
  56 .\".if \\n(VS>=40 .vs \\n(VSu
  57 .\".if \\n(VS<=39 .vs \\n(VSp
  58 ..
  59 .de De
  60 .ce 0
  61 .if \\n(BD .DF
  62 .nr BD 0
  63 .in \\n(OIu
  64 .if \\n(TM .ls 2
  65 .sp \\n(DDu
  66 .fi
  67 ..
  68 .de FD
  69 .LP
  70 .KS
  71 .TA .5i 3i
  72 .ta .5i 3i
  73 .nf
  74 ..
  75 .de FN
  76 .fi
  77 .KE
  78 .LP
  79 ..
  80 .de IN          \" send an index entry to the stderr
  81 ..
  82 .de C{
  83 .KS
  84 .nf
  85 .D
  86 .\"
  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...
  91 .\"
  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
  96 .el .ft R
  97 .ps \\n(PS
  98 .ie \\n(VS>40 .vs \\n(VSu
  99 .el .vs \\n(VSp
 100 ..
 101 .de C}
 102 .DE
 103 .R
 104 ..
 105 .de Pn
 106 .ie t \\$1\fB\^\\$2\^\fR\\$3
 107 .el \\$1\fI\^\\$2\^\fP\\$3
 108 ..
 109 .de ZN
 110 .ie t \fB\^\\$1\^\fR\\$2
 111 .el \fI\^\\$1\^\fP\\$2
 112 ..
 113 .de hN
 114 .ie t <\fB\\$1\fR>\\$2
 115 .el <\fI\\$1\fP>\\$2
 116 ..
 117 .de NT
 118 .ne 7
 119 .ds NO Note
 120 .if \\n(.$>$1 .if !'\\$2'C' .ds NO \\$2
 121 .if \\n(.$ .if !'\\$1'C' .ds NO \\$1
 122 .ie n .sp
 123 .el .sp 10p
 124 .TB
 125 .ce
 126 \\*(NO
 127 .ie n .sp
 128 .el .sp 5p
 129 .if '\\$1'C' .ce 99
 130 .if '\\$2'C' .ce 99
 131 .in +5n
 132 .ll -5n
 133 .R
 134 ..
 135 .               \" Note End -- doug kraft 3/85
 136 .de NE
 137 .ce 0
 138 .in -5n
 139 .ll +5n
 140 .ie n .sp
 141 .el .sp 10p
 142 ..
 143 .ny0
 144 '\" t
 145 .TH XmbTextListToTextProperty __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
 146 .SH NAME
 147 XmbTextListToTextProperty, XwcTextListToTextProperty, Xutf8TextListToTextProperty, XmbTextPropertyToTextList, XwcTextPropertyToTextList, Xutf8TextPropertyToTextList, XwcFreeStringList, XDefaultString \- convert text lists and text property structures
 148 .SH SYNTAX
 149 .HP
 150 int XmbTextListToTextProperty\^(\^Display *\fIdisplay\fP\^, char
 151 **\fIlist\fP\^, int \fIcount\fP\^, XICCEncodingStyle \fIstyle\fP\^,
 152 XTextProperty *\fItext_prop_return\fP\^);
 153 .HP
 154 int XwcTextListToTextProperty\^(\^Display *\fIdisplay\fP\^, wchar_t
 155 **\fIlist\fP\^, int \fIcount\fP\^, XICCEncodingStyle \fIstyle\fP\^,
 156 XTextProperty *\fItext_prop_return\fP\^);
 157 .HP
 158 int Xutf8TextListToTextProperty\^(\^Display *\fIdisplay\fP\^, char
 159 **\fIlist\fP\^, int \fIcount\fP\^, XICCEncodingStyle \fIstyle\fP\^,
 160 XTextProperty *\fItext_prop_return\fP\^);
 161 .HP
 162 int XmbTextPropertyToTextList\^(\^Display *\fIdisplay\fP\^, XTextProperty
 163 *\fItext_prop\fP\^, char ***\fIlist_return\fP\^, int *\fIcount_return\fP\^);
 164 .HP
 165 int XwcTextPropertyToTextList\^(\^Display *\fIdisplay\fP\^, XTextProperty
 166 *\fItext_prop\fP\^, wchar_t ***\fIlist_return\fP\^, int
 167 *\fIcount_return\fP\^);
 168 .HP
 169 int Xutf8TextPropertyToTextList\^(\^Display *\fIdisplay\fP\^, XTextProperty
 170 *\fItext_prop\fP\^, char ***\fIlist_return\fP\^, int *\fIcount_return\fP\^);
 171 .HP
 172 void XwcFreeStringList\^(\^wchar_t **\fIlist\fP\^);
 173 .HP
 174 char *XDefaultString\^(void)
 175 .SH ARGUMENTS
 176 .IP \fIdisplay\fP 1i
 177 Specifies the connection to the X server.
 178 .IP \fIlist\fP 1i
 179 Specifies a list of null-terminated character strings.
 180 .IP \fIcount\fP 1i
 181 Specifies the number of strings specified.
 182 .IP \fIstyle\fP 1i
 183 Specifies the manner in which the property is encoded.
 184 .IP \fItext_prop_return\fP 1i
 185 Returns the
 186 .ZN XTextProperty
 187 structure.
 188 .IP \fItext_prop\fP 1i
 189 Specifies the
 190 .ZN XTextProperty
 191 structure to be used.
 192 .IP \fIlist_return\fP 1i
 193 Returns a list of null-terminated character strings.
 194 .ds Cn strings
 195 .IP \fIcount_return\fP 1i
 196 Returns the number of \*(Cn.
 197 .IP \fIlist\fP 1i
 198 Specifies the list of strings to be freed.
 199 .SH DESCRIPTION
 200 The
 201 .ZN XmbTextListToTextProperty ,
 202 .ZN XwcTextListToTextProperty
 203 and
 204 .ZN Xutf8TextListToTextProperty
 205 functions set the specified
 206 .ZN XTextProperty
 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
 211 and
 212 .ZN XwcTextListToTextProperty ),
 213 or in UTF-8 encoding (for
 214 .ZN Xutf8TextListToTextProperty ).
 215 .LP
 216 The functions set the encoding field of text_prop_return to an
 217 .ZN Atom
 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.
 222 If the style
 223 .ZN XStringStyle
 224 or
 225 .ZN XCompoundTextStyle
 226 is specified,
 227 this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
 228 If the style
 229 .ZN XUTF8StringStyle
 230 is specified,
 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 .)
 235 If the style
 236 .ZN XTextStyle
 237 is specified,
 238 this encoding is the encoding of the current locale.
 239 If the style
 240 .ZN XStdICCTextStyle
 241 is specified,
 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.
 246 .LP
 247 If insufficient memory is available for the new value string,
 248 the functions return
 249 .ZN XNoMemory .
 250 If the current locale is not supported,
 251 the functions return
 252 .ZN XLocaleNotSupported .
 253 In both of these error cases,
 254 the functions do not set text_prop_return.
 255 .LP
 256 To determine if the functions are guaranteed not to return
 257 .ZN XLocaleNotSupported ,
 258 use
 259 .ZN XSupportsLocale .
 260 .LP
 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
 266 .ZN Success .
 267 Note that full convertibility to all styles except
 268 .ZN XStringStyle
 269 is guaranteed.
 270 .LP
 271 To free the storage for the value field, use
 272 .ZN XFree .
 273 .LP
 274 The
 275 .ZN XmbTextPropertyToTextList ,
 276 .ZN XwcTextPropertyToTextList
 277 and
 278 .ZN Xutf8TextPropertyToTextList
 279 functions return a list of text strings representing the
 280 null-separated elements of the specified
 281 .ZN XTextProperty
 282 structure. The returned strings are encoded using the current locale encoding
 283 (for
 284 .ZN XmbTextPropertyToTextList
 285 and
 286 .ZN XwcTextPropertyToTextList )
 287 or in UTF-8 (for
 288 .ZN Xutf8TextPropertyToTextList ).
 289 The data in text_prop must be format 8.
 290 .LP
 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.
 295 .LP
 296 If insufficient memory is available for the list and its elements,
 297 .ZN XmbTextPropertyToTextList ,
 298 .ZN XwcTextPropertyToTextList
 299 and
 300 .ZN Xutf8TextPropertyToTextList
 301 return
 302 .ZN XNoMemory .
 303 If the current locale is not supported,
 304 the functions return
 305 .ZN XLocaleNotSupported .
 306 Otherwise, if the encoding field of text_prop is not convertible
 307 to the encoding of the current locale,
 308 the functions return
 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
 313 .ZN XSupportsLocale
 314 returns
 315 .ZN True
 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.
 321 .LP
 322 Otherwise,
 323 .ZN XmbTextPropertyToTextList ,
 324 .ZN XwcTextPropertyToTextList
 325 and
 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.
 329 .LP
 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,
 336 use
 337 .ZN XDefaultString .
 338 Otherwise,
 339 .ZN XmbTextPropertyToTextList ,
 340 .ZN XwcTextPropertyToTextList
 341 and
 342 .ZN Xutf8TextPropertyToTextList
 343 return
 344 .ZN Success .
 345 .LP
 346 To free the storage for the list and its contents returned by
 347 .ZN XmbTextPropertyToTextList
 348 or
 349 .ZN Xutf8TextPropertyToTextList ,
 350 use
 351 .ZN XFreeStringList .
 352 To free the storage for the list and its contents returned by
 353 .ZN XwcTextPropertyToTextList ,
 354 use
 355 .ZN XwcFreeStringList .
 356 .LP
 357 The
 358 .ZN XwcFreeStringList
 359 function frees memory allocated by
 360 .ZN XwcTextPropertyToTextList .
 361 .LP
 362 The
 363 .ZN XDefaultString
 364 function returns the default string used by Xlib for text conversion
 365 (for example, in
 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
 370 .ZN XDefaultString
 371 is the empty string ("\^"),
 372 no character is output in the converted text.
 373 .ZN XDefaultString
 374 does not return NULL.
 375 .LP
 376 The string returned by
 377 .ZN XDefaultString
 378 is independent of the default string for text drawing;
 379 see
 380 .ZN XCreateFontSet
 381 to obtain the default string for an
 382 .ZN XFontSet .
 383 .LP
 384 The behavior when an invalid codepoint is supplied to any Xlib function is
 385 undefined.
 386 .LP
 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.
 391 .LP
 392 The functions
 393 .ZN Xutf8TextListToTextProperty
 394 and
 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 .
 400 .SH STRUCTURES
 401 The
 402 .ZN XTextProperty
 403 structure contains:
 404 .LP
 405 .Ds 0
 406 .TA .5i 2.5i
 407 .ta .5i 2.5i
 408 typedef struct {
 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 */
 413 } XTextProperty;
 414 .De
 415 .LP
 416 The
 417 .ZN XICCEncodingStyle
 418 structure contains:
 419 .LP
 420 .TS
 421 lw(.5i) lw(2i) lw(2.5i).
 422 T{
 423 \&#define
 424 T}      T{
 425 .ZN XNoMemory
 426 T}      T{
 427 \-1
 428 T}
 429 T{
 430 \&#define
 431 T}      T{
 432 .ZN XLocaleNotSupported
 433 T}      T{
 434 \-2
 435 T}
 436 T{
 437 \&#define
 438 T}      T{
 439 .ZN XConverterNotFound
 440 T}      T{
 441 \-3
 442 T}
 443 .TE
 444 .Ds 0
 445 .TA .5i 2.5i
 446 .ta .5i 2.5i
 447 typedef enum {
 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 */
 453 } XICCEncodingStyle;
 454 .De
 455 .SH "SEE ALSO"
 456 XSetTextProperty(__libmansuffix__),
 457 XStringListToTextProperty(__libmansuffix__)
 458 .br
 459 \fI\*(xL\fP