Improved documentation

Author: dave

examples/arduino32/dynamicMenuItems/dynamicMenuItems.emf

@@ -386,7 +386,7 @@
       },
       {
         "name": "DISPLAY_BUFFER_SIZE",
-        "latestValue": "0",
+        "latestValue": "20",
         "subsystem": "DISPLAY"
       },
       {
@@ -521,12 +521,12 @@
       },
       {
         "name": "ITEM_FONT",
-        "latestValue": "def:,1",
+        "latestValue": "ada:OpenSansCyrillicLatin12,0",
         "subsystem": "THEME"
       },
       {
         "name": "TITLE_FONT",
-        "latestValue": "def:,1",
+        "latestValue": "ada:OpenSansCyrillicLatin12,0",
         "subsystem": "THEME"
       },
       {
@@ -541,7 +541,7 @@
       },
       {
         "name": "USE_TC_UNICODE",
-        "latestValue": "false",
+        "latestValue": "true",
         "subsystem": "THEME"
       },
       {

examples/arduino32/dynamicMenuItems/dynamicMenuItems.ino

@@ -2,12 +2,14 @@
  * This example shows how to create scroll choices, lists, and dynamically add items to both dialogs and existing menus
  * at runtime.
  *
- * Test environment: Seeed MG126 - Adafruit 128x128 display, encoder on device pins.
+ * Test environment: Seeed MG126 - Matrix Keyboard, Adafruit 128x128 display, rotary encoder
  *
  * Although it's set up to run on SAMD there is no reason it could not be easily reconfigured for any
- * other board.
+ * other board. This is one of the biggest advantages of this framework, moving boards is easier.
  *
  * Getting started: https://www.thecoderscorner.com/products/arduino-libraries/tc-menu/tcmenu-overview-quick-start/
+ * Dialogs: https://www.thecoderscorner.com/products/arduino-libraries/tc-menu/rendering-with-tcmenu-lcd-tft-oled/
+ * MenuManager: https://www.thecoderscorner.com/products/arduino-libraries/tc-menu/menumanager-and-iteration/
  */
 
 #include "dynamicMenuItems_menu.h"
@@ -17,14 +19,17 @@
 #include <tcMenuVersion.h>
 #include <IoLogging.h>
 
-// Pizza toppings that we forward referenced in the scroll choice item, when in RAM or EEPROM then they are declared in
-// a flat array based on the item size.
-//                            0123456789 0123456789 0123456789 0123456789 0123456789 0123456789
+//
+// ScrollChoice menu items when using data in RAM mode reference a fixed width array in your code, these will be
+// created by the code generator if needed. Genreally they are an array of char large enough to hold all items.
+// In this case they are pizza toppings, each zero terminated.
+//                       0123456789 0123456789 0123456789 0123456789 0123456789 0123456789
 char pizzaToppings[] = {"Peperoni\0 Onions\0   Olives\0   Sweetcorn\0Mushrooms\0Peppers\0  "};
 
 //
 // We now create some menu items that we manually add to the oven menu during initialisation. We set the sub menu child
-// to be the first of the two menu items, which are provided in a linked list.
+// to be the first of the two menu items, which are provided in a linked list. Notice that these are completely created
+// RAM, and not program memory.
 //
 BooleanMenuInfo minfoOvenFull = { "Start Oven", nextRandomId(), 0xffff, 1, NO_CALLBACK, NAMING_YES_NO};
 BooleanMenuItem menuOvenFull(&minfoOvenFull, false, nullptr, false);
@@ -48,10 +53,13 @@ public:
         allowDialogBack = allow;
     }
 
+    // called when the structure of the menu has completely changed, IE menu items added or removed from the tree
     void structureHasChanged() override {
         serdebugF("Structure of menu tree has changed, IE item added or removed!");
     }
 
