update font and dashboard docs

Author: dave

content/arduino-libraries/tc-menu.md

@@ -62,7 +62,7 @@ We have tested the designer application and embedCONTROL on a Raspberry PI, so n
 * [Creating and using TitleWidgets and bitmaps]({{< relref "creating-and-using-bitmaps-menu.md" >}})
 * [Themes, properties, grids and icons]({{< relref "rendering-with-themes-icons-grids.md" >}})
 * [How to define fonts within theme configuration]({{< relref "using-custom-fonts-in-menu.md" >}})
-* [Taking over the display]({{< relref "renderer-take-over-display.md" >}})
+* [Taking over the display and dashboards]({{< relref "renderer-take-over-display.md" >}})
 * [DfRobot LCD shield driver]({{< relref "dfrobot-input-display-plugin.md" >}})
 * [LiquidCrystal / hd44780 display driver]({{< relref "liquidcrystalio-hd44780-renderer-plugin.md" >}})
 * [AdaFruit_GFX driver - ILI9341, ST7735, Nokia5110 etc]({{< relref "adafruit_gfx-renderer-plugin.md" >}})

content/arduino-libraries/tc-menu/renderer-take-over-display.md

@@ -14,17 +14,21 @@ weight = 2
 toc_needed = true
 +++
 
-TcMenu allows you to take over the display from the renderer very easily, once you own the display, you will be called back at regular intervals by the rendering class, and it is your responsibility to update the display at this time (if there are changes that require redrawing). **You should never update the screen outside of these callbacks**, as doing so would interfere with TcMenu rendering.
+TcMenu allows you to take over the display from the renderer very easily, and once you own the display, you will be called back at regular intervals by the rendering class. During the time that you've taken over the display or presented a dashboard, you're responsible for the user input and rendering. **Please note that you should never update the screen outside of these callbacks**, as doing so would interfere with TcMenu rendering.
 
-There are three choices for drawing custom screens:
+{{< blockClear "left" >}}
+
+## Different methods for taking control of the display
+
+There are three choices for custom drawing:
 
 * A functional approach based on providing a callback function that gets called frequently to draw
 * An object-oriented approach, where you provide an extension of `CustomDrawing` to the renderer, it gets called at various points in the renderer's lifecycle (reset, start, draw).
 * Using the custom `DrawableDashboard` support where you provide one or more dashboard configurations, with the option of further customizing it using a delegate. 
 
 Below we discuss them all in turn.
 
-## Functional approach to take over display
+## 1. Functional approach to take over display
 
 To use a regular function callback to take over the display:
 
@@ -46,7 +50,7 @@ When conditions change such that you no longer need display control:
 
     renderer.giveBackDisplay();
 
-## Functional approach to capturing display timeout / reset
+### Functional approach to capturing display timeout / reset
 
 You can also add a callback function that will be informed when the menu is reset after timing out, by default this happens after 30 seconds of inactivity. This is useful if you don't want to display the menu all the time. First define the function:
 
@@ -71,7 +75,7 @@ Or even turn off the reset / inactivity support altogether:
 
 The original purpose of the reset / inactivity support was for complex menus, where if the user left the system deeply nested several menus down, after a timeout it would return to the root of the structure ready for the next user. 
 
-## Object oriented approach to display management
+## 2. Object oriented approach to display management
 
 If we extend the class `CustomDrawing` and provide that instance to the renderer, then we can both handle taking over the display and reset events at the same time. {{< refdocs title="See custom drawing class in reference docs" src="/tcmenu/html/class_custom_drawing.html" >}}. Here we present a simple way to extend it.
 
@@ -115,50 +119,55 @@ Then to take over the display, use the no parameter version of the method:
 
     renderer.takeOverDisplay(); 
 
-## Using the `DrawableDashboard` to draw a dashboard
+## 3. Using the `DrawableDashboard` to draw a dashboard
 
 `DrawableDashboard` makes it possible to create dashboard style views out of menu items with only a few lines of code. Each dash item is basically a menu item that you can choose how it is presented. You can set where they appear on the screen, color, font and how much space to take up. The easiest way to get started is probably to look at one of the examples (such as the SimHub example).
 
-You can have more than one dashboard but only one can be attached to the renderer at once.
+Below is an example dashboard from the `esp32Simhub` example, it is from a racing simulator and contains a few different menu items presented in the dashboard, and also some custom items as well. We'll go through each below.
+
+{{< figure src="/products/arduino-libraries/images/electronics/arduino/themes/tft-dashboard-example.jpg" title="Dashboard example on ILI9431" alt="An example dashboard rendered onto a TFT ILI9431 display" width="200px" >}}
 
