Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/The-Young-Maker/OpenMenuOS/llms.txt

Use this file to discover all available pages before exploring further.

SettingsScreen provides a ready-made interface for user-configurable options. Rather than building toggle switches, sliders, and option pickers from scratch, you declare what kind of setting you need, supply its default value, and the library handles rendering, user interaction, and persistent storage. On ESP32 the Preferences library is used; on ESP8266 the standard EEPROM library is used. Both are abstracted away — your code is the same either way.

​
The four setting types

Setting::Type is an enum that determines how a setting is displayed and edited:
TypeRenders asValue stored
BOOLEANAnimated toggle switchbool (returned as uint8_t 0 or 1)
RANGESlider with optional unit labeluint8_t (min–max inclusive)
OPTIONCycling option listuint8_t index into options array
SUBSCREENNavigation link (arrow)— (navigates to another Screen)
Each type has a dedicated add* helper method on SettingsScreen.
SettingsScreen enforces MAX_ITEMS = 10 settings per instance. Use addSubscreenSetting() to chain additional SettingsScreen objects when you need more.

​
Adding settings

​
Boolean setting

A boolean setting renders as an animated toggle switch. The user flips it with the Select button. 
settingsScreen.addBooleanSetting("Animations", true);   // name, default value
settingsScreen.addBooleanSetting("Sound", false);

​
Range setting

A range setting renders as a horizontal slider. The user increments or decrements the value with Up/Down. The optional unit string is displayed alongside the value. 
settingsScreen.addRangeSetting("Brightness", 0, 100, 75, "%");
// name, min, max, default, unit

settingsScreen.addRangeSetting("Volume", 0, 10, 5);
// unit is optional — omit it or pass nullptr

​
Option setting

An option setting cycles through a fixed array of string labels. Pass a const char** array and its length. 
const char *themes[] = {"Dark", "Light", "Auto"};
settingsScreen.addOptionSetting("Theme", themes, 3, 0);
// name, options array, count, default index

const char *styleOptions[] = {"Default", "Modern"};
settingsScreen.addOptionSetting("Style", styleOptions, 2, 1);

​
Subscreen setting

A subscreen setting renders as a labelled row with a right-arrow indicator. Selecting it navigates to the target Screen (typically another SettingsScreen). 
SettingsScreen speakerSettings("Advanced Settings");
speakerSettings.addRangeSetting("Speaker Power", 1, 30, 5, "dB");
speakerSettings.addBooleanSetting("Sound", false);

settingsScreen.addSubscreenSetting("Speaker", &speakerSettings);
// name, pointer to target screen

​
Reading setting values

Two overloads of getSettingValue() let you retrieve the current value of any setting.
Access a setting by its position (zero-based) in the order it was added.
uint8_t brightness = settingsScreen.getSettingValue(2);
// returns the uint8_t value: range value, 0/1 for boolean, option index
Both overloads return uint8_t. For boolean settings 0 = off, 1 = on. For option settings the value is the selected index into the options array. 
// Applying settings in the main loop:
void loop() {
    menu.setAnimation(settingsScreen.getSettingValue("Animations"));
    menu.setOptimizeDisplayUpdates(
        settingsScreen.getSettingValue("Optimize Display Updates")
    );
    menu.loop();
}

​
Automatic EEPROM persistence

Settings are automatically saved whenever the user changes a value. On the next boot, SettingsScreen reads the stored values before the first draw(), so the UI reflects the user’s last choices without any code in setup().
  • ESP32: Uses the Preferences library (key-value namespace)
  • ESP8266: Uses the EEPROM library (byte-addressed storage)
Each setting is identified by a hash of its name and type, so renaming a setting effectively creates a new storage entry and falls back to the default value.
The Preferences namespace is closed automatically when a SettingsScreen is destroyed, preventing resource leaks on ESP32.

​
Resetting to defaults

Call resetSettings() to wipe persisted values and revert all settings to the defaults specified in the add* calls. A restart is required for the reset to take full effect. 
settingsScreen.resetSettings();
// Typically called from an action callback or confirmation popup:

void onFactoryReset() {
    settingsScreen.resetSettings();
    PopupManager::showInfo("Settings reset. Please restart.", "Factory Reset");
}

​
Complete settings setup example

#include "OpenMenuOS.h"

OpenMenuOS menu;
MenuScreen mainMenu("Main Menu");
SettingsScreen settingsScreen("Settings");
SettingsScreen speakerSettings("Speaker Settings");

void setup() {
    // Boolean settings
    settingsScreen.addBooleanSetting("Animations", true);
    settingsScreen.addBooleanSetting("Optimize Display Updates", true);

    // Range setting with unit
    settingsScreen.addRangeSetting("Brightness", 0, 100, 75, "%");

    // Option setting
    const char *themes[] = {"Dark", "Light", "Auto"};
    settingsScreen.addOptionSetting("Theme", themes, 3, 0);

    // Subscreen link — speaker settings live on a separate screen
    speakerSettings.addRangeSetting("Speaker Power", 1, 30, 5, "dB");
    speakerSettings.addBooleanSetting("Sound", false);
    settingsScreen.addSubscreenSetting("Speaker", &speakerSettings);

    mainMenu.addItem("Settings", &settingsScreen);

    menu.begin(&mainMenu);
}

void loop() {
    menu.setAnimation(settingsScreen.getSettingValue("Animations"));
    menu.loop();
}

Build docs developers (and LLMs) love

Get started for freeTalk to us