Knowledgebase

This is an old revision of the document!

---

# 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 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.

## Quick Start

1. Open `http://192.168.1.20/dialog_creator/`.
2. Choose `Dialog UI` or `HUD / Turret Optics`.
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/action stubs into SQF.

## Project Setup Fields

- Class: top-level display or resource class name.
- IDD: display ID. Keep this stable and avoid collisions with other addon displays.
- Namespace key: `uiNamespace` variable used by generated `onLoad` and `onUnload` hooks.
- IDC start: first positive IDC assigned to interactive controls.
- Surface: use `Dialog / RscDisplay` for interactive screens and `RscTitles overlay` for HUD-style overlays.
- 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

- Add: click a control type in the left palette.
- Select: click a control or its layer entry.
- Move: drag the selected 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 mouse move/resize but keeps the control selectable.
- Hide: lowers visibility in the editor preview but keeps the control in the project and export.
- Zoom: mouse wheel or the `-` / `+` buttons.
- Pan: drag empty canvas space.
- Reset view: press `100`.

## Inspector Fields

- Class: generated config class. Use stable names once SQF refers to them.
- Base class: inherited Arma UI class such as `RscText`, `RscPicture`, or `RscButton`.
- IDC: positive ID for controls read by SQF; use `-1` for static controls.
- Text / texture: visible text for text/buttons or texture path for pictures.
- X, Y, W, H: normalized canvas position and size.
- Style: numeric Arma style flags.
- sizeEx: text size.
- Font: Arma font class.
- colorText[] and colorBackground[]: Arma color arrays.
- 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.

## Image Preview

`RscPicture` controls can preview local `PNG`, `JPG/JPEG`, or `TGA` files.

1. Select an `RscPicture` control.
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 to HPP, and not saved into project JSON. It is only a browser-side visual aid.

## Tutorial: Background Image

1. Choose `Dialog UI`.
2. Open `Workflow` and select `Create Background Image`.
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

1. Open `Workflow` and choose `Create Button`.
2. Give it a short visible label such as `Apply`.
3. Use a short action string such as `['apply', _this] call TAG_fnc_dialogAction`.
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

1. Open `Workflow` and choose `Create Animated Button`.
2. Set the visible text, action, and location.
3. The wizard creates hover fade/commit event handlers.
4. Keep the animation lightweight because it runs on the local client UI.
5. Test in game because UI fade behavior can vary with parent display and control base class.

## Tutorial: Dropdown With Options

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

1. Use `Create Panel Layout` for the backing panel.
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

1. Open `Workflow` and choose `Create Map Selector`.
2. Position the map region and the coordinate/output controls.
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

1. Choose `HUD / Turret Optics`.
2. Use workflow wizards for reticle, range ladder, compass/azimuth tape, status block, and vision/lock cues.
3. Keep most backgrounds transparent.
4. Use consistent colors and sizes so the overlay is readable over day/night/thermal imagery.
5. Export as an overlay resource and test in the target turret/vehicle camera.

## Export And Addon Integration

1. Copy or download the generated HPP.
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/action functions through `CfgFunctions`.
7. Test the display in game and review the RPT for config or script errors.

## 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.