Dietpi banner upgrades

CONTRIBUTING.md

@@ -55,13 +55,13 @@ Guidance:
 ### Core concepts
 
 - Globals: scripts source `dietpi/func/dietpi-globals` for shared helpers and
-  environment setup (`G_INIT`, `G_EXIT`, color vars, etc.). Read this file
+  environment setup (`G_INIT()`, `G_EXIT()`, color vars, etc.). Read this file
   first to understand helper semantics and cancel/error behavior.
 - UI: prefer `G_WHIP_*` dialog helpers for menus, input and confirmations to
   maintain a consistent user experience across scripts.
-- Error-handling: use `G_EXEC` to wrap any command call, so DietPi's error
+- Error-handling: use `G_EXEC()` to wrap any command call, so DietPi's error
   handler and consistent console output apply. Validate root permissions and
-  write access using `G_CHECK_ROOT_USER` / `G_CHECK_ROOTFS_RW` where required.
+  write access using `G_CHECK_ROOT_USER()` / `G_CHECK_ROOTFS_RW()` where required.
 - Persistence: Write arrays or variables into a preference file `/boot/dietpi/.<prog_settings>`.
   Persist arrays as indexed assignments (e.g. `aARRAY[index]=1`). Convert ESC bytes to `\e`
   when saving text if needed. Load the preferences with `. "/boot/dietpi/.<prog_settings>"`
@@ -76,65 +76,49 @@ DietPi provides many `G_` prefixed helpers in `dietpi/func/dietpi-globals`. Usag
   consistent and reduce reviewer friction.
 
 Below are the most useful ones for contributors and how to use them safely.
-- `G_INIT` — initialize script runtime, sets up the working directory, exit
+- `G_INIT()` — initialize script runtime, sets up the working directory, exit
    traps, consistent locale for parsing external command outputs, and handles
    concurrent execution checks. Call early after sourcing `dietpi-globals`.
 
-- `G_EXEC` — robust command executor with built-in retries and an interactive
+- `G_EXEC()` — robust command executor with built-in retries and an interactive
   error handler. Use instead of direct `rm`/`systemctl` in scripts so
   failures are presented to the user and logged consistently. Optional
   env vars: `$G_EXEC_DESC`, `$G_EXEC_RETRIES`, `$G_EXEC_OUTPUT`.
 
-- `G_CONFIG_INJECT` — targeted config-file editing helper. Use to atomically
-  replace, uncomment, or add config lines using predictable patterns rather
-  than ad-hoc `sed` calls.
-
-- `G_WHIP_*` family — dialog and UI helpers: (`G_WHIP_MSG`, `G_WHIP_YESNO`,
-  `G_WHIP_MENU`, `G_WHIP_CHECKLIST`, `G_WHIP_INPUTBOX`, `G_WHIP_PASSWORD`,
-  `G_WHIP_VIEWFILE`).
-  Prefer these for user interaction to maintain consistent UX and behavior.
-
-- `G_CHECK_ROOT_USER`, `G_CHECK_ROOTFS_RW` — validate that the script runs
+- `G_CHECK_ROOT_USER()`, `G_CHECK_ROOTFS_RW()` — validate that the script runs
   with necessary privileges and writable rootfs before performing writes.
   Using `G_CHECK_ROOT_USER "$@"`, if the script does not have root permissions,
   re-executes with `sudo`. "$@" passes all CLI arguments to the `sudo-ed` script.
 
-- `G_GET_NET`, `G_GET_WAN_IP` — network helpers that return standardized
+- `G_CONFIG_INJECT()` — targeted config-file editing helper. Use to atomically
+  replace, uncomment, or add config lines using predictable patterns rather
+  than ad-hoc `sed` calls.
+
+- `G_GET_NET()`, `G_GET_WAN_IP()` — network helpers that return standardized
   values; use `-q` to hide error messages.
 
-- `G_DIETPI-NOTIFY` / `G_BUG_REPORT` — helpers to generate formatted bug
+- `G_DIETPI-NOTIFY()` / `G_BUG_REPORT()` — helpers to generate formatted bug
   reports and diagnostics. Use when capturing logs for PRs / issues.
 
