Migration

This guide details the changes and how to change your code between versions of the LcdMenu library.

Migration from v5.0.0 to v5.1.x

This guide details the changes and how to change your code to migrate to LcdMenu v5.1.x

LcdMenu initialization changes

In v5.0.0, the menu was initialized with the display adapter interface. In this version, the menu is initialized with a renderer.

Imports

The first change you’ll need to make is to add the import for the renderer. Currently, the only renderer available is the CharacterDisplayRenderer.

#include <renderer/CharacterDisplayRenderer.h>

Construct the renderer interface

The renderer instance is created and passed to the menu.

 LiquidCrystal_I2C lcd(0x27, LCD_COLS, LCD_ROWS);
 LiquidCrystal_I2CAdapter lcdAdapter(&lcd);
 CharacterDisplayRenderer renderer(&lcdAdapter, LCD_COLS, LCD_ROWS);
 LcdMenu menu(renderer);

Setup changes

The setup function remains the same, but the menu is now initialized with the renderer.

 void setup() {
     lcdAdapter.begin();
     renderer.begin();
 }

This change allows for more flexibility in the display interface and the ability to create custom renderers.

Migration from v4.x.x to v5.0.0

This guide details the changes and how to change your code to migrate to LcdMenu v5.0.0

This is a major release with a lot of changes.

Display interface changes

In v4.x, the display instance was created and initialised in the display adapter. In this version, the display instance is created separately and passed to the display adapter. The existing display adapters have been renamed and placed in a new directory to closely match the display they are designed for.

Imports

The first change you’ll need to make is to add the import for your desired display interface.

Liquid Crystal I2C

#include <interface/LiquidCrystalI2CAdapter.h>
#include <LiquidCrystal_I2C.h>
#include <display/LiquidCrystal_I2CAdapter.h>

Liquid Crystal

#include <interface/LiquidCrystalAdapter.h>
#include <LiquidCrystal.h>
#include <display/LiquidCrystalAdapter.h>

Construct the display adapter interface

The display instance is created and passed to the display adapter.

Liquid Crystal I2C

LiquidCrystalI2CAdapter lcdAdapter(0x27, LCD_COLS, LCD_ROWS);
LiquidCrystal_I2C lcd(0x27, 16, 2);
LiquidCrystal_I2CAdapter lcdAdapter(lcd);

Liquid Crystal

LiquidCrystalAdapter lcdAdapter(12, 11, 5, 4, 3, 2);
LiquidCrystal lcd(12, 11, 5, 4, 3, 2);
LiquidCrystalAdapter lcdAdapter(lcd);

Initialise the menu

The next change is to create and initialise the menu with the display adapter interface.

LcdMenu menu(lcdAdapter);

Finally, begin the display instance in the setup function.

Liquid Crystal I2C

void setup() {
   lcd.begin();
}

Liquid Crystal

void setup() {
   lcd.begin();
}

Menu creation changes

In previous versions, menus were created using the MAIN_MENU and SUB_MENU macros. In this version, menus are created using the MENU_SCREEN macro.

MAIN_MENU(
MENU_SCREEN(mainScreen, mainItems,
   ITEM("Start service"),
   ITEM("Connect to WiFi"),
   SUBMENU("Settings", settingsScreen),
   ITEM("Blink SOS"),
   ITEM("Blink random"));

// Settings menu
SUB_MENU(settingsMenu,
MENU_SCREEN(settingsScreen, settingsItems,
   ITEM("Change password"),
   ITEM("Change username"),
   ITEM("Change email"));

Initialisation of the menu

menu.initialize(mainMenu);
menu.setScreen(mainScreen);

Menu control changes

Instead of having multiple control functions, the menu control functions have been consolidated into a single control function: LcdMenu::process()

Checkout this guide for a detailed explanation of the new menu control system.

Migration from v3.x to v4.x

This guide details the changes and how to change your code to migrate to LcdMenu v4.x.

New imports

The biggest change from this version is the separation of the menu drawing logic from the menu control logic.

The first change you’ll need to make is to add the import for your desired display interface, seen all the available interfaces here

#include <interface/LiquidCrystalI2CAdapter.h>

Construct the display adapter interface

The second change is to construct the display adapter interface. For example, if you are using the LiquidCrystalI2CAdapter, you will need to construct it like this:

LiquidCrystalI2CAdapter lcd(0x27, 16, 2);

Finally, initialise the menu

The final change is to initialise the menu with the display adapter interface. For example, if you are using the LiquidCrystalI2CAdapter, you will need to initialise the menu like this:

menu.initialize(mainMenu);

That’s it! You should now be able to run your code with LcdMenu v4.x.

Other changes

Cursor icon, edit cursor icon and display timeout are now updated by defining the following constants:

#define CURSOR_ICON 0x00
#define EDIT_CURSOR_ICON 0x00
#define DISPLAY_TIMEOUT 10000 // 10 seconds

Note

The lcd instance now resides in the adapter so if you need to perform custom printing or any other function of LiquidCrystal like turning on/off backlight, you now need to reference it from the lcdAdapter not the menu.