Today I bring you a module that I have created, which will allow you to create menus for your Arduino and compatible ones, such as ESP8266. Currently it is only compatible with two displays: Nokia 5510 (PCD8544) and those that use the ST77XX chip, with the Adafruit libraries. In the future I will try to make it compatible with more displays, but it will likely work with any display that uses an Adafruit library.
This library was born from the intention that it be easy to use, that it works with several screens, and due to several functionalities that I did not see in other libraries.
Features
- It is not blocking, you can show the menu and operate it without stopping the main loop of the program
- It is controlled with three functions (enter, up and down), so it can be controlled with any method: buttons, encoder, serial port, bluetooth …
- Four types of objects: Menu, Function, Toggle and Range (I talk about them below)
- Infinite menu levels (with Menu type objects), limited by microcontroller memory.
- Custom selection icon, being able to also select inverted text
- Custom font size (based on library sizes).
How can I create menus
This library has four main functions: drawMenu, enter, up and down.
drawMenu
This function is used to display the menu. For its operation to be correct, the rest of the application must stop writing on the display, so the recommendation is to put a function that deactivates the rest of the updates and executes this function.
enter
This function acts as an accept button. That is why depending on the item, it will perform one action or another:
- Menu: Draw the submenu
- Function: Call the function associated with the item. If this function returns true, it returns to the top menu
- Toggle: Call the toggle function associated with the item, and update the icon on the right depending on the result of this.
- Range: Displays a small box to select a number within a range. The range must be controlled by the callback function
up
This function selects the previous item in the menu, and in the case of being in a range, calls the callback function with 1 as argument.
down
This function selects the next item in the menu, and if it is in a range, it calls the callback function with -1 as an argument.
Types of objects for creating menus
To create the menus, the library has four types of objects:
- AM_ITEM_TYPE_HEADER
- AM_ITEM_TYPE_MENU
- AM_ITEM_TYPE_COMMAND
- AM_ITEM_TYPE_RANGE
- AM_ITEM_TYPE_TOGGLE
- AM_ITEM_TYPE_EOM
AM_ITEM_TYPE_HEADER
This object is displayed first on the menu and is always there. It does not have functions nor is it selectable, there can only be one per menu (the others are ignored), and it has to be the first.
AM_ITEM_TYPE_MENU
This object allows you to contain menus in it, which allows you to create submenus. Selecting it simply draws the submenu.
AM_ITEM_TYPE_COMMAND
This object has a callback function associated with it, which is called when selected. This function has to return a boolean (true or false), returning to the previous menu if it is true or staying in the current one if it is false.
AM_ITEM_TYPE_RANGE
Displays a box (optional) with a range selector, which allows you to select a number within a specific range. The callback function has to handle the range, and receives one call for each call to the up/down functions. This call contains an int argument, which is 0 when you want to retrieve the current state, 1 when the up function has been called, -1 when the down function has been called, and 2 when enter has been called to close the selector. This callback function has to return the current number because the menu updates the selector.
AM_ITEM_TYPE_TOGGLE
An object of type toggle that displays a status icon on the right side of the menu. This object calls a callback function when it is selected and depending on whether that function returns true or false, the icon on the right will be hollow or full. The callback function is called with a boolean argument, which is true to indicate that there is a state change (the object has been selected), or false when the menu simply needs to retrieve the current state.
AM_ITEM_TYPE_EOM
This object serves the menu to detect that the menu has finished. It is very important to add it and make it the last one, otherwise the menu will not know when to stop displaying objects and therefore the application will crash.
The operation of this function is similar to that of the object of type AM_ITEM_TYPE_COMMAND, with the difference that it always returns to the top menu regardless of what the callback function returns. If this menu does not exist, only the callback function will be called, which can be used to hide the menu for example and reactivate the normal operation of the application.
Download and install the library to create menus
The library can be downloaded from Bitbucket where I will possibly add new features. The installation is like any library, unzip the downloaded zip and copy the content to the folder:
C:\Users\<user>\Documents\Arduino\libraries\ArduMenu
To know how to use it, take a look at the examples folder, where I will have updated examples of how to use the library.
I hope you liked it. Greetings!