XmbTextPropertyToTextList

Syntax

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;

Arguments

Description

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().

See also