repository·master·Indexed 42 days ago
https://github.com/forntoh/lcdmenuAn open-source Arduino library for creating menu systems on character LCDs and graphical/OLED displays. It features a flexible architecture using display interfaces, renderers, and input adapters for hardware such as rotary encoders, joysticks, and buttons (including AnalogButtonAdapter and ButtonAdapter).
lcdmenu is an open-source Arduino library used to create menu systems. It provides a simple API for menu creation and user input handling. The library is designed to be flexible, supporting various display types through built-in display interfaces:
|project| provides built-in renderers designed to draw menu items on various output devices. You can use these to customize the appearance of menu items, including font size, color, and layout.
The library includes the following built-in renderers:
character-displaygraphical-displayThe MenuScreen class is the core component of the menu system. It represents a single screen within a menu hierarchy and is responsible for:
MenuItem objects.BACK and RIGHT commands.MenuScreen is designed to work in conjunction with LcdMenu (for input/lifecycle) and MenuRenderer (for display output).
The ItemRange class is a wrapper around ItemWidget designed to simplify the creation of menu items that allow users to select a value within a specific range (e.g., volume, brightness, or temperature). It reduces boilerplate when an item only requires a single WidgetRange.
There are two primary ways to implement this:
ITEM_RANGE<T>(...): Creates a standalone item with a range of values.ITEM_RANGE_REF<T>(...): Creates an item that uses a reference to track and update the currently selected value, allowing the value to be updated or accessed externally.Best Practices:
int or float for performance-critical applications.ITEM_RANGE_REF, remember that external changes to the referenced variable will automatically be reflected in the menu display.// Simple range usage
ITEM_RANGE<int>("Volume", 50, 5, 0, 100, [](const int value) {
Serial.println(value);
}, "%d%%")
// Range with reference usage
int selectedTemperature = 20;
ITEM_RANGE_REF<int>("Temperature", selectedTemperature, 1, 0, 40, [](const Ref<int> value) {
Serial.println(value.value);
}, "%d°C")lcdmenu. Each menu item is an interactive element that can contain zero or more widgets. You can use built-in menu items to construct your menu structure or create custom items by extending the base menu item class or existing items.Widgets are interactive components that are added to menu items to provide user input and display capabilities. They allow menu items to support features such as boolean toggles, list selections, and range inputs while ensuring a consistent interface across the menu system.
Common widget types include:
To keep the base API lightweight for simple character displays while supporting advanced features, |project| uses an extension model.
Advanced renderers can expose specialized features (such as explicit frame lifecycle hooks) by implementing MenuRenderer::queryExtension().
Similarly, menu items can expose optional capabilities using MenuItem::queryCapability(). This allows renderers to query whether a specific item or the renderer itself supports a particular advanced functionality.
The WidgetList widget allows users to select an item from a list of options (up to 255 items). The list can contain any data type that can be converted to a string (e.g., const char*, uint8_t).
std::vector of the items to choose from.0)."%s").0).true, selection cycles back to the start when reaching the end of the list (default: false).WidgetItem, you may prefer to handle selection in the WidgetItem callback instead.std::vector<const char*> listItems = { "Item 1", "Item 2", "Item 3", "Item 4" };
WIDGET_LIST(listItems, 0, "%s", 0, false, [](const char* item) {
// Callback function to handle item selection
})The menu system does not interact with physical hardware directly. Instead, it relies on input adapters to translate physical user input (like a button press or a rotary encoder turn) into the control commands (UP, DOWN, etc.) understood by LcdMenu::process.
To make your menu interactive, you must use or implement an input adapter. The system provides several built-in adapters out of the box:
keyboardbuttonrotary-encoderanalogButtonjoystickThe renderer uses GraphicalMenuItem to provide enhanced visual states for items without requiring RTTI. The following capabilities are supported:
ITEM_BOOL and ITEM_TOGGLE render graphical checkbox or toggle boxes.ITEM_LIST and ITEM_RANGE render list indicators. Submenu items render a submenu indicator.ITEM_VALUE provides width information to allow for right-aligned value layouts.Advanced features like specific indicator styles or value selection highlighting can be accessed via queryExtension() using GraphicalIndicatorRenderer or GraphicalValueSelectionRenderer.
When creating a ButtonAdapter, you can enable auto-repeat functionality for commands (useful for scrolling through menus).
By providing two additional integer parameters (in milliseconds) after the command, you define how the button behaves when held:
Example: ButtonAdapter(&menu, &button, UP, 500, 200) will wait 500ms after the initial press, then send the UP command every 200ms until released.