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.

Related documentation:

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, you can change the display renderer by clicking on the image to the left of the renderer.

Adafruit_GFX rendering option

Image showing Adafruit_GFX renderer choice

There are two possibilities for Adafruit_GFX based displays, the first and easiest is the “quick start” option, it supports a few common displays (ST7735, ST7789, ILI9341 and Nokia 5110), it creates all the variables and initialises the display for you. We’ll refer to this option as quick start.

If you need full control over the display variable, and all the configuration options, then you choose the “Manual Declaration” option, in which case you prepare the variable yourself, and just tell tcMenu the name and type of variable you’ve created. We’ll refer to this as “Manual Configuration”.

Quick Start

If you choose quick start, then the code generator will create the variable, and initialise the display on your behalf. It is obviously far less configurable than manual option, but easier for a few select display. It looks like there are more options than for the manual case, but that is because we will create everything on your behalf.

Property Choices for quick start renderer

Image showing properties for Adafruit_GFX quick start

Variable Name

The graphics variable that the generator will generate on your behalf, it will be exported with this name to use in your own code.

Display Type

We support only a few displays with this quick start method, if your display is not listed, use the manual configuration option instead. Select the appropriate display driver for your hardware. Supported quick start displays:

  • ST7735 - no frame buffer
  • ST7789 - no frame buffer
  • ILI9341 - no frame buffer
  • Nokia 5110 - memory frame buffer

Display configuration property

You can either use the default configuration (leave blank) or provide your own. See the section on display configuration further down.

Display Width & Height property

Set these to the hardware width and height of your display

Reset pin (optional)

You can configure a reset pin if your display requires it. Either set to a pin value or -1 for none.

CS pin (for all SPI cases)

Set this to the chip select (CS) pin for the display. All displays in this category need this.

RS / DC pin (for all SPI cases)

Set this to the pin for Register select or Data/Command. All displays in this category need this.

Data pin and clock pin (software SPI)

Only set these two pins to a value other than -1 if you want to use software SPI. This is much slower than hardware SPI, so do not use on bigger displays.

Display rotation

You can specify the initial rotation of the display as a value from 0 to 3.

Manual Configuration

When you choose the manual configuration option, you need to create the display variable in your sketch, and make sure it is fully initialised before calling setupMenu in your sketch.

Property Choices for manual config renderer

Image showing property choices for Adafruit_GFX manual configuration

Display variable property

In this case 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.

Display variable type property

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 configuration property

You can either use the default configuration (leave blank) or provide your own. See the section on display configuration further down.

Buffered display property

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.

Configuring a display using the AdaColorGfxMenuConfig structure

When using this driver, you may well need to change the drawing settings such as font, spacing and colors to suit your display. For Adafruit_GFX this is the configuration type, if you leave the config field blank, the generator will provide a default with name gfxConfig.

AdaColorGfxMenuConfig gfxConfig;

It is probable that you’ll either want to completely override, or make some small adjustments to the graphics configuration. See the graphical configuration section in this rendering guide.

When you don’t choose a graphics configuration by leaving the property blank, the code generator will use a default one on your behalf, by adding it to your <project>_menu.cpp file:

// for low resolution monochrome displays this is the default
void prepareAdaMonoGfxConfigLoRes(AdaColorGfxMenuConfig* myConfig);
// for OLED displays, this is the default
void prepareAdaMonoGfxConfigOled(AdaColorGfxMenuConfig* myConfig);
// for color displays, this is the default.
void prepareAdaColorDefaultGfxConfig(AdaColorGfxMenuConfig* myConfig);

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 and ST7735

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.