Home

#ArduinoMenu Library 3.x Wiki

Menu library basics

This library is divided in parts to be included on your project as needed, this is a way of minimizing system resource usage. Be sure to include the needed parts.

The code is focused on lower resource profile.

The menu is static constructed to allow PROGMEM usage. Meaning that construction is more complicated than dynamic menus

The menu system does not store field variables, instead it uses references to variables already in your code, this makes integration easier and avoids translations and extra functions.

##Menu software components

###Menu structure

This is done using a set of macros to define menus, atach menus to other menus to form sub-menus, numeric fields and choice/selection fields. Macros are used to define most of the menu data as static and stored on flash memory, because ram memory is critical on AVR devices. Also all menu used ram is allocated at startup, avoiding dynamic ram allocation and making memory usage more predictable.

###Inputs

We support multiple parallel inputs, so the input is usually defined as an array of devices.

the following macro can be used

MENU_INPUTS(«name», «input device» [,«list of input devices»]);

where:

«name» is the variable name that will be created on your sketch to hold the inputs lists. you can latter refer to that variable if needed.

the name is followed by a list of input devices (anything that can be a stream)

example:

//create a variable 'in' and store there an input, in this case simply the serial input
MENU_INPUTS(in,&Serial);

the inputs list can also be defined without the macro using several definitions

###Outputs

We support multiple parallel devices, this is useful on final products because it provides alternatives in case of failure of the main output device. Usually an LCD or TFT as main output and serial output as a maintenance/backup output device.

MENU_OUTPUTS(«name»,«MAX_DEPTH» ,«output device» ,«output device» [,«output device»] );

example:

MENU_OUTPUTS(out,MAX_DEPTH
  ,SERIAL_OUT(Serial)
  ,NONE//must have 2 items at least
);

where: «name» is the c++ variable name that will hold the outputs list «MAX_DEPTH» is an integer defining the maximum depth of navigation layers (sub-menus and choice/select fields) that can be nested. this is followed by a list of output devices (minimum 2).

See also max. depth definition on the navigation control

###Navigation control All navigation is centrally controlled by a navigation root object

the navigation root object holds the lists of inputs and outputs as well as a list layer navigation status used to navigate down on sub-menus and to preserve status when we navigate back. Because this menu avoids dynamic memory allocation, we need to tell beforehand the maximum nested depth level, any sub-menu or choice/select field must count as one depth layer.

NAVROOT(«name»,«menu entry»,«MAX_DEPTH»,«in»,«out»);

«name» is the c++ variable name to hold this navigation object (class navRoot instance), you can latter refer to this or call members functions of this object. «menu entry» - the c++ variable name given to a menu that you want to be the main or entry level for this navigation. «MAX_DEPTH» - integer specifying the maximum navigation depth «in» c++ variable name given when defined the list of inputs «out» c++ variable name given when defined the output devices list.

example:

NAVROOT(nav,mainMenu,MAX_DEPTH,in,out);

###Menu execution

The menu system depends on your code to call one of its functions to iterate the system. So if none is called the menu is not executing any IO and your code is free to use the IO devices. Also if the menu system calls one of your functions as a result of iteration, then the menu will not be executing while your function does not return. Unless of course you define some other interrupt driven method that calls the menu meanwhile.

menu execution/iteration is done by using some API functions

One of this functions must be called regularly because the system just verifies if there is available input or output need and returns.

void poll();

the most simple and powerful menu execution function,it will deal with all IO driving the menu on a full automated mode.

inline void doInput();

check inputs list for available data

void doInput(const char*in);

call the menu system to consider one given character as input

inline void doOutput();

verify the need of output and satisfy it.