MainMenu

Overview

The MainMenu widget is a scroll-wheel menu container. It combines a ScrollWheelWithSelectionStyle (center item visually distinct from surrounding items) with a built-in ScrollIndicator. The screen provides item data through callbacks — MainMenu handles all wheel rendering, animation, and indicator synchronization.

This package replaces the older Menu, MenuItemNotSelected, and MenuItemSelected widgets and adds support for richer item styles, layout customization, and animation callbacks.

Bundled Files

The package includes several interdependent classes:

File	Role
MainMenu	Top-level container (Designer custom container)
MainMenuItem	Surrounding (non-selected) wheel item
MainMenuCenterItem	Center (selected) wheel item
MenuItemConfig	Data struct describing a single item
MenuItemRenderer	Stateless rendering helpers (header-only)
ScrollIndicator	Arc position indicator (managed internally)
Toggle	Toggle switch used by TOGGLE style

Components (Designer)

Name	Type	Size
wheel	ScrollWheelWithSelectionStyle	240×132 px
scrollIndicator	ScrollIndicator instance	36×146 px

Item Styles

Each item is configured via MenuItemConfig::Style:

Style	Center item	Surrounding item	Description
SIMPLE	✓	✓	Centered label text only
TOGGLE	✓	— (degrades to SIMPLE)	Label + interactive Toggle switch
TIP	✓	✓	Label + smaller hint text below
INLINE	✓	✓	Label + hint on same line, baseline-aligned
ICON	✓	✓	Static bitmap + label
ICON_EXT	✓	— (falls back to ICON/SIMPLE)	Dynamic raw-pixel bitmap + label

MenuItemConfig

struct MenuItemConfig {
    Style style = SIMPLE;

    // Main text (priority: msgId > msgText > msgChar)
    TypedTextId msgId     = TYPED_TEXT_INVALID;
    TypedTextId msgIdType = TYPED_TEXT_INVALID;  // font/alignment override
    const Unicode::UnicodeChar* msgText = nullptr;
    const char*                 msgChar = nullptr;

    // Hint text — TIP / INLINE styles
    TypedTextId tipId     = TYPED_TEXT_INVALID;
    TypedTextId tipIdType = TYPED_TEXT_INVALID;
    const Unicode::UnicodeChar* tipText  = nullptr;
    const char*                 tipChar  = nullptr;
    colortype   tipColor = Color::getColorFromRGB(192, 192, 192);

    // Icon — ICON / ICON_EXT styles
    BitmapId       iconId  = BITMAP_INVALID;
    const uint8_t* extIcon = nullptr;   // raw ABGR2222 pixels, 60×60 (ICON_EXT)

    // Toggle state — TOGGLE style
    bool toggleState = false;

    // Per-item layout overrides (optional)
    const CenterItemLayout* centerLayout = nullptr;
    const ItemLayout*       itemLayout   = nullptr;
};

Layout Priority

Layout geometry (text positions, icon positions) is resolved in this order:

1. MenuItemConfig::centerLayout / itemLayout — per-item override

2. MainMenu::setCenterItemLayout() / setItemLayout() — menu-wide default

3. Built-in hardcoded defaults

API

Wheel size

void    setNumberOfItems(int16_t count);  // configures wheel + ScrollIndicator
int16_t getNumberOfItems();

Navigation

void     selectNext();                   // animated, fires middle + ended callbacks
void     selectPrev();                   // animated, fires middle + ended callbacks
void     selectItem(int16_t index);      // instant jump, no animation callbacks
uint16_t getSelectedItem();

Item callbacks

// Called for each surrounding item during scroll:
void setUpdateItemCallback(GenericCallback<MainMenuItem&, int16_t>& cb);

// Called for the center item during scroll:
void setUpdateCenterItemCallback(GenericCallback<MainMenuCenterItem&, int16_t>& cb);

Inside each callback, call item.apply(cfg) to render the item.

Animation callbacks

// Fires at the midpoint of selectNext/selectPrev animation (not fired by selectItem):
void setAnimationMiddleCallback(GenericCallback<int16_t>& cb);

