Navigation

class navRoot

A central navigation control, automating a menu structure, a list of inputs and a list of outputs. This object uses a list of navigation nodes, one for each depth level.

A depth level is any sub-menu or choice/select/toggle field.

Version 4.x allows multiple concurrent root structures that can have independent IO and possibly independent menu structures.

example:

A main menu with some sub-menus and multiple choice fields will have depth 2, provided that the sub-menus are simple (do not have other sub-sub-menus).

public data members

outputsList &out list of available outputs

Stream& in input stream (can be an agglomeration of streams)

navNode path* hold information for each navigation step, entering a sub-menu or choice/select field

const idx_t maxDepth hold max depth used to construct this navigation control

idx_t level active navigation level, use this to index on path[level]

bool suspended=false suspension status, when suspended polling will result on a suspension function being called. The menu system auto-suspends when exiting from the navigation root

bool showTitle=true when true show menu title on top line if devices has more than one line.

idleFunc idleTask=inaction what to do when menu exits, by default this idleFunc is pointed as sleepTask when menu is suspended

idleFunc sleepTask=NULL user task when suspending menu, see idleOn / idleOff

navTarget navFocus=NULL** shortcut for the current input target (selected element)

new options added on version 4, they were on config options previously

bool nav2D=false not used

bool canExit=true v4.0 moved from global options, signal if can exit from this navRoot into suspended mode.

bool useUpdateEvent=false if false, when field value is changed use enterEvent instead.

idx_t inputBurst=1 limit of inputs that can be processed before output, nice for slow update output devices.

bool useAccel=true use numeric accelerators. Numeric keys (1-9) will jump to the respective menu element. Also disable accelerators print on devices that show them.

constructing

navRoot(menuNode& root,navNode* path,idx_t maxDepth,Stream& in,outputsList &o)

where:

root menu object for entry level

path array of navigation level controllers (size maxDepth)

maxDepth max. navigation path depth

in inputs control object (can be NO_INPUTS_NAV)

out outputs control object (can be NO_OUTPUTS_NAV)

public member functions

navNode& node() const get current navigation level control node (path[level])

menuNode& active() get current menu object target

prompt& selected() const get selection of active node

bool changed(const menuOut& out) const check if current item needs to be redraw on output device out.

bool changed(idx_t n) const check if current item needs to be redraw on output device index n.

bool async(const char at)* aux function to allow async calls (experimental), used on web interface.

menuOut& printPath(menuOut& o) const aux function, prints back-reference used on web interface.

Used printMenu() const ask output controller to draw the current menu

Used printMenu(menuOut& o) const printMenu on arbitrary menuOut device

void doInput(Stream& in) process input from given stream

void doInput(const char*in) process characters as input (experimental)

void doInput() process input from registered inputs

void doOutput() print menu on registered devices as needed

void poll() full automation mode tick. Does input and output as needed

void doNav(navCmd cmd) send navigation command to this object

navCmd enter() aux function, process enter command.

navCmd exit() aux function, process exit command.

void idleOn(idleFunc task=inaction) enter idle mode with optional processing function, the menu will stop processing inputs and will only call the pointed function on start/end of idle and on poll if the output device has not the minimalRedraw style.

void idleOff() leave idle mode and continue processing input/output

*void alert(char msg,bool modal=true) try to print message to output (experimental), this is known to bad behave on some devices (flicking).

class navNode

This object controls a single navigation depth layer, targeting a menu or multi-choice option. navRoot object uses an array of this object with size maxDepth.

public data members

idx_t sel=0 current selection index

menuNode target* focused menu node

static navRoot root* navigation root object (experimental), this might change to non static to allow multiple navigation root objects.

public member functions

idx_t sz() const number of menu or selection/choice elements.

prompt const * data() const* menu data

prompt& selected() const focused menu element

bool wrap() const true if current target uses wrap navigation

result event(eventMask e,idx_t i) send event to item index i

result event(eventMask e) send event to current item

result sysEvent(eventMask e,idx_t i) send system event to item index i

result sysEvent(eventMask e) send system event to current item

navCmd navKeys(char ch) produce navigation command from navigation character

navCmd doNavigation(navCmd cmd) aux function, generic navigation routine

bool changed(const menuOut& out) const true if current item needs to be drawn on out device

prompt& operator[](idx_t i) const get item by index

navCmd structure

this structure represents a navigation command, it can be used to call navRoot::doNav and drive the system programmatically.

struct navCmd {
  navCmds cmd;
  idx_t param;
  inline navCmd(navCmds cmd):cmd(cmd),param(-1) {}
  inline navCmd(navCmds cmd,idx_t p):cmd(cmd),param(p) {}
  inline bool operator==(navCmds n) const {return cmd==n;}
  inline operator navCmds() const {return cmd;}
};

where

cmd is one of the navCmds listed bellow

param is an aux. value to be interpreted/used by the command. The meaning depends only on the command.

functions:

navCmd(navCmds cmd) construct a navCmd structure

navCmd(navCmds cmd,idx_t p) construct a navCmd structure with an aux. value.

bool operator==(navCmds n) compare commands

operator navCmds() const conversion to raw navCmd code when needed

enum navCmds

• noCmd do nothing
• escCmd escape/exit
• enterCmd enter current options
• upCmd move up
• downCmd move down
• leftCmd N/A
• rightCmd N/A
• idxCmd select option by index
• scrlUpCmd N/A
• scrlDownCmd N/A

Example

nav.doNav(navCmd(idxCmd,1)); //hilite second option
nav.doNav(navCmd(enterCmd)); //execute option