1XmStringGetNextComponent(library call)  XmStringGetNextComponent(library call)
2
3
4

NAME

6       XmStringGetNextComponent  — A compound string function that returns the
7       type and value of the next component in a compound string
8

SYNOPSIS

10       #include <Xm/Xm.h>
11       XmStringComponentType XmStringGetNextComponent(
12       XmStringContext context,
13       char **text,
14       XmStringTag *tag,
15       XmStringDirection *direction,
16       XmStringComponentType *unknown_tag,
17       unsigned short *unknown_length,
18       unsigned char **unknown_value);
19

DESCRIPTION

21       This function is obsolete and exists for  compatibility  with  previous
22       releases. It is replaced by XmStringGetNextTriple.  XmStringGetNextCom‐
23       ponent returns the type and value of the next component in the compound
24       string  identified  by context.  Components are returned one at a time.
25       On return, only some output parameters will be valid; which ones can be
26       determined by examining the returned component type.  The following ta‐
27       ble describes the valid returns for each component type.
28
29       ┌─────────────────────┬──────────────────────────────┐
30       │Valid Fields         │ Component Type               │
31       ├─────────────────────┼──────────────────────────────┤
32       │tag                  │ XmSTRING_COMPONENT_LOCALE,   │
33       │                     │ XmSTRING_COMPONENT_TAG       │
34       ├─────────────────────┼──────────────────────────────┤
35       │text                 │ XmSTRING_COMPO‐              │
36       │                     │ NENT_LOCALE_TEXT,            │
37       │                     │ XmSTRING_COMPONENT_TEXT,     │
38       │                     │ XmSTRING_COMPO‐              │
39       │                     │ NENT_WIDECHAR_TEXT           │
40       ├─────────────────────┼──────────────────────────────┤
41       │direction            │ XmSTRING_COMPONENT_DIRECTION │
42       ├─────────────────────┼──────────────────────────────┤
43       │unknown_tag,         │ XmSTRING_COMPONENT_LAY‐      │
44       │unknown_length,      │ OUT_POP,     XmSTRING_COMPO‐ │
45       │unknown_value        │ NENT_LAYOUT_PUSH,            │
46       │                     │ XmSTRING_COMPONENT_TAB,      │
47       │                     │ XmSTRING_COMPONENT_RENDI‐    │
48       │                     │ TION_BEGIN,  XmSTRING_COMPO‐ │
49       │                     │ NENT_RENDITION_END           │
50       ├─────────────────────┼──────────────────────────────┤
51       │no valid field       │ XmSTRING_COMPONENT_SEPARA‐   │
52       │                     │ TOR, XmSTRING_COMPONENT_END, │
53       │                     │ XmSTRING_COMPONENT_UNKNOWN   │
54       ├─────────────────────┼──────────────────────────────┤
55       └─────────────────────┴──────────────────────────────┘
56       Note  that several components produce a return value of XmSTRING_COMPO‐
57       NENT_UNKNOWN. The data returned by these components is returned in  the
58       unknown_tag,  unknown_length,  and  unknown_value fields. This apparent
59       inconsistency is designed to accomodate older applications that may not
60       be  equipped  to  handle the newer component types of Motif version 2.0
61       and beyond.  Consequently, the use of  this  procedure  is  not  recom‐
62       mended.  Instead,  use  the XmStringGetNextTriple procedure, which pro‐
63       vides all the functionality of XmStringGetNextComponent, and  is  fully
64       compatible with the newer component types.
65
66       If  the  function  return  value  is  XmSTRING_COMPONENT_LOCALE_TEXT or
67       XmSTRING_COMPONENT_TEXT, the the function allocates space to  hold  the
68       returned  text.   If  the  function  return  value  is  XmSTRING_COMPO‐
69       NENT_FONTLIST_ELEMENT_TAG, or XmSTRING_COMPONENT_TAG, then the function
70       allocates space to hold the returned tag.  The application is responsi‐
71       ble for managing the allocated space.  The application can recover  the
72       allocated space by calling XtFree.
73
74       context   Specifies  the string context structure that was allocated by
75                 the XmStringInitContext function.
76
77       text      Specifies a pointer to a NULL terminated string.
78
79       tag       Specifies a pointer to the tag component associated with  the
80                 text.  The  value  XmFONTLIST_DEFAULT_TAG identifies a locale
81                 text segment.
82
83       direction Specifies a pointer to the direction of the text.
84
85       unknown_tag
86                 Specifies a pointer to the tag of an unknown component.
87
88       unknown_length
89                 Specifies a pointer to the length of an unknown component.
90
91       unknown_value
92                 Specifies a pointer to the value of an unknown component.
93

RETURN

95       Returns the type of component found.  Refer to  the  XmStringComponent‐
96       Type(3) reference page for a list of component types.
97

99       XmStringComponentType(3),   XmStringCreate(3),   and   XmStringInitCon‐
100       text(3).
101
102
103
104                                        XmStringGetNextComponent(library call)
Impressum