This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
| tools:dialog_creator_documentation [2026/07/23 12:27] – created rock | tools:dialog_creator_documentation [2026/07/23 15:55] (current) – rock | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | <code -> | + | ====== |
| - | # Arma 3 Dialog Creator User Guide | + | |
| - | ## What This Tool Creates | + | ===== What This Tool Creates |
| Arma 3 Dialog Creator builds config-ready HPP for two related UI surfaces: | Arma 3 Dialog Creator builds config-ready HPP for two related UI surfaces: | ||
| - | - Dialog UI: interactive displays with buttons, edit boxes, listboxes, dropdowns, map controls, panels, and apply/ | + | * **Dialog UI:** interactive displays with buttons, edit boxes, listboxes, dropdowns, map controls, panels, and apply/ |
| - | - HUD / Turret Optics: overlay-style resources for reticles, range ladders, sensor/ | + | * **HUD / Turret Optics:** overlay-style resources for reticles, range ladders, sensor/ |
| - | The tool edits a browser project and exports text. It does not pack a PBO, validate base classes from your addon, or test the UI in Arma. Always test the exported display in game. | + | The tool creates the static display structure. Your addon still owns the runtime behavior: SQF population, validation, multiplayer authority, object selection, and gameplay changes. |
| - | ## Quick Start | + | ===== The Core Idea ===== |
| - | 1. Open `http:// | + | An Arma UI normally has two layers of work: |
| - | 2. Choose `Dialog | + | |
| - | 3. Set the display class, IDD, namespace key, IDC start, surface, and canvas ratio in the left panel. | + | |
| - | 4. Add controls from the left palette or choose a guided wizard from `Workflow`. | + | |
| - | 5. Drag controls on the canvas to move them. Drag the bottom-right handle to resize. | + | |
| - | 6. Use the right inspector for exact class names, IDC values, positions, sizes, colors, actions, and tooltips. | + | |
| - | 7. Use mouse wheel to zoom the canvas and drag empty canvas space to pan. | + | |
| - | 8. Open `Export`, then copy or download the generated HPP. | + | |
| - | 9. Include the HPP from your addon config and wire the generated lifecycle/ | + | |
| - | ## Project Setup Fields | + | * **HPP/ |
| + | * **SQF:** fills controls with live data, reacts to clicks, validates input, and applies changes. | ||
| - | - Class: top-level display or resource class name. | + | This tool helps with the first layer and gives notes for the second. It cannot prove that your addon include path, inherited base classes, texture paths, or SQF functions exist. That still needs addon-side validation |
| - | - IDD: display ID. Keep this stable and avoid collisions | + | |
| - | - Namespace key: `uiNamespace` variable used by generated `onLoad` and `onUnload` hooks. | + | |
| - | - IDC start: | + | |
| - | - Surface: use `Dialog / RscDisplay` for interactive screens | + | |
| - | - Canvas ratio: preview aspect ratio. Check common ratios such as 16:9, 16:10, 21:9, and narrow windowed layouts. | + | |
| - | - Safezone output: exports safezone-based expressions instead of raw normalized coordinates. | + | |
| - | - Export defines: writes `#define` constants for IDD and positive IDC values. | + | |
| - | - Snap to grid and Grid step: control move/resize increments. | + | |
| - | ## Canvas Controls | + | ===== Quick Start With Reasons ===== |
| - | - Add: click a control type in the left palette. | + | |
| - | - Select: click a control | + | * **Why:** the tool is file-backed and runs in the browser. There is no database or install step. |
| - | - Move: drag the selected control. | + | - Choose '' |
| - | - Resize: drag the bottom-right handle. | + | * **Dialog UI** means the player interacts with controls: buttons, lists, edit boxes, maps, checkboxes. |
| - | - Duplicate: copies | + | * **HUD / Turret Optics** means the UI is mostly an overlay: reticle, range ladder, headings, lock state, sensor state. |
| - | - Delete: removes | + | * **Why:** the chosen mode changes the defaults, wizards, and export assumptions. |
| - | - Reorder: use layer up/ | + | - Fill in the left setup panel before building. |
| - | - Lock: prevents mouse move/ | + | * **Why:** class names, IDD, IDC ranges, and namespace keys are the contract between config |
| - | - Hide: lowers visibility in the editor preview but keeps the control in the project | + | - Add controls with the palette or guided wizards. |
| - | - Zoom: mouse wheel or the `-` / `+` buttons. | + | * **Palette:** use when you know the exact '' |
| - | - Pan: drag empty canvas space. | + | * **Workflow wizards:** use when you want a complete pattern with related controls and notes. |
| - | - Reset view: press `100`. | + | - Place controls visually, then refine |
| + | * **Why:** dragging is fast for rough layout, | ||
| + | - Export HPP and include it from your addon config. | ||
| + | * **Why:** Arma reads displays from config. The exported HPP is not active until included by a real addon or mission config. | ||
| + | - Implement or connect the generated SQF function names. | ||
| + | * **Why:** button '' | ||
| + | - Test in game and read the RPT. | ||
| + | * **Why:** browser preview can catch layout mistakes, but only Arma can confirm inherited classes, safezone behavior, texture loading, control events, and script errors. | ||
| - | ## Inspector | + | ===== Setup Fields: What They Mean ===== |
| - | - Class: generated config class. Use stable names once SQF refers to them. | + | ==== Class ==== |
| - | - Base class: inherited Arma UI class such as `RscText`, `RscPicture`, | + | |
| - | - IDC: positive ID for controls read by SQF; use `-1` for static controls. | + | |
| - | - Text / texture: visible text for text/ | + | |
| - | - X, Y, W, H: normalized canvas position and size. | + | |
| - | - Style: numeric Arma style flags. | + | |
| - | - sizeEx: text size. | + | |
| - | - Font: Arma font class. | + | |
| - | - colorText[] and colorBackground[]: | + | |
| - | - Tooltip: in-game tooltip text. | + | |
| - | - Action: button action string. | + | |
| - | - Background control: sends the control to `controlsBackground`. | + | |
| - | String fields commit when you leave the box or press Enter. Numeric fields update live. | + | The top-level display |
| - | ## Image Preview | + | **Why it matters:** this is how the display is opened or referenced from config. Keep it stable and unique, usually with your addon tag or prefix. |
| - | `RscPicture` controls can preview local `PNG`, `JPG/JPEG`, or `TGA` files. | + | ==== IDD ==== |
| - | 1. Select an `RscPicture` control. | + | The display ID. |
| - | 2. Set `Text / texture` to the Arma texture path that should be exported. | + | |
| - | 3. Use `Choose preview` to pick a local image file. | + | |
| - | 4. The preview appears in the inspector and canvas. | + | |
| - | The preview file is not uploaded, not written | + | **Why it matters:** Arma uses IDD values |
| - | ## Tutorial: Background Image | + | ==== Namespace key ==== |
| - | 1. Choose `Dialog UI`. | + | The '' |
| - | 2. Open `Workflow` | + | |
| - | 3. Enter a class name such as `Dialog_Background`. | + | |
| - | 4. Enter the Arma texture path, for example `\myAddon\ui\dialog_background_ca.paa`. | + | |
| - | 5. Set X/Y/W/H to cover the desired area. | + | |
| - | 6. Create the control. | + | |
| - | 7. Select the new picture and use `Choose preview` if you have a PNG, JPG, or TGA reference. | + | |
| - | 8. Keep `Background control` enabled and `IDC = -1` unless SQF must access it. | + | |
| - | ## Tutorial: Button With Action | + | **Why it matters:** '' |
| - | 1. Open `Workflow` and choose `Create Button`. | + | ==== IDC start ==== |
| - | 2. Give it a short visible label such as `Apply`. | + | |
| - | 3. Use a short action string such as `[' | + | |
| - | 4. Create the button and position it on the canvas. | + | |
| - | 5. In your addon, implement the function called by the action string. | + | |
| - | 6. Validate MP-sensitive behavior outside the UI before changing gameplay state. | + | |
| - | ## Tutorial: Animated Button | + | The first positive control ID used for interactive controls. |
| - | 1. Open `Workflow` and choose `Create Animated Button`. | + | **Why it matters:** SQF finds controls with '' |
| - | 2. Set the visible text, action, and location. | + | |
| - | 3. The wizard creates hover fade/commit event handlers. | + | |
| - | 4. Keep the animation lightweight because | + | |
| - | 5. Test in game because UI fade behavior can vary with parent display and control base class. | + | |
| - | ## Tutorial: Dropdown With Options | + | ==== Surface ==== |
| - | 1. Open `Workflow` and choose `Create Dropdown`. | + | * '' |
| - | 2. Enter options one per line. | + | * '' |
| - | 3. Use `Label=stableData` when the visible label is not the value your SQF should use. | + | |
| - | 4. Export the HPP. | + | |
| - | 5. Use the generated lifecycle notes to populate options during `onLoad`. | + | |
| - | 6. Read selected data with list/combo APIs rather than relying only on visible text. | + | |
| - | ## Tutorial: Apply / Reset / Cancel Dialog | + | **Why it matters:** overlays use different lifecycle expectations from interactive dialogs. A turret optic/status display normally belongs closer to '' |
| - | 1. Use `Create Panel Layout` for the backing panel. | + | ==== Canvas ratio ==== |
| - | 2. Add the required fields: edit boxes, dropdowns, listboxes, checkboxes, or map controls. | + | |
| - | 3. Use `Create Apply / Reset / Cancel Row`. | + | |
| - | 4. Keep each button action short and route it into a registered function. | + | |
| - | 5. In SQF, read all fields, validate them, then apply changes. | + | |
| - | 6. Reset should restore the UI state without mutating gameplay state unexpectedly. | + | |
| - | 7. Cancel should close the display or discard pending local state. | + | |
| - | ## Tutorial: Map Selector | + | The browser preview aspect ratio. |
| - | 1. Open `Workflow` and choose `Create Map Selector`. | + | **Why it matters:** Arma users may run 16:9, 16:10, 21:9, or windowed layouts. A panel that looks correct at one ratio can overlap or drift at another. |
| - | 2. Position the map region and the coordinate/ | + | |
| - | 3. Export the HPP. | + | |
| - | 4. In SQF, use the generated map-click guidance and convert clicks with `ctrlMapScreenToWorld`. | + | |
| - | 5. Validate selected positions before using them for spawning, targeting, teleporting, or mission logic. | + | |
| - | ## Tutorial: HUD / Turret Optics Overlay | + | ==== Safezone output ==== |
| - | 1. Choose `HUD / Turret Optics`. | + | Exports positions |
| - | 2. Use workflow wizards for reticle, range ladder, compass/ | + | |
| - | 3. Keep most backgrounds transparent. | + | |
| - | 4. Use consistent colors and sizes so the overlay is readable over day/ | + | |
| - | 5. Export | + | |
| - | ## Export And Addon Integration | + | **Why it matters:** safezone output adapts to UI scaling and aspect ratio better than raw screen constants. It still needs in-game testing. |
| - | 1. Copy or download the generated HPP. | + | ==== Export defines ==== |
| - | 2. Include it from your addon `config.cpp` or an included UI HPP. | + | |
| - | 3. Confirm all inherited base classes exist where the HPP is included. | + | |
| - | 4. Keep `controlsBackground` for static panels, labels, frames, and pictures. | + | |
| - | 5. Keep interactive controls in `controls`. | + | |
| - | 6. Register lifecycle/ | + | |
| - | 7. Test the display in game and review the RPT for config or script errors. | + | |
| - | ## Pre-Pack Checklist | + | Generates '' |
| - | - Display class is included from the intended config root. | + | **Why it matters:** named constants are safer than scattered numeric literals. They make SQF and config easier to audit. |
| - | - IDD does not collide with another display. | + | |
| - | - Positive IDC values are unique within the display. | + | ==== Snap to grid and Grid step ==== |
| - | - Static controls use `idc = -1` unless SQF reads them. | + | |
| - | - `onLoad` publishes the display to `uiNamespace`. | + | Controls placement increments when moving, resizing, and keyboard nudging. |
| - | - `onUnload` clears the display reference. | + | |
| - | - Button/ | + | **Why it matters:** consistent grid values produce cleaner HPP and reduce near-miss alignment issues. |
| - | - Lists, combos, and trees store stable row data. | + | |
| - | - Texture paths exist in the packed addon. | + | ===== Canvas: How To Use It ===== |
| - | - Layout is checked at 16:9, 16:10, 21:9, and narrow windowed ratios. | + | |
| - | - MP-sensitive actions validate locality and authority outside the UI layer. | + | * **Add:** click a control type in the left palette. |
| - | </ | + | * **Select:** click a control or its layer entry. |
| + | * **Move:** drag the control. | ||
| + | * **Resize:** drag the bottom-right handle. | ||
| + | * **Duplicate: | ||
| + | * **Delete:** removes the selected control. | ||
| + | * **Reorder: | ||
| + | * **Lock:** prevents accidental mouse movement/ | ||
| + | * **Hide:** visually dims the control in the editor but keeps it in the project/ | ||
| + | * **Zoom:** use mouse wheel or the '' | ||
| + | * **Pan:** drag empty canvas space. | ||
| + | * **Reset view:** click '' | ||
| + | |||
| + | **Why zoom/pan does not affect export:** the tool transforms only the browser preview. The actual control coordinates remain normalized 0..1 layout values. | ||
| + | |||
| + | ===== Inspector Fields: What They Mean ===== | ||
| + | |||
| + | * **Class:** the generated control class name. Use stable, readable names. | ||
| + | * **Base class:** the inherited Arma control class, such as '' | ||
| + | * **IDC:** positive value for controls accessed by SQF; '' | ||
| + | * **Text / texture:** visible text for text/ | ||
| + | * **X/ | ||
| + | * **Style:** numeric Arma style flags. Use only when you know the base class expects them. | ||
| + | * **sizeEx:** text size. Browser preview is approximate; | ||
| + | * **Font:** Arma font class. | ||
| + | * **colorText[]: | ||
| + | * **colorBackground[]: | ||
| + | * **Tooltip: | ||
| + | * **Action:** button action string. | ||
| + | * **Background control:** places the control in '' | ||
| + | * **Visible: | ||
| + | * **Locked:** prevents mouse move/ | ||
| + | |||
| + | String fields commit when you leave the box or press Enter. This avoids redrawing picture/ | ||
| + | |||
| + | ===== Image Preview ===== | ||
| + | |||
| + | '' | ||
| + | |||
| + | - Select an '' | ||
| + | - Set '' | ||
| + | - Use '' | ||
| + | - Use the preview to align and size the image. | ||
| + | |||
| + | **Why preview is separate from texture path:** Arma commonly uses '' | ||
| + | |||
| + | The preview file is not uploaded, not written to HPP, and not saved into project JSON. | ||
| + | |||
| + | ====== Tutorial ====== | ||
| + | |||
| + | ===== Background Image ===== | ||
| + | |||
| + | **Goal:** create a non-interactive picture or panel behind the rest of the dialog. | ||
| + | |||
| + | - Choose '' | ||
| + | * **Why:** a dialog background normally belongs to an interactive display, not a HUD overlay. | ||
| + | - Open '' | ||
| + | * **What this creates:** an '' | ||
| + | - Enter a class name such as '' | ||
| + | * **Why:** class names should explain purpose. This helps when reading exported HPP later. | ||
| + | - Enter the Arma texture path, for example '' | ||
| + | * **What this means:** this becomes '' | ||
| + | * **Common mistake:** using a Windows path like '' | ||
| + | - Set X/Y/W/H. | ||
| + | * **Why:** these values define where the picture sits in normalized display space. | ||
| + | * **Tip:** use a broad backing image first, then add smaller frames or labels above it. | ||
| + | - Create the control. | ||
| + | * **What happens:** it appears on the canvas and is exported in '' | ||
| + | - Optional: choose a local PNG/JPG/TGA preview. | ||
| + | * **Why:** preview helps align the image without requiring the browser to read '' | ||
| + | - Keep '' | ||
| + | * **Why:** static art does not need a positive IDC. Saving positive IDCs for live controls keeps SQF lookup clean. | ||
| + | |||
| + | ===== Button With Action ===== | ||
| + | |||
| + | **Goal:** add a button that calls SQF when clicked. | ||
| + | |||
| + | - Choose '' | ||
| + | * **What this creates:** an '' | ||
| + | - Give it a short visible label such as '' | ||
| + | * **Why:** buttons should use short verbs. Longer explanations belong in tooltips or nearby text. | ||
| + | - Set a tooltip. | ||
| + | * **Why:** tooltips explain the consequence without making the button large. | ||
| + | - Use a short action string such as '' | ||
| + | * **What this means:** the UI passes a command key and Arma event arguments to a function. | ||
| + | * **Why:** short event strings are easier to debug than large inline SQF blocks. | ||
| + | - Give the button a positive IDC. | ||
| + | * **Why:** interactive controls may need lookup, enable/ | ||
| + | - Implement the called function in your addon. | ||
| + | * **Common mistake:** exporting a button that calls '' | ||
| + | - Validate before changing gameplay state. | ||
| + | * **Why:** dialog code runs locally. Multiplayer-sensitive actions need locality/ | ||
| + | |||
| + | ===== Animated Button ===== | ||
| + | |||
| + | **Goal:** make a button visibly react to hover. | ||
| + | |||
| + | - Choose '' | ||
| + | * **What this creates:** a button with mouse-enter/ | ||
| + | - Set the visible text and action. | ||
| + | * **Why:** hover animation should not replace the actual click behavior. | ||
| + | - Keep the animation subtle. | ||
| + | * **Why:** UI animation runs locally and can become distracting or expensive if overused. | ||
| + | - Test the result in Arma. | ||
| + | * **Why:** inherited control classes, parent display behavior, and UI scale can change how fade/commit appears. | ||
| + | |||
| + | ===== Dropdown With Options ===== | ||
| + | |||
| + | **Goal:** let the user choose one value from a controlled list. | ||
| + | |||
| + | - Choose '' | ||
| + | * **What this creates:** an '' | ||
| + | - Enter options one per line. | ||
| + | * **Simple format:** '' | ||
| + | * **Stable data format:** '' | ||
| + | - Use stable data when possible. | ||
| + | * **Why:** visible labels are for the user and may be renamed or translated. SQF should read stable data keys. | ||
| + | - Give the combo a positive IDC. | ||
| + | * **Why:** the lifecycle function needs to find it with '' | ||
| + | - Populate rows on '' | ||
| + | * **Why:** lists and combos are normally filled by SQF when the display opens, especially if options depend on mission state. | ||
| + | - Read selected data on Apply. | ||
| + | * **Why:** reading only the visible text can break if labels change. | ||
| + | |||
| + | ===== Apply / Reset / Cancel Dialog ===== | ||
| + | |||
| + | **Goal:** build a predictable dialog where the user can edit values safely before committing them. | ||
| + | |||
| + | - Create a panel layout. | ||
| + | * **Why:** a stable frame/ | ||
| + | - Add input controls. | ||
| + | * **Examples: | ||
| + | - Add Apply / Reset / Cancel buttons. | ||
| + | * **Apply** means validate and commit. | ||
| + | * **Reset** means restore UI values. | ||
| + | * **Cancel** means close or discard pending local state. | ||
| + | - Route all buttons into a function. | ||
| + | * **Example: | ||
| + | * **Why:** one dispatcher function can handle all dialog commands consistently. | ||
| + | - In SQF, read values by IDC. | ||
| + | * **Why:** IDC lookup is stable and does not depend on visual layer order. | ||
| + | - Validate before applying. | ||
| + | * **Examples: | ||
| + | - Apply changes only after validation succeeds. | ||
| + | * **Why:** users should not partially mutate gameplay state by simply typing into fields. | ||
| + | |||
| + | ===== Map Selector ===== | ||
| + | |||
| + | **Goal:** let the user choose a world position from a map control. | ||
| + | |||
| + | - Choose '' | ||
| + | * **What this creates:** a map control plus supporting controls for the selected output. | ||
| + | - Position the map area. | ||
| + | * **Why:** map controls usually need more space than text controls. Avoid squeezing them into small panels. | ||
| + | - Use a click event to capture screen position. | ||
| + | * **What this means:** SQF receives the map click event and converts it to world coordinates. | ||
| + | - Convert with '' | ||
| + | * **Why:** the mouse click is screen/ | ||
| + | - Validate the selected position. | ||
| + | * **Why:** spawning, teleporting, | ||
| + | |||
| + | ===== HUD / Turret Optics Overlay ===== | ||
| + | |||
| + | **Goal:** create a readable overlay for a gunner, camera, sensor, or turret view. | ||
| + | |||
| + | - Choose '' | ||
| + | * **Why:** this mode assumes overlay behavior and '' | ||
| + | - Add a reticle first. | ||
| + | * **Why:** the reticle anchors the viewer' | ||
| + | - Add range ladder, heading/ | ||
| + | * **Why:** these are supporting cues around the reticle. They should not obscure the target. | ||
| + | - Use transparent backgrounds by default. | ||
| + | * **Why:** optics must be readable over terrain, sky, smoke, thermal imagery, and night vision. | ||
| + | - Use backing plates only where readability needs them. | ||
| + | * **Why:** too many opaque panels reduce situational awareness. | ||
| + | - Test in the target vehicle/ | ||
| + | * **Why:** browser preview cannot reproduce FOV, camera shake, optics post-processing, | ||
| + | |||
| + | ==== Export And Addon Integration ==== | ||
| + | |||
| + | - Copy or download the generated HPP. | ||
| + | - Include it from your addon '' | ||
| + | - Confirm all inherited base classes exist where the HPP is included. | ||
| + | - Register lifecycle and action functions in '' | ||
| + | - Keep static panels, frames, labels, and pictures in '' | ||
| + | - Keep interactive controls in '' | ||
| + | - Check IDD and IDC collisions. | ||
| + | - Pack the addon. | ||
| + | - Open the display in game. | ||
| + | - Review the RPT for config and script errors. | ||
| + | |||
| + | ==== Common Problems ==== | ||
| + | |||
| + | * **The display opens but buttons do nothing:** the action function probably is not registered or the event string points at the wrong tag/ | ||
| + | * **A control cannot be found by SQF:** it may have '' | ||
| + | * **A picture does not show in game:** the texture path may be wrong, the file may not be packed, or the image may need conversion to PAA. | ||
| + | * **Layout looks wrong in game:** safezone/UI scale/ | ||
| + | * **Dropdown labels work but behavior is wrong:** SQF may be reading visible text instead of stable row data. | ||
| + | * **Multiplayer action works locally but not for other players:** the button runs on the local client and needs a validated remote/ | ||
| + | |||
| + | ==== Pre-Pack Checklist ==== | ||
| + | |||
| + | * Display class is included from the intended config root. | ||
| + | | ||
| + | | ||
| + | | ||
| + | * '' | ||
| + | * '' | ||
| + | | ||
| + | | ||
| + | | ||
| + | | ||
| + | | ||