1cdk_traverse(3) Library Functions Manual cdk_traverse(3)
2
6 cdk_traverse - functions to support keyboard traversal
7
9 cc [ flag ... ] file ... -lcdk [ library ... ]
10 #include <cdk.h>
12 CDKOBJS *getCDKFocusCurrent (CDKSCREEN *screen);
14 CDKOBJS *setCDKFocusCurrent (CDKSCREEN *screen, CDKOBJS *obj);
16 CDKOBJS *setCDKFocusFirst (CDKSCREEN *screen);
18 CDKOBJS *setCDKFocusLast (CDKSCREEN *screen);
20 CDKOBJS *setCDKFocusNext (CDKSCREEN *screen);
22 CDKOBJS *setCDKFocusPrevious (CDKSCREEN *screen);
24 int traverseCDKScreen (CDKSCREEN *screen);
26 void exitOKCDKScreen (CDKSCREEN *screen);
28 void exitCancelCDKScreen (CDKSCREEN *screen);
30 void resetCDKScreen (CDKSCREEN *screen);
32 void exitOKCDKScreenOf(CDKOBJS *obj);
34 void exitCancelCDKScreenOf (CDKOBJS *obj);
36 void resetCDKScreenOf (CDKOBJS *obj);
38 void traverseCDKOnce (
40 CDKSCREEN *screen,
41 CDKOBJS *curobj,
42 int keyCode,
43 boolean functionKey,
44 CHECK_KEYCODE funcMenuKey);
45
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 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 In addition, the following object properties must be properly handled:
66 acceptsFocus
67 hasFocus
68 inputWindow
69 dataPtr
70 dataType
71 At the time of this writing, not all widgets have been modified to work
73 with the screen-traversal facility.
74
76 int traverseCDKScreen (CDKSCREEN *screen);
77 This function contains the main screen traversal engine. It does
78 the following:
79 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 2. Calls the focusObject method on the first widget.
85 3. Repeats the following until one of the exit functions listed
87 above has been called:
88 · Read a keystroke from the keyboard.
90 · 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 · 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 · If the keystroke is the EXIT-SAVE keystroke, then call the
101 saveData method on each widget and return 1.
102 · If the keystroke is the EXIT-CANCEL keystroke, return 0
104 without saving changes made by the user.
105 · 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 · Otherwise, pass the keystroke to the current widget.
112 CDKOBJS *getCDKFocusCurrent (CDKSCREEN *screen);
114 Return a pointer to the object which currently has focus in the
115 given screen.
116 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 CDKOBJS *setCDKFocusFirst (CDKSCREEN *screen);
123 Set focus on the first object in the given screen.
124 CDKOBJS *setCDKFocusLast (CDKSCREEN *screen);
126 Set focus on the last object in the given screen.
127 CDKOBJS *setCDKFocusNext (CDKSCREEN *screen);
129 Set focus on the next object in the given screen.
130 CDKOBJS *setCDKFocusPrevious (CDKSCREEN *screen);
132 Set focus on the previous object in the given screen.
133 exitOKCDKScreen
135 Causes the traversal engine to exit after calling the saveData
136 method for each of the widgets.
137 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 exitCancelCDKScreen
144 Causes the traversal engine to exit without saving user modified
145 data.
146 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 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 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 traverseCDKOnce
163 This is a utility function, one of the pieces from which you can
164 construct a customized version of traverseCDKScreen.
165
167 Not all widgets have had the extra methods added so that they work with
168 the screen traversal engine.
169
171 Grant Edwards, Aspen Research Corporation
172 Thomas Dickey and contributors.
173
175 cdk(3), cdk_binding(3), cdk_display(3), cdk_screen(3)
176 cdk_traverse(3)