XmCvtTextPropertyToXmStringTable






XmCvtTextPropertyToXmStringTable — A function that converts
from a TextProperty Structure to a StringTable



     #include <Xm/Xm.h>
int XmCvtTextPropertyToXmStringTable (display, text_prop, string_table_return, count_return)
        Display *display;
        XTextProperty   *text_prop;
        XmStringTable   *string_table_return;
        int     *count_return;
(void)



     XmCvtTextPropertyToXmStringTable converts the specified
XTextProperty structure into an XmStringTable, as follows:

   •  If the encoding member of text_prop is the Atom
      STRING, each returned XmString has a tag of
      "ISO8859‐1" and a text type of XmCHARSET_TEXT.

   •  If the encoding member of text_prop is the encoding of
      the current locale, and if that encoding is not
      STRING, each returned XmString has a tag of
      _MOTIF_DEFAULT_LOCALE and a text type of
      XmMULTIBYTE_TEXT.

   •  If the encoding member of text_prop is other than
      STRING or the encoding of the current locale, the
      contents of the returned compound strings are
      implementation dependent.

     If conversion depends on the locale and the current
locale is not supported, the function returns
XLocaleNotSupported. If conversion to the encoding of the
current locale is required and if the locale is supported
but no converter is available for the encoding specified in
text_prop, the function returns XConverterNotFound. For
supported 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 characters). Conversion of other encodings to
the encoding of the current locale is implementation
dependent. In all of these error cases, the function does
not set any return values.

     If an element of the value member of text_prop is not
convertible to XmString, the corresponding entry in the
returned XmStringTable will be NULL, and
XmCvtTextPropertyToXmStringTable returns Success.











                             ‐2‐


     To free the storage for the XmStringTable and its
count_return compound strings returned by this function,
first free each XmString in the table using XmStringFree,
and then free the XmStringTable itself using XtFree.

display   Specifies the connection to the X server.

text_prop Specifies a pointer to the XTextProperty.  The
          format member of text_prop must be 8.

string_table_return
          Specifies the XmStringTable array into which the
          converted compound strings are placed.

count_return
          Specifies the number of XmStrings returned by this
          function.



     Upon success, this function returns the set of
XmStrings in string_table_return, and it returns the number
of XmStrings in count_return, and returns Success.
Otherwise, it returns the following:

XLocaleNotSupported
          Returned if conversion depends on the locale and
          the current locale is not supported.

XConverterNotFound
          Returned if conversion to the encoding of the
          current locale is required and if the locale is
          supported but no converter is available for the
          encoding specified in text_prop.



     XmCvtXmStringTableToTextProperty(3), XmText(3), and
XmTextGetString(3).