By dave | May 10, 2019

TcMenu - Using Adafruit_GFX to render menus

In this guide we show how to use the Adafruit_GFX library to renderer menu items with tcMenu. This rendering driver for Adafruit_GFX is built into the core menu designer download, meaning it’s available out of the box.

The Adafruit_GFX library supports a lot of different displays, with very different capabilities. Some are monochrome with an in-memory buffer; whereas others are high resolution colour displays that are not buffered in memory. In order to make our renderer as generic as possible it supports both of these capabilities through configuration. It’s worth reading this guide fully so that you understand how we manage the various capabilities.

Before proceeding, you’ll need to make sure you’ve installed both the Adafruit_GFX core library and the library that is compatible with your display. Also, I’d recommend taking a read through the Adafruit_GFX library documentation if you’re not familiar with the library already. We’ll also assume you’ve got a menu structure already prepared in the menu designer UI.

Configuring the rendering for your display

First, ensure your menu structure is saved and then choose Code -> Generate Code from the menu. Once the code generation dialog appears, to the right of the current display type will be a button named “Change”. Click this button and choose the following new driver by clicking select on the right.

Adafruit_GFX rendering option

Image showing Adafruit_GFX renderer choice

Once you’ve chosen this display type, the following properties will be added to the table at the bottom:

Property Choices for this renderer

Image showing property choices for Adafruit_GFX rendering


There are just too many choices and options for us to create the graphics object on your behalf. Instead, you simply create a global variable in your sketch that creates the graphics object. You make sure that the library has been initialised before calling setupMenu() in your sketch. Set this value to the name of the global variable.


There are many types of display supported by this library, therefore you just provide the variable type that you declared. For example Adafruit_SSD1306.

DISPLAY_CONFIG and the AdaColorGfxMenuConfig structure

When using this driver, you may well need to change the settings to suit your display. There are a lot of available options to customise how you display the menu. If you don’t specify this value, the default settings assume a colour, high resolution screen.

If you need to override, in your sketch create a global variable to hold the configuration and set this property to that variable name (eg: myConfig in this case):

AdaColorGfxMenuConfig myConfig;

Like we have defaults for color screens, there’s also a function that will prepare the structure for Nokia 5110, call before setupMenu() in setup().

void prepareAdaMonoGfxConfigLoRes(AdaColorGfxMenuConfig* myConfig);

Otherwise, prepare the structure yourself before calling setupMenu() in setup, the recommended way is to create a function that initialises all the fields. You can set the fonts, edit and active icons to NULL, these will then default, all other parameters must be provided:

void prepareDisplayConfig() {
    // first we set the padding around the title, each item and any widgets.
    makePadding(myConfig.titlePadding, top, right, bottom, left);
    makePadding(myConfig.itemPadding, top, right, bottom, left);
    makePadding(myConfig.widgetPadding, top, right, bottom, left);

    // we set the forground and background of any item
    // WHITE and BLACK are always defined.
    myConfig.bgTitleColor = WHITE;
    myConfig.fgTitleColor = BLACK;
    // we can override the title font, NULL for default.
    myConfig.titleFont = NULL;
    // we add some space after the title.
    myConfig.titleBottomMargin = 1;
    // we set the colour for the widgets
    // colours can be defined using RGB, always use 8 bit values 0..255.
    myConfig.widgetColor = RGB(255, 100, 0);
    // we set the title font size.
    myConfig.titleFontMagnification = 1;

    // We need to set the item colours, both normal and when selected
    myConfig.bgItemColor = RGB(255, 0, 0);
    myConfig.fgItemColor = RGB(200, 200, 200);
    myConfig.bgSelectColor = BLACK;
    myConfig.fgSelectColor = WHITE;
    // we can change the item font - NULL is default
    myConfig.itemFont = NULL;
    // we can set the item font size
    myConfig.itemFontMagnification = 1;
    // the LoRes icons for editing and selecting can be changed from the high res ones.
    // if you leave both icons as NULL, the default will be used, you can redefine your
    // own, see bitmap docs on adafruit site.
    myConfig.editIcon = loResEditingIcon;
    myConfig.activeIcon = loResActiveIcon;
    myConfig.editIconHeight = 6;
    myConfig.editIconWidth = 8;
    // The hi-res icons for editing and selecting that are built in, you can redefine your
    // own, see bitmap docs on adafruit site. 
    myConfig.editIcon = defEditingIcon;
    myConfig.activeIcon = defActiveIcon;
    myConfig.editIconWidth = 16;
    myConfig.editIconHeight = 12;


Indicates if this display uses memory buffering. Often, mono displays are memory buffered. For example Nokia 5110 and SSD1306 are memory buffered. When displays are memory buffered, the library will then call display() after each rendering change.

Pre-tested displays with Adafruit_GFX

Each of the display drivers shown below is fully tested with every release of tcMenu. Many other displays will probably work with this renderer, but we’ve not got one to hand to test.

Using the menu library with Nokia 5110

The library for this display is both memory buffered and monochrome. There is a complete example menu packaged with the core tcMenu library. This example was tested on MEGA / AVR with a UipEthernet remote. However, the concepts are generally applicable. Link below takes you to the source on github.


Using the menu library with OLED SSD1306

The library for this display is both memory buffered and monochrome. Again there is a complete example menu packaged with tcMenu. This example was tested on both ESP32 and ESP8266, but the concepts are generally applicable to any processor. Link below takes you to the source on github.


Using the menu library with color TFT’s - ILI9431

The library for this display is an unbuffered color driver. Again there is an example menu packaged with tcMenu. Using the SPI driver for this display is quite slow, there are noticeable refresh gaps. The example was compiled and tested with SAMD, but is generally applicable to any processor. The link below is to the github page showing the example.


Back to tcMenu main page

Other pages within this category

comments powered by Disqus

We use cookies to analyse traffic and to personalise content. We also embed Twitter, Youtube and Disqus content on some pages, these companies have their own privacy policies.

Please see our privacy policy should you need more information or wish to adjust your settings.

Send a message

This message will be securely transmitted to Nutricherry LTD servers.