#236 theme builder and grid layout fixes, example improvements. More logging.

Author: davetcc

examples/arduino32/stm32DuinoDemo/RawCustomDrawing.h

@@ -20,7 +20,7 @@ class MyCustomDrawing : public CustomDrawing {
     }
 
     void started(BaseMenuRenderer *currentRenderer) override {
-        // called once when the take-over display  is started before calling renderLoop so you can set things up.
+        // called once when the take-over display is started before calling renderLoop so you can set things up.
         switches.getEncoder()->changePrecision(100, 50);
     }
 
@@ -35,7 +35,7 @@ class MyCustomDrawing : public CustomDrawing {
         }
         else if(++ticks % 10 == 1) {
             // Why write your own code using device drawable? The main reason is, that it works exactly the same over
-            // adafruit, u8g2 and TFTeSPI with a moderately complete API.
+            // Adafruit, PicoSDK, FrameBuffer, u8g2 and TFTeSPI with a moderately complete API.
             DeviceDrawable *dd = dev.getDeviceDrawable();
             dd->startDraw();
             const Coord &dims = dd->getDisplayDimensions();

examples/arduino32/stm32DuinoDemo/stm32DuinoDemo.ino

@@ -3,6 +3,10 @@
  * are available. By default it is setup for an OLED screen and a rotary encoder, although it could be moved to use
  * many other different display and input technologies.
  *
+ * It demonstrates the use of the card menu layout, where items are shown one at a time as you scroll through them,
+ * configuring some items to use larger than usual fonts, and other items to render as icons. It also has an ethernet
+ * network remote included too.
+ *
  * Getting started: https://www.thecoderscorner.com/products/arduino-libraries/tc-menu/tcmenu-overview-quick-start/
  */
 
@@ -49,12 +53,15 @@ const uint8_t standardNetMask[] = { 255, 255, 255, 0 };
 // 2. https://tcmenu.github.io/documentation/arduino-libraries/tc-menu/themes/rendering-with-themes-icons-grids/
 
 // here we provide two title widgets, for ethernet connection, and client connection
-TitleWidget widgetConnection(iconsConnection, 2, 16, 12, nullptr);
-TitleWidget widgetEthernet(iconsEthernetConnection, 2, 16, 12, &widgetConnection);
+TitleWidget widgetConnection(iconsConnection, 2, 16, 12);
+TitleWidget widgetEthernet(iconsEthernetConnection, 2, 16, 12);
 
 color_t defaultCardPalette[] = {1, 0, 1, 1};
 
 void overrideDrawingForMainMenu(TcThemeBuilder& themeBuilder) {
+    // now we make the two settings and status menus use icons instead of regular drawing, and the numbered menu items
+    // 33,45,78 to use a larger font so it takes the entire screen.
+
     // we're going to use this a few times so declare once
     const Coord iconSize(APPICONS_WIDTH, APPICONS_HEIGHT);
 
@@ -105,32 +112,44 @@ void overrideDrawingForMainMenu(TcThemeBuilder& themeBuilder) {
 }
 
 void overrideDrawingForCardMenu(TcThemeBuilder& themeBuilder) {
-    // override every single item on the card menu to have larger font and different padding/justification
+    // override  back button on the card menu to be the default 32x32 back icon
+    themeBuilder.menuItemOverride(menuBackStatusCards)
+            .withJustification(tcgfx::GridPosition::JUSTIFY_CENTER_WITH_VALUE)
+            .withPadding(MenuPadding(2))
+            .withPalette(defaultCardPalette)
+            .withImageXbmp(Coord(32, 32), defaultBackIconBitmap)
+            .onRow(0) // <== if you prefer that the back item is not first, you can change its order here
+            .apply();
+
+    // override every single item on the card sub menu to have larger font and different padding/justification
     themeBuilder.submenuPropertiesActionOverride(menuStatusCards)
             .withJustification(tcgfx::GridPosition::JUSTIFY_CENTER_NO_VALUE)
-            .withNativeFont(u8g2_font_inr33_mn, 1)
+            .withNativeFont(u8g2_font_inb16_mf, 1)
             .withPadding(MenuPadding(2))
             .apply();
 }
 
-void setupGridLayoutForCardView() {
+void setupCardLayoutAndWidgets() {
     // create a theme builder to help us configure how to draw.
     TcThemeBuilder themeBuilder(renderer);
 
     // enable card layout providing the left and right icons. This enables for root menu
     themeBuilder.enableCardLayoutWithXbmImages(Coord(11, 22), ArrowHoriz11x22BitmapLeft, ArrowHoriz11x22BitmapRight, true)
         .setMenuAsCard(menuStatusCards, true);
 
-    // see the method above where we override drawing for all items that are in card layout.
+    // these two functions, defined directly above this one configure the icons and special text arrangements for
+    // the items in the card layouts.
     overrideDrawingForMainMenu(themeBuilder);
     overrideDrawingForCardMenu(themeBuilder);
 
-    // now we make the two settings and status menus use icons instead of regular drawing.
+    themeBuilder.addingTitleWidget(widgetEthernet)
+            .addingTitleWidget(widgetConnection);
+
+    // You must always call apply after doing anything with theme builder.
     themeBuilder.apply();
 
     // now we set the title widgets that appear on the top right, for the link status we check the ethernet library
     // status every half second and update the widget to represent that status.
-    renderer.setFirstWidget(&widgetEthernet);
     taskManager.scheduleFixedRate(500, [] {
         widgetEthernet.setCurrentState(Ethernet.linkStatus() == LinkON ? 1 : 0);
     });
@@ -148,17 +167,18 @@ using namespace tcremote;
 
 void setup() {
     // This example logs using IoLogging, see the following guide to enable
-    // https://www.thecoderscorner.com/products/arduino-libraries/io-abstraction/arduino-logging-with-io-logging/
+    // https://tcmenu.github.io/documentation/arduino-libraries//io-abstraction/arduino-logging-with-io-logging/
     IOLOG_START_SERIAL
     serEnableLevel(SER_NETWORK_DEBUG, true);
+    serEnableLevel(SER_TCMENU_DEBUG, true);
 
-    // Start up serial and prepare the correct SPI, your pins may differ
+    // Start up serial and prepare the correct SPI, your pins or method of doing this may differ
     SPI.setMISO(PB4);
     SPI.setMOSI(PB5);
     SPI.setSCLK(PB3);
 
-    //
-    // Here we start up the Stm32Ethernet library for STM32 boards/chips with built-in ethernet
+    // Here we start up the Stm32Ethernet library for STM32 boards/chips with built-in ethernet, again you could
+    // easily change this for your own boards network arrangements
     Ethernet.begin();
     Serial.print("My IP address is ");
     Ethernet.localIP().printTo(Serial);
@@ -167,13 +187,14 @@ void setup() {
     // and then run the menu setup
     setupMenu();
 
-    // now load back values from EEPROM, but only when we can read the confirmatory magic key, see EEPROM loading in the docs
+    // now load back values from EEPROM, but only when we can read the confirmatory magic key, see EEPROM docs:
+    // https://tcmenu.github.io/documentation/arduino-libraries/tc-menu/menu-eeprom-integrations/
     menuMgr.load(0xd00d, [] {
         // this gets called when the menu hasn't been saved before, to initialise the first time.
         menuDecimal.setCurrentValue(4);
     });
 
-    // here we register the custom drawing we created earlier with the renderer
+    // here we register the custom drawing created in `RawCustomDrawing.h`
     myCustomDrawing.registerWithRenderer();
 
     // We can set a callback for when the title item is pressed on the main menu, here we just take over the display
@@ -185,7 +206,7 @@ void setup() {
     menuRuntimesCustomList.setNumberOfRows(10);
 
     // now we set up the layouts to make the card view look right.
-    setupGridLayoutForCardView();
+    setupCardLayoutAndWidgets();
 }
 
 void loop() {

src/BaseRenderers.h

@@ -450,6 +450,7 @@ class BaseMenuRenderer : public MenuRenderer, Executable {
 	 * @param the first widget in a chain of widgets linked by next pointer.
 	 */
 	void setFirstWidget(TitleWidget* widget);
+    TitleWidget* getFirstWidget() { return this->firstWidget; }
 
 	/**
 	 * Called when the menu has been altered, to reset the countdown to

src/MenuItems.cpp

@@ -80,7 +80,7 @@ uint8_t MenuItem::copyNameToBuffer(char* buf, int offset, int size) const {
 
 uint16_t MenuItem::getId() const
 {
-	if (info == nullptr) {
+	if (info == nullptr || menuType == MENUTYPE_BACK_VALUE) {
 		return asRuntimeItem(this)->getRuntimeId();
 	}
 

src/RuntimeMenuItem.h

@@ -15,7 +15,9 @@
 #include "tcUtil.h"
 
 /** For items that dont need to have the same id each time (such as back menu items), we just randomly give them an ID */
-#define RANDOM_ID_START 50000
+#ifndef RANDOM_ID_START
+#define RANDOM_ID_START 30000
+#endif
 
 /** For items that dont need to have the same id each time (such as back menu items), we just randomly give them an ID */
 menuid_t nextRandomId();

src/graphics/BaseGraphicalRenderer.cpp

@@ -323,7 +323,9 @@ void BaseGraphicalRenderer::recalculateDisplayOrder(MenuItem *root, bool safeMod
     if(root->getMenuType() == MENUTYPE_BACK_VALUE) {
         serlogF2(SER_TCMENU_DEBUG, "Handling back item", root->getId());
         auto* myProps = getDisplayPropertiesFactory().configFor(root, ItemDisplayProperties::COMPTYPE_TITLE);
-        itemOrderByRow.add(GridPositionRowCacheEntry(root, GridPosition(GridPosition::DRAW_TITLE_ITEM, myProps->getDefaultJustification(), 0), myProps));
+        auto *confGrid = getDisplayPropertiesFactory().gridPositionForItem(item);
+        auto pos = (confGrid) ? confGrid->getPosition() : GridPosition(GridPosition::DRAW_TITLE_ITEM, myProps->getDefaultJustification(), 0);
+        itemOrderByRow.add(GridPositionRowCacheEntry(root, pos, myProps));
         item = root->getNext();
     }
 

src/graphics/GfxMenuConfig.cpp

@@ -66,14 +66,17 @@ void prepareDefaultGfxConfig(ColorGfxMenuConfig<void*>* config) {
 ItemDisplayProperties *ConfigurableItemDisplayPropertiesFactory::configFor(MenuItem *pItem, ItemDisplayProperties::ComponentType compType) {
     // make sure that we never return null, in the worst case, provide a default row for this.
     if(displayProperties.count()==0) {
+        serlogF(SER_WARNING, "No theme set");
         color_t defaultColors[] = { RGB(255,255,255), RGB(0,0,0), RGB(192, 192, 192), RGB(255, 255, 255)};
         setDrawingPropertiesDefault(ItemDisplayProperties::COMPTYPE_ITEM, defaultColors, MenuPadding(2), nullptr,
                                     1, 2, 12, GridPosition::JUSTIFY_TITLE_LEFT_VALUE_RIGHT, MenuBorder());
     }
 
     ItemDisplayProperties *pConf = nullptr;
     if(pItem != nullptr) {
-        pConf = displayProperties.getByKey(MakePropsKey(pItem->getId(), false, compType));
+        auto key = MakePropsKey(pItem->getId(), false, compType);
+        pConf = displayProperties.getByKey(key);
+        serlogF3(SER_TCMENU_DEBUG, "Find by key: ", key, pConf != nullptr);
         if(pConf) return pConf;
     }
     return configForCurrentSub(compType);
@@ -90,9 +93,13 @@ ItemDisplayProperties *ConfigurableItemDisplayPropertiesFactory::configForCurren
     ItemDisplayProperties *pConf = nullptr;
     auto sub = menuMgr.getCurrentSubMenu();
     uint16_t subId = sub ? sub->getId() : 0;
-    pConf = displayProperties.getByKey(MakePropsKey(subId, true, compType));
+    uint32_t key = MakePropsKey(subId, true, compType);
+
+    pConf = displayProperties.getByKey(key);
+    serlogF3(SER_TCMENU_DEBUG, "Find key sub: ", key, pConf != nullptr);
     if(pConf) return pConf;
 
+    serlogF(SER_TCMENU_DEBUG, "Find use def");
     pConf = displayProperties.getByKey(MakePropsKey(MENUID_NOTSET, false, compType));
     if(pConf) return pConf;
 

src/graphics/GfxMenuConfig.h

@@ -455,7 +455,7 @@ namespace tcgfx {
 #define MENUID_NOTSET 0xffff
 
     inline uint32_t MakePropsKey(uint16_t menuId, bool parentKey, ItemDisplayProperties::ComponentType ty) {
-        return (uint32_t)menuId | (parentKey ? 0x10000UL : 0UL) | ((uint32_t)ty << 18UL);
+        return ((uint32_t)menuId) | (parentKey ? 0x10000UL : 0UL) | ((uint32_t)ty << 18UL);
     }
 
     /**
@@ -587,7 +587,10 @@ namespace tcgfx {
          */
         void setDrawingPropertiesDefault(ItemDisplayProperties::ComponentType drawing, const color_t* palette, MenuPadding pad, const void *font, uint8_t mag,
                                          uint8_t spacing, uint8_t requiredHeight, GridPosition::GridJustification defaultJustification, MenuBorder border) {
-            setDrawingProperties(MakePropsKey(MENUID_NOTSET, false, drawing), palette, pad, font, mag, spacing, requiredHeight, defaultJustification, border);
+
+            auto key = MakePropsKey(MENUID_NOTSET, false, drawing);
+            serlogF2(SER_TCMENU_DEBUG, "Add def prop: ", key);
+            setDrawingProperties(key, palette, pad, font, mag, spacing, requiredHeight, defaultJustification, border);
         }
 
         /**
@@ -605,7 +608,9 @@ namespace tcgfx {
          */
         void setDrawingPropertiesForItem(ItemDisplayProperties::ComponentType drawing, uint16_t id, const color_t* palette, MenuPadding pad, const void *font, uint8_t mag,
                                          uint8_t spacing, uint8_t requiredHeight, GridPosition::GridJustification defaultJustification, MenuBorder border) {
-            setDrawingProperties(MakePropsKey(id, false, drawing), palette, pad, font, mag, spacing, requiredHeight, defaultJustification, border);
+            auto key = MakePropsKey(id, false, drawing);
+            serlogF3(SER_TCMENU_DEBUG, "Add item prop: ", key, id);
+            setDrawingProperties(key, palette, pad, font, mag, spacing, requiredHeight, defaultJustification, border);
         }
 
         /**
@@ -623,7 +628,9 @@ namespace tcgfx {
          */
         void setDrawingPropertiesAllInSub(ItemDisplayProperties::ComponentType drawing, uint16_t id, const color_t* palette, MenuPadding pad, const void *font, uint8_t mag,
                                           uint8_t spacing, uint8_t requiredHeight, GridPosition::GridJustification defaultJustification, MenuBorder border) {
-            setDrawingProperties(MakePropsKey(id, true, drawing), palette, pad, font, mag, spacing, requiredHeight, defaultJustification, border);
+            auto key = MakePropsKey(id, true, drawing);
+            serlogF3(SER_TCMENU_DEBUG, "Add sub prop: ", key, id);
+            setDrawingProperties(key, palette, pad, font, mag, spacing, requiredHeight, defaultJustification, border);
         }
 
         /**

src/graphics/GraphicsDeviceRenderer.cpp

@@ -466,7 +466,7 @@ namespace tcgfx {
                 forceDrawWidgets = true;
             }
             if (titleNeeded && (locRedrawMode == MENUDRAW_COMPLETE_REDRAW || titleEntry->getMenuItem()->isChanged(displayNumber))) {
-                bool active = titleNeeded && activeItem == titleEntry->getMenuItem();
+                bool active = activeItem == titleEntry->getMenuItem();
                 drawMenuItem(titleEntry, Coord(0, 0), cardLayoutPane->getTitleSize(), DrawingFlags(true, active, menuMgr.getCurrentEditor() == titleEntry->getMenuItem()));
                 forceDrawWidgets = true;
             } else {
@@ -478,7 +478,7 @@ namespace tcgfx {
                 int offsetY = (cardLayoutPane->getMenuSize().y - int(entry->getHeight())) / 2;
                 Coord menuStart(cardLayoutPane->getMenuLocation().x, cardLayoutPane->getMenuLocation().y + offsetY);
                 Coord menuSize(cardLayoutPane->getMenuSize().x, int(entry->getHeight()));
-                bool active = titleNeeded && activeItem == entry->getMenuItem();
+                bool active = activeItem == entry->getMenuItem();
                 drawMenuItem(entry, menuStart, menuSize, DrawingFlags(false, active, menuMgr.getCurrentEditor() == entry->getMenuItem()));
             }
             cardLayoutPane->prepareAndPaintButtons(this, activeIndex, itemOrderByRow.count(), titleMode != NO_TITLE);

src/graphics/TcThemeBuilder.cpp

@@ -100,11 +100,22 @@ TcThemeBuilder& TcThemeBuilder::withPalette(const color_t *cols) {
 }
 
 ThemePropertiesBuilder &TcThemeBuilder::menuItemOverride(MenuItem &item) {
-    ItemDisplayProperties::ComponentType ty = (isItemActionable(&item)) ? ItemDisplayProperties::COMPTYPE_ACTION : ItemDisplayProperties::COMPTYPE_ITEM;
+    ItemDisplayProperties::ComponentType ty = ItemDisplayProperties::COMPTYPE_ITEM;
+    if(isItemActionable(&item)) {
+        ty = ItemDisplayProperties::COMPTYPE_ACTION;
+    } else if(item.getMenuType() == MENUTYPE_TITLE_ITEM || item.getMenuType() == MENUTYPE_BACK_VALUE) {
+        ty = ItemDisplayProperties::COMPTYPE_TITLE;
+    }
     propertiesBuilder.initForLevel(this, ty, ThemePropertiesBuilder::THEME_ITEM, &item);
     return propertiesBuilder;
 }
 
+ThemePropertiesBuilder &TcThemeBuilder::menuItemOverride(MenuItem &item, ItemDisplayProperties::ComponentType componentType) {
+    propertiesBuilder.initForLevel(this, componentType, ThemePropertiesBuilder::THEME_ITEM, &item);
+    return propertiesBuilder;
+}
+
+
 TcThemeBuilder& TcThemeBuilder::enableCardLayoutWithXbmImages(Coord iconSize, const uint8_t *leftIcon, const uint8_t *rightIcon, bool isMono) {
     auto left = new DrawableIcon(-1, iconSize, tcgfx::DrawableIcon::ICON_XBITMAP, leftIcon, nullptr);
     auto right = new DrawableIcon(-1, iconSize, tcgfx::DrawableIcon::ICON_XBITMAP, rightIcon, nullptr);
@@ -141,4 +152,19 @@ TcThemeBuilder& TcThemeBuilder::manualDimensions(int x, int y) {
     return *this;
 }
 
+TcThemeBuilder &TcThemeBuilder::addingTitleWidget(TitleWidget &theWidget) {
+    TitleWidget *pWidget = renderer.getFirstWidget();
+    if(pWidget == nullptr) {
+        renderer.setFirstWidget(&theWidget);
+    } else {
+        int loopCount = 0;
+        while(pWidget->getNext() != nullptr && ++loopCount < 10) {
+            pWidget = pWidget->getNext();
+        }
+        pWidget->setNext(&theWidget);
+        renderer.redrawRequirement(MENUDRAW_COMPLETE_REDRAW);
+    }
+    return *this;
+}
+
 

src/graphics/TcThemeBuilder.h

@@ -461,11 +461,23 @@ namespace tcgfx {
 
         /**
          * Get access to theme properties for a specific menu item, with this you can change how an item renders, and
-         * even apply different grid settings.
+         * even apply different grid settings. This guesses the component type in most cases but if you want to force a
+         * particular component type see the override method with the second parameter.
+         * @param item the menu item to override drawing
          * @return a theme properties builder
          */
         ThemePropertiesBuilder &menuItemOverride(MenuItem &item);
 
+        /**
+         * Get access to theme properties for a specific menu item, with this you can change how an item renders, and
+         * even apply different grid settings. This specifically sets the component type for situations where it cannot
+         * be easily guessed.
+         * @param item the menu item to override drawing.
+         * @param componentType one of `COMPTYPE_TITLE`, `COMPTYPE_ITEM`, `COMPTYPE_ACTION`
+         * @return a theme properties builder
+         */
+        ThemePropertiesBuilder &menuItemOverride(MenuItem &item, ItemDisplayProperties::ComponentType componentType);
+
         /**
          * Get access to theme properties for a sub menu, with this you can change how all items in that submenu render
          * This applies to regular items
@@ -551,6 +563,8 @@ namespace tcgfx {
          * @return reference to itself for chaining
          */
         TcThemeBuilder& setMenuAsCard(SubMenuItem& item, bool on);
+        
+        TcThemeBuilder& addingTitleWidget(TitleWidget& theWidget);
 
         /**
          * Call after you've finished configuring your theme, this forces a refresh and ensures it presents properly.

src/stockIcons/directionalIcons.h

@@ -34,4 +34,21 @@ const uint8_t ArrowHoriz11x22BitmapRight[] PROGMEM = {
         0x03,0x00,0x01,0x00
 };
 
+/**
+ * defaultBackIconBitmap - the default back icon that can be used with card layout. It is 32x32 in size.
+ */
+// XBM_LSB_FIRST width=32, height=32, size=128
+// auto size = Coord(32, 32);
+const uint8_t defaultBackIconBitmap[] PROGMEM = {
+        0x00,0x00,0x00,0x00,0x00,0xc0,0x00,0x00,0x00,0xf0,0x00,0x00,0x00,0xf8,0x00,0x00,0x00,0xfc,0x00,0x00,
+        0x00,0xff,0x00,0x00,0x80,0xff,0x00,0x00,0xe0,0xff,0x03,0x00,0xf0,0xff,0x3f,0x00,0xfc,0xff,0xff,0x00,
+        0xfe,0xff,0xff,0x03,0xff,0xff,0xff,0x0f,0xff,0xff,0xff,0x1f,0xfe,0xff,0xff,0x3f,0xfc,0xff,0xff,0x3f,
+        0xf0,0xff,0xff,0x7f,0xe0,0xff,0xff,0x7f,0x80,0xff,0x00,0x7f,0x00,0xff,0x00,0x7c,0x00,0xfc,0x00,0x70,
+        0x00,0xf8,0x00,0x60,0x00,0xf0,0x00,0x40,0x00,0xc0,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x0f,0x78,
+        0x00,0x00,0x01,0x40,0x00,0x00,0x01,0x40,0x00,0x00,0x01,0x40,0x00,0x00,0x61,0x43,0x00,0x00,0x61,0x43,
+        0x00,0x00,0x0f,0x78,0x00,0x00,0x00,0x00
+};
+
+
+
 #endif //TCMENU_DIRECTIONAL_ICONS_H