-#### G_WHIP specifics
-
-These details are commonly needed when implementing menus and input boxes.
-
-- `G_WHIP_INPUTBOX`:
-  - Use `$G_WHIP_INPUTBOX_REGEX` to provide an optional validation regex and
-    `$G_WHIP_INPUTBOX_REGEX_TEXT` to describe allowed input (human-friendly).
-    By default, any non-empty input is allowed.
-  - `$G_WHIP_DEFAULT_ITEM` pre-fills the input field. The helper loops until
-    input matches the regex or the user cancels (`|| return`).
-  - On success the entered value is returned in `$G_WHIP_RETURNED_VALUE`.
-
-- `G_WHIP_YESNO`:
-  - Presents a Yes/No dialog. Exit status `0` indicates Yes/Ok; non-zero is
-    No/Cancel.
-  - Use for confirmations before destructive actions. Combine with
-    `G_EXEC` for safe command execution on confirmation.
-
-- `$G_WHIP_DEFAULT_ITEM`:
-  - Controls the pre-selected menu item or prefilled input box value.
-  - When using `G_WHIP_MENU`, set it to a label matching one of the menu
-    entries to pre-select that entry (exact match is used).
-
-- `$G_WHIP_SIZE_X_MAX`:
-  - Optional integer to limit dialog width (chars). Useful for dialogs with
-    very few content or checklists, where too wide dialog boxes may look weird.
-    By default, all `G_WHIP` dialogs are max 120 characters wide, capped by the
-    terminal width.
-  - Set it before calling a `G_WHIP_*` helper; the helper respects it when
-    calculating `$WHIP_SIZE_X`.
+- `G_WHIP_*` family — dialog and UI helpers: (`G_WHIP_MSG()`, `G_WHIP_YESNO()`,
+  `G_WHIP_MENU()`, `G_WHIP_CHECKLIST()`, `G_WHIP_INPUTBOX()`, `G_WHIP_PASSWORD()`,
+  `G_WHIP_VIEWFILE()`). Prefer these for user interaction to maintain
+  consistent UX and behavior. Quick notes:
+
+  - **Return value**: `$G_WHIP_RETURNED_VALUE` holds the helper result — a
+    single value for inputbox and menus, or an array of enabled indices for checklists.
+  - **Default item**: `$G_WHIP_DEFAULT_ITEM` sets the pre-selected value. For
+    `G_WHIP_MENU()` it must exactly match a menu label.
+  - **Checklist structure**: `$G_WHIP_CHECKLIST_ARRAY` entries are triples:
+    `'tag' 'Description' 'on/off'`. Use safe tags (letters, digits, underscore)
+    to avoid parsing issues.
+  - **Enumerated checklists**: set `G_WHIP_CHECKLIST_ENUM=1` to display numeric
+    indices in the UI to avoid long, complex, or non-safe keys.
+  - **Input validation**: `G_WHIP_INPUTBOX()` supports `$G_WHIP_INPUTBOX_REGEX`
+    and `$G_WHIP_INPUTBOX_REGEX_TEXT` to validate and describe allowed input.
+    The helper loops until input matches the regex or the user cancels (`|| return`).
+  - **Dialog sizing**: use `$G_WHIP_SIZE_X_MAX` to limit dialog width; helpers
+    respect terminal width and default to a max of 120 chars.
 
 ### Menu extension pattern (safe, minimal)
 
@@ -159,7 +143,7 @@ Below are minimal, copy-paste-ready examples that follow DietPi conventions.
   G_INIT
   ```
 
-- `G_WHIP_MENU` (single choice):
+- `G_WHIP_MENU()` a menu of items the user can scroll through (choose one):
   ```
   G_WHIP_MENU_ARRAY=( 'Start' 'Start the service' 'Stop' 'Stop the service' )
   G_WHIP_DEFAULT_ITEM='Start'
@@ -170,60 +154,75 @@ Below are minimal, copy-paste-ready examples that follow DietPi conventions.
   esac
   ```
 
-- `$G_WHIP_CHECKLIST_ARRAY` (multi-select):
+- `G_WHIP_CHECKLIST()` a list of items the user can enabled/disabled (multi-select):
   ```
   G_WHIP_CHECKLIST_ARRAY=()
   G_WHIP_CHECKLIST_ARRAY+=( '5' 'Enable Foo' "${aENABLED[5]:=0}" )
   G_WHIP_CHECKLIST_ARRAY+=( '6' 'Enable Bar' "${aENABLED[6]:=0}" )
