XmStringGetNextComponent - Man Page

A compound string function that returns the type and value of the next component in a compound string

Synopsis

#include <Xm/Xm​.h>
XmStringComponentType XmStringGetNextComponent(
XmStringContext context,
char **text,
XmStringTag *tag,
XmStringDirection *direction,
XmStringComponentType *unknown_tag,
unsigned short *unknown_length,
unsigned char **unknown_value);

Description

This function is obsolete and exists for compatibility with previous releases​. It is replaced by XmStringGetNextTriple​.

XmStringGetNextComponent returns the type and value of the next component in the compound string identified by context​. Components are returned one at a time​. On return, only some output parameters will be valid; which ones can be determined by examining the returned component type​. The following table describes the valid returns for each component type​.

Valid FieldsComponent Type
tagXmSTRING_COMPONENT_LOCALE, XmSTRING_COMPONENT_TAG
textXmSTRING_COMPONENT_LOCALE_TEXT, XmSTRING_COMPONENT_TEXT, XmSTRING_COMPONENT_WIDECHAR_TEXT
directionXmSTRING_COMPONENT_DIRECTION
unknown_tag, unknown_length, unknown_valueXmSTRING_COMPONENT_LAYOUT_POP, XmSTRING_COMPONENT_LAYOUT_PUSH, XmSTRING_COMPONENT_TAB, XmSTRING_COMPONENT_RENDITION_BEGIN, XmSTRING_COMPONENT_RENDITION_END
no valid fieldXmSTRING_COMPONENT_SEPARATOR, XmSTRING_COMPONENT_END, XmSTRING_COMPONENT_UNKNOWN

Note that several components produce a return value of XmSTRING_COMPONENT_UNKNOWN​. The data returned by these components is returned in the unknown_tag, unknown_length, and unknown_value fields​. This apparent inconsistency is designed to accommodate older applications that may not be equipped to handle the newer component types of Motif version 2​.0 and beyond​. Consequently, the use of this procedure is not recommended​. Instead, use the XmStringGetNextTriple procedure, which provides all the functionality of XmStringGetNextComponent, and is fully compatible with the newer component types​.

If the function return value is XmSTRING_COMPONENT_LOCALE_TEXT or XmSTRING_COMPONENT_TEXT, the the function allocates space to hold the returned text​. If the function return value is XmSTRING_COMPONENT_FONTLIST_ELEMENT_TAG, or XmSTRING_COMPONENT_TAG, then the function allocates space to hold the returned tag​. The application is responsible for managing the allocated space​. The application can recover the allocated space by calling XtFree​.

context

Specifies the string context structure that was allocated by the XmStringInitContext function​.

text

Specifies a pointer to a NULL terminated string​.

tag

Specifies a pointer to the tag component associated with the text​. The value XmFONTLIST_DEFAULT_TAG identifies a locale text segment​.

direction

Specifies a pointer to the direction of the text​.

unknown_tag

Specifies a pointer to the tag of an unknown component​.

unknown_length

Specifies a pointer to the length of an unknown component​.

unknown_value

Specifies a pointer to the value of an unknown component​.

Return

Returns the type of component found​. Refer to the XmStringComponentType(3) reference page for a list of component types​.