1cdk_traverse(3)            Library Functions Manual            cdk_traverse(3)
2
3
4

NAME

6       cdk_traverse - functions to support keyboard traversal
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       CDKOBJS *getCDKFocusCurrent (CDKSCREEN *screen);
14
15       CDKOBJS *setCDKFocusCurrent (CDKSCREEN *screen, CDKOBJS *obj);
16
17       CDKOBJS *setCDKFocusFirst (CDKSCREEN *screen);
18
19       CDKOBJS *setCDKFocusLast (CDKSCREEN *screen);
20
21       CDKOBJS *setCDKFocusNext (CDKSCREEN *screen);
22
23       CDKOBJS *setCDKFocusPrevious (CDKSCREEN *screen);
24
25       int traverseCDKScreen (CDKSCREEN *screen);
26
27       void exitOKCDKScreen (CDKSCREEN *screen);
28
29       void exitCancelCDKScreen (CDKSCREEN *screen);
30
31       void resetCDKScreen (CDKSCREEN *screen);
32
33       void exitOKCDKScreenOf(CDKOBJS *obj);
34
35       void exitCancelCDKScreenOf (CDKOBJS *obj);
36
37       void resetCDKScreenOf (CDKOBJS *obj);
38
39       void traverseCDKOnce (
40                      CDKSCREEN *screen,
41                      CDKOBJS *curobj,
42                      int keyCode,
43                      boolean functionKey,
44                      CHECK_KEYCODE funcMenuKey);
45

DESCRIPTION

47       The  functions  above  handle  the traversal of a screen populated with
48       various widgets.  Once the screen has been created and  populated  with
49       widgets,  a  single  call to traverseCDKScreen() will allow the user to
50       move between widgets and enter data (or otherwise manipulate  widgets).
51       Other functions are provided for use as callbacks by the widgets on the
52       screen.  Finally, there are several functions which allow the caller to
53       manipulate  the  state  of  the  traversal,  i.e., the object which has
54       focus.
55
56       In order for widgets to be used on a screen which is to be  handled  by
57       traverseCDKScreen(), it must have the following methods available:
58          injectCharObj
59          inputWindowObj
60          focusObj
61          unfocusObj
62          saveDataObj
63          refreshDataObj
64
65       In addition, the following object properties must be properly handled:
66          acceptsFocus
67          hasFocus
68          inputWindow
69          dataPtr
70          dataType
71
72       At the time of this writing, not all widgets have been modified to work
73       with the screen-traversal facility.
74

AVAILABLE FUNCTIONS

76       int traverseCDKScreen (CDKSCREEN *screen);
77          This function contains the main screen traversal  engine.   It  does
78          the following:
79
80           1. Calls the refreshData method on each of the widgets to tell them
81              to update their appearance to match the data  which  are  refer‐
82              enced by their respective data pointers.
83
84           2. Calls the focusObject method on the first widget.
85
86           3. Repeats  the  following  until  one of the exit functions listed
87              above has been called:
88
89              ·   Read a keystroke from the keyboard.
90
91              ·   If the keystroke is ESCAPE and a  menu  widget  is  present,
92                  activate  the menu and traverse it until the user selects an
93                  entry or hits TAB.
94
95              ·   If the keystroke is TAB/BACKTAB then call the  unfocusObject
96                  method  on  the  current  widget,  and  move  focus  to  the
97                  next/previous widget (not counting menu widgets).  Call  the
98                  focusObject method on the newly current widget.
99
100              ·   If  the  keystroke is the EXIT-SAVE keystroke, then call the
101                  saveData method on each widget and return 1.
102
103              ·   If the keystroke is  the  EXIT-CANCEL  keystroke,  return  0
104                  without saving changes made by the user.
105
106              ·   If  the keystroke is the RESET-DATA keystroke, then call the
107                  refreshData method on each of the  widgets  to  reset  their
108                  appearance  to  match the data values that were present upon
109                  entry.
110
111              ·   Otherwise, pass the keystroke to the current widget.
112
113       CDKOBJS *getCDKFocusCurrent (CDKSCREEN *screen);
114            Return a pointer to the object which currently has  focus  in  the
115            given screen.
116
117       CDKOBJS *setCDKFocusCurrent (CDKSCREEN *screen, CDKOBJS *obj);
118            Set  the  focus  to  the given object, if the screen contains that
119            object.  If the screen does not contain the object,  return  null.
120            Otherwise, return the object.
121
122       CDKOBJS *setCDKFocusFirst (CDKSCREEN *screen);
123            Set focus on the first object in the given screen.
124
125       CDKOBJS *setCDKFocusLast (CDKSCREEN *screen);
126            Set focus on the last object in the given screen.
127
128       CDKOBJS *setCDKFocusNext (CDKSCREEN *screen);
129            Set focus on the next object in the given screen.
130
131       CDKOBJS *setCDKFocusPrevious (CDKSCREEN *screen);
132            Set focus on the previous object in the given screen.
133
134       exitOKCDKScreen
135          Causes  the  traversal  engine  to  exit  after calling the saveData
136          method for each of the widgets.
137
138       exitOKCDKScreenOf
139          Calls exitOKCDKScreen() on the screen associated  with  widget  obj.
140          This  function  was  designed to be used as a callback routine for a
141          button widget used as an OK button on a data-entry screen.
142
143       exitCancelCDKScreen
144          Causes the traversal engine to exit  without  saving  user  modified
145          data.
146
147       exitCancelCDKScreenOf
148          Calls  exitCancelCDKScreen()  on  the  screen associated with widget
149          obj.  This function was designed to be used as  a  callback  routine
150          for a button widget used as a Cancel button on a data-entry screen.
151
152       resetCDKScreen
153          Causes  the traversal engine to call the refreshData method for each
154          widget.  This will cause any unsaved changes to be discarded and the
155          widget states will be restored to their initial values.
156
157       resetCDKScreenOf
158          Calls  resetCDKScreen()  on  the  screen associated with widget obj.
159          This function was designed to be used as a callback  routine  for  a
160          button widget used as a Reset button on a data-entry screen.
161
162       traverseCDKOnce
163          This  is  a  utility  function, one of the pieces from which you can
164          construct a customized version of traverseCDKScreen.
165

BUGS

167       Not all widgets have had the extra methods added so that they work with
168       the screen traversal engine.
169

AUTHOR

171       Grant Edwards, Aspen Research Corporation
172       Thomas Dickey and contributors.
173

SEE ALSO

175       cdk(3), cdk_binding(3), cdk_display(3), cdk_screen(3)
176
177
178
179                                                               cdk_traverse(3)
Impressum