Knowledgebase

User Tools

Site Tools

You are here: HOME » tools » dialog_creator_documentation
tools:dialog_creator_documentation

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
tools:dialog_creator_documentation [2026/07/23 12:39] – rocktools:dialog_creator_documentation [2026/07/23 15:55] (current) – rock
Line 1: Line 1:
-===== Tutorial: Animated Button =====+====== Arma 3 Dialog Creator User Guide ====== 
 + 
 +===== What This Tool Creates ===== 
 + 
 +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/cancel workflows. 
 +  * **HUD / Turret Optics:** overlay-style resources for reticles, range ladders, sensor/weapon status, lock cues, compass tapes, and ''RscTitles''-style HUD output. 
 + 
 +The tool creates the static display structure. Your addon still owns the runtime behavior: SQF population, validation, multiplayer authority, object selection, and gameplay changes. 
 + 
 +===== The Core Idea ===== 
 + 
 +An Arma UI normally has two layers of work: 
 + 
 +  * **HPP/config:** declares the display class and its controls. 
 +  * **SQF:** fills controls with live data, reacts to clicks, validates input, and applies changes. 
 + 
 +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 and in-game testing. 
 + 
 +===== Quick Start With Reasons ===== 
 + 
 +  - Open [[http://dialogcreator.rkslstudios.info/]]. 
 +    * **Why:** the tool is file-backed and runs in the browser. There is no database or install step. 
 +  - Choose ''Dialog UI'' or ''HUD / Turret Optics''. 
 +    * **Dialog UI** means the player interacts with controls: buttons, lists, edit boxes, maps, checkboxes. 
 +    * **HUD / Turret Optics** means the UI is mostly an overlay: reticle, range ladder, headings, lock state, sensor state. 
 +    * **Why:** the chosen mode changes the defaults, wizards, and export assumptions. 
 +  - Fill in the left setup panel before building. 
 +    * **Why:** class names, IDD, IDC ranges, and namespace keys are the contract between config and SQF. Changing them late can break scripts that already reference them. 
 +  - Add controls with the palette or guided wizards. 
 +    * **Palette:** use when you know the exact ''Rsc*'' control you want. 
 +    * **Workflow wizards:** use when you want a complete pattern with related controls and notes. 
 +  - Place controls visually, then refine in the inspector. 
 +    * **Why:** dragging is fast for rough layout, but exact X/Y/W/H values are better for repeatable addon work. 
 +  - 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 ''action'' strings and lifecycle hooks call functions. If those functions are missing, the display may open but behavior will fail. 
 +  - 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. 
 + 
 +===== Setup Fields: What They Mean ===== 
 + 
 +==== Class ==== 
 + 
 +The top-level display or resource class name in the generated HPP. 
 + 
 +**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. 
 + 
 +==== IDD ==== 
 + 
 +The display ID. 
 + 
 +**Why it matters:** Arma uses IDD values to identify displays. Collisions with other displays can make scripts target the wrong display or fail unpredictably. 
 + 
 +==== Namespace key ==== 
 + 
 +The ''uiNamespace'' variable used by generated ''onLoad'' and ''onUnload''. 
 + 
 +**Why it matters:** ''uiNamespace'' lets SQF find the live display after it opens. ''onUnload'' must clear the reference so scripts do not hold stale display handles. 
 + 
 +==== IDC start ==== 
 + 
 +The first positive control ID used for interactive controls. 
 + 
 +**Why it matters:** SQF finds controls with ''displayCtrl IDC_NAME''. Static controls should normally use ''idc = -1''; controls that SQF reads or modifies need positive unique IDC values. 
 + 
 +==== Surface ==== 
 + 
 +  * ''Dialog / RscDisplay'': for interactive UI opened as a dialog/display. 
 +  * ''RscTitles overlay'': for persistent HUD-style overlay resources. 
 + 
 +**Why it matters:** overlays use different lifecycle expectations from interactive dialogs. A turret optic/status display normally belongs closer to ''RscTitles'' behavior. 
 + 
 +==== Canvas ratio ==== 
 + 
 +The browser preview aspect ratio. 
 + 
 +**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. 
 + 
 +==== Safezone output ==== 
 + 
 +Exports positions as safezone-relative expressions. 
 + 
 +**Why it matters:** safezone output adapts to UI scaling and aspect ratio better than raw screen constants. It still needs in-game testing. 
 + 
 +==== Export defines ==== 
 + 
 +Generates ''#define'' constants for the display ID and positive IDC values. 
 + 
 +**Why it matters:** named constants are safer than scattered numeric literals. They make SQF and config easier to audit. 
 + 
 +==== Snap to grid and Grid step ==== 
 + 
 +Controls placement increments when moving, resizing, and keyboard nudging. 
 + 
 +**Why it matters:** consistent grid values produce cleaner HPP and reduce near-miss alignment issues. 
 + 
 +===== Canvas: How To Use It ===== 
 + 
 +  * **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:** copies the selected control and offsets it slightly. 
 +  * **Delete:** removes the selected control. 
 +  * **Reorder:** use layer up/down in the layer list. 
 +  * **Lock:** prevents accidental mouse movement/resizing. 
 +  * **Hide:** visually dims the control in the editor but keeps it in the project/export. 
 +  * **Zoom:** use mouse wheel or the ''-'' / ''+'' controls. 
 +  * **Pan:** drag empty canvas space. 
 +  * **Reset view:** click ''100''. 
 + 
 +**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 ''RscText'', ''RscPicture'', ''RscButton'', ''RscListbox''. 
 +  * **IDC:** positive value for controls accessed by SQF; ''-1'' for static controls. 
 +  * **Text / texture:** visible text for text/buttons or texture path for ''RscPicture''. 
 +  * **X/Y/W/H:** normalized left/top/width/height values. 
 +  * **Style:** numeric Arma style flags. Use only when you know the base class expects them. 
 +  * **sizeEx:** text size. Browser preview is approximate; test in game. 
 +  * **Font:** Arma font class. 
 +  * **colorText[]:** text color or picture tint. 
 +  * **colorBackground[]:** background color array. 
 +  * **Tooltip:** in-game tooltip shown on hover. 
 +  * **Action:** button action string. 
 +  * **Background control:** places the control in ''controlsBackground''. 
 +  * **Visible:** hides/dims the control in the editor preview. 
 +  * **Locked:** prevents mouse move/resize. 
 + 
 +String fields commit when you leave the box or press Enter. This avoids redrawing picture/background controls on every keypress while editing long paths. 
 + 
 +===== Image Preview ===== 
 + 
 +''RscPicture'' controls can preview local ''PNG'', ''JPG/JPEG'', or ''TGA'' files. 
 + 
 +  - Select an ''RscPicture''. 
 +  - Set ''Text / texture'' to the Arma texture path that will be exported. 
 +  - Use ''Choose preview'' to pick a local PNG, JPG, or TGA. 
 +  - Use the preview to align and size the image. 
 + 
 +**Why preview is separate from texture path:** Arma commonly uses ''.paa'', but browsers do not display ''.paa''. A local PNG/JPG/TGA preview lets you design visually while still exporting the real Arma texture path. 
 + 
 +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 ''Dialog UI''. 
 +    * **Why:** a dialog background normally belongs to an interactive display, not a HUD overlay. 
 +  - Open ''Workflow'' and choose ''Create Background Image''. 
 +    * **What this creates:** an ''RscPicture'' control with ''background = true''. 
 +  - Enter a class name such as ''Dialog_Background''. 
 +    * **Why:** class names should explain purpose. This helps when reading exported HPP later. 
 +  - Enter the Arma texture path, for example ''\myAddon\ui\dialog_background_ca.paa''. 
 +    * **What this means:** this becomes ''text = "\myAddon\ui\dialog_background_ca.paa";'' in the HPP. 
 +    * **Common mistake:** using a Windows path like ''C:\...''. Arma needs an addon-relative path. 
 +  - 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 ''controlsBackground''. 
 +  - Optional: choose a local PNG/JPG/TGA preview. 
 +    * **Why:** preview helps align the image without requiring the browser to read ''.paa''. 
 +  - Keep ''idc = -1'' unless SQF needs to access the picture. 
 +    * **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 ''Create Button''. 
 +    * **What this creates:** an ''RscButton'' with text, tooltip, position, and action string. 
 +  - Give it a short visible label such as ''Apply''. 
 +    * **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 ''['apply', _this] call TAG_fnc_dialogAction''. 
 +    * **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/disable state, or runtime updates. 
 +  - Implement the called function in your addon. 
 +    * **Common mistake:** exporting a button that calls ''TAG_fnc_dialogAction'' before that function exists in ''CfgFunctions''. 
 +  - Validate before changing gameplay state. 
 +    * **Why:** dialog code runs locally. Multiplayer-sensitive actions need locality/authority checks outside the UI. 
 + 
 +===== Animated Button ===== 
 **Goal:** make a button visibly react to hover. **Goal:** make a button visibly react to hover.
 +
   - Choose ''Create Animated Button''.   - Choose ''Create Animated Button''.
     * **What this creates:** a button with mouse-enter/mouse-exit event strings using fade/commit behavior.     * **What this creates:** a button with mouse-enter/mouse-exit event strings using fade/commit behavior.
Line 9: Line 205:
   - Test the result in Arma.   - Test the result in Arma.
     * **Why:** inherited control classes, parent display behavior, and UI scale can change how fade/commit appears.     * **Why:** inherited control classes, parent display behavior, and UI scale can change how fade/commit appears.
-===== Tutorial: Dropdown With Options =====+ 
 +===== Dropdown With Options ===== 
 **Goal:** let the user choose one value from a controlled list. **Goal:** let the user choose one value from a controlled list.
 +
   - Choose ''Create Dropdown''.   - Choose ''Create Dropdown''.
     * **What this creates:** an ''RscCombo'' plus generated notes for row population.     * **What this creates:** an ''RscCombo'' plus generated notes for row population.
Line 24: Line 223:
   - Read selected data on Apply.   - Read selected data on Apply.
     * **Why:** reading only the visible text can break if labels change.     * **Why:** reading only the visible text can break if labels change.
-===== Tutorial: Apply / Reset / Cancel Dialog =====+ 
 +===== Apply / Reset / Cancel Dialog ===== 
 **Goal:** build a predictable dialog where the user can edit values safely before committing them. **Goal:** build a predictable dialog where the user can edit values safely before committing them.
 +
   - Create a panel layout.   - Create a panel layout.
     * **Why:** a stable frame/header/body/footer makes the dialog easier to scan and extend.     * **Why:** a stable frame/header/body/footer makes the dialog easier to scan and extend.
Line 43: Line 245:
   - Apply changes only after validation succeeds.   - Apply changes only after validation succeeds.
     * **Why:** users should not partially mutate gameplay state by simply typing into fields.     * **Why:** users should not partially mutate gameplay state by simply typing into fields.
-===== Tutorial: Map Selector =====+ 
 +===== Map Selector ===== 
 **Goal:** let the user choose a world position from a map control. **Goal:** let the user choose a world position from a map control.
 +
   - Choose ''Create Map Selector''.   - Choose ''Create Map Selector''.
     * **What this creates:** a map control plus supporting controls for the selected output.     * **What this creates:** a map control plus supporting controls for the selected output.
Line 55: Line 260:
   - Validate the selected position.   - Validate the selected position.
     * **Why:** spawning, teleporting, targeting, and artillery-style actions can break gameplay if the point is invalid or unauthorized.     * **Why:** spawning, teleporting, targeting, and artillery-style actions can break gameplay if the point is invalid or unauthorized.
-===== Tutorial: HUD / Turret Optics Overlay =====+ 
 +===== HUD / Turret Optics Overlay ===== 
 **Goal:** create a readable overlay for a gunner, camera, sensor, or turret view. **Goal:** create a readable overlay for a gunner, camera, sensor, or turret view.
 +
   - Choose ''HUD / Turret Optics''.   - Choose ''HUD / Turret Optics''.
     * **Why:** this mode assumes overlay behavior and ''RscTitles''-style output rather than an interactive dialog.     * **Why:** this mode assumes overlay behavior and ''RscTitles''-style output rather than an interactive dialog.
Line 69: Line 277:
   - Test in the target vehicle/turret camera.   - Test in the target vehicle/turret camera.
     * **Why:** browser preview cannot reproduce FOV, camera shake, optics post-processing, thermal contrast, or game UI scaling.     * **Why:** browser preview cannot reproduce FOV, camera shake, optics post-processing, thermal contrast, or game UI scaling.
-===== Export And Addon Integration =====+ 
 +==== Export And Addon Integration ==== 
   - Copy or download the generated HPP.   - Copy or download the generated HPP.
   - Include it from your addon ''config.cpp'' or UI include file.   - Include it from your addon ''config.cpp'' or UI include file.
Line 80: Line 290:
   - Open the display in game.   - Open the display in game.
   - Review the RPT for config and script errors.   - Review the RPT for config and script errors.
-===== Common Problems =====+ 
 +==== 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/function.   * **The display opens but buttons do nothing:** the action function probably is not registered or the event string points at the wrong tag/function.
   * **A control cannot be found by SQF:** it may have ''idc = -1'', a duplicate IDC, or a define mismatch.   * **A control cannot be found by SQF:** it may have ''idc = -1'', a duplicate IDC, or a define mismatch.
Line 87: Line 299:
   * **Dropdown labels work but behavior is wrong:** SQF may be reading visible text instead of stable row data.   * **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/server path.   * **Multiplayer action works locally but not for other players:** the button runs on the local client and needs a validated remote/server path.
-===== Pre-Pack Checklist =====+ 
 +==== Pre-Pack Checklist ==== 
   * Display class is included from the intended config root.   * Display class is included from the intended config root.
   * IDD does not collide with another display.   * IDD does not collide with another display.
Line 99: Line 313:
   * Layout is checked at 16:9, 16:10, 21:9, and narrow windowed ratios.   * 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.   * MP-sensitive actions validate locality and authority outside the UI layer.
 +
 +
tools/dialog_creator_documentation.1784810389.txt.gz · Last modified: by rock

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial 4.0 International
CC Attribution-Noncommercial 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki