![]() |
MD_Menu Library
1.0.0
Library for 1 or 2 line display menu management
|
The MD_Menu library is designed to allow definition and navigation of a menu system by moving between the menu nodes. At a leaf node, YAMS_LCD can either call user subroutines or manage editing values of specific (defined) types.
All menu nodes are equal but are classified as node or leaf. All the menu trees starts from a unique node at the root of the tree, which is the first node that is defined. As each node is added, it is linked to its parent node. The parent node of a root is the root node itself.
Each node is an instance of class YAMS_Node. All nodes have a common attribute of a label, the text shown on the LCD for menu item. Leaves have additional attributes associated with the types of data to edit or actions that they enable the user to perform once they have reached the leaf node.
Leaf nodes are always associated with a user variable when they are created. The definition is a pointer to appropriately typed data in the user code. The data types supported are listed in the varType_t enumerated types. Variables are associated to the menu items by using the add*() methods of the YAMS_Node class and any edited changes from the menu are updated in these user variables.
Menu navigation is carried out under the control of user code input invoked as a callback routine. The code must comply with the cbUserNav function prototype.
The callback routine implementation is dependent on the type of input hardware, but the return codes for the required actrions must be one of the userNavAction_t enumerated type.
Navigation is carried out with 4 keys:
A number of input hardware setups are demonstrated in the Test example code.
Menu display is enabled by user code as a callback routine from the library. The callback must comply with the cbUserDisplay function prototype.
The callback is provided with a request of type userDisplayAction_t and a message to display.
Display hardware must be able to display one or two lines for the menu display. All menu screens are structured with the first line as title and the second as the current menu selection or currently edited value, as appropriate. If the display can only support one line, then the fisrt line is discarded and the only the second line is displayed.
The limited amount of RAM available in micro controllers is a challenge for menu systems, as the contain considerable data required for text labels and other status information.
The MD_Menu library uses statically allocated data located in PROGMEM for the menu system and only copies the current menu record into RAM.
As shown in the figure above, the library uses three types of objects, each identified with a unique id within the object type. A menu header (of type mnuHeader_t) defines a menu. The header conatins a label for the title and the range of menu items (of type mnuItem_t identified) that should be displayed for the menu. Menu item Ids between the start and end id locations include all the ids in locations in between, even if they are out of number sequence.
A menu item may lead to another menu (if it is a node in the menu tree) or an input item (of type mnuInput_t) if it is a leaf of the menu system. The depth of the menu tree is restricted by the defined MENU_STACK_SIZE constant. When this limit is exceeded, the library will just ignore requests that cause additinal menu depth but continues to run.
Menu input items define the type of value that is to be edited by the user and parameters associated with managing the input for that value. Before the value is edited a callback following the cbValueRequest prototype is called to get a retrieve a pointer to a variable with the current value. The input item id and index value are provided to identify which value is being requested. A copy of the user variable is used for editing and a second cbValueRequest is invoked after the value is updated, enabling the user code to take action on the change. If the variable edit is cancelled, the second cbValueRequest call does not occur.
Variables may be of the following types: