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 renders an interactive list of configurable settings. It supports four setting types — boolean toggles, numeric ranges, option selectors, and links to sub-screens — each with its own visual control. Values are persisted automatically to EEPROM (ESP8266) or Preferences (ESP32) and restored on the next boot.
Each SettingsScreen supports a maximum of MAX_ITEMS = 10 settings. Attempting to add more than 10 settings to a single screen will exceed this limit. Split large setting sets across multiple SettingsScreen instances linked via addSubscreenSetting().

​
Constructors

​
SettingsScreen()

Creates a settings screen without a title. 
SettingsScreen settingsScreen;

​
SettingsScreen(const char* title)

Creates a settings screen with the given title shown in the header.
​
title
const char*
required
Title string displayed at the top of the screen.
SettingsScreen settingsScreen("Settings");

​
Adding settings

​
addBooleanSetting(const char* name, bool defaultValue)

Adds an on/off toggle setting rendered as an animated switch.
​
name
const char*
required
Display name of the setting. Also used as the key for getSettingValue(const char*).
​
defaultValue
bool
required
Initial value used when no persisted value exists.
settingsScreen.addBooleanSetting("WiFi", true);
settingsScreen.addBooleanSetting("Animations", true);

​
addRangeSetting(const char* name, uint8_t min, uint8_t max, uint8_t defaultValue, const char* unit)

Adds a numeric range setting rendered as a scrollable value with optional unit label.
​
name
const char*
required
Display name of the setting.
​
min
uint8_t
required
Minimum allowed value (inclusive).
​
max
uint8_t
required
Maximum allowed value (inclusive).
​
defaultValue
uint8_t
required
Initial value used when no persisted value exists.
​
unit
const char*
default:"nullptr"
Optional unit string displayed after the value (e.g. "%", "°C", "dB").
settingsScreen.addRangeSetting("Brightness", 0, 100, 75, "%");
settingsScreen.addRangeSetting("Volume", 0, 10, 5, nullptr);
settingsScreen.addRangeSetting("Speaker Power", 1, 30, 5, "dB");

​
addOptionSetting(const char* name, const char** options, uint8_t count, uint8_t defaultIndex)

Adds a setting that cycles through a fixed list of string options.
​
name
const char*
required
Display name of the setting.
​
options
const char**
required
Pointer to an array of option label strings.
​
count
uint8_t
required
Number of entries in the options array.
​
defaultIndex
uint8_t
required
Zero-based index of the initially selected option.
const char* themes[] = {"Dark", "Light", "Auto"};
settingsScreen.addOptionSetting("Theme", themes, 3, 0);

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

​
addSubscreenSetting(const char* name, Screen* targetScreen)

Adds a navigation entry that pushes a different screen when selected. Use this to link to a secondary SettingsScreen when you need more than MAX_ITEMS settings.
​
name
const char*
required
Label displayed in the settings list.
​
targetScreen
Screen*
required
Screen to navigate to when the item is selected.
SettingsScreen speakerSettings("Advanced Settings");
speakerSettings.addRangeSetting("Speaker Power", 1, 30, 5, "dB");
speakerSettings.addBooleanSetting("Sound", false);

settingsScreen.addSubscreenSetting("Speaker", &speakerSettings);

​
Reading values

​
getSettingValue(int index)

Returns the current value of a setting by its zero-based position in the list.
  • For BOOLEAN: returns 1 (true) or 0 (false).
  • For RANGE: returns the current numeric value.
  • For OPTION: returns the current selected index.
Returns: uint8_t
​
index
int
required
Zero-based index of the setting.
uint8_t brightness = settingsScreen.getSettingValue(1); // Index 1
bool wifiOn = settingsScreen.getSettingValue(0);        // Index 0

​
getSettingValue(const char* name)

Returns the current value of a setting looked up by its name string. Returns: uint8_t
​
name
const char*
required
Name string matching the one passed to add*Setting().
uint8_t brightness = settingsScreen.getSettingValue("Brightness");
bool wifiOn        = settingsScreen.getSettingValue("WiFi");

// Apply in loop
menu.setAnimation(settingsScreen.getSettingValue("Animations"));
menu.setOptimizeDisplayUpdates(settingsScreen.getSettingValue("Optimize Display Updates"));

​
getSettingName(int index)

Returns the display name of the setting at the given index. Returns: String
​
index
int
required
Zero-based index of the setting.
String name = settingsScreen.getSettingName(0); // e.g. "WiFi"

​
getSettingType(uint8_t index)

Returns the type enum of the setting at the given index. Returns: Setting::Type — one of Setting::BOOLEAN, Setting::RANGE, Setting::OPTION, or Setting::SUBSCREEN.
​
index
uint8_t
required
Zero-based index of the setting.
Setting::Type t = settingsScreen.getSettingType(0);
if (t == Setting::BOOLEAN) {
  // handle boolean
}

​
Modification

​
modify(int8_t direction, int index)

Programmatically increments or decrements a setting value by index. Use +1 to move forward and -1 to move backward.
​
direction
int8_t
required
1 to increment / toggle on; -1 to decrement / toggle off.
​
index
int
required
Zero-based index of the setting to modify.
settingsScreen.modify(1, 0);  // Increment setting at index 0
settingsScreen.modify(-1, 2); // Decrement setting at index 2

​
modify(int8_t direction, const char* name)

Programmatically changes a setting value by name.
​
direction
int8_t
required
1 to increment / toggle on; -1 to decrement / toggle off.
​
name
const char*
required
Name string of the setting to modify.
settingsScreen.modify(1, "Brightness");
settingsScreen.modify(-1, "Volume");

​
Storage

​
resetSettings()

Clears all persisted values and restores every setting to its defaultValue. A restart is required for the reset to take full effect in the UI. 
settingsScreen.resetSettings();
EEPROM/Preferences storage is fully automatic. You do not need to call any save or load function — values are persisted whenever a setting is changed and restored on the next begin(). saveToEEPROM() and readFromEEPROM() are private implementation details.

​
Constants

ConstantValueDescription
MAX_ITEMS10Maximum number of settings per SettingsScreen instance.

​
Complete example

#include "OpenMenuOS.h"

OpenMenuOS menu(19, 18, 2);

SettingsScreen settingsScreen("Settings");
SettingsScreen speakerSettings("Speaker");

void setup() {
  // Boolean toggle
  settingsScreen.addBooleanSetting("WiFi", true);
  settingsScreen.addBooleanSetting("Animations", true);

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

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

  // Sub-screen link (goes to speakerSettings)
  speakerSettings.addRangeSetting("Speaker Power", 1, 30, 5, "dB");
  speakerSettings.addBooleanSetting("Sound", false);
  settingsScreen.addSubscreenSetting("Speaker", &speakerSettings);

  menu.begin(&settingsScreen);
}

void loop() {
  menu.loop();

  // Read settings values and apply them
  bool animations = settingsScreen.getSettingValue("Animations");
  menu.setAnimation(animations);

  uint8_t brightness = settingsScreen.getSettingValue("Brightness");
  analogWrite(TFT_BL, map(brightness, 0, 100, 0, 255));
}

Build docs developers (and LLMs) love

Get started for freeTalk to us