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)