NAME

       XmStringGetNextComponent  —  A  compound  string  function  that  returns  the type and value of the next
       component   in   a   compound   string    "XmStringGetNextComponent"    "compound    string    functions"
       "XmStringGetNextComponent"

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 Fields         │ Component Type                      │
       ├─────────────────────┼─────────────────────────────────────┤
       │tag                  │ XmSTRING_COMPONENT_LOCALE,          │
       │                     │ XmSTRING_COMPONENT_TAG              │
       ├─────────────────────┼─────────────────────────────────────┤
       │text                 │ XmSTRING_COMPONENT_LOCALE_TEXT,     │
       │                     │ XmSTRING_COMPONENT_TEXT,            │
       │                     │ XmSTRING_COMPONENT_WIDECHAR_TEXT    │
       ├─────────────────────┼─────────────────────────────────────┤
       │direction            │ XmSTRING_COMPONENT_DIRECTION        │
       ├─────────────────────┼─────────────────────────────────────┤
       │unknown_tag,         │ XmSTRING_COMPONENT_LAYOUT_POP,      │
       │unknown_length,      │ XmSTRING_COMPONENT_LAYOUT_PUSH,     │
       │unknown_value        │ XmSTRING_COMPONENT_TAB,             │
       │                     │ XmSTRING_COMPONENT_RENDITION_BEGIN, │
       │                     │ XmSTRING_COMPONENT_RENDITION_END    │
       ├─────────────────────┼─────────────────────────────────────┤
       │no valid field       │ XmSTRING_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.

RELATED

       XmStringComponentType(3), XmStringCreate(3), and XmStringInitContext(3).

                                                                                     XmStringGetNextComponent(3)