+  # Set G_WHIP_CHECKLIST_ENUM=1 to display numeric indices in the UI
   G_WHIP_CHECKLIST 'Choose features to enable:' || return
   for i in $G_WHIP_RETURNED_VALUE; do aENABLED[$i]=1; done
   Save > "$FP_SAVEFILE"
   ```
 
-- `G_WHIP_INPUTBOX` (validated input):
+- `G_WHIP_INPUTBOX()` a text entry box (validated input):
   ```
   G_WHIP_INPUTBOX_REGEX='^[0-9]+$' G_WHIP_INPUTBOX_REGEX_TEXT='a number' G_WHIP_DEFAULT_ITEM=10
   G_WHIP_INPUTBOX 'Set retry count:' || return
   RETRIES=$G_WHIP_RETURNED_VALUE
   ```
 
-- `G_WHIP_YESNO` (confirmation):
+- `G_WHIP_YESNO()` Yes/No prompt (confirmation):
   ```
   if G_WHIP_YESNO 'Delete backup?'; then
     G_EXEC rm -rf "$TARGET"
   fi
   ```
 
-- `G_WHIP_VIEWFILE` (show a logfile):
+- `G_WHIP_VIEWFILE()` displays a file that can be scrolled:
   ```
   log=1 G_WHIP_VIEWFILE "$FP_LOG" || return
   ```
 
-- `Save()` persistence pattern (follow dietpi-banner conventions):
+- `G_TRUNCATE_MID()` shorten long strings by squishing the middle characters:
+  ```
+  G_TRUNCATE_MID "Long text to be shortened by removing the middle" 26
+  # -> "Long text to... the middle"
+
+  # And `G_TRUNCATE_MID "alphabetical" N` returns the below, as N decreases
+  # alp...al
+  # al...al
+  # alphab
+  # alpha
+  # alph
+  # alp
+  ```
+
+- `Save()` example persistence pattern (beware of escape sequences):
   ```
   Save(){
-    # `echo` text to be evaluated when re-loading
-    # Call with `Save > "preference/filepath"`
+    # `echo` text to be eval-ed when re-loading
+    # Call with `Save > "preference/file/path"`
     echo "aDESCRIPTION[10]='${aDESCRIPTION[10]}'"
     for i in "${!aENABLED[@]}"; do echo "aENABLED[$i]=${aENABLED[$i]}"; done
     for i in {0..6}; do val="${aCOLOUR[$i]}"; esc=$(printf '%s' "$val" | sed $'s/\x1b/\\e/g'); esc=${esc//\'/\\\'}; echo "aCOLOUR[$i]='$esc'"; done
   }
   ```
 
-### Banner extension pattern (example)
+### DietPi-Banner extension pattern
 
-When adding banner items (e.g. `dietpi-banner`), follow this minimal pattern:
+When adding banner items, follow this minimal pattern:
 
 - Describe: add the label to `aDESCRIPTION[index]` and a default to
-  `aENABLED[index]` during initialization.
+  `aENABLED[index]` during initialization if relevant (the standard default is disabled=0).
+  If the item needs to show in the main menu checklist, add `index` to MENU_ITEMS.
 
-- Output: implement `Print_<ShortName>()` or add a guarded line in `Print_Banner_raw()`:
+- Output: implement `Get_<Shortname>()` and add a guarded line in `Print_Banner_raw()`:
   ```
-  (( ${aENABLED[index]} )) && echo -e "$GREEN_BULLET ${aCOLOUR[1]}${aDESCRIPTION[index]} $GREEN_SEPARATOR $(Print_<ShortName>)"
+  (( ${aENABLED[index]} )) && Print_Item_State "${aDESCRIPTION[index]}" "$(Get_Shortname 2>&1)"
   ```
 
-- Persist: ensure `Save()` writes `aENABLED[index]=...` and any custom
-  `aDESCRIPTION[...]` lines so the state survives restarts.
+- Persist: ensure `Save()` writes `aENABLED[index]=...` so the state survives restarts.
 
 ### Nested / multi-page menu pattern