Manual Pages for UNIX Operating System command usage for man Xutf8TextListToTextProperty

XLIB FUNCTIONS                    XmbTextListToTextProperty(3x11)



NAME
     XmbTextListToTextProperty, XwcTextListToTextProperty,
     Xutf8TextListToTextProperty, XmbTextPropertyToTextList,
     XwcTextPropertyToTextList, Xutf8TextPropertyToTextList,
     XwcFreeStringList, XDefaultString - convert text lists and
     text property structures

SYNTAX
     cc [ flag... ] file... -lX11 [ library... ]

     int XmbTextListToTextProperty(Display *display, char **list,
          int count, XICCEncodingStyle style, XTextProperty
          *text_prop_return);

     int XwcTextListToTextProperty(Display *display, wchar_t
          **list, int count, XICCEncodingStyle style, XTextPro-
          perty *text_prop_return);

     int Xutf8TextListToTextProperty(Display *display, char
          **list, int count, XICCEncodingStyle style, XTextPro-
          perty *text_prop_return);

     int XmbTextPropertyToTextList(Display *display, XTextPro-
          perty *text_prop, char ***list_return, int
          *count_return);

     int XwcTextPropertyToTextList(Display *display, XTextPro-
          perty *text_prop, wchar_t ***list_return, int
          *count_return);

     int Xutf8TextPropertyToTextList(Display *display, XTextPro-
          perty *text_prop, char ***list_return, int
          *count_return);

     void XwcFreeStringList(wchar_t **list);

     char *XDefaultString(void)

ARGUMENTS
     display   Specifies the connection to the X server.

     list      Specifies a list of null-terminated character
               strings.

     count     Specifies the number of strings specified.

     style     Specifies the manner in which the property is
               encoded.

     text_prop_return
               Returns the XTextProperty structure.




X Version 11        Last change: libX11 1.3.5                   1






XLIB FUNCTIONS                    XmbTextListToTextProperty(3x11)



     text_prop Specifies the XTextProperty structure to be used.

     list_return
               Returns a list of null-terminated character
               strings.

     count_return
               Returns the number of strings.

     list      Specifies the list of strings to be freed.

DESCRIPTION
     The XmbTextListToTextProperty, XwcTextListToTextProperty and
     Xutf8TextListToTextProperty functions set the specified
     XTextProperty value to a set of null-separated elements
     representing the concatenation of the specified list of
     null-terminated text strings. The input text strings must be
     given in the current locale encoding (for XmbTextListTo-
     TextProperty and XwcTextListToTextProperty), or in UTF-8
     encoding (for Xutf8TextListToTextProperty).

     The functions set the encoding field of text_prop_return to
     an Atom for the specified display naming the encoding deter-
     mined by the specified style and convert the specified text
     list to this encoding for storage in the text_prop_return
     value field.  If the style XStringStyle or XCom-
     poundTextStyle is specified, this encoding is ``STRING'' or
     ``COMPOUND_TEXT'', respectively.  If the style
     XUTF8StringStyle is specified, this encoding is
     ``UTF8_STRING''. (This is an extension introduced by The
     XFree86 Project, Inc. in their 4.0.2 release. Its presence
     is indicated by the macro X_HAVE_UTF8_STRING.)  If the style
     XTextStyle is specified, this encoding is the encoding of
     the current locale.  If the style XStdICCTextStyle is speci-
     fied, this encoding is ``STRING'' if the text is fully con-
     vertible to STRING, else ``COMPOUND_TEXT''.  A final ter-
     minating null byte is stored at the end of the value field
     of text_prop_return but is not included in the nitems
     member.

     If insufficient memory is available for the new value
     string, the functions return XNoMemory.  If the current
     locale is not supported, the functions return XLocaleNotSup-
     ported.  In both of these error cases, the functions do not
     set text_prop_return.

     To determine if the functions are guaranteed not to return
     XLocaleNotSupported, use XSupportsLocale.

     If the supplied text is not fully convertible to the speci-
     fied encoding, the functions return the number of unconver-
     tible characters.  Each unconvertible character is converted



X Version 11        Last change: libX11 1.3.5                   2






