OpenMenuOS class reference

OpenMenuOS is the central controller for the entire menu system. You instantiate it once with your button pins, call begin() in setup(), and call loop() in Arduino’s main loop. Everything else — display rendering, input routing, animations, and screen transitions — is handled internally.

Constructor

OpenMenuOS(int btn_up = -1, int btn_down = -1, int btn_sel = -1)

Creates a new menu system instance. All pin parameters default to -1 (disabled), so you can create an instance without arguments and configure pins separately via setUpPin(), setDownPin(), and setSelectPin().

btn_up

int

default:"-1"

GPIO pin for the UP button. Pass -1 to disable.

btn_down

int

default:"-1"

GPIO pin for the DOWN button. Pass -1 to disable.

btn_sel

int

default:"-1"

GPIO pin for the SELECT button. Pass -1 to disable.

// With explicit pin assignments
OpenMenuOS menu(19, 18, 2);

// Without pins — configure later
OpenMenuOS menu;

Core methods

`begin(Screen* mainMenu)`

Initializes the TFT display and enters the main menu screen using the default display rotation.

Pointer to the root screen shown on startup.

MenuScreen mainMenu("Main Menu");

void setup() {
  menu.begin(&mainMenu);
}

`begin(int rotation, Screen* mainMenu)`

Initializes the display with an explicit rotation value before entering the main menu.

rotation

int

required

Display rotation: 0, 1, 2, or 3.

Pointer to the root screen shown on startup.

menu.begin(1, &mainMenu);

`loop()`

Processes input and redraws the current screen. Call this every iteration of Arduino’s loop().

void loop() {
  menu.loop();
}

When using PopupManager, call PopupManager::update() before menu.loop() so popup input is consumed before it reaches the underlying screen.

`redirectToScreen(Screen* screen)`

Navigates programmatically to any screen, pushing the current screen onto the back-navigation stack.

screen

Screen*

required

Pointer to the target screen.

void openSettings() {
  menu.redirectToScreen(&settingsScreen);
}

`navigateBack()`

Returns to the previous screen in the navigation history stack. Has no effect if you are already at the root.

void goBack() {
  menu.navigateBack();
}

`getLibraryVersion()`

Returns the version string of the library. Returns: const char* — e.g. "3.1.0"

Serial.println(menu.getLibraryVersion()); // "3.1.0"

Display configuration

`setDisplayRotation(int rotation)`

Sets the TFT display rotation at runtime.

rotation

int

required

Rotation value 0–3.

menu.setDisplayRotation(1); // Landscape

`setOptimizeDisplayUpdates(bool enabled)`

Enables frame comparison before pushing canvas data to the display. When enabled, the library skips the physical display write if the rendered frame is identical to the last one, reducing flicker and CPU overhead.

enabled

bool

default:"true"

Pass true to enable optimized updates.

menu.setOptimizeDisplayUpdates(true);

`getOptimizeDisplayUpdates()`

Returns the current state of display update optimization. Returns: bool

bool optimized = menu.getOptimizeDisplayUpdates();

`drawCanvasOnTFT()`

Manually pushes the current canvas sprite to the physical display. You rarely need to call this directly — loop() handles it — but it is useful inside custom drawing code when you need an explicit flush.

menu.drawCanvasOnTFT();

Styling

`useStylePreset(char* preset)`

Applies a named built-in style preset. Available values are "Default" and "Rabbit_R1".

preset

char*

required

Preset name: "Default" or "Rabbit_R1".

menu.useStylePreset("Rabbit_R1");

`useStylePreset(int preset)`

Applies a style preset by its numeric index instead of its name.

preset

int

required

Preset index (e.g. 0 for Default, 1 for Rabbit_R1).

menu.useStylePreset(1);

`setMenuStyle(int style)`

Controls how the selection highlight is rendered.

style

int

required

0 = outlined selection rectangle, 1 = filled selection rectangle.

menu.setMenuStyle(1); // Filled highlight

