Differences

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

--- tools:dialog_creator_documentation [2026/07/23 12:39] – rock
+++ tools:dialog_creator_documentation [2026/07/23 15:55] (current) – rock
@@ Line 1: / Line 1: @@
 ====== 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://192.168.1.20/dialog_creator/''.
+  - 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''.
@@ Line 32: / Line 40: @@
   - 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.
+  - Choose ''Create Animated Button''.
+    * **What this creates:** a button with mouse-enter/mouse-exit event strings using fade/commit behavior.
+  - 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 ''Create Dropdown''.
+    * **What this creates:** an ''RscCombo'' plus generated notes for row population.
+  - Enter options one per line.
+    * **Simple format:** ''Display Text''
+    * **Stable data format:** ''Display Text=internalValue''
+  - 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 ''displayCtrl''.
+  - Populate rows on ''onLoad''.
+    * **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/header/body/footer makes the dialog easier to scan and extend.
+  - Add input controls.
+    * **Examples:** edit fields for text/numbers, combos for controlled choices, checkboxes for binary settings, listboxes for larger selections.
+  - 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:** ''['apply', _this] call TAG_fnc_dialogAction''.
+    * **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:** numeric range checks, class existence checks, object locality, selected row data, map position validity.
+  - 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 ''Create Map Selector''.
+    * **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 ''ctrlMapScreenToWorld''.
+    * **Why:** the mouse click is screen/control space; gameplay systems usually need world position.
+  - Validate the selected position.
+    * **Why:** spawning, teleporting, targeting, and artillery-style actions can break gameplay if the point is invalid or unauthorized.
+===== HUD / Turret Optics Overlay =====
+**Goal:** create a readable overlay for a gunner, camera, sensor, or turret view.
+  - Choose ''HUD / Turret Optics''.
+    * **Why:** this mode assumes overlay behavior and ''RscTitles''-style output rather than an interactive dialog.
+  - Add a reticle first.
+    * **Why:** the reticle anchors the viewer's attention and sets the center reference.
+  - Add range ladder, heading/compass tape, weapon status, sensor mode, and lock cues.
+    * **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/turret camera.
+    * **Why:** browser preview cannot reproduce FOV, camera shake, optics post-processing, thermal contrast, or game UI scaling.
+==== Export And Addon Integration ====
+  - Copy or download the generated HPP.
+  - Include it from your addon ''config.cpp'' or UI include file.
+  - Confirm all inherited base classes exist where the HPP is included.
+  - Register lifecycle and action functions in ''CfgFunctions''.
+  - Keep static panels, frames, labels, and pictures in ''controlsBackground''.
+  - Keep interactive controls in ''controls''.
+  - 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/function.
+  * **A control cannot be found by SQF:** it may have ''idc = -1'', a duplicate IDC, or a define mismatch.
+  * **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/aspect ratio differs from the browser preview.
+  * **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.
+==== Pre-Pack Checklist ====
+  * Display class is included from the intended config root.
+  * IDD does not collide with another display.
+  * Positive IDC values are unique within the display.
+  * Static controls use ''idc = -1'' unless SQF reads them.
+  * ''onLoad'' publishes the display to ''uiNamespace''.
+  * ''onUnload'' clears the display reference.
+  * Button/event strings call registered functions.
+  * Lists, combos, and trees store stable row data.
+  * Texture paths exist in the packed addon.
+  * 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.

Knowledgebase

User Tools

Site Tools

Differences

Page Tools