XLIB FUNCTIONS                    XmbTextListToTextProperty(3x11)



     to an implementation-defined and encoding-specific default
     string.  Otherwise, the functions return Success.  Note that
     full convertibility to all styles except XStringStyle is
     guaranteed.

     To free the storage for the value field, use XFree.

     The XmbTextPropertyToTextList, XwcTextPropertyToTextList and
     Xutf8TextPropertyToTextList functions return a list of text
     strings representing the null-separated elements of the
     specified XTextProperty structure. The returned strings are
     encoded using the current locale encoding (for XmbTextPro-
     pertyToTextList and XwcTextPropertyToTextList) or in UTF-8
     (for Xutf8TextPropertyToTextList).  The data in text_prop
     must be format 8.

     Multiple elements of the property (for example, the strings
     in a disjoint text selection) are separated by a null byte.
     The contents of the property are not required to be null-
     terminated; any terminating null should not be included in
     text_prop.nitems.

     If insufficient memory is available for the list and its
     elements, XmbTextPropertyToTextList, XwcTextPropertyTo-
     TextList and Xutf8TextPropertyToTextList return XNoMemory.
     If the current locale is not supported, the functions return
     XLocaleNotSupported.  Otherwise, if the encoding field of
     text_prop is not convertible to the encoding of the current
     locale, the functions return XConverterNotFound.  For sup-
     ported locales, existence of a converter from COMPOUND_TEXT,
     STRING, UTF8_STRING or the encoding of the current locale is
     guaranteed if XSupportsLocale returns True for the current
     locale (but the actual text may contain unconvertible char-
     acters).  Conversion of other encodings is implementation-
     dependent.  In all of these error cases, the functions do
     not set any return values.

     Otherwise, XmbTextPropertyToTextList, XwcTextPropertyTo-
     TextList and Xutf8TextPropertyToTextList return the list of
     null-terminated text strings to list_return and the number
     of text strings to count_return.

     If the value field of text_prop is not fully convertible to
     the encoding of the current locale, the functions return the
     number of unconvertible characters.  Each unconvertible
     character is converted to a string in the current locale
     that is specific to the current locale.  To obtain the value
     of this string, use XDefaultString.  Otherwise, XmbTextPro-
     pertyToTextList, XwcTextPropertyToTextList and
     Xutf8TextPropertyToTextList return Success.





X Version 11        Last change: libX11 1.3.5                   3






XLIB FUNCTIONS                    XmbTextListToTextProperty(3x11)



     To free the storage for the list and its contents returned
     by XmbTextPropertyToTextList or Xutf8TextPropertyToTextList,
     use XFreeStringList.  To free the storage for the list and
     its contents returned by XwcTextPropertyToTextList, use
     XwcFreeStringList.

     The XwcFreeStringList function frees memory allocated by
     XwcTextPropertyToTextList.

     The XDefaultString function returns the default string used
     by Xlib for text conversion (for example, in XmbTextProper-
     tyToTextList).  The default string is the string in the
     current locale that is output when an unconvertible charac-
     ter is found during text conversion.  If the string returned
     by XDefaultString is the empty string (""), no character is
     output in the converted text.  XDefaultString does not
     return NULL.

     The string returned by XDefaultString is independent of the
     default string for text drawing; see XCreateFontSet to
     obtain the default string for an XFontSet.

     The behavior when an invalid codepoint is supplied to any
     Xlib function is undefined.

     The returned string is null-terminated.  It is owned by Xlib
     and should not be modified or freed by the client.  It may
     be freed after the current locale is changed.  Until freed,
     it will not be modified by Xlib.

     The functions Xutf8TextListToTextProperty and
     Xutf8TextPropertyToTextList are extensions introduced by The
     XFree86 Project, Inc. in their 4.0.2 release. Their presence
     is indicated by the macro X_HAVE_UTF8_STRING.

STRUCTURES
     The XTextProperty structure contains:

     typedef struct {
          unsigned char *value;/* property data */
          Atom encoding;      /* type of property */
          int format;         /* 8, 16, or 32 */
          unsigned long nitems;/* number of items in value */
     } XTextProperty;

     The XICCEncodingStyle structure contains:

     #define   XNoMemory              -1
     #define   XLocaleNotSupported    -2
     #define   XConverterNotFound     -3
     typedef enum {
          XStringStyle,       /* STRING */



X Version 11        Last change: libX11 1.3.5                   4






XLIB FUNCTIONS                    XmbTextListToTextProperty(3x11)



          XCompoundTextStyle, /* COMPOUND_TEXT */
          XTextStyle,         /* text in owner's encoding (current locale) */
          XStdICCTextStyle,   /* STRING, else COMPOUND_TEXT */
          XUTF8StringStyle    /* UTF8_STRING */
     } XICCEncodingStyle;

SEE ALSO
     XSetTextProperty(3x11), XStringListToTextProperty(3x11)
     Xlib - C Language X Interface


ATTRIBUTES
     See attributes(5) for descriptions of the following attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | x11/library/libx11          |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | See XInitThreads(3X11)      |
    |_____________________________|_____________________________|































X Version 11        Last change: libX11 1.3.5                   5