-Generally speaking we create a main dashboard object as a pointer to a `DrawableDashboard`. For example, you may create it as follows:
+If we look at the above image, we see that it has a very large `N` item on the left which is the value of the current gear menu item, this is using a very large font that can easily be generated using [tcMenu Designers font generator]({{< relref "using-custom-fonts-in-menu.md">}}). To the right we have some more menu items with static text next to them, and at the top, we custom draw the LED matrix. The full example is packaged with [tcMenu library in the examples/esp folder](https://github.com/TcMenu/tcMenuLib/blob/main/examples/esp/esp32SimHub/dashboardSetup.cpp).
+
+To get started, we create a main `DrawableDashboard` object and as it is done only once at startup we normally use `new` to create it. For example:
 
     mainDashboard = new DrawableDashboard(renderer.getDeviceDrawable(), &renderer, &widgetConnected,
                                           DrawableDashboard::DASH_ON_RESET_CLICK_EXIT);
 
-You then set the main colors for the dashboard (background and primary foreground):
+Where:
 
-    mainDashboard->setBaseColors(RGB(0, 0, 0), RGB(220, 220, 220));
+* deviceDrawable is generally just taken from the renderer as follows `renderer.getDeviceDrawable()`
+* renderer is generally `rederer`
+* widget you can also render a title widget in the top right corner
+* dashboardMode is one of `DASH_ON_RESET_CLICK_EXIT, DASH_ON_RESET_MANUAL_EXIT, DASH_FULLY_MANUAL, DASH_MANUAL_START_CLICK_EXIT`
 
-Now you can add drawing items for each menu item you want on the dashboard
+You then set the main colors for the dashboard (background and primary foreground):
 
-Optionally, you can set a delegate if you want to draw extra things to the display, or need more control around how it opens and closes.
+    mainDashboard->setBaseColors(RGB(0, 0, 0), RGB(220, 220, 220));
 
-* Step 1 - create a class that extends from `DrawableDashboardDelegate`
-* Step 2 - now override the functions you need to handle, see the documentation for the class for the options.
-* Step 3 - add the delegate to the dash, `mainDashboard->setDelegate(&myDelegate);`
+Now you can add drawing items for each menu item you want on the dashboard:
 
-Then, you add drawing items to the dashboard one at a time:
+To add a drawing item thats based on a menu item we call `addDrawingItem`
 
     mainDashboard->addDrawingItem(&menuItem, Coord(x, y), &drawingParameters, valueChars,
                                   [overrideTitle = nullptr], [updateTicks = 5]);
 
-Where the coordinates are the top left, the parameters are described below, the valueChars is the width in characters, you can optionally override the title, and optionally set how many ticks the value highlights on update for. 
+Where `menuItem` is the item to present, then the coordinates provided by the `Coord` are the top left, the `drawingParameters` are described below, the valueChars is the width in characters, you can optionally override the title for the item, and optionally set how many ticks the value highlights on update for. Colors are best provided using the `RGB(red, green, blue)` macro using values between 0..255.
 
-The simplest drawing parameters is defined as follows, the colors never change:
+The simplest drawing parameters is defined as follows, the colors are fixed, and you can provide alignment (see below) and font:
 
     DashDrawParameters simpleDrawParameters(fgCol, bgCol, fontPtr, [alignment]);
 
-You can define parameters that highlight the value when the value changes:
+In addition to above, You can define parameters that highlight the value when the value changes, parameters are as above, but with a highlight background and foreground color:
 
     DashDrawParametersUpdate updateParameters(fgCol, bgCol, fgUpdateCol, bgUpdateCol, 
                                               fontPtr, [alignment]);
 
-You can define parameters that highlight as integer values change, relevent to Analog, Enum, Boolean and ScrollChoice menu items:
+You can define parameters that highlight as integer values change, for example an analog value may turn red when a certain value is reached, this is relevant to Analog, Enum, Boolean and ScrollChoice menu items:
 
     DashDrawParametersIntUpdateRange::IntColorRange drawColorRanges[] {
-        {fg1, bg1, 0, 50}, // for values from 0..50
-        {fg2, bg2, 51, 100} // for values from 51..100
+        {fgColor1, bgColor1, 0, 50}, // for values from 0..50
+        {fgColor2, bgColor2, 51, 100} // for values from 51..100
     };
     DashDrawParametersIntUpdateRange drawParamsWithRanges(fgCol, bgCol,fgUpdateCol, bgUpdateCol,
                     fontPtr, drawColorRanges, numRanges, [alignment]);
@@ -174,15 +183,24 @@ You can define parameters for text items that match on equality:
 
 For alignment the options are:
 
-* TITLE_LEFT_VALUE_LEFT
-* TITLE_LEFT_VALUE_RIGHT
-* NO_TITLE_VALUE_LEFT
-* NO_TITLE_VALUE_RIGHT 
-* TITLE_RIGHT_VALUE_LEFT
-* TITLE_RIGHT_VALUE_RIGHT
+* `TITLE_LEFT_VALUE_LEFT`
+* `TITLE_LEFT_VALUE_RIGHT`
+* `NO_TITLE_VALUE_LEFT`
+* `NO_TITLE_VALUE_RIGHT` 
+* `TITLE_RIGHT_VALUE_LEFT`
+* `TITLE_RIGHT_VALUE_RIGHT`
 
 Along with the ability to use a delegate this gives a lot of flexibility in screen drawing outside the regular menu rendering.
 
 ## Setting the speed of rendering
 
 You can adjust the number of update cycles per second by calling `setUpdatesPerSecond` on the renderer, it takes place immediately, even if already started.
+
+## Using a delegate to customize the dashboard - ADVANCED
+
+Optionally, you can set a delegate if you want to draw extra things to the display, or need more control around how it opens and closes.
+
+* Step 1 - create a class that extends from `DrawableDashboardDelegate`
+* Step 2 - now override the functions you need to handle, see the documentation for the class for the options.
+* Step 3 - add the delegate to the dash, `mainDashboard->setDelegate(&myDelegate);`
+

content/arduino-libraries/tc-menu/using-custom-fonts-in-menu.md

@@ -15,7 +15,7 @@ toc_needed = true
 
 In the theme plugin properties you can often select the font to use. However, there are a few points to bear in mind when using fonts. Here are the key points:
 
-* From version 3.0 Most graphical plugins (other than Uno specific) support TcUnicode, a font rendering system that has full Unicode UTF-8 support. These fonts can be easily created in the designer UI, see further down. It is also backward compatible with Adafruit fonts.    
+* Most graphical plugins (other than Uno specific) support TcUnicode, a font rendering system that has full Unicode UTF-8 support. These fonts can be easily created in the designer UI, see further down. It is also backward compatible with Adafruit fonts.    
 * Each plugin's text drawing can also use native text drawing, based on how the underlying library itself draws fonts. You must use a compatible font.
 * Some libraries such as U8G2 and TFT_eSPI generally include the fonts in the package, and it is up to you to know which ones are available.
 * For Adafruit_GFX the fonts are generally included as needed from the `Fonts` directory, either in the package itself, or from your local project. They will be included once only in the C++ menu file and the variable for the font will be exported.
@@ -62,23 +62,22 @@ It is a struct, so has trivially simple copy characteristics.
 
 ## Creating a Unicode or Adafruit font using the designer UI
 
-From V3.0 of designer onwards you can create an embedded font from a font available on your desktop. The font creator presently supports header generation for both Adafruit_GFX or TcUnicode fonts. TcUnicode fonts are described in more detail in the next section.
+TcMenu Designer can create an embedded font from a font available on your desktop. The font creator presently supports header generation for both Adafruit_GFX or TcUnicode fonts. TcUnicode fonts are described in more detail in the next section.
 
 **NOTE: It is your responsibility to check the usage license on the font you choose, to ensure you are legally allowed to use it in an embedded context.** 
 
 To start the font creation utility, it is best to have a project open first, as it will then offer to save within your project.
 
-From the "Code" menu select "Font Creation Utility" (requires 3.0) and the following dialog will be shown:
+From the "Code" menu select "Font Creation Utility" and the following dialog will be shown:
 
 {{< figure src="/products/arduino-libraries/images/electronics/arduino/tcMenu/generator-font-creator-utility.jpg" alt="Font creation dialog with highlighted points" title="Font Creation Dialog" >}} 
 
-Notice that the above diagram is annotated with numbers, this is roughly the order that you'd use the panel. Each point is described below:
+We'll now go through the general way in which to work with fonts:
 
-1. Font load button. Click this button to load a font into the creator tool. Once loaded by default it will show the glyphs for Latin in the selection area (4). Clicking on the "Choose Ranges" in the button bar (5) allows you to change the Unicode ranges that are selected.
-2. Size in pixels of the font to generate, adjust this as needed, as you adjust the font will update in the selection area.
-3. Font style allows you to change the style, toggling italics and bold typeface, again the selection area automatically updates.
-4. The selection area is where you can turn on and off both character groups and characters. Toggle the group by clicking the checkbox next to it. To add/remove whole groups use the "Choose Ranges" button.
-5. The button bar has the two options for code generation, each of these will take a file name and write the font in the format selected. Each of these formats, and their limitations are described below.
+1. Open a font into the editor either using `Open Embedded Font` which allows you to open an existing font XML file previously saved. Alternatively, `Import Font` imports a font from any file format supported by FreeFont library. When importing a font, make sure you choose the Unicode ranges that you want to include, by default all Latin ranges are selected.
+2. One a font is opened you can choose which glyphs to include, and also touch up any minor rendering errors. To either select or deselect a glyph click on it, a popup will allow you to either edit the glyph or toggle its selection status. To toggle the group by clicking the `select/clear all` checkbox next to it. 
+3. You can `Save` the font as XML, it can be loaded back at any time using `Open Embedded Font`.
+4. To export the font simply use the `Generate` menu button, where you can choose either to export to clipboard or file. When the clipboard option is ticked, the header file will be saved to the clipboard. The two export options are discussed below.  
 
 ### Exporting to Adafruit_GFX font format