Compound Text Functions

The functions defined in this section are for parsing Compound Text strings, decomposing them into individual segments. Definitions needed to use these routines are in the include file <X11/Xmu/Xct.h> and link against the libXmu library.

Warning

The functions in this section are deprecated because they shift the burden for recently introduced locale encodings to the application. The use of the UTF8_STRING text encoding provides a better alternative.

A Compound Text string is represented as the following type:

	typedef unsigned char *XctString;

	typedef unsigned char *XctString;

XctData XctCreate(const XctString string, int length, XctFlags flags);

XctData XctCreate(const XctString string, int length, XctFlags flags);

string	the Compound Text string
length	the number of bytes in string
flags	parsing control flags

This function creates an XctData structure for parsing a Compound Text string. The string need not be null terminated. The following flags are defined to control parsing of the string:

XctSingleSetSegments	This means that returned segments should contain characters from only one set (C0, C1, GL, GR). When this is requested, XctSegment is never returned by XctNextItem, instead XctC0Segment, XctC1Segment, XctGlSegment, and XctGRSegment are returned. C0 and C1 segments are always returned as singleton characters.
XctProvideExtensions	This means that if the Compound Text string is from a higher version than this code is implemented to, then syntactically correct but unknown control sequences should be returned as XctExtension items by XctNextItem. If this flag is not set, and the Compound Text string version indicates that extensions cannot be ignored, then each unknown control sequence will be reported as an XctError.
XctAcceptC0Extensions	This means that if the Compound Text string is from a higher version than this code is implemented to, then unknown C0 characters should be treated as if they were legal, and returned as C0 characters (regardless of how XctProvideExtensions is set) by XctNextItem. If this flag is not set, then all unknown C0 characters are treated according to XctProvideExtensions.
XctAcceptC1Extensions	This means that if the Compound Text string is from a higher version than this code is implemented to, then unknown C1 characters should be treated as if they were legal, and returned as C1 characters (regardless of how XctProvideExtensions is set) by XctNextItem. If this flag is not set, then all unknown C1 characters are treated according to XctProvideExtensions.
XctHideDirection	This means that horizontal direction changes should be reported as XctHorizontal items by XctNextItem. If this flag is not set, then direction changes are not returned as items, but the current direction is still maintained and reported for other items. The current direction is given as an enumeration, with the values XctUnspecified, XctLeftToRight, and XctRightToLeft.
XctFreeString	This means that XctFree should free the Compound Text string that is passed to XctCreate. If this flag is not set, the string is not freed.
XctShiftMultiGRToGL	This means that XctNextItem should translate GR segments on-the-fly into GL segments for the GR sets: GB2312.1980-1, JISX0208.1983-1, and KSC5601.1987-1.

void XctReset(XctData data);

void XctReset(XctData data);

data	specifies the Compound Text structure

This function resets the XctData structure to reparse the Compound Text string from the beginning.

XctResult XctNextItem(XctData data);

data	specifies the Compound Text structure

This function parses the next “item” from the Compound Text string. The return value indicates what kind of item is returned. The item itself, its length, and the current contextual state, are reported as components of the XctData structure. XctResult is an enumeration, with the following values:

XctSegment	the item contains some mixture of C0, GL, GR, and C1 characters.
XctC0Segment	the item contains only C0 characters.
XctGLSegment	the item contains only GL characters.
XctC1Segment	the item contains only C1 characters.
XctGRSegment	the item contains only GR characters.
XctExtendedSegment	the item contains an extended segment.
XctExtension	the item is an unknown extension control sequence.
XctHorizontal	the item indicates a change in horizontal direction or depth. The new direction and depth are recorded in the XctData structure.
XctEndOfText	The end of the Compound Text string has been reached.
XctError	the string contains a syntactic or semantic error; no further parsing should be performed.

The following state values are stored in the XctData structure:

    XctString		item;		/* the action item */
    unsigned		item_length;	/* length of item in bytes */
    int			char_size;	/* the number of bytes per character in
					 * item, with zero meaning variable */
    char		*encoding;	/* the XLFD encoding name for item */
    XctHDirection	horizontal;	/* the direction of item */
    unsigned		horz_depth;	/* the current direction nesting depth */
    char		*GL;		/* the "{I} F" string for the current GL */
    char		*GL_encoding;	/* the XLFD encoding name for the current GL */
    int			GL_set_size;	/* 94 or 96 */
    int			GL_char_size;	/* the number of bytes per GL character */
    char		*GR;		/* the "{I} F" string for the current GR */
    char		*GR_encoding;	/* the XLFD encoding name for the current GR */
    int			GR_set_size;	/* 94 or 96 */
    int			GR_char_size;	/* number of bytes per GR character */
    char		*GLGR_encoding;	/* the XLFD encoding name for the current
					 *  GL+GR, if known */
	

void XctFree(XctData data);

void XctFree(XctData data);

data	specifies the Compound Text structure

This function frees all data associated with the XctData structure.