Repository files navigation

Menu creation Arduino library for LCDs, wrapsLiquidCrystal.

LiquidMenu wraps Arduino'sLiquidCrystal library with the ability to create menus.It simplifies the menu creation process by abstracting the elements of a menu into hierarchically organized classes.

• fast and easy menu creation
• selectable menu items
• callback functions
• parallel or I2C connection

• Examples
• API reference
• Discussions

UseArduino's library manager (recommended) or download it directly fromhere.

• Arduino'sLiquidCrystal or similar library
• LCD supported byLiquidCrystal (with Hitachi HD44780 or a compatible chipset)
• Arduino board or a compatible microcontroller
• push-buttons or something similar

The library uses hierarchically structured classes to represent the different elements of a menu.

TheLiquidLine class represents aline of text/numbers on the display.

TheLiquidScreen class represents a collection oflines that are shown together on the display (i.e. the current screen).

TheLiquidMenu class combines thescreens to form amenu. This class is used for controlling themenu (switching betweenscreens, selectinglines, calling functions etc...).

If your structure consists of multiple differentmenus, for example a "Main menu" that displays sensor information on multiple screens and a "Settings" menu for configuring the sensors, you can combine the differentmenus inside aLiquidSystem class. That way, you can browse the screens of just themenu you are currently on.LiquidSystem has the same public interface asLiquidMenu. Sub-menusclasses structure diagram.

Menu creation is all about structure. First there are variables/constants that go into theLiquidLine objects. Then theLiquidLine objects go into theLiquidScreen objects. ThenLiquidScreen objects go into theLiquidMenu object(s). And optionally theLiquidMenu objects go into theLiquidSystem object.This structure can be established either on object instantiation or later using the classes' methods.

// Takes column and row for the position and 1 to 4 variable references. These variable// references are what is going to be printed on the display. They can be integers,// string literals or char[] arrays for dynamic text.LiquidLine(byte column, byte row, A &variableA...);// Takes 0 to 4 LiquidLine objects.LiquidScreen(LiquidLine &liquidLine1...);// Takes a reference to the LiquidCrystal object, 0 to 4 LiquidScreen objects and// optionally the number of the screen that will be shown first.LiquidMenu(LiquidCrystal &liquidCrystal, LiquidScreen &liquidScreen1..., byte startingScreen =1);// Takes 0 to 4 LiquidMenu objects and optionally the number of the menu that will be shown first.LiquidSystem(LiquidMenu &liquidMenu1..., byte startingMenu =1);

The menu is navigated from theLiquidMenu object or if there are multiple menus - theLiquidSystem object. Thescreens can by cycled forward and backward, it's also possible to jump to a specificscreen using its object or consecutive number:

voidLiquidMenu::next_screen();voidLiquidMenu::previous_screen();boolLiquidMenu::change_screen(LiquidScreen &liquidScreen);

Thelines of text/numbers shown on the display can be made interactive. Every line can have callback functions attached to it (up to 8 by default). Every attached callback function must be identified by number:

boolLiquidLine::attach_function(byte number,void (*function)(void));

To call aline's attached function, theline needs to befocused (selected). To cycle thefocus through thelines shown on thescreen use:

voidLiquidMenu::switch_focus(bool forward =true);

When theline is selected one of its attached functions can be called with:

voidLiquidMenu::call_function(byte number);

Thenumber specifies which one of the attached functions should be called.

Conceptionally similar functions should be attached under the same number to the differentlines. For example if we are printing the state of four LEDs. Each LEDis instantiated in aLiquidLine object with their name and their state. The functions used to turn them on can be attached under number1 and the functions for turning them off - under number2. Then if we have 3 buttons, one can be used to switch the focus, the second (say 'UP') button can be used to call function1 and the third (say 'DOWN') button can be used to call function2.

// ...// First we need to instantiate the LiquidCrystal object.LiquidCrystallcd(LCD_RS, LCD_E, LCD_D4, LCD_D5, LCD_D6, LCD_D7);// a variable that will be updated periodically somewhere in our codefloat temperature =0.0f;// ----- WELCOME SCREEN -----// a line of one string literalLiquidLinelineHello(2,0,"Hello world!");LiquidLinelineRight(7,1,">");// create a screen from the above linesLiquidScreenscreenMain(lineHello, lineRight);// --------------------------// ----- STATUS SCREEN -----// a line of two string literals and a float variableLiquidLinelineTemp(0,0,"Temp:", temperature,"C");LiquidScreenscreenStatus(lineTemp);// -------------------------// ----- MENU -----// create a menu from the screensLiquidMenumenu(lcd, screenMain, screenStatus);// ----------------voidsetup() {    lcd.begin(16,2);// ...}voidloop() {    temperature =readTemperature();    menu.update();// update the display to show the new informationif (rightButton()) {        menu.next_screen();    }if (leftButton()) {        menu.previous_screen();    }// ...}

❔ If you have a question head over toDiscussions - Q&A.

🐛 If you encounter a bug, feel free to open anissue.

💡 To propose a feature go toDiscussions - Ideas.

😎 You are also welcome to show off your project inDiscussions - Show & Tell.

All other forms of contributions (bug fixes, feature implementations, documentation improvements, typos, etc...) are welcome. To get started see thecontributing guide.

• Richard Wardlow - Scrolling lines and configuring the number of digits shown after the decimal point.
• jmpmscorp - Getter functions inlines.
• RobotGrrl - Fixing bugs inLiquidSystem.
• thijstriemstra andDarioMaechler - Configurable focus indicator "ghosting".
• per1234 - Fixing configuration files problems.

The MIT License (MIT)

Copyright (c) 2016 Vasil Kalchev

Permission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.