cdk_traverse(3)

💖 cdk_traverse — the keyboard-traversal era of your CDK era 💖

okay bestie, settle in, because this is the page from the cdk_traverse(3) manual — a Library calls page, no cap — and it's all about moving focus around a screen full of widgets like the main character you are. 👑

---

✨ NAME ✨

cdk_traverse — Cdk functions for 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 🌸

so the functions up there 👆 are the whole friend group that handles traversal of a screen that's been populated with various widgets. once you've created the screen and filled it with widgets, one single call to traverseCDKScreen() is all it takes for the user to move between widgets and enter data (or otherwise manipulate widgets). literally one call, that's the vibe. ✨

other functions in the lineup are there to be used as callbacks by the widgets on the screen. and then, finally, there are several functions that let the caller manipulate the state of the traversal — i.e., the object which has focus. that's the whole point, bestie, focus is the currency here. 👑

for widgets to be usable on a screen that's going to be handled by traverseCDKScreen(), it must have the following methods available:

injectCharObj
inputWindowObj
focusObj
unfocusObj
saveDataObj
refreshDataObj

plus, the following object properties have to 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 is THE main screen traversal engine, the icon, the moment. here's what it does:

1. calls the refreshData method on each of the widgets, telling 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);

returns a pointer to the object which currently has focus in the given screen. the moment's current holder, fr fr.

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

sets the focus to the given object, if the screen contains that object. if the screen does not contain the object, returns null. otherwise, returns the object. it's giving "you can sit with us, but only if you're on the list". 💀

⭐ CDKOBJS *setCDKFocusFirst (CDKSCREEN *screen);

sets focus on the first object in the given screen.

🦋 CDKOBJS *setCDKFocusLast (CDKSCREEN *screen);

sets focus on the last object in the given screen.

✨ CDKOBJS *setCDKFocusNext (CDKSCREEN *screen);

sets focus on the next object in the given screen.

💜 CDKOBJS *setCDKFocusPrevious (CDKSCREEN *screen);

sets 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. saving on the way out, obsessed.

🌸 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. iykyk.

💀 exitCancelCDKScreen

causes the traversal engine to exit without saving user modified data. bye, changes, you never happened. 🙈

🧚 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. full factory reset energy, periodt.

🌈 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. build-your-own-icon kit, basically. 💅

---

💀 BUGS 💀

not all widgets have had the extra methods added so that they work with the screen traversal engine. some of them simply did not get the memo. 😭

---

🫶 AUTHORS 🫶

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

---

🌟 SEE ALSO 🌟

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

---

and that's the whole page, bestie — from the cdk_traverse(3) manual, this little bundle of joy came stamped with 2024-03-28 as its date. mwah, take care of your focus, it's precious. 🎀💖✨