Added documentation for the new UI tools and simulator

dev/ui_tools/resize_window.pl

@@ -44,6 +44,9 @@ sub help {
 
         If no parameters are sent in, we'll display the current window size.
 
+        if only one of -x or -y are sent in, we'll re-use the existing setting
+        for the missing value.
+
         Parameters:
 
         -x Optional: Number of horizontal pixels

doc/Berrybrew development.md

@@ -12,7 +12,7 @@ This document contains information on the entire development lifecycle of
 - [Compile Full Build (With Installer)](#development-installer-build)
 - [Compile Binary Only](#berrybrew-binary-only)
 - [Compile API Only](#api-only)
-- [Compile User Interface](#user-interface)
+- [User Interface](#user-interface)
 - [Manually Compile Your Own](#manually-compile-your-own)
 - [Unit Testing](#unit-testing)
 - [Production Build for Testing](#production-build)
@@ -49,6 +49,9 @@ These are the files and tools in the `dev\` directory, and their purposes:
 | **release.pl**                         | Creates a Berrybrew release. See [Create a Release](Create%20a%20release.md)                                                                                                                |
 | **release_cycle.pl**                   | After a release, this script cycles the repository in preparation for the next version. See [Prepare for next version](Create%20a%20release.md#prepare-a-branch-for-the-next-release-cycle) |
 | **release_post.pl**                    | After a release, restores any backed up configuration files (very rarely used)                                                                                                              |
+| **ui_simulator.pl**                    | Non-functional layout simulator of the UI for modifying its config file |
+| **ui_tools\move_element_block.pl**     | Move an element block of the UI up or down |
+| **ui_tools\resize_window.pl**          | Resize the UI main window |
 
 ### Berrybrew data directory layout
 
@@ -120,12 +123,7 @@ and perl instances in `C:\berrybrew-staging\instance`.
 
 ### User Interface
 
-- Run the `dev\build_staging_ui.bat` script, which runs `dev\build_staging.bat`
-compiling the API and the `berrybrew` binary, followed by the UI binary itself.
-
-- Run the `staging\berrybrew-ui.exe` to start the UI. Note that the staging UI
-build will execute out of a command line window, so that you can see the debugging
-output.
+See the [User Interface development](UI.md) document.
 
 ### Manually Compile your Own
 
@@ -142,7 +140,7 @@ See the [Unit Testing](Unit%20testing.md) document.
 ### Production Build
 
 To perform testing with the production aspects of `berrybrew` without creating
-a full blown release, run the `dev\build_prod.bat` script. The production build
+a full-blown release, run the `dev\build_prod.bat` script. The production build
 operates out of the `bin\` directory (ie. `bin\berrybrew.exe`).
 
 The production installer can be built using the `dev\build_prod_installer.bat`

doc/UI.md

@@ -0,0 +1,87 @@
+# User Interface development
+
+- Code is in `src/berrybrew-ui.cs`
+- Staging UI built binary is `staging/berrybrew-ui.exe`
+- Production UI built binary is `bin/berrybrew-ui.exe`
+- Configuration for UI layout is `dev/data/ui.json`
+
+- [UI Build](#ui-build)
+- [UI Simulator](#ui-simulator)
+- [UI Tools](#ui-tools)
+- [UI Tools - Move element block](#move-element-block)
+- [UI Tools - Resize main window](#resize-main-window)
+
+### UI Build
+
+To build and test the development/staging UI:
+
+- Run the `dev\build_staging_ui.bat` script, which runs `dev\build_staging.bat`
+  compiling the API and the `berrybrew` binary, followed by the UI binary itself.
+- Run the `staging\berrybrew-ui.exe` to start the UI. Note that the staging UI
+  build will execute out of a command line window, so that you can see the debugging
+  output.
+
+To build the production UI for testing, see the 
+[Prod UI build](Berrybrew%20development.md#production-build) documentation.
+
+### UI Simulator
+
+To aid in manipulating the UI element layout collected from the
+`dev\data\ui.json` configuration file, we've got a UI simulator in
+`dev\ui_simulator.pl`.
+
+This simulator is `Tkx` based, and runs on MacOS and Linux.
+
+It is non-functional; it's used solely to replicate the exact layout. If you
+modify any of the elements in the `src\ui.json` configuration file, a click of
+any button in the UI simulator will reload the window live time, so you don't
+have to close and reopen the UI sim on each change.
+
+### UI Tools
+
+The UI manipulation tool scripts reside in the `dev/ui_tools` directory.
+
+#### Move element block
+
+This script is `dev/ui_tools/move_element_block.pl`.
+
+It allows you to move an entire element block up and down by a pixel count.
+The element block types are listed in the `dev/data/ui.json` file. It will
+automatically update the configuration file.
+
+If this script is used to move an element block down, you will be asked if you
+want to resize the main window by the same number of pixels you move the block.
+
+Usage of the script:
+
+    dev/ui_tools/move_element_block.pl
+
+    Parameters:
+
+    -e|--element    Mandatory: The element type
+    -d|--direction  Mandatory: 'down' or 'up'
+    -p|--pixels     Mandatory: The number of pixels to move the elements
+
+#### Resize main window
+
+This script is `dev/ui_tools/resize_window.pl`.
+
+It allows you to resize the main window dynamically. It will automatically
+update the configuration file.
+
+Usage of the script:
+
+    dev/ui_tools/resize_window.pl
+
+    If no parameters are sent in, we'll display the current window size.
+
+    if only one of -x or -y are sent in, we'll re-use the existing setting
+    for the missing value.
+
+    Parameters:
+
+    -x Optional: Number of horizontal pixels
+    -y Optional: Number of vertical pixels
+    -h Optional: Display this help screen
+
+© 2016-2023 by Steve Bertrand