Deprecated graphics configurations for renderers

In TcMenu 2.0 we are making some changes to the way that renderers work, this makes the library viable going forward, and provides huge render quality improvements for nearly everyone. However, we’ve had a to deprecate the ColorGfxMenuConfig method of specifying configuration, and we may remove it in a future version completely.

Further we made a few other changes, the easiest way to pick up these changes is to let the designer do code generation on your project, it will put the most recent plugin files in places automatically. However, if you cannot do that, and you don’t want to copy in the latest plugin code yourself, then these are the most important changes:

• Most graphical components are moved to namespace tcgfx and GfxMenuConfig.h moved into the graphics directory.
• On BaseDialog, the header used to be held as a pointer to an item in program memory, it is now a character array held within the object.

DEPRECATED Graphics configuration documentation

Do not use in new projects

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);

Configuring a display with U8g2GfxMenuConfig

When using this driver, the font, spacing and colors are controlled by a graphics configuration. There are a lot of available options to customise how you display the menu. The default assumption is a medium resolution screen of (128x64).

For this driver the graphical configuration is of type:

U8g2GfxMenuConfig myConfig;

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.

Display configuration for bitmapped displays (AdaGfx and U8G2)

We can set the font, color, and spacing around items on a bitmap display by adjusting the configuration. All bitmapped displays based on Adafruit_GFX and U8G2 require a graphics configuration. The menu designer will attempt to add sensible defaults for you, but in many cases, you’ll need to tweak these settings to get the best results.

For Adafruit_GFX based displays the configuration type is AdaColorGfxMenuConfig and fonts are of type GFXfont*. There are many fonts provided with the library, and you can use any of those or create one. You can also set the text magnification.

For U8G2 based displays the configuration type is U8g2GfxMenuConfig and fonts are of type const uint8_t*. Again there are many provided fonts with the library that you can use. There is no text magnification with u8g2 so it should always be 1.

For Adafruit graphics colours are defined as 16 bit, and we have an RGB(r, g, b) macro that can be used. Where values are between 0 and 255. BLACK and WHITE are always defined.

Padding structures can be easily defined using this function:

makePadding(MenuPadding& padding, int top, int right, int bottom, int left)

These are the fields that are available in the configuration structure.:

template<typename FONTPTR> struct ColorGfxMenuConfig {
    uint32_t bgTitleColor;
    uint32_t fgTitleColor;
    MenuPadding titlePadding;
    FONTPTR titleFont;

    uint32_t bgItemColor;
    uint32_t fgItemColor;
    MenuPadding itemPadding;
    FONTPTR itemFont;

    uint32_t bgSelectColor;
    uint32_t fgSelectColor;
    uint32_t widgetColor;
    MenuPadding widgetPadding;

    const uint8_t* activeIcon;
    const uint8_t* editIcon;
    uint8_t editIconWidth;
    uint8_t editIconHeight;
        
    uint8_t titleBottomMargin;
    uint8_t titleFontMagnification;
    uint8_t itemFontMagnification;
}

To override the graphics configuration there are two options, you can either completely define your own structure, or you can adjust a few values on the existing one that the designer provides:

Create your own graphics config from scratch

• In your sketch create a variable of the appropriate type for your display.
• Ensure the setup of the config is BEFORE calling setupMenu() during initialisation.
• Fully populate the fields - this is imperative as it’s a struct type.
• The fonts can be NULL as can the activeIcon and editIcon. This implies the default values.
• In the designer’s code generator window, put the name of the config variable into the CONFIG property.
• See the examples for more on how to override configuration.

Modify designer provided graphics config

In this case, leave the graphics config variable blank in the code generator dialog, this means that the config will be provided by the designer. For all Adafruit and U8g2 options the designer will create a config variable called gfxConfig.

Final notes

If you want to continue to use the method of configuration, we recommend that you create your own structure and provide in the renderer, it will be good through at least the 2.0 releases.