Docs/form designer enhancements

.gitignore

@@ -22,6 +22,16 @@ Documentation/English/HTML
 Documentation/French/HTML
 Documentation/German/HTML
 
+## ==================
+## CHM Help Previews
+## ==================
+Documentation/English/CHM/*
+Documentation/French/CHM/*
+Documentation/German/CHM/*
+!Documentation/English/CHM/PureBasic.chm
+!Documentation/French/CHM/PureBasic.chm
+!Documentation/German/CHM/PureBasic.chm
+
 ## ===============
 ## Misc Work Files
 ## ===============

.vscode/tasks.json

@@ -0,0 +1,99 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Build: MakeWindows.cmd",
+            "type": "shell",
+            "command": "powershell",
+            "args": [
+                "-ExecutionPolicy", "Bypass",
+                "-NoProfile",
+                "-Command",
+                "$config = Get-Content ..\\config.json | ConvertFrom-Json; cmd /c MakeWindows.cmd $config.PureBasicPath"
+            ],
+            "options": {
+                "cwd": "${workspaceFolder}\\PureBasicIDE"
+            },
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "problemMatcher": []
+        },
+
+        {
+            "label": "Docs: Build HTML (de)",
+            "type": "shell",
+            "command": "powershell",
+            "args": [
+                "-ExecutionPolicy", "Bypass",
+                "-NoProfile",
+                "-Command",
+                "$config = Get-Content ${workspaceFolder}\\config.json | ConvertFrom-Json; env:PUREBASIC_HOME = $config.PureBasicPath; cmd /c HTML-BUILD.bat de"
+            ],
+            "options": {
+                "cwd": "${workspaceFolder}\\Documentation"
+            },
+            "group": "build",
+            "problemMatcher": []
+        },
+        {
+            "label": "Docs: Build HTML (all)",
+            "type": "shell",
+            "command": "powershell",
+            "args": [
+                "-ExecutionPolicy", "Bypass",
+                "-NoProfile",
+                "-Command",
+                "$config = Get-Content ${workspaceFolder}\\config.json | ConvertFrom-Json; $env:PUREBASIC_HOME = $config.PureBasicPath; cmd /c HTML-BUILD.bat all"
+            ],
+            "options": {
+                "cwd": "${workspaceFolder}\\Documentation"
+            },
+            "group": "build",
+            "problemMatcher": []
+        },
+        {
+            "label": "Docs: Build CHM (de)",
+            "type": "shell",
+            "command": "powershell",
+            "args": [
+                "-ExecutionPolicy", "Bypass",
+                "-NoProfile",
+                "-Command",
+                "$config = Get-Content ${workspaceFolder}\\config.json | ConvertFrom-Json; $env:PUREBASIC_HOME = $config.PureBasicPath; if ($config.HhcPath) { $env:HHC = $config.HhcPath }; cmd /c CHM-BUILD.bat de"
+            ],
+            "options": {
+                "cwd": "${workspaceFolder}\\Documentation"
+            },
+            "group": "build",
+            "problemMatcher": []
+        },
+        {
+            "label": "Docs: Build CHM (all)",
+            "type": "shell",
+            "command": "powershell",
+            "args": [
+                "-ExecutionPolicy", "Bypass",
+                "-NoProfile",
+                "-Command",
+                "$config = Get-Content ${workspaceFolder}\\config.json | ConvertFrom-Json; $env:PUREBASIC_HOME = $config.PureBasicPath; if ($config.HhcPath) { $env:HHC = $config.HhcPath }; cmd /c CHM-BUILD.bat all"
+            ],
+            "options": {
+                "cwd": "${workspaceFolder}\\Documentation"
+            },
+            "group": "build",
+            "problemMatcher": []
+        },
+        {
+            "label": "Docs: Build HTML+CHM (de)",
+            "dependsOrder": "sequence",
+            "dependsOn": [
+                "Docs: Build HTML (de)",
+                "Docs: Build CHM (de)"
+            ],
+            "problemMatcher": []
+        }
+
+    ]
+}

Documentation/CHM-BUILD.bat

@@ -0,0 +1,179 @@
+:: "Documentation\CHM-BUILD.bat" | v1.0.0 | 2026/02/03
+:: Builds PureBasic CHM help files via DocMaker + HTML Help Workshop (hhc.exe).
+
+@ECHO OFF
+setlocal enableExtensions enableDelayedExpansion
+
+ECHO.
+ECHO ##############################################################################
+ECHO #                                                                            #
+ECHO # PureBasic Help CHM Builder                                                 #
+ECHO #                                                                            #
+ECHO ##############################################################################
+
+IF [%1]==[] GOTO :Instructions
+
+:: Check that DocMaker is available:
+CALL :FindDocMaker
+IF NOT EXIST !DocMaker! GOTO :DocMakerNotFound
+
+:: Check that HTML Help Workshop compiler (hhc.exe) is available:
+CALL :FindHhc
+IF NOT EXIST !Hhc! GOTO :HhcNotFound
+
+:: Track which locales will be converted:
+SET _DE=0
+SET _EN=0
+SET _FR=0
+
+IF /I %1==de  SET _DE=1
+IF /I %1==en  SET _EN=1
+IF /I %1==fr  SET _FR=1
+IF /I %1==all (
+  SET _DE=1
+  SET _EN=1
+  SET _FR=1
+)
+
+:: Carry out the actual conversions:
+IF !_DE! EQU 1 CALL :DocMakerBuild German
+IF !_EN! EQU 1 CALL :DocMakerBuild English
+IF !_FR! EQU 1 CALL :DocMakerBuild French
+
+GOTO :EndScript
+
+
+:DocMakerBuild
+SET "outDir=%~dp0%~1\CHM"
+
+ECHO.
+ECHO Building PureBasic %~1 CHM: ".\%~1\CHM\"
+
+RD /Q /S "!outDir!" >nul 2>&1
+MD "!outDir!" >nul 2>&1
+
+:: DocMaker CLI parameters per official DocMaker Help:
+:: /CHM requires /HTMLWORKSHOP with full path to hhc.exe
+!DocMaker! ^
+  /DOCUMENTATIONPATH "%~dp0" ^
+  /OUTPUTPATH "!outDir!" ^
+  /LANGUAGE %~1 ^
+  /FORMAT Html ^
+  /OS Windows ^
+  /CHM ^
+  /HTMLWORKSHOP !Hhc!
+
+IF ERRORLEVEL 1 EXIT /B 1
+
+:: Fallback: If DocMaker produced a .hhp but no .chm (depends on setup),
+:: try compiling the generated project via hhc.exe directly.
+SET hasChm=0
+FOR /F "delims=" %%F IN ('dir /b /a:-d "!outDir!\*.chm" 2^>nul') DO SET hasChm=1
+
+IF !hasChm! EQU 0 (
+  FOR /F "delims=" %%P IN ('dir /b /a:-d "!outDir!\*.hhp" 2^>nul') DO (
+    ECHO No CHM found yet - compiling "%%P" via hhc.exe ...
+    !Hhc! "!outDir!\%%P"
+  )
+)
+
+EXIT /B
+
+
+:Instructions
+ECHO Missing parameter! Invoke me with one of (de^|en^|fr^|all):
+ECHO.
+ECHO de  -- Builds German CHM in: "German\CHM\"
+ECHO en  -- Builds English CHM in: "English\CHM\"
+ECHO fr  -- Builds French CHM in: "French\CHM\"
+ECHO all -- Builds all three locales.
+ECHO.
+ECHO Notes:
+ECHO  - CHM requires HTML Help Workshop (hhc.exe) and DocMaker's /HTMLWORKSHOP parameter.
+ECHO  - You can override the hhc.exe path via environment variable HHC, e.g.:
+ECHO      set HHC=C:\Program Files (x86)\HTML Help Workshop\hhc.exe
+GOTO :EndScript
+
+
+:FindHhc
+:: Allow user override: set HHC=full\path\hhc.exe
+IF DEFINED HHC SET Hhc="!HHC!"
+IF EXIST !Hhc! EXIT /B
+
+:: Default installation paths:
+SET Hhc="!ProgramFiles(x86)!\HTML Help Workshop\hhc.exe"
+IF EXIST !Hhc! EXIT /B
+
+SET Hhc="!ProgramFiles!\HTML Help Workshop\hhc.exe"
+IF EXIST !Hhc! EXIT /B
+
+EXIT /B
+
+
+:FindDocMaker
+:: This logic mirrors Documentation\HTML-BUILD.bat (DocMaker discovery).
+:: Check if !DocMaker! is already valid:
+IF EXIST !DocMaker! EXIT /B
+
+:: Default location:
+SET DocMaker="!ProgramFiles!\PureBasic\SDK\DocMaker\DocMaker.exe"
+IF EXIST !DocMaker! EXIT /B
+
+:: Relative to !PUREBASIC_HOME! (used in other build scripts):
+SET DocMaker="!PUREBASIC_HOME!\SDK\DocMaker\DocMaker.exe"
+IF EXIST !DocMaker! EXIT /B
+
+:: Relative to environmental variables set for IDE tools:
+CALL :ExtractProgramDir !PB_TOOL_IDE!
+SET DocMaker="!ProgramDir!\SDK\DocMaker\DocMaker.exe"
+IF EXIST !DocMaker! EXIT /B
+
+CALL :ExtractProgramDir !PB_TOOL_Compiler!
+SET DocMaker="!ProgramDir!\..\SDK\DocMaker\DocMaker.exe"
+IF EXIST !DocMaker! EXIT /B
+
+:: Read the command line created by IDE to open PureBasic files from explorer.exe:
+FOR /f "Skip=2 Tokens=*" %%i IN ( 'Reg Query HKEY_CURRENT_USER\Software\Classes\PureBasic.exe\shell\open\command /ve' ) DO (
+  SET str=%%i
+  CALL :ExtractProgramDir !str:*REG_SZ =!
+)
+
+SET DocMaker="!ProgramDir!SDK\DocMaker\DocMaker.exe"
+IF EXIST !DocMaker! EXIT /B
+
+EXIT /B
+
+
+:ExtractProgramDir
+SET ProgramDir=%~dp1
+EXIT /B
+
+
+:DocMakerNotFound
+ECHO *** ERROR!!! *** Couldn't find DocMaker at the expected path:
+ECHO.
+ECHO !DocMaker!
+ECHO.
+ECHO This script needs a standard PureBasic installation to be present on the system.
+ECHO /// Aborting conversion ///
+GOTO :EndScript
+
+
+:HhcNotFound
+ECHO *** ERROR!!! *** Couldn't find HTML Help Workshop compiler (hhc.exe).
+ECHO.
+ECHO Looked for:
+ECHO   - Environment variable HHC
+ECHO   - "!ProgramFiles(x86)!\HTML Help Workshop\hhc.exe"
+ECHO   - "!ProgramFiles!\HTML Help Workshop\hhc.exe"
+ECHO.
+ECHO Install "HTML Help Workshop" and/or set:
+ECHO   set HHC=full\path\to\hhc.exe
+ECHO /// Aborting conversion ///
+GOTO :EndScript
+
+
+:EndScript
+:: Only pause before quitting if the script was launched via File Explorer:
+ECHO "!cmdcmdline!" | FINDSTR /IC:"%~0" >nul && PAUSE
+EXIT /B

Documentation/German/Reference/ide_form.txt

@@ -46,7 +46,45 @@
 
   This panel list all available gadgets. Select one, and draw directly on the form the size needed. When
   a gadget is selected on the form, its properties are display on this panel and can be modified here.
-
+
+@Section Advanced code generation options
+
+@Bold "Explicit IDs via Variable (Name=Number)"
+@LineBreak
+  To force stable numeric IDs for a window or gadget, enter:
+  Name=Number (for example: ID13310=13310 or Dlg=133) in the "Variable" property.
+  The Form Designer will generate an explicit assignment in the enumeration:
+@LineBreak
+@Code
+  Enumeration FormGadget
+    #ID13310 = 13310
+  EndEnumeration
+@EndCode
+@LineBreak
+  Note: If no '=' is used, behavior is unchanged (backward compatible).
+@LineBreak
+@LineBreak
+
+@Bold "Custom parent window (=expression)"
+@LineBreak
+  The window "Parent" value can be a raw expression by prefixing it with '='.
+  In this case :contentReference[oaicite:20]{index=20}ll pass the expression directly (no WindowID(...) wrapper).
+@LineBreak
+@LineBreak
+
+@Bold "Custom Flags"
+@LineBreak
+  The window property "Cust:contentReference[oaicite:21]{index=21}tional flags separated by '|'.
+  These flags are appended to the generated OpenWindow() flags.
+  Custom flags do not affect the visual rendering inside the Form Designer.
+@LineBreak
+@LineBreak
+
+@Bold "FrameGadget as container (#PB_Frame_Container)"
+@LineBreak
+  FrameGadget supports the flag #PB_Frame_Container. If set, the FrameGadget is treated as a container
+  and can be used as a parent for other gadgets.
+
 @Section Using the form designer in real world projects
 
   The form designer has been created to allow modular forms and easy maintenance. Each form has to be
@@ -162,7 +200,45 @@
   Sie direkt auf dem Formular die benötigte Größe. Wenn ein Gadget auf dem Formular ausgewählt
   wird, dann werden seine Eigenschaften auf dieser Leiste angezeigt und können auch hier
   verändert werden.
-
+
+@Section Erweiterte Optionen der Codegenerierung
+
+@Bold "Explizite IDs über Variable (Name=Nummer)"
+@LineBreak
+  Um feste numerische IDs für Fenster oder Gadgets zu erzwingen, kann im Property "Variable"
+  die Syntax Name=Nummer verwendet werden (z.B. ID13310=13310 oder Dlg=133).
+  Der Form-Designer generiert dann eine explizite Zuweisung in der Enumeration:
+@LineBreak
+@Code
+  Enumeration FormGadget
+    #ID13310 = 13310
+  EndEnumeration
+@EndCode
+@LineBreak
+  Hinweis: Ohne '=' bleibt das Verhalten unverändert (abwärtskompatibel).
+@LineBreak
+@LineBreak
+
+@Bold "Benutzerdefinierter Parent (=Ausdruck)"
+@LineBreak
+  Der Fenster-Parent kann als „roher“ Ausdruck angegeben werden, indem er mit '=' beginnt.
+  In diesem Fall wird der Ausdruck im generierten Code direkt übergeben (ohne WindowID(...)-Wrapper).
+@LineBreak
+@LineBreak
+
+@Bold "Custom Flags"
+@LineBreak
+  Das Fenster-Property "Custom Flags" erlaubt zusätzliche Flags, getrennt durch '|'.
+  Diese Flags werden an die generierten OpenWindow()-Flags angehängt.
+  Custom Flags beeinflussen nicht die Darstellung im Form-Designer.
+@LineBreak
+@LineBreak
+
+@Bold "FrameGadget als Container (#PB_Frame_Container)"
+@LineBreak
+  FrameGadget unterstützt das Flag #PB_Frame_Container. Wenn es gesetzt ist, wird das FrameGadget
+  als Container behandelt und kann als Parent für andere Gadgets verwendet werden.
+
 @Section Verwendung des Form-Designers in echten Projekten
 
   Der Form-Designer wurde erschaffen, um modulare Formulare und deren einfache Wartung zu ermöglichen.