Major improvements to the Embedded Raspberry PI code generator (#540)

* #537 improve custom panel support embed control
* #537 documentation and a few minor updates.
* #537 documentation and a few minor updates.
* #537 clean up embed control code
* #537 clean up embed control documentation
* #538 Java project now based on the template project

Author: davetcc

embedCONTROLCore/src/main/java/com/thecoderscorner/embedcontrol/core/controlmgr/BaseEditorComponent.java

@@ -8,14 +8,21 @@
 
 import java.util.Set;
 
-/**
- * The absolute base class of editor components, this class contains many helper functions needed to be able to render
- * a menu item onto the display, regardless of the type of item, or display technology. This includes working out
- * what text needs to be displayed, handling updates including the momentary change in color on value change. Error
- * handling and correlation is also dealt with here.
- *
- * @param <W> The window component type
- */
+/// This class is the base of all editor components that can represent a menu item onto a window, and as such contains
+/// many helper functions needed to be able to keep the control in sync with the menu item, regardless of the type of
+/// item, or display technology. Normally for JavaFX the generic type is `Node`.
+///
+/// In order to present a menu item onto the display, we need to work out what text needs to be displayed, what kind
+/// of control is capable of presenting the menu item, and handling updates including a momentary change in color on
+/// value change. Error handling and correlation is also dealt with here.
+///
+/// You normally create items of this class by interacting with the `MenuEditorFactory` interface. If you're trying
+/// to create a custom page within `EmbedControl` it is recommended to start with `BaseCustomMenuPanel` as that already
+/// creates everything you're likely to need, and has examples of creating controls.
+///
+/// @see MenuEditorFactory
+/// @see com.thecoderscorner.embedcontrol.jfx.controlmgr.panels.BaseCustomMenuPanel
+/// @param <W> The window component type for JavaFX it is Node.
 public abstract class BaseEditorComponent<W> implements EditorComponent<W> {
     public static final int MAX_CORRELATION_WAIT = 5000;
 

embedCONTROLCore/src/main/java/com/thecoderscorner/embedcontrol/core/controlmgr/BaseUpDownIntEditorComponent.java

@@ -4,6 +4,13 @@
 import com.thecoderscorner.menu.domain.state.MenuState;
 import com.thecoderscorner.menu.domain.util.MenuItemFormatter;
 
+/// BaseUpDownIntEditorComponent is an abstract class that handles
+/// the core logic for an editor component with up/down integer adjustments.
+/// This class extends [BaseEditorComponent] and encapsulates the functionalities
+/// required to manage integer values.
+///
+/// @param <T> The type of the value this editor component will manage.
+/// @param <W> The type of the widget component.
 public abstract class BaseUpDownIntEditorComponent<T, W> extends BaseEditorComponent<W> {
     protected T currentVal;
 

embedCONTROLCore/src/main/java/com/thecoderscorner/embedcontrol/core/controlmgr/ComponentPositioning.java

@@ -1,9 +1,7 @@
 package com.thecoderscorner.embedcontrol.core.controlmgr;
 
-/**
- * Represents an abstract way of positioning menu item controls for display in a grid. Containing the row, column
- * and span of each.
- */
+/// Represents an abstract way of positioning menu item controls for display in a grid. Containing the row, column
+/// and span of each. Generally always used with {@link ComponentSettings}
 public class ComponentPositioning {
     private final int row;
     private final int col;

embedCONTROLCore/src/main/java/com/thecoderscorner/embedcontrol/core/controlmgr/ComponentSettings.java

@@ -9,12 +9,15 @@
 import static com.thecoderscorner.embedcontrol.core.controlmgr.RedrawingMode.SHOW_NAME_VALUE;
 import static com.thecoderscorner.embedcontrol.customization.MenuFormItem.FONT_100_PERCENT;
 
-/**
- * When automatic menu layout is used, the layout is described in terms of font, color, position and justification using
- * this class. It can either be auto-generated on the fly, or selected by a user and serialized by the layout persister
- * for later reloading. This is essentially a value class.
- *
- */
+/// This class describes how a menu item should be rendered onto the display. It contains the most important drawing
+/// settings along with grid positioning data. It also allows for conditional colouring and custom drawing. Usually
+/// use the {@link ComponentSettingsBuilder} in order to create an instance of this class.
+///
+/// For automatic menu layout cases, the layout is described in terms of font, color, position and justification using
+/// this class based on some standard defaults.
+///
+/// @see CustomDrawingConfiguration
+/// @see ConditionalColoring
 public class ComponentSettings {
     public static final ComponentSettings NO_COMPONENT = new ComponentSettings(new NullConditionalColoring(),
             FONT_100_PERCENT, PortableAlignment.LEFT, new ComponentPositioning(0, 0), SHOW_NAME_VALUE,

embedCONTROLCore/src/main/java/com/thecoderscorner/embedcontrol/core/controlmgr/ComponentSettingsBuilder.java

@@ -0,0 +1,183 @@
+package com.thecoderscorner.embedcontrol.core.controlmgr;
+
+import com.thecoderscorner.embedcontrol.core.controlmgr.color.ConditionalColoring;
+import com.thecoderscorner.embedcontrol.customization.FontInformation;
+import com.thecoderscorner.embedcontrol.customization.customdraw.CustomDrawingConfiguration;
+import com.thecoderscorner.menu.domain.*;
+
+import java.util.Set;
+
+import static com.thecoderscorner.embedcontrol.core.controlmgr.EditorComponent.PortableAlignment;
+import static com.thecoderscorner.embedcontrol.customization.MenuFormItem.FONT_100_PERCENT;
+
+/**
+ * ComponentSettingsBuilder is a builder class for creating instances of ComponentSettings.
+ * It provides various methods to customize the settings of a component, such as font, colors,
+ * justification, position, control type, drawing mode, and custom drawing configuration.
+ */
+public class ComponentSettingsBuilder {
+    public enum BuildingMode { MENU, TEXT, IMAGE }
+
+    private final static Set<EditItemType> POSSIBLE_TIME_TYPES = Set.of(
+            EditItemType.TIME_12H,
+            EditItemType.TIME_24_HUNDREDS,
+            EditItemType.TIME_24H,
+            EditItemType.TIME_12H_HHMM,
+            EditItemType.TIME_24H_HHMM);
+
+    private BuildingMode mode;
+    private String text;
+    private MenuItem item;
+    private FontInformation fontInfo = FONT_100_PERCENT;
+    private ConditionalColoring colors;
+    private PortableAlignment justification = PortableAlignment.LEFT_VAL_RIGHT;
+    private ComponentPositioning position = new ComponentPositioning(0, 0);
+    private ControlType controlType = ControlType.TEXT_CONTROL;
+    private RedrawingMode drawMode = RedrawingMode.SHOW_NAME_VALUE;
+    private CustomDrawingConfiguration customDrawing = CustomDrawingConfiguration.NO_CUSTOM_DRAWING;
+
+    /// Create component settings builder object from a menu item. It defaults the fields to reasonable values as
+    /// much as possible by setting the font to 100% size, setting the control type to the default, and setting the
+    /// justification to the default too.
+    /// @param item the menu item to build for
+    /// @param color the colors to use for the control
+    public static ComponentSettingsBuilder forMenuItem(MenuItem item, ConditionalColoring color) {
+        var b = new ComponentSettingsBuilder();
+        b.mode = BuildingMode.MENU;
+        b.colors = color;
+        b.item = item;
+        b.withControlType(defaultControlForType(item));
+        b.withJustification(defaultJustificationForType(b.controlType));
+        return b;
+    }
+
+    /// Create a component settings builder object that will represent some text on the display at a
+    /// particular grid position, will default to the text color, 100% font size, and left justification.
+    /// @param text the text to present
+    /// @param color the color set to use
+    public static ComponentSettingsBuilder forText(String text, ConditionalColoring color) {
+        var b = new ComponentSettingsBuilder();
+        b.mode = BuildingMode.TEXT;
+        b.colors = color;
+        b.text = text;
+        b.withControlType(ControlType.TEXT_CONTROL);
+        b.withJustification(PortableAlignment.LEFT);
+        return b;
+    }
+
+    private static PortableAlignment defaultJustificationForType(ControlType controlType) {
+        return switch(controlType) {
+            case HORIZONTAL_SLIDER, UP_DOWN_CONTROL -> PortableAlignment.LEFT_VAL_RIGHT;
+            case BUTTON_CONTROL, VU_METER, ROTARY_METER -> PortableAlignment.CENTER;
+            default -> PortableAlignment.LEFT;
+        };
+    }
+
+    public static ControlType defaultControlForType(MenuItem item) {
+        return switch(item) {
+            case SubMenuItem _, BooleanMenuItem _, ActionMenuItem _ -> ControlType.BUTTON_CONTROL;
+            case AnalogMenuItem _ -> ControlType.HORIZONTAL_SLIDER;
+            case EnumMenuItem _, ScrollChoiceMenuItem _ -> ControlType.UP_DOWN_CONTROL;
+            case Rgb32MenuItem _ -> ControlType.RGB_CONTROL;
+            case RuntimeListMenuItem _ -> ControlType.LIST_CONTROL;
+            case CustomBuilderMenuItem _ -> ControlType.AUTH_IOT_CONTROL;
+            case EditableTextMenuItem txt when txt.getItemType() == EditItemType.GREGORIAN_DATE -> ControlType.DATE_CONTROL;
+            case EditableTextMenuItem txt when POSSIBLE_TIME_TYPES.contains(txt.getItemType())  -> ControlType.TIME_CONTROL;
+            default -> ControlType.TEXT_CONTROL;
+        };
+    }
+
+    /// Override the font from the default 100% size to another value
+    /// @param fontInfo  the font to override with.
+    public ComponentSettingsBuilder withFont(FontInformation fontInfo) {
+        this.fontInfo = fontInfo;
+        return this;
+    }
+
+    /// Change the conditional coloring from the default one chosen.
+    /// @param colors the conditional colors
+    public ComponentSettingsBuilder withColors(ConditionalColoring colors) {
+        this.colors = colors;
+        return this;
+    }
+
+    /// Change the justification from the default value which is guessed during `forMenuItem` based on the control.
+    /// @param justification the justification to use
+    public ComponentSettingsBuilder withJustification(PortableAlignment justification) {
+        this.justification = justification;
+        return this;
+    }
+
+    /// Set the position of the control in the grid. Must always be set, for simpler cases with
+    /// no span you can use `withRowCol`
+    /// @param position the position and span in the grid to create with
+    public ComponentSettingsBuilder withPosition(ComponentPositioning position) {
+        this.position = position;
+        return this;
+    }
+
+    /// Set the position of the control in the grid. Must always be set
+    /// @param row the zero based row
+    /// @param col the zero based column
+    public ComponentSettingsBuilder withRowCol(int row, int col) {
+        this.position = new ComponentPositioning(row, col);
+        return this;
+    }
+
+    /// Override the control type that was guessed during `forMenuItem`. You should be careful that the control type
+    /// you choose is compatible with the menu item type.
+    /// @param controlType  the control type to use
+    /// @throws IllegalArgumentException if the control type is invalid for the menu item
+    public ComponentSettingsBuilder withControlType(ControlType controlType) {
+        if(mode != BuildingMode.MENU) {
+            controlType = ControlType.TEXT_CONTROL;
+        } else if(!controlType.isSupportedFor(item)) {
+            throw new IllegalArgumentException("Control type %s cannot render %s".formatted(controlType, item.getClass().getSimpleName()));
+        } else {
+            this.controlType = controlType;
+        }
+        return this;
+    }
+
+    /// Sets the drawing mode for the item, defaults to show name and item.
+    /// @param drawMode  the drawing mode
+    public ComponentSettingsBuilder withDrawMode(RedrawingMode drawMode) {
+        this.drawMode = drawMode;
+        return this;
+    }
+
+    /// Configure a custom drawing for the item, again make sure it is compatible with the menu type your using.
+    /// @param customDrawing the custom drawing to be used, must be compatible with the menu item type.
+    /// @throws IllegalArgumentException if the custom drawing is incompatible with the menu item type
+    public ComponentSettingsBuilder withCustomDrawing(CustomDrawingConfiguration customDrawing) {
+        if(!customDrawing.isSupportedFor(item)) {
+            throw new IllegalArgumentException("Custom drawing %s cannot render %s".formatted(customDrawing, item.getClass().getSimpleName()));
+        }
+        this.customDrawing = customDrawing;
+        return this;
+    }
+
+    /// Get the menuitem for this builder
+    /// @return menu item
+    public MenuItem getItem() {
+        return item;
+    }
+
+    /// Get the static text associated with this builder
+    /// @return  the static text
+    public String getText() {
+        return text;
+    }
+
+    /// Get the mode of the building, IE text, menu item etc.
+    /// @return the building mode
+    public BuildingMode getMode() {
+        return mode;
+    }
+
+    /// Creates the component settings
+    /// @return the built object
+    public ComponentSettings build() {
+        return new ComponentSettings(colors, fontInfo, justification, position, drawMode, controlType, customDrawing, true);
+    }
+}

embedCONTROLCore/src/main/java/com/thecoderscorner/embedcontrol/core/controlmgr/ControlType.java

@@ -5,7 +5,7 @@
 import java.util.List;
 
 /**
- * Represents the type of embedCONTROL control to use, these are hints to the rendering layer to help it to decide
+ * Represents the type of Embed Control display item to use, these are hints to the rendering layer to help it to decide
  * what to display.
  */
 public enum ControlType {

embedCONTROLCore/src/main/java/com/thecoderscorner/embedcontrol/core/controlmgr/EditorComponent.java

@@ -5,11 +5,19 @@
 import com.thecoderscorner.menu.remote.commands.AckStatus;
 import com.thecoderscorner.menu.remote.protocol.CorrelationId;
 
-/**
- * This interface represents an item that can be drawn onto a display, it does not say what the control should be
- * directly, the control is created by a call to createComponent, which generates the required UI node.
- * @param <T> the base node type for the UI
- */
+/// This interface represents an item that can be drawn onto a display, it does not say what the control should be
+/// directly, the control is created by a call to createComponent, which generates the required UI node.
+///
+/// In order to present a menu item onto the display, we need to work out what text needs to be displayed, what kind
+/// of control is capable of presenting the menu item, and handling updates including a momentary change in color on
+/// value change. Error handling and correlation is also dealt with here.
+///
+/// You normally create items of this class by interacting with the `MenuEditorFactory` interface. If you're trying
+/// to create a custom page within `EmbedControl` it is recommended to start with `BaseCustomMenuPanel` as that already
+/// creates everything you're likely to need, and has examples of creating controls.
+///
+/// @see BaseEditorComponent
+/// @param <T> the base node type for the UI
 public interface EditorComponent<T> {
 
     /**

embedCONTROLCore/src/main/java/com/thecoderscorner/embedcontrol/core/controlmgr/MenuComponentControl.java

@@ -6,8 +6,9 @@
 import com.thecoderscorner.menu.remote.protocol.CorrelationId;
 
 /**
- * embedCONTROL is used in both local and remote settings, as such there is a need for different implementations of
- * things such as updates, and connection handling. This interface bridges the gap between the two.
+ * Embed Control is used in both local and remote settings, as such there is a need for different implementations of
+ * things such as updates, and connection handling. This interface provides a way to provide a suitable implementation
+ * for all environments.
  */
 public interface MenuComponentControl {
     /**

embedCONTROLCore/src/main/java/com/thecoderscorner/embedcontrol/core/controlmgr/MenuEditorFactory.java

@@ -6,12 +6,19 @@
 import java.util.Optional;
 import java.util.function.Consumer;
 
-/**
- * A menu control grid is responsible for actually placing controls onto the UI. It has a method for each type of
- * control that can be added, and has helper methods to clear down the grid, and to nest menu items, this allows for
- * cases where recursive menu rendering is used to give visual clues such as indentation.
- * @param <T>
- */
+/// This factory is responsible for creating controls that can be placed into a window or screen. The default JavaFX
+/// implementation creates JavaFX `Node` objects for each editor component. For the standard case that you want to
+/// create a custom panel in Embed Control then you should most likely start with `BaseCustomMenuPanel`.
+///
+/// The factory has a method for each type of control that can be added. The `getComponentEditorItem` method takes a
+/// `ComponentSettings` and returns an `EditorComponent`. The editor component is kind of like a wrapper around the
+/// actual control, and can keep the control up-to-date and in the right state when associated with a
+/// [com.thecoderscorner.embedcontrol.jfx.controlmgr.panels.BaseCustomMenuPanel]. If you want to use these components
+/// outside of the base custom panel, then you should look at the custom panel implementation to see how to interact
+/// with editor components.
+///
+/// @see com.thecoderscorner.embedcontrol.jfx.controlmgr.JfxMenuEditorFactory
+/// @param <T> the control type
 public interface MenuEditorFactory<T>
 {
     /**