14.1.2 Converting String Lists

Many of the text properties allow a variety of types and formats. Because the data stored in these properties are not simple null-terminated strings, a XTextProperty structure is used to describe the encoding, type, and length of the text as well as its value. The XTextProperty structure contains:

typedef struct {
	unsigned char *value;	/* property data */
	Atom encoding;		/* type of property */
	int format;		/* 8, 16, or 32 */
	unsigned long nitems;	/* number of items in value */
} XTextProperty;

Xlib provides functions to convert localized text to or from encodings that support the inter-client communication conventions for text. In addition, functions are provided for converting between lists of pointers to character strings and text properties in the STRING encoding.

The functions for localized text return a signed integer error status that encodes Success as zero, specific error conditions as negative numbers, and partial conversion as a count of unconvertible characters.


#define XNoMemory -1
#define XLocaleNotSupported -2
#define XConverterNotFound -3

typedef enum {
	XStringStyle,		/* STRING */
	XCompoundTextStyle,	/* COMPOUND_TEXT */
	XTextStyle,		/* text in owner's encoding (current locale) */
	XStdICCTextStyle	/* STRING, else COMPOUND_TEXT */
} XICCEncodingStyle;

To convert a list of text strings to an XTextProperty structure, use XmbTextListToTextProperty() or XwcTextListToTextProperty().

To obtain a list of text strings from an XTextProperty structure, use XmbTextPropertyToTextList() or XwcTextPropertyToTextList().

To free the in-memory data associated with the specified wide character string list, use XwcFreeStringList().

To obtain the default string for text conversion in the current locale, use XDefaultString().

To set the specified list of strings in the STRING encoding to a XTextProperty structure, use XStringListToTextProperty().

To obtain a list of strings from a specified XTextProperty structure in the STRING encoding, use XTextPropertyToStringList().

To free the in-memory data associated with the specified string list, use XFreeStringList().

Next: Setting and Reading Text Properties

Christophe Tronche, [email protected]