// Fires when animation completes:
void setAnimationEndedCallback(GenericCallback<int16_t>& cb);

void setAnimationSteps(int16_t steps);  // default: 4

Layout

void setCenterItemLayout(const CenterItemLayout& layout);
void setItemLayout(const ItemLayout& layout);

Usage in TouchGFX Designer

1. Import the package:

   • Open TouchGFX Designer

   • Go to Edit → Import → Custom Containers

   • Select MainMenu.tpkg

2. Add to screen: drag the MainMenu container onto your screen.

3. No designer properties — all configuration is done in C++.

Usage in C++ Code

#include <gui/containers/MainMenu.hpp>
#include <gui/containers/MenuItemConfig.hpp>

// In the View header:
MainMenu mainMenu;
touchgfx::Callback<MyView, MainMenuItem&, int16_t>       mItemCb;
touchgfx::Callback<MyView, MainMenuCenterItem&, int16_t> mCenterCb;
touchgfx::Callback<MyView, int16_t>                      mAnimMiddleCb;
touchgfx::Callback<MyView, int16_t>                      mAnimEndedCb;

// In setupScreen():
mItemCb.setHandler(*this,       &MyView::onUpdateItem);
mCenterCb.setHandler(*this,     &MyView::onUpdateCenterItem);
mAnimMiddleCb.setHandler(*this, &MyView::onAnimMiddle);
mAnimEndedCb.setHandler(*this,  &MyView::onAnimEnded);

mainMenu.setUpdateItemCallback(mItemCb);
mainMenu.setUpdateCenterItemCallback(mCenterCb);
mainMenu.setAnimationMiddleCallback(mAnimMiddleCb);
mainMenu.setAnimationEndedCallback(mAnimEndedCb);
mainMenu.setNumberOfItems(5);

// Item callback:
void MyView::onUpdateItem(MainMenuItem& item, int16_t index)
{
    MenuItemConfig cfg;
    cfg.style  = MenuItemConfig::TIP;
    cfg.msgId  = myItems[index].titleId;
    cfg.tipChar = myItems[index].subtitle;
    item.apply(cfg);
}

// Center item callback:
void MyView::onUpdateCenterItem(MainMenuCenterItem& item, int16_t index)
{
    MenuItemConfig cfg;
    cfg.style       = MenuItemConfig::TOGGLE;
    cfg.msgId       = myItems[index].titleId;
    cfg.toggleState = mySettings[index];
    item.apply(cfg);
}

// Navigate:
mainMenu.selectNext();
mainMenu.selectPrev();
mainMenu.selectItem(2);  // instant, no animation
uint16_t current = mainMenu.getSelectedItem();

Files Included

• manifest.xml — package manifest (requires TouchGFX ≥ 4.26.1)

• content/CustomContainerExport.touchgfx — Designer container definition

• content/CustomContainerManifest.xml — container manifest

• content/texts.xml — text database

• files/gui/include/gui/containers/MainMenu.hpp — top-level container header

• files/gui/src/containers/MainMenu.cpp

• files/gui/include/gui/containers/MainMenuItem.hpp

• files/gui/src/containers/MainMenuItem.cpp

• files/gui/include/gui/containers/MainMenuCenterItem.hpp

• files/gui/src/containers/MainMenuCenterItem.cpp

• files/gui/include/gui/containers/MenuItemConfig.hpp — data structs (header-only)

• files/gui/include/gui/containers/MenuItemRenderer.hpp — rendering helpers (header-only)

• files/gui/include/gui/containers/ScrollIndicator.hpp + .cpp — bundled dependency

• files/gui/include/gui/containers/Toggle.hpp + .cpp — bundled dependency

• files/assets/fonts/ — Poppins Regular, Medium, SemiBold, Italic

Dependencies

• TouchGFX Framework (minimum version 4.26.1)

• Poppins font family (bundled in package)

• BitmapDatabase.hpp — for static icon bitmap IDs (ICON style)

• TextKeysAndLanguages.hpp — for typed text IDs