Man Linux: Main Page and Category List

NAME

       XmStringGetNextComponent  — 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 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  accomodate  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(library call)