diff --git a/.gitignore b/.gitignore index f81b589b..8ada2b59 100644 --- a/.gitignore +++ b/.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 ## =============== diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 00000000..b569e8f1 --- /dev/null +++ b/.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": [] + } + + ] +} diff --git a/Documentation/CHM-BUILD.bat b/Documentation/CHM-BUILD.bat new file mode 100644 index 00000000..dfdadaf0 --- /dev/null +++ b/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 diff --git a/Documentation/German/CHM/PureBasic.chm b/Documentation/German/CHM/PureBasic.chm new file mode 100644 index 00000000..206a015e Binary files /dev/null and b/Documentation/German/CHM/PureBasic.chm differ diff --git a/Documentation/German/Reference/ide_form.txt b/Documentation/German/Reference/ide_form.txt index 03def840..6b4962cd 100644 --- a/Documentation/German/Reference/ide_form.txt +++ 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. diff --git a/config.json b/config.json new file mode 100644 index 00000000..6a57f376 --- /dev/null +++ b/config.json @@ -0,0 +1,10 @@ +{ + "PureBasicPath": "C:\\PureBasic", + "_comment_PureBasicPath": "Path to the PureBasic installation directory. WARNING: During compilation, PureBasic.exe is overwritten/updated in this directory. Use a dedicated PureBasic install if you want to avoid modifying your main installation.", + + "HhcPath": "C:\\Program Files (x86)\\HTML Help Workshop\\hhc.exe", + "_comment_HhcPath": "Full path to hhc.exe (Microsoft HTML Help Workshop). Required for CHM compilation." +} + + +