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

NAME

6       XmProcessTraversal   —  A  function  that  determines  which  component
7       receives keyboard events when a widget has the focus
8

SYNOPSIS

10       #include <Xm/Xm.h>
11       Boolean XmProcessTraversal(
12       Widget widget,
13       XmTraversalDirection direction);
14

DESCRIPTION

16       XmProcessTraversal determines which component of a  hierarchy  receives
17       keyboard  events  when the hierarchy that contains the given widget has
18       keyboard focus.
19
20       XmProcessTraversal changes focus only when the keyboard focus policy of
21       the widget hierarchy is explicit.  If the XmNkeyboardFocusPolicy of the
22       nearest shell ancestor of the given widget is  not  XmEXPLICIT,  XmPro‐
23       cessTraversal returns False without making any focus changes.
24
25       widget    Specifies  the  widget ID of the widget whose hierarchy is to
26                 be traversed
27
28       direction Specifies the direction of traversal
29
30   DEFINITIONS
31       In order to be eligible to receive  keyboard  focus  when  the  shell's
32       XmNkeyboardFocusPolicy  is XmEXPLICIT, a widget or gadget must meet the
33       following conditions:
34
35          ·  The widget and its ancestors are not  in  the  process  of  being
36             destroyed.
37
38          ·  The  widget  and its ancestors are sensitive.  A widget is sensi‐
39             tive when its XmNsensitive and XmNancestorSensitive resources are
40             both True.
41
42          ·  The  XmNtraversalOn  resource for the widget and its ancestors is
43             True.
44
45          ·  The widget is viewable.  This  means  that  the  widget  and  its
46             ancestors are managed, realized, and (except for gadgets) mapped.
47             Furthermore, in general, some part of  the  widget's  rectangular
48             area must be unobscured by the widget's ancestors. If an applica‐
49             tion unmaps a widget that has its  XmNmappedWhenManaged  resource
50             set to True, the result is undefined.
51
52                 In  a  ScrolledWindow  with  an XmNscrollingPolicy of XmAUTO‐
53                 MATIC, a widget that is obscured because it is not within the
54                 clip  window may be able to receive focus if some part of the
55                 widget is within the work area and if an XmNtraverseObscured‐
56                 Callback routine can make the widget at least partially visi‐
57                 ble by scrolling the window.
58
59       In general only primitives, gadgets, and Drawing Area are  eligible  to
60       receive  focus.   Most  managers cannot receive focus even if they meet
61       all these conditions.
62
63       The direction argument identifies the kind of traversal action to take.
64       The  descriptions  of these actions below refer to traversable non-tab-
65       group widgets and traversable tab groups.
66
67          ·  A traversable non-tab-group widget is a widget that is not a  tab
68             group  and  that  meets  all  the  conditions for receiving focus
69             described above.
70
71          ·  A traversable tab group widget is a tab group widget  that  meets
72             the  same  conditions,  except that a manager that is a tab group
73             and meets the other conditions is also eligible for traversal  as
74             long as it contains a descendant that can receive focus.
75
76       A tab group is a widget whose XmNnavigationType is:
77
78          ·  XmTAB_GROUP  or  XmSTICKY_TAB_GROUP,  if the hierarchy (up to the
79             nearest shell ancestor) that contains the widget  has  no  widget
80             whose XmNnavigationType is XmEXCLUSIVE_TAB_GROUP
81
82          ·  XmEXCLUSIVE_TAB_GROUP or XmSTICKY_TAB_GROUP, if the hierarchy (up
83             to the nearest shell ancestor) that contains the widget  has  any
84             widget whose XmNnavigationType is XmEXCLUSIVE_TAB_GROUP
85
86   TRAVERSAL ACTIONS
87       The  hierarchy  to be traversed is that containing the widget argument.
88       This hierarchy is traversed  only  up  to  the  nearest  shell;  XmPro‐
89       cessTraversal  does  not  move focus from one shell to another.  If the
90       shell containing widget does not currently have the focus,  any  change
91       that  XmProcessTraversal  makes  to  the element with focus within that
92       shell does not take effect until  the  next  time  the  shell  receives
93       focus.
94
95       XmProcessTraversal  begins  the traversal action from the widget in the
96       hierarchy that currently has keyboard focus or that last had focus when
97       the user traversed away from the shell hierarchy.
98
99       The  value of the direction argument determines which of three kinds of
100       traversal action to take:
101
102          ·  Traversal to a non-tab-group widget.  This kind of  traversal  is
103             possible  only  when the widget that currently has focus is not a
104             tab group; otherwise, XmProcessTraversal returns False for  these
105             actions.
106
107                 These  actions  do  not  move  focus  from  one  tab group to
108                 another.  The actions  first  determine  the  containing  tab
109                 group.  This is the tab group containing the widget that cur‐
110                 rently has focus.  The actions traverse only  to  a  non-tab-
111                 group widget within the containing tab group.
112
113                 A non-tab-group widget is eligible for this kind of traversal
114                 if the widget is traversable and has no tab  group  ancestors
115                 up to the containing tab group.  If the tab group contains no
116                 traversable non-tab-group widgets, XmProcessTraversal returns
117                 False.
118
119                 Following  are the possible values of the direction argument.
120                 Note that when actions wrap, wrapping occurs in the traversal
121                 direction.  The following describes what happens in a left to
122                 right environment:
123
124                    ·  XmTRAVERSE_RIGHT—If the XmNnavigationType of  the  con‐
125                       taining  tab  group is not XmEXCLUSIVE_TAB_GROUP, focus
126                       moves to the next traversable non-tab-group  widget  to
127                       the right of the widget that currently has focus.  In a
128                       left to right environment, at the right side of the tab
129                       group  this action wraps to the non-tab-group widget at
130                       the left side and  next  toward  the  bottom.   At  the
131                       rightmost  widget  in  the  bottom row of the tab group
132                       this action wraps to the non-tab-group  widget  at  the
133                       leftmost widget in the upper row.
134
135                           In  a  right to left environment, at the right side
136                           of the tab group, this action wraps to the non-tab-
137                           group  widget  at the left side and next toward the
138                           top. At the rightmost widget in the  upper  row  of
139                           the  tab  group  this  action wraps to the non-tab-
140                           group widget at the leftmost widget in  the  bottom
141                           row.
142
143                           If  the  XmNnavigationType  of  the  containing tab
144                           group is XmEXCLUSIVE_TAB_GROUP, focus moves to  the
145                           next  traversable  non-tab-group  widget in the tab
146                           group, proceeding in the order in which the widgets
147                           appear  in their parents' XmNchildren lists.  After
148                           the last widget in the tab group, this action wraps
149                           to the first non-tab-group widget.
150
151                    ·  XmTRAVERSE_LEFT—If  the  XmNnavigationType  of the con‐
152                       taining tab group is not  XmEXCLUSIVE_TAB_GROUP,  focus
153                       moves  to  the next traversable non-tab-group widget to
154                       the left of the widget that currently has focus.  In  a
155                       left  to right environment, at the left side of the tab
156                       group this action wraps to the non-tab-group widget  at
157                       the  right  side and next toward the top.  At the left‐
158                       most widget in the upper row  of  the  tab  group  this
159                       action  wraps to the non-tab-group widget at the right‐
160                       most widget in the bottom row.
161
162                           In a right to left environment, at the left side of
163                           the  tab  group  this  action wraps to the non-tab-
164                           group widget at the right side and next toward  the
165                           bottom. At the leftmost widget in the bottom row of
166                           the tab group this action  wraps  to  the  non-tab-
167                           group  widget  at the rightmost widget in the upper
168                           row.
169
170                           If the  XmNnavigationType  of  the  containing  tab
171                           group  is XmEXCLUSIVE_TAB_GROUP, focus moves to the
172                           previous traversable non-tab-group  widget  in  the
173                           tab group, proceeding in the reverse order in which
174                           the widgets appear in  their  parents'  XmNchildren
175                           lists.   After  the  first widget in the tab group,
176                           this action wraps to the last non-tab-group widget.
177
178                    ·  XmTRAVERSE_DOWN—If the XmNnavigationType  of  the  con‐
179                       taining  tab  group is not XmEXCLUSIVE_TAB_GROUP, focus
180                       moves to  the  next  traversable  non-tab-group  widget
181                       below  the  widget that currently has focus.  In a left
182                       to right environment, at the bottom of  the  tab  group
183                       this  action  wraps  to the non-tab-group widget at the
184                       top and next toward the right.  At the bottom widget in
185                       the rightmost column of the tab group this action wraps
186                       to the non-tab-group widget at the top  widget  in  the
187                       leftmost column.
188
189                           In  a  right  to left environment, at the bottom of
190                           the tab group this action  wraps  to  the  non-tab-
191                           group  widget  at the top and next toward the left.
192                           At the bottom widget of the leftmost widget of  the
193                           tab  group  this  action wraps to the non-tab-group
194                           widget at the top widget of the rightmost column.
195
196                           If the  XmNnavigationType  of  the  containing  tab
197                           group  is XmEXCLUSIVE_TAB_GROUP, focus moves to the
198                           next traversable non-tab-group widget  in  the  tab
199                           group, proceeding in the order in which the widgets
200                           appear in their parents' XmNchildren lists.   After
201                           the last widget in the tab group, this action wraps
202                           to the first non-tab-group widget.
203
204                    ·  XmTRAVERSE_UP—If the XmNnavigationType of the  contain‐
205                       ing tab group is not XmEXCLUSIVE_TAB_GROUP, focus moves
206                       to the next traversable non-tab-group widget above  the
207                       widget  that  currently  has focus.  In a left to right
208                       environment, at the top of the tab  group  this  action
209                       wraps  to  the  non-tab-group  widget at the bottom and
210                       next toward the left.  At the top widget of  the  left‐
211                       most  column  of the tab group this action wraps to the
212                       non-tab-group widget at the bottom widget of the right‐
213                       most column.
214
215                           In  a  right to left environment, at the top of the
216                           tab group this action wraps  to  the  non-tab-group
217                           widget  at the bottom and next toward the right. At
218                           the top widget of the right most column of the  tab
219                           group this action wraps to the non-tab-group widget
220                           at the bottom widget of the leftmost column.
221
222                           If the  XmNnavigationType  of  the  containing  tab
223                           group  is XmEXCLUSIVE_TAB_GROUP, focus moves to the
224                           previous traversable non-tab-group  widget  in  the
225                           tab group, proceeding in the reverse order in which
226                           the widgets appear in  their  parents'  XmNchildren
227                           lists.   After  the  first widget in the tab group,
228                           this action wraps to the last non-tab-group widget.
229
230                    ·  XmTRAVERSE_NEXT—Focus moves  to  the  next  traversable
231                       non-tab-group  widget  in  the tab group, proceeding in
232                       the order in which the widgets appear in their parents'
233                       XmNchildren  lists.   After  the last widget in the tab
234                       group, this action wraps  to  the  first  non-tab-group
235                       widget.
236
237                    ·  XmTRAVERSE_PREV—Focus moves to the previous traversable
238                       non-tab-group widget in the tab  group,  proceeding  in
239                       the  reverse order in which the widgets appear in their
240                       parents' XmNchildren lists.  After the first widget  in
241                       the  tab  group, this action wraps to the last non-tab-
242                       group widget.
243
244                    ·  XmTRAVERSE_HOME—If the XmNnavigationType  of  the  con‐
245                       taining  tab  group is not XmEXCLUSIVE_TAB_GROUP, focus
246                       moves to the first traversable non-tab-group widget  at
247                       the initial focus of the tab group.
248
249                           If  the  XmNnavigationType  of  the  containing tab
250                           group is XmEXCLUSIVE_TAB_GROUP, focus moves to  the
251                           first  traversable  non-tab-group widget in the tab
252                           group, according to the order in which the  widgets
253                           appear in their parents' XmNchildren lists.
254
255          ·  Traversal to a tab group.  These actions first determine the cur‐
256             rent widget hierarchy and the containing tab group.  The  current
257             widget  hierarchy is the widget hierarchy whose root is the near‐
258             est shell ancestor of the widget that currently has  focus.   The
259             containing  tab  group  is is the tab group containing the widget
260             that currently has focus.  If the current widget  hierarchy  con‐
261             tains  no  traversable  tab  groups,  XmProcessTraversal  returns
262             False.
263
264                 Following are the possible values of the direction  argument.
265                 If  any tab group in the current widget hierarchy has an XmN‐
266                 navigationType of  XmEXCLUSIVE_TAB_GROUP,  traversal  of  tab
267                 groups  in  the hierarchy proceeds to widgets in the order in
268                 which their XmNnavigationType  resources  were  specified  as
269                 XmEXCLUSIVE_TAB_GROUP or XmSTICKY_TAB_GROUP.:
270
271                    ·  XmTRAVERSE_NEXT_TAB_GROUP—Finds the hierarchy that con‐
272                       tains widget, finds the active tab group (if any),  and
273                       makes  the  next  tab group the active tab group in the
274                       hierarchy.
275
276                    ·  XmTRAVERSE_PREV_TAB_GROUP—Finds the hierarchy that con‐
277                       tains  widget, finds the active tab group (if any), and
278                       makes the previous tab group the active  tab  group  in
279                       the hierarchy.
280
281          ·  Traversal to any widget.  In this case the widget argument is the
282             widget to which XmProcessTraversal tries to give focus.   If  the
283             widget is not traversable, XmProcessTraversal returns False.
284
285                 Following are the possible values of the direction argument:
286
287                    ·  XmTRAVERSE_CURRENT—Finds  the  hierarchy  and  the  tab
288                       group that contain widget.  If this tab  group  is  not
289                       the  active  tab group, this action makes it the active
290                       tab group.  If widget is an  item  in  the  active  tab
291                       group, this action makes it the active item.  If widget
292                       is the active tab group, this action  makes  the  first
293                       traversable item in the tab group the active item.
294
295   CAUTIONS
296       Using  XmProcessTraversal to traverse to MenuBars, Pulldown menu panes,
297       or Popup menu panes is not supported.
298
299       XmProcessTraversal cannot be called  recursively.   In  particular,  an
300       application  cannot  call this routine from an XmNfocusCallback or XmN‐
301       losingFocusCallback procedure.
302

RETURN

304       Returns True if the traversal action succeeded.  Returns False  if  the
305       XmNkeyboardFocusPolicy  of  the nearest shell ancestor of widget is not
306       XmEXPLICIT, if the traversal action  finds  no  traversable  widget  to
307       receive focus, or if the call to the routine has invalid arguments.
308
310       XmGetVisibility(3) and XmIsTraversable(3).
311
312
313
314                                              XmProcessTraversal(library call)
Impressum