XmbTextListToTextProperty(3X11)

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

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

          int XwcTextListToTextProperty(display, list, count, style,
          text_prop_return)
                Display *display;
                wchar_t **list;
                int count;
                XICCEncodingStyle style;
                XTextProperty *text_prop_return;

          int XmbTextPropertyToTextList(display, text_prop,
          list_return, count_return)
                Display *display;
                XTextProperty *text_prop;
                char ***list_return;
                int *count_return;

          int XwcTextPropertyToTextList(display, text_prop,
          list_return, count_return)
                Display *display;
                XTextProperty *text_prop;
                wchar_t ***list_return;
                int *count_return;

          void XwcFreeStringList(list)
                wchar_t **list;

          char *XDefaultString()

     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.

          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 and XwcTextListToTextProperty
          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.  A final
          terminating null is stored at the end of the value field of
          text_prop_return but is not included in the nitems member.

          The functions set the encoding field of text_prop_return to
          an Atom for the specified display naming the encoding
          determined 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
          XCompoundTextStyle is specified, this encoding is ``STRING''
          or ``COMPOUND_TEXT'', respectively.  If the style XTextStyle
          is specified, this encoding is the encoding of the current
          locale.  If the style XStdICCTextStyle is specified, this
          encoding is ``STRING'' if the text is fully convertible to
          STRING, else ``COMPOUND_TEXT''.

          If insufficient memory is available for the new value
          string, the functions return XNoMemory.  If the current
          locale is not supported, the functions return
          XLocaleNotSupported.  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
          specified encoding, the functions return the number of
          unconvertible characters.  Each unconvertible character is
          converted 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 and XwcTextPropertyToTextList
          functions return a list of text strings in the current
          locale representing the null-separated elements of the
          specified XTextProperty structure.  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 and
          XwcTextPropertyToTextList 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
          supported locales, existence of a converter from
          COMPOUND_TEXT, 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 characters).  Conversion of other encodings is
          implementation-dependent.  In all of these error cases, the
          functions do not set any return values.

          Otherwise, XmbTextPropertyToTextList and
          XwcTextPropertyToTextList 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,
          XmbTextPropertyToTextList and XwcTextPropertyToTextList
          return Success.

          To free the storage for the list and its contents returned
          by XmbTextPropertyToTextList, 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
          XmbTextPropertyToTextList).  The default string is the
          string in the current locale that is output when an
          unconvertible character 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.

     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 */
               XCompoundTextStyle, /* COMPOUND_TEXT */
               XTextStyle,         /* text in owner's encoding (current locale) */
               XStdICCTextStyle    /* STRING, else COMPOUND_TEXT */
          } XICCEncodingStyle;

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