NAME

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

SYNOPSIS

       #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)

DESCRIPTION

       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.

       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.

RETURN VALUES

       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.

RELATED INFORMATION

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

                                                              XmCvtTextPropertyToXmStringTable(3)