`setSelectionBorderColor(uint16_t color)`

Sets the border color of the selection rectangle using RGB565 format.

color

uint16_t

required

RGB565 color value (e.g. TFT_WHITE, TFT_CYAN).

menu.setSelectionBorderColor(TFT_CYAN);

`setSelectionFillColor(uint16_t color)`

Sets the fill color of the selection rectangle.

color

uint16_t

required

RGB565 color value.

menu.setSelectionFillColor(TFT_DARKGREY);

`setScrollbar(bool enabled)`

Shows or hides the scrollbar on menu and settings screens.

enabled

bool

required

true to show the scrollbar, false to hide it.

menu.setScrollbar(true);

`setScrollbarStyle(int style)`

Controls the visual appearance of the scrollbar.

style

int

required

0 = Default style, 1 = Modern style.

menu.setScrollbarStyle(1); // Modern

`setScrollbarColor(uint16_t color)`

Sets the color of the scrollbar track and thumb.

color

uint16_t

required

RGB565 color value.

menu.setScrollbarColor(TFT_WHITE);

Font configuration

`setMenuFont(const GFXfont* font)`

Sets the regular (non-selected) text font for menu items. Accepts any Adafruit GFX-compatible font pointer.

font

const GFXfont*

required

Pointer to a GFX font struct.

#include <Fonts/FreeMono9pt7b.h>
menu.setMenuFont(&FreeMono9pt7b);

`setMenuFontBold(const GFXfont* font)`

Sets the bold font used for the currently selected menu item.

font

const GFXfont*

required

Pointer to a GFX font struct.

#include <Fonts/FreeMonoBold9pt7b.h>
menu.setMenuFontBold(&FreeMonoBold9pt7b);

Input configuration

`setButtonsMode(char* mode)`

Configures the active voltage level for all buttons.

mode

char*

required

"High" if buttons read HIGH when pressed; "low" if they read LOW.

menu.setButtonsMode("low"); // Active-low buttons

`setEncoderPin(uint8_t clk, uint8_t dt)`

Enables rotary encoder input and assigns the CLK and DT pins. Enabling an encoder also activates encoder navigation inside PopupManager.

clk

uint8_t

required

GPIO pin connected to the encoder CLK output.

uint8_t

required

GPIO pin connected to the encoder DT output.

menu.setEncoderPin(5, 2); // CLK=5, DT=2

`setUpPin(uint8_t pin)`

Assigns the UP button pin at runtime, overriding the constructor value.

uint8_t

required

GPIO pin number.

menu.setUpPin(19);

`setDownPin(uint8_t pin)`

Assigns the DOWN button pin at runtime.

uint8_t

required

GPIO pin number.

menu.setDownPin(18);

`setSelectPin(uint8_t pin)`

Assigns the SELECT button pin at runtime. Also used as the encoder push-button when an encoder is configured.

uint8_t

required

GPIO pin number.

menu.setSelectPin(19);

Animation and behavior

`setAnimation(bool enabled)`

Enables or disables scroll animations for menu item transitions.

enabled

bool

required

true to enable smooth animations.

menu.setAnimation(true);

`setTextScroll(bool enabled)`

Controls horizontal scrolling for menu item labels that are too long to fit on screen.

enabled

bool

required

true to enable text scrolling.

menu.setTextScroll(false); // Disable for better performance

`setButtonAnimation(bool enabled)`

Enables or disables the visual press animation shown when a button is activated.

enabled

bool

required

true to enable button animations.

menu.setButtonAnimation(true);

Boot configuration

`showBootImage(bool enabled)`

Controls whether a boot image is displayed during initialization.

enabled

bool

required

true to show the boot image on startup.

menu.showBootImage(true);

`setBootImage(uint16_t* image, uint16_t h, uint16_t w)`

Provides a custom boot splash image as a raw RGB565 pixel array.

image

uint16_t*

required

Pointer to the pixel data array in RGB565 format.

uint16_t

required

Height of the image in pixels.

uint16_t

required

Width of the image in pixels.

extern const uint16_t myBootLogo[];
menu.showBootImage(true);
menu.setBootImage((uint16_t*)myBootLogo, 64, 128);

Utility

`getTftHeight()`

Returns the current display height in pixels. Returns: int

int h = menu.getTftHeight();

`getTftWidth()`

Returns the current display width in pixels. Returns: int

int w = menu.getTftWidth();

`UpButton()`

Returns the GPIO pin number assigned to the UP button. Returns: int

int pin = menu.UpButton();

`DownButton()`

Returns the GPIO pin number assigned to the DOWN button. Returns: int

int pin = menu.DownButton();

`SelectButton()`

Returns the GPIO pin number assigned to the SELECT button. Returns: int

int pin = menu.SelectButton();

Main Classes

Popup System

Data Types

Documentation Index

​Constructor

​Core methods

​begin(Screen* mainMenu)

​begin(int rotation, Screen* mainMenu)

​loop()

​redirectToScreen(Screen* screen)

​navigateBack()

​getLibraryVersion()

​Display configuration

​setDisplayRotation(int rotation)

​setOptimizeDisplayUpdates(bool enabled)

​getOptimizeDisplayUpdates()

​drawCanvasOnTFT()

​Styling

​useStylePreset(char* preset)

​useStylePreset(int preset)

​setMenuStyle(int style)

​setSelectionBorderColor(uint16_t color)

​setSelectionFillColor(uint16_t color)

​setScrollbar(bool enabled)

​setScrollbarStyle(int style)

​setScrollbarColor(uint16_t color)

​Font configuration

​setMenuFont(const GFXfont* font)

​setMenuFontBold(const GFXfont* font)

​Input configuration

​setButtonsMode(char* mode)

​setEncoderPin(uint8_t clk, uint8_t dt)

​setUpPin(uint8_t pin)

​setDownPin(uint8_t pin)

​setSelectPin(uint8_t pin)

​Animation and behavior

​setAnimation(bool enabled)

​setTextScroll(bool enabled)

​setButtonAnimation(bool enabled)

​Boot configuration

​showBootImage(bool enabled)

​setBootImage(uint16_t* image, uint16_t h, uint16_t w)

​Utility

​getTftHeight()

​getTftWidth()

​UpButton()

​DownButton()

​SelectButton()

Build docs developers (and LLMs) love

Constructor

Core methods

`begin(Screen* mainMenu)`

`begin(int rotation, Screen* mainMenu)`

`loop()`

`redirectToScreen(Screen* screen)`

`navigateBack()`

`getLibraryVersion()`

Display configuration

`setDisplayRotation(int rotation)`

`setOptimizeDisplayUpdates(bool enabled)`

`getOptimizeDisplayUpdates()`

`drawCanvasOnTFT()`

Styling

`useStylePreset(char* preset)`

`useStylePreset(int preset)`

`setMenuStyle(int style)`

`setSelectionBorderColor(uint16_t color)`

`setSelectionFillColor(uint16_t color)`

`setScrollbar(bool enabled)`

`setScrollbarStyle(int style)`

`setScrollbarColor(uint16_t color)`

Font configuration

`setMenuFont(const GFXfont* font)`

`setMenuFontBold(const GFXfont* font)`

Input configuration

`setButtonsMode(char* mode)`

`setEncoderPin(uint8_t clk, uint8_t dt)`

`setUpPin(uint8_t pin)`

`setDownPin(uint8_t pin)`

`setSelectPin(uint8_t pin)`

Animation and behavior

`setAnimation(bool enabled)`

`setTextScroll(bool enabled)`

`setButtonAnimation(bool enabled)`

Boot configuration

`showBootImage(bool enabled)`

`setBootImage(uint16_t* image, uint16_t h, uint16_t w)`

Utility

`getTftHeight()`

`getTftWidth()`

`UpButton()`

`DownButton()`

`SelectButton()`