https://invisible-island.net/cdk/manpage/


cdk_traverse 3

cdk_traverse(3)           Library Functions Manual           cdk_traverse(3)

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  wid-
       gets).  Other functions are provided for use as callbacks by the wid-
       gets 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 han-
       dled:
          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:

              o   Read a keystroke from the keyboard.

              o   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.

              o   If  the  keystroke is TAB/BACKTAB then call the unfocusOb-
                  ject 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.

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

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

              o   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.

              o   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 Dickey and contributors.

SEE ALSO

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

                                                             cdk_traverse(3)