XmCvtTextPropertyToXmStrinUNIXmCvtTextPropertyToXmStringTable(3X)
NAME
XmCvtTextPropertyToXmStringTable - A function that converts
from a TextProperty Structure to a StringTable
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)
VERSION
This page documents Motif 2.1.
DESCRIPTION
XmCvtTextPropertyToXmStringTable converts the specified
XTextProperty structure into an XmStringTable, as follows:
o If the encoding member of text_prop is the Atom
STRING, each returned XmStringhas a tag of "ISO8859-1"
and a text type of XmCHARSET_TEXT.
o 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.
o 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, 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
Page 1 (printed 7/20/06)
XmCvtTextPropertyToXmStrinUNIXmCvtTextPropertyToXmStringTable(3X)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).
Page 2 (printed 7/20/06)