+    // editing is about to start on an item, or a submenu is about to be shown, return true to show the menu, false
+    // to prevent the item from being edited or submenu shown
     bool menuEditStarting(MenuItem *item) override {
         serdebugF2("Item about to be actioned/editing", item->getId());
 
@@ -73,10 +81,14 @@ public:
         return true; // otherwise, default to allowing all actions.
     }
 
+    // called when the menu has finished editing or a menu is coming off the display. Note that in the special case
+    // of a submenu being shown, this will be after the new `menuEditStarted` because that could be prevented by
+    // returning false.
     void menuEditEnded(MenuItem *item) override {
         serdebugF2("Edit has completed for ID ", item->getId());
     }
 
+    // called whenever the active item changes
     void activeItemHasChanged(MenuItem* newActive) override {
         serdebugF2("The active item changed to ", newActive->getId())
     }
@@ -122,13 +134,14 @@ void onTitlePressed(int /*id*/) {
 }
 
 void setup() {
-    // If we use wire or serial, it's our responsibility to prepare it.
-    Serial.begin(115200);
-    //while(!Serial);
-    Wire.begin();
-
+    // 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/
+    IOLOG_START_SERIAL
     serEnableLevel(SER_TCMENU_DEBUG, true);
 
+    // start wire if using I2C
+    Wire.begin();
+
     // now we turn off the reset support
     renderer.turnOffResetLogic();
 
@@ -149,12 +162,17 @@ void loop() {
     taskManager.runLoop();
 }
 
+//
+// Helper function to print a menu items name and value
+//
 void serialPrintMenuItem(MenuItem* item) {
     char sz[32];
     copyMenuItemNameAndValue(item, sz, sizeof sz);
     Serial.println(sz);
 }
 
+//
+// Called when the start cooking menu item is clicked. It prints all the associated menu items out
 void CALLBACK_FUNCTION onStartCooking(int id) {
     Serial.println("We are making pizza!");
     serialPrintMenuItem(&menuPizzaMakerOvenTemp);
@@ -172,6 +190,8 @@ RENDERING_CALLBACK_NAME_INVOKE(fnExtraDialogLine, textItemRenderFn, "Detail: ",
 TextMenuItem secondItem(fnExtraDialogLine, nextRandomId(), 12, nullptr);
 
 void CALLBACK_FUNCTION onDialogInfo(int id) {
+    // withMenuDialogIfAvailable checks if the dialog can be presented now, and if so will call the function
+    // provided with the dialog as the parameter. you then just prepare the dialog to be shown.
     withMenuDialogIfAvailable([](MenuBasedDialog* dlg) {
         // we set it to have only one button, named close.
         dlg->setButtons(BTNTYPE_NONE, BTNTYPE_CLOSE);
@@ -198,20 +218,28 @@ const char pgmQuestionHeader[] PROGMEM = {"Override the title?"};
 const char pgmTitleOverride[] PROGMEM = {"Title Overridden"};
 taskid_t questionTask = TASKMGR_INVALIDID;
 void CALLBACK_FUNCTION onDialogQuestion(int id) {
+    // withMenuDialogIfAvailable checks if the dialog can be presented now, and if so will call the function
+    // provided with the dialog as the parameter. you then just prepare the dialog to be shown.
     withMenuDialogIfAvailable([] (MenuBasedDialog* dlg) {
+        // present a dialog with OK and CANCEL buttons with the question message, it has a completion handler.
         dlg->setButtons(BTNTYPE_OK, BTNTYPE_CANCEL);
         dlg->show(pgmQuestionHeader, true, [](ButtonType btn, void* data) {
             // this is the completion task that runs when the dialog is dismissed.
             Serial.print("Question result was "); Serial.println(btn);
             if(btn == BTNTYPE_OK) {
+                // here we override the main menu title to a new value
                 appTitleMenuItem.setTitleOverridePgm(pgmTitleOverride);
             }
             else {
+                // here we clear the title override, and put it back to default.
                 appTitleMenuItem.clearTitleOverride();
             }
+
+            // we must cancel the task that we started when the dialog was created
             taskManager.cancelTask(questionTask);
         });
 
+        // we create a task that keeps updating the value in the dialog buffer item.
         dlg->copyIntoBuffer("...");
         questionTask = taskManager.scheduleFixedRate(250, [] {
             char sz[10];
@@ -283,6 +311,8 @@ public:
 MyDialogController dialogController;
 
 void CALLBACK_FUNCTION onDialogController(int id) {
+    // withMenuDialogIfAvailable checks if the dialog can be presented now, and if so will call the function
+    // provided with the dialog as the parameter. you then just prepare the dialog to be shown.
     withMenuDialogIfAvailable([](MenuBasedDialog* dlg) {
         dlg->setButtons(BTNTYPE_OK, BTNTYPE_CUSTOM0);
         dlg->showController(true, &dialogController);

examples/arduino32/dynamicMenuItems/dynamicMenuItems_menu.cpp

@@ -11,12 +11,13 @@
 #include <tcMenu.h>
 #include "dynamicMenuItems_menu.h"
 #include "ThemeCoolBlueTraditional.h"
+#include <Fonts/OpenSansCyrillicLatin12.h>
 
 // Global variable declarations
 const  ConnectorLocalInfo applicationInfo = { "Dynamic Menus", "5f22995e-8da2-49c4-9ec8-d055901003af" };
 IoAbstractionRef ioexp_io23017 = ioFrom23017(0x20, ACTIVE_LOW_OPEN, 10);
 Adafruit_ST7735 gfx(1, 0, -1);
-AdafruitDrawable gfxDrawable(&gfx, 0);
+AdafruitDrawable gfxDrawable(&gfx, 20);
 GraphicsDeviceRenderer renderer(30, applicationInfo.name, &gfxDrawable);
 MatrixKeyboardManager keyboard;
 const char keyboardKeys[]  = "123A456B789C*0#D";
@@ -98,6 +99,7 @@ void setupMenu() {
     keyboard.setRepeatKeyMillis(850, 350);
     renderer.setTitleMode(BaseGraphicalRenderer::TITLE_FIRST_ROW);
     renderer.setUseSliderForAnalog(true);
-    installCoolBlueTraditionalTheme(renderer, MenuFontDef(nullptr, 1), MenuFontDef(nullptr, 1), true);
+    renderer.enableTcUnicode();
+    installCoolBlueTraditionalTheme(renderer, MenuFontDef(&OpenSansCyrillicLatin12, 0), MenuFontDef(&OpenSansCyrillicLatin12, 0), true);
 }
 

examples/arduino32/dynamicMenuItems/dynamicMenuItems_menu.h

@@ -13,6 +13,7 @@
 
 #include <Arduino.h>
 #include <tcMenu.h>
+#include <tcUnicodeHelper.h>
 #include "tcMenuAdaFruitGfx.h"
 #include <tcMenuKeyboard.h>
 #include <RuntimeMenuItem.h>
@@ -27,6 +28,7 @@ extern AdafruitDrawable gfxDrawable;
 extern GraphicsDeviceRenderer renderer;
 extern MatrixKeyboardManager keyboard;
 extern MenuEditingKeyListener tcMenuKeyListener;
+extern const UnicodeFont OpenSansCyrillicLatin12[];
 
 // Any externals needed by IO expanders, EEPROMs etc
 extern IoAbstractionRef ioexp_io23017;

examples/arduino32/piPicoTftEncoder/piPicoTftEncoder.ino

@@ -27,10 +27,9 @@ const char* fileNames[] = {
 void onTitlePressed(int);
 
 void setup() {
-    // Initialise serial for logging
-    // If you're using a pico probe, set build flag LoggingPort=Serial1 and initialise serial port 1.
-    //Serial.begin(115200);
-    Serial1.begin(115200);
+    // 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/
+    IOLOG_START_SERIAL
 
     // This is added by the code generator, it initialises the menu
     setupMenu();

examples/arduino32/picoAdafruitDashboard/dashboardConfig.cpp

@@ -1,8 +1,17 @@
+//
+// This file contains a simple dashboard that is set up using the dashboard classes
+// within the menu library extras. See ref docs:
+//
+// Reference docs https://www.thecoderscorner.com/ref-docs/tcmenu/html/_drawable_dashboard_8h.html
+//
 
 #include "picoAdafruitDashboard_menu.h"
 #include <Adafruit_ILI9341.h>
 #include "dashboardConfig.h"
 
+// START a title widget that was built using TcMenu Designers widget generator, see the "Code" menu for the widget
+// generator. This is added to both the main renderer and the dashboard.
+
 // YesNo icon=0, width=17, height=12, size=36
 const uint8_t YesNoWidIcon0[] PROGMEM = {
         0x00,0x40,0x00,0x00,0xe0,0x00,0x00,0xf0,0x01,0x00,0xf8,0x00,0x00,0x7c,0x00,0x04,0x3e,0x00,0x0e,0x1f,
@@ -18,59 +27,105 @@ const uint8_t* const YesNoWidIcons[] PROGMEM = { YesNoWidIcon0, YesNoWidIcon1 };
 // Widget Generator yesNo
 TitleWidget YesNoWidget(YesNoWidIcons, 2, 17, 12, nullptr);
 
+// END title widget
 
 // TickIcon icon=0, width=17, height=12, size=36
 const uint8_t TickIconBitmap0[] PROGMEM = {
         0x00,0x40,0x00,0x00,0xe0,0x00,0x00,0xf0,0x01,0x00,0xf8,0x00,0x00,0x7c,0x00,0x04,0x3e,0x00,0x0e,0x1f,
         0x00,0x9f,0x0f,0x00,0xfe,0x07,0x00,0xfc,0x03,0x00,0xf8,0x01,0x00,0xf0,0x00,0x00
 };
 
+// we define a global pointer to the dashboard, it will be created during the dash setup.
 DrawableDashboard* mainDashboard;
 
+// Any value item or scroll choice (integer based items) can have ranges of colors, these allow the color to be
+// selected based on the value, IE for a rev-counter above 8000 RPM may be shown in red, otherwise green. These
+// represented as below. In this case we are creating for an enum value.
+// Note that this is a parameter, not the actual dashboard item, they are defined below
 DashDrawParametersIntUpdateRange::IntColorRange drawEnumColorRanges[] {
         {ILI9341_YELLOW, ILI9341_RED, 0, 1},
         {ILI9341_CYAN, ILI9341_BLUE, 2, 3}
 };
 DashDrawParametersIntUpdateRange drawEnumWithIntRange(ILI9341_WHITE, ILI9341_BLACK, ILI9341_BLACK, ILI9341_YELLOW,
                                                        &RobotoMedium24, drawEnumColorRanges, 2);
 
+// As above we create another one for the analog item, it has two ranges.
+// Note that this is a parameter, not the actual dashboard item, they are defined below
 DashDrawParametersIntUpdateRange::IntColorRange drawAnalogColorRanges[] {
         {ILI9341_LIGHTGREY, ILI9341_BLUE, 0, 50},
         {ILI9341_YELLOW, ILI9341_RED, 51, 100}
 };
 DashDrawParametersIntUpdateRange drawAnalogValueWithIntRange(ILI9341_WHITE, ILI9341_BLACK, ILI9341_BLACK, ILI9341_WHITE,
                                                        &RobotoMedium24, drawAnalogColorRanges, 2);
+
+// and lastly we create a simple one for the title.
+// Note that this is a parameter, not the actual dashboard item, they are defined below
 DashDrawParameters titleDrawParameters(ILI9341_WHITE, ILI9341_BLACK, &RobotoMedium24);
 
+//
+// Although the dashboard support provides a wide range of menu drawing capabilities, it does not cover every case
+// so you can create a delegate that can do the extra drawing and other functions that are needed. Here is a simple
+// example that draws a few extra items onto the display
+// For drawing onto device drawble see:
+//  https://www.thecoderscorner.com/products/arduino-libraries/tc-menu/rendering-with-tcmenu-lcd-tft-oled/#drawing-direct-to-the-display-with-devicedrawabl
+// For more on the delegate class and all the points where you can extend
+//  https://www.thecoderscorner.com/ref-docs/tcmenu/html/class_drawable_dashboard_delegate.html
+//
 class MyDrawableDashboardDelegate : public DrawableDashboardDelegate {
 public:
+    // this is called after the dashboard has opened
     void dashboardDidOpen(BaseMenuRenderer *renderer) override {
         switches.getEncoder()->changePrecision(320, 100);
     }
 
+    // this is called before the dashboard draws any items
     void dashboardWillDraw(unsigned int encVal, RenderPressMode mode) override {
         renderer.getDeviceDrawable()->drawXBitmap(Coord(300, 30), Coord(17, 12), TickIconBitmap0);
     }
 
+    // this is called after the dashboard has drawn all items, you get the current value of the encoder and the
+    // current state of the select button.
     void dashboardDidDraw(unsigned int encVal, RenderPressMode mode) override {
+        // get the drawing device from the renderer and its dimensions
         DeviceDrawable *pDrawable = renderer.getDeviceDrawable();
         const Coord &totalSize = Coord(pDrawable->getDisplayDimensions().x, 20);
+
+        // create a dashboard wrapper that can work out if we are on a sub device or the main device.
         DrawableWrapper wrapper(pDrawable, &titleDrawParameters, &menuSettings, Coord(0, 200), totalSize);
+
+        // now we draw onto the drawable, we don't need to care if it is buffered or not
         wrapper.getDrawable()->setDrawColor(wrapper.bgCol());
         wrapper.getDrawable()->drawBox(wrapper.offsetLocation(Coord(0, 200)), totalSize, true);
         wrapper.getDrawable()->setDrawColor(wrapper.fgCol());
         wrapper.getDrawable()->drawBox(wrapper.offsetLocation(Coord(0, 200)), Coord(encVal, 20), true);
+
+        // lastly we tell the wrapper that we are done, if needed it will push  the buffer to the screen
         wrapper.endDraw();
     }
 } myDrawableDashboardDelegate;
 
 void setupDashboard() {
+    // Reference docs https://www.thecoderscorner.com/ref-docs/tcmenu/html/_drawable_dashboard_8h.html
+
+    // create a dashboard instance, giving it the renderer and drawable, any widgets to display in the top corner,
+    // and the mode in which it is to operate
     mainDashboard = new DrawableDashboard(renderer.getDeviceDrawable(), &renderer, &YesNoWidget,
                                           DrawableDashboard::DASH_ON_RESET_CLICK_EXIT);
+
+    // here we tell the dashboard about the delegate we created above.
     mainDashboard->setDelegate(&myDrawableDashboardDelegate);
+
+    // now prepare the base colors
     mainDashboard->setBaseColors(RGB(0, 0, 0), RGB(220, 220, 220));
+
+    // here we set up the entries on the dashboard, this is where we provide the menu item and position on the display
+    // for each entry. A parameter object that we defined above is then associated with an item. Note that more than
+    // one entry can share a parameter.
     mainDashboard->addDrawingItem(&menuAnalog, Coord(0, 0), &drawAnalogValueWithIntRange, 10, nullptr, 10);
     mainDashboard->addDrawingItem(&menuEnum, Coord(0, 50), &drawEnumWithIntRange, 10, nullptr, 10);
     mainDashboard->addDrawingItem(&menuSettings, Coord(0, 100), &titleDrawParameters, 0, "Dashboard");
+
+    // lastly, add the dashboard to the renderer, this is important, the dashboard implements CustomDrawing so it
+    // handles taking over the display and reset notification.
     renderer.setCustomDrawingHandler(mainDashboard);
-}
+}