NAME

       cdk_traverse - functions to support keyboard traversal

SYNOPSIS

       cc [ flag ... ] file ...  -lcdk [ library ... ]

       #include <cdk.h>

       CDKOBJS *getCDKFocusCurrent (CDKSCREEN *screen);

       CDKOBJS *setCDKFocusCurrent (CDKSCREEN *screen, CDKOBJS *obj);

       CDKOBJS *setCDKFocusFirst (CDKSCREEN *screen);

       CDKOBJS *setCDKFocusLast (CDKSCREEN *screen);

       CDKOBJS *setCDKFocusNext (CDKSCREEN *screen);

       CDKOBJS *setCDKFocusPrevious (CDKSCREEN *screen);

       int traverseCDKScreen (CDKSCREEN *screen);

       void exitOKCDKScreen (CDKSCREEN *screen);

       void exitCancelCDKScreen (CDKSCREEN *screen);

       void resetCDKScreen (CDKSCREEN *screen);

       void exitOKCDKScreenOf(CDKOBJS *obj);

       void exitCancelCDKScreenOf (CDKOBJS *obj);

       void resetCDKScreenOf (CDKOBJS *obj);

       void traverseCDKOnce (
                      CDKSCREEN *screen,
                      CDKOBJS *curobj,
                      int keyCode,
                      boolean functionKey,
                      CHECK_KEYCODE funcMenuKey);

DESCRIPTION

       The functions above handle the traversal of a screen populated with various widgets.  Once the screen has
       been created and populated with widgets, a single call to traverseCDKScreen() will allow the user to move
       between  widgets  and enter data (or otherwise manipulate widgets).  Other functions are provided for use
       as callbacks by the widgets on the screen.  Finally, there are several functions which allow  the  caller
       to manipulate the state of the traversal, i.e., the object which has focus.

       In  order  for widgets to be used on a screen which is to be handled by traverseCDKScreen(), it must have
       the following methods available:
          injectCharObj
          inputWindowObj
          focusObj
          unfocusObj
          saveDataObj
          refreshDataObj

       In addition, the following object properties must be properly handled:
          acceptsFocus
          hasFocus
          inputWindow
          dataPtr
          dataType

       At the time of this writing, not all widgets  have  been  modified  to  work  with  the  screen-traversal
       facility.

AVAILABLE FUNCTIONS

       int traverseCDKScreen (CDKSCREEN *screen);
          This function contains the main screen traversal engine.  It does the following:

           1. Calls  the  refreshData  method  on each of the widgets to tell them to update their appearance to
              match the data which are referenced by their respective data pointers.

           2. Calls the focusObject method on the first widget.

           3. Repeats the following until one of the exit functions listed above has been called:

              •   Read a keystroke from the keyboard.

              •   If the keystroke is ESCAPE and a menu widget is present, activate the  menu  and  traverse  it
                  until the user selects an entry or hits TAB.

              •   If  the keystroke is TAB/BACKTAB then call the unfocusObject method on the current widget, and
                  move focus to the next/previous widget (not counting  menu  widgets).   Call  the  focusObject
                  method on the newly current widget.

              •   If  the keystroke is the EXIT-SAVE keystroke, then call the saveData method on each widget and
                  return 1.

              •   If the keystroke is the EXIT-CANCEL keystroke, return 0 without saving  changes  made  by  the
                  user.

              •   If  the keystroke is the RESET-DATA keystroke, then call the refreshData method on each of the
                  widgets to reset their appearance to match the data values that were present upon entry.

              •   Otherwise, pass the keystroke to the current widget.

       CDKOBJS *getCDKFocusCurrent (CDKSCREEN *screen);
            Return a pointer to the object which currently has focus in the given screen.

       CDKOBJS *setCDKFocusCurrent (CDKSCREEN *screen, CDKOBJS *obj);
            Set the focus to the given object, if the screen contains that  object.   If  the  screen  does  not
            contain the object, return null.  Otherwise, return the object.

       CDKOBJS *setCDKFocusFirst (CDKSCREEN *screen);
            Set focus on the first object in the given screen.

       CDKOBJS *setCDKFocusLast (CDKSCREEN *screen);
            Set focus on the last object in the given screen.

       CDKOBJS *setCDKFocusNext (CDKSCREEN *screen);
            Set focus on the next object in the given screen.

       CDKOBJS *setCDKFocusPrevious (CDKSCREEN *screen);
            Set focus on the previous object in the given screen.

       exitOKCDKScreen
          Causes the traversal engine to exit after calling the saveData method for each of the widgets.

       exitOKCDKScreenOf
          Calls  exitOKCDKScreen()  on  the screen associated with widget obj.  This function was designed to be
          used as a callback routine for a button widget used as an OK button on a data-entry screen.

       exitCancelCDKScreen
          Causes the traversal engine to exit without saving user modified data.

       exitCancelCDKScreenOf
          Calls exitCancelCDKScreen() on the screen associated with widget obj.  This function was  designed  to
          be used as a callback routine for a button widget used as a Cancel button on a data-entry screen.

       resetCDKScreen
          Causes  the  traversal  engine  to  call  the refreshData method for each widget.  This will cause any
          unsaved changes to be discarded and the widget states will be restored to their initial values.

       resetCDKScreenOf
          Calls resetCDKScreen() on the screen associated with widget obj.  This function  was  designed  to  be
          used as a callback routine for a button widget used as a Reset button on a data-entry screen.

       traverseCDKOnce
          This  is  a  utility  function, one of the pieces from which you can construct a customized version of
          traverseCDKScreen.

BUGS

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

AUTHOR

       Grant Edwards, Aspen Research Corporation
       Thomas E. Dickey and contributors.

SEE ALSO

       cdk(3), cdk_binding(3), cdk_display(3), cdk_screen(3)

                                                                                                 cdk_traverse(3)