{"id":13581258,"url":"https://github.com/VasilKalchev/LiquidMenu","last_synced_at":"2025-04-06T07:31:53.427Z","repository":{"id":46226488,"uuid":"64065157","full_name":"VasilKalchev/LiquidMenu","owner":"VasilKalchev","description":"Menu creation Arduino library for LCDs, wraps LiquidCrystal.","archived":false,"fork":false,"pushed_at":"2024-05-20T07:03:27.000Z","size":6131,"stargazers_count":265,"open_issues_count":2,"forks_count":51,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-05-20T08:25:38.522Z","etag":null,"topics":["arduino","arduino-library","hd44780","i2c","lcd","liquidcrystal","menu"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VasilKalchev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-24T12:50:49.000Z","updated_at":"2024-05-20T08:25:40.346Z","dependencies_parsed_at":"2022-09-15T15:50:41.183Z","dependency_job_id":"b82616f2-96ee-405e-8913-d0152e774e28","html_url":"https://github.com/VasilKalchev/LiquidMenu","commit_stats":null,"previous_names":["vasilkalchev/liquidmenu"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VasilKalchev%2FLiquidMenu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VasilKalchev%2FLiquidMenu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VasilKalchev%2FLiquidMenu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VasilKalchev%2FLiquidMenu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VasilKalchev","download_url":"https://codeload.github.com/VasilKalchev/LiquidMenu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423512,"owners_count":20936626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","arduino-library","hd44780","i2c","lcd","liquidcrystal","menu"],"created_at":"2024-08-01T15:01:59.731Z","updated_at":"2025-04-06T07:31:52.841Z","avatar_url":"https://github.com/VasilKalchev.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"![Logo][logo-img]\n\n\u003cp align=center\u003e\n  \u003ci\u003eMenu creation Arduino library for LCDs, wraps \u003ca href=\"https://github.com/arduino-libraries/LiquidCrystal\"\u003eLiquidCrystal\u003c/a\u003e.\u003c/i\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/VaSe7u/LiquidMenu/archive/v1.6.0.zip\"\u003e\u003cimg alt=\"Download\" src=\"https://img.shields.io/badge/download-1.6.0-blue.svg?style=flat-square\u0026logo=github\u0026logoColor=white\u0026color=1cb3e4\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://vasilkalchev.github.io/LiquidMenu/annotated.html\"\u003e\u003cimg alt=\"Documentation\" src=\"https://img.shields.io/badge/docs-doxygen-blue.svg?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/VaSe7u/LiquidMenu/discussions\"\u003e\u003cimg alt=\"Documentation\" src=\"https://img.shields.io/github/discussions/vase7u/liquidmenu?style=flat-square\u0026color=blueviolet\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/VaSe7u/LiquidMenu/actions/workflows/compile-examples.yml\"\u003e\u003cimg alt=\"GitHub workflow - compile examples\" src=\"https://img.shields.io/github/actions/workflow/status/VaSe7u/LiquidMenu/compile-examples.yml?color=orange\u0026label=build%20examples\u0026style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://choosealicense.com/licenses/mit/\"\u003e\u003cimg alt=\"MIT license\" src=\"https://img.shields.io/badge/license-MIT-lightgrey.svg?style=flat-square\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**LiquidMenu** wraps Arduino's [LiquidCrystal][LiquidCrystal-lib] library with the ability to create menus.\nIt simplifies the menu creation process by abstracting the elements of a menu into hierarchically organized classes.\n\n\n## Features\n- fast and easy menu creation\n- selectable menu items\n- callback functions\n- parallel or I2C connection\n\n## Resources\n - [Examples][examples-dir]\n - [API reference][doxygen-doc]\n - [Discussions][disc]\n\n## Installation\nUse _Arduino's library manager_ (recommended) or download it directly from [here][latest_release].\n\n\u003c!-- \u003c/br\u003e --\u003e\n\n# Quick start\n### Requirements\n- Arduino's [LiquidCrystal][LiquidCrystal-lib] or similar library\n- LCD supported by [LiquidCrystal][LiquidCrystal-lib] (with Hitachi HD44780 or a compatible chipset)\n- Arduino board or a compatible microcontroller\n- push-buttons or something similar\n\n### Classes organization\nThe library uses hierarchically structured classes to represent the different elements of a menu.\n\n#### Basic classes structure diagram:\n![basic classes structure diagram](https://raw.githubusercontent.com/VaSe7u/LiquidMenu/master/doc/img/classes-structure/menu.png \"Basic classes structure diagram\")\n\nThe `LiquidLine` class represents a *line* of text/numbers on the display.\n\nThe `LiquidScreen` class represents a collection of *lines* that are shown together on the display (i.e. the current screen).\n\nThe `LiquidMenu` class combines the *screens* to form a *menu*. This class is used for controlling the *menu* (switching between *screens*, selecting *lines*, calling functions etc...).\n\nIf your structure consists of multiple different *menus*, for example a \"Main menu\" that displays sensor information on multiple screens and a \"Settings\" menu for configuring the sensors, you can combine the different *menus* inside a `LiquidSystem` class. That way, you can browse the screens of just the *menu* you are currently on. `LiquidSystem` has the same public interface as `LiquidMenu`. Sub-menus [classes structure diagram](https://raw.githubusercontent.com/VaSe7u/LiquidMenu/master/doc/img/classes-structure/system.png).\n\n\n### Creating a menu\nMenu creation is all about structure. First there are variables/constants that go into the `LiquidLine` objects. Then the `LiquidLine` objects go into the `LiquidScreen` objects. Then `LiquidScreen` objects go into the `LiquidMenu` object(s). And optionally the `LiquidMenu` objects go into the `LiquidSystem` object.\nThis structure can be established either on object instantiation or later using the classes' methods.\n```c++\n// Takes column and row for the position and 1 to 4 variable references. These variable\n// references are what is going to be printed on the display. They can be integers,\n// string literals or char[] arrays for dynamic text.\nLiquidLine(byte column, byte row, A \u0026variableA...);\n\n// Takes 0 to 4 LiquidLine objects.\nLiquidScreen(LiquidLine \u0026liquidLine1...);\n\n// Takes a reference to the LiquidCrystal object, 0 to 4 LiquidScreen objects and\n// optionally the number of the screen that will be shown first.\nLiquidMenu(LiquidCrystal \u0026liquidCrystal, LiquidScreen \u0026liquidScreen1..., byte startingScreen = 1);\n\n// Takes 0 to 4 LiquidMenu objects and optionally the number of the menu that will be shown first.\nLiquidSystem(LiquidMenu \u0026liquidMenu1..., byte startingMenu = 1);\n```\n\n### Navigating the menu\nThe menu is navigated from the `LiquidMenu` object or if there are multiple menus - the `LiquidSystem` object. The *screens* can by cycled forward and backward, it's also possible to jump to a specific *screen* using its object or consecutive number:\n```c++\nvoid LiquidMenu::next_screen();\nvoid LiquidMenu::previous_screen();\nbool LiquidMenu::change_screen(LiquidScreen \u0026liquidScreen);\n```\n\n### Focus and callback functions\nThe *lines* 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:\n```c++\nbool LiquidLine::attach_function(byte number, void (*function)(void));\n```\n\nTo call a *line's* attached function, the *line* needs to be *focused* (selected). To cycle the *focus* through the *lines* shown on the *screen* use:\n```c++\nvoid LiquidMenu::switch_focus(bool forward = true);\n```\n\nWhen the *line* is selected one of its attached functions can be called with:\n```c++\nvoid LiquidMenu::call_function(byte number);\n```\nThe `number` specifies which one of the attached functions should be called.\n\n\u003e Conceptionally similar functions should be attached under the same number to the different *lines*. For example if we are printing the state of four LEDs. Each LEDis instantiated in a `LiquidLine` object with their name and their state. The functions used to turn them on can be attached under number *1* and the functions for turning them off - under number *2*. Then if we have 3 buttons, one can be used to switch the focus, the second (say 'UP') button can be used to call function *1* and the third (say 'DOWN') button can be used to call function *2*.\n\n### Basic example\n```c++\n// ...\n\n// First we need to instantiate the LiquidCrystal object.\nLiquidCrystal lcd(LCD_RS, LCD_E, LCD_D4, LCD_D5, LCD_D6, LCD_D7);\n\n// a variable that will be updated periodically somewhere in our code\nfloat temperature = 0.0f;\n\n// ----- WELCOME SCREEN -----\n// a line of one string literal\nLiquidLine lineHello(2, 0, \"Hello world!\");\nLiquidLine lineRight(7, 1, \"\u003e\");\n\n// create a screen from the above lines\nLiquidScreen screenMain(lineHello, lineRight);\n// --------------------------\n\n// ----- STATUS SCREEN -----\n// a line of two string literals and a float variable\nLiquidLine lineTemp(0, 0, \"Temp: \", temperature, \"C\");\nLiquidScreen screenStatus(lineTemp);\n// -------------------------\n\n// ----- MENU -----\n// create a menu from the screens\nLiquidMenu menu(lcd, screenMain, screenStatus);\n// ----------------\n\nvoid setup() {\n    lcd.begin(16, 2);\n    \n    // ...\n}\n\nvoid loop() {\n    temperature = readTemperature();\n    menu.update(); // update the display to show the new information\n    \n    if (rightButton()) {\n        menu.next_screen();\n    }\n    if (leftButton()) {\n        menu.previous_screen();\n    }\n    \n    // ...\n}\n```\n\n# Community and contributing\n:grey_question: If you have a question head over to [Discussions - Q\u0026A][q\u0026a-disc].\n\n:bug: If you encounter a bug, feel free to open an [issue][issues].\n\n:bulb: To propose a feature go to [Discussions - Ideas][ideas-disc].\n\n:sunglasses: You are also welcome to show off your project in [Discussions - Show \u0026 Tell][show\u0026tell-disc].\n\nAll other forms of contributions (bug fixes, feature implementations, documentation improvements, typos, etc...) are welcome. To get started see the [contributing][contributing-doc] guide.\n\n\n## Contributors\n - [Richard Wardlow](https://github.com/circuitsforfun) - Scrolling lines and configuring the number of digits shown after the decimal point.\n - [jmpmscorp](https://github.com/jmpmscorp) - Getter functions in *lines*.\n - [RobotGrrl](https://github.com/RobotGrrl) - Fixing bugs in `LiquidSystem`.\n - [thijstriemstra](https://github.com/thijstriemstra) and [DarioMaechler](https://github.com/DarioMaechler) - Configurable focus indicator \"ghosting\".\n - [per1234](https://github.com/per1234) - Fixing configuration files problems.\n\n\n# License\nThe MIT License (MIT)\n\nCopyright (c) 2016 Vasil Kalchev\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n\n\u003c!-- [logo-img]: https://github.com/VaSe7u/LiquidMenu/blob/65ef1aa297d14bff1a26df25bd7a97d059a8a0a8/doc/img/logo/logo.png --\u003e\n[logo-img]: https://raw.githubusercontent.com/VaSe7u/LiquidMenu/master/doc/img/logo/logo.png\n[LiquidCrystal-lib]: https://github.com/arduino-libraries/LiquidCrystal\n[doxygen-doc]: https://vase7u.github.io/LiquidMenu/annotated.html\n[examples-dir]: /examples\n[disc]: https://github.com/VaSe7u/LiquidMenu/discussions\n[q\u0026a-disc]: https://github.com/VaSe7u/LiquidMenu/discussions/categories/q-a\n[ideas-disc]: https://github.com/VaSe7u/LiquidMenu/discussions/categories/ideas\n[show\u0026tell-disc]: https://github.com/VaSe7u/LiquidMenu/discussions/categories/show-tell\n[issues]: https://github.com/VaSe7u/LiquidMenu/issues/new/choose\n[latest_release]: https://github.com/VaSe7u/LiquidMenu/releases/latest\n[code_of_conduct-doc]: /.github/CODE_OF_CONDUCT.md\n[contributing-doc]: /.github/CONTRIBUTING.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVasilKalchev%2FLiquidMenu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVasilKalchev%2FLiquidMenu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVasilKalchev%2FLiquidMenu/lists"}