> For the complete documentation index, see [llms.txt](https://smartui-docs.pixelperfectstudio.mx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://smartui-docs.pixelperfectstudio.mx/framework-addons/dialogs.md).

# Dialogs

SmartUI Dialog Behavior operation and ACEs.

<img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2Fx4yaWHHTfoEqERUehPYj%2Ficon.svg?alt=media&amp;token=92ca7ead-243b-4d75-8359-56403751f4c2" alt="" data-size="line"> Dialogs are the best way to organize your UI into comprehensible and interactive containers that can be created on the fly. Keep your scene clean until you need to receive input from the user; then call a Dialog to display the required UI elements and collect the expected input.&#x20;

Dialogs inherit their properties directly from [Containers](/framework-addons/container-behavior.md). They provide the same navigation capabilities and can lock the operational context when they are modal dialogs, preventing lower z-index level components from reacting to unwanted interactions. The best thing about SmartUI Dialogs is that you can instantiate as many as you want in the same layer, allowing you to create visually well-organized, complex UI games. Dialogs are complex composite objects and are structured as listed below.

## **Composition**

1. A base container, the <img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2Fx4yaWHHTfoEqERUehPYj%2Ficon.svg?alt=media&amp;token=92ca7ead-243b-4d75-8359-56403751f4c2" alt="" data-size="line"> Dialog behavior itself.
2. Three operational <img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2FxKAFoQLyUNo848uv4SeN%2Ficon.svg?alt=media&amp;token=a5bf7e43-6e48-4f2d-b82f-2813ba41135a" alt="" data-size="line"> [buttons](/framework-addons/button-behavior.md): <mark style="color:red;">**close**</mark>, <mark style="color:yellow;">**minimize**</mark> and <mark style="color:green;">**maximize**</mark>.&#x20;
3. A minimized <img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2FxKAFoQLyUNo848uv4SeN%2Ficon.svg?alt=media&amp;token=a5bf7e43-6e48-4f2d-b82f-2813ba41135a" alt="" data-size="line"> [button](/framework-addons/button-behavior.md), that will act as an <mark style="color:yellow;">**icon**</mark>.

{% hint style="warning" %} <mark style="color:orange;">**These buttons are completely optional**</mark><mark style="color:orange;">;</mark> you can still control the dialog through the available ACEs. However, it is recommended to include at least a close button to provide users with a way to dismiss the dialog.
{% endhint %}

<figure><img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2FVA7qS22u7silTxEtsfFn%2Fimage.png?alt=media&amp;token=bd43a8e7-c49e-4dd4-b174-5452bf88cfad" alt="" width="563"><figcaption><p>Dialog composition</p></figcaption></figure>

All of its components must be children of the dialog container. Each component must have a unique *<mark style="color:blue;">**component name**</mark>* within the hierarchy to properly interact with the dialog behavior. The Dialog Behavior must be the top-most object in the hierarchy.

{% hint style="warning" %}
Dialogs are not draggable natively. By design, this feature was omitted with the assumption that the [Drag and Drop ](https://www.construct.net/en/make-games/manuals/construct-3/behavior-reference/drag-drop)behavior could cover this functionality. It's up to the developer to decide if this feature should be present.
{% endhint %}

{% hint style="info" %}
Dialogs can be used in 3D layers, and all of their children support coordinate translation to 3D planes. To ensure correct rendering, it is recommended to set the *<mark style="color:blue;">**Draw Order**</mark>* to be <mark style="color:green;">**z-Ordered**</mark>. See [layers ](https://www.construct.net/en/make-games/manuals/construct-3/project-primitives/layers)documentation for more details.
{% endhint %}

<figure><img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2FMdVPDLqoz0JmzYO0GRXA%2Fimage.png?alt=media&amp;token=79ec38d4-432e-49a3-ae2b-19da2e32222d" alt=""><figcaption><p>3D Layer draw order set to z-Order</p></figcaption></figure>

Another key feature of dialogs is that they don't need to be included in the same layout that you are designing. You can create a separate layout to store all your dialog designs, known as a [prefab layout](#user-content-fn-1)[^1]*,* and create an instance of the dialog only when needed. This can help save memory and processing power in your game.

<figure><img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2FKKAatkdhjErA4rM6QLni%2Fimage.png?alt=media&amp;token=25931e91-62a2-4be4-a83a-10af5135d8b2" alt="" width="375"><figcaption><p>Two different dialog windows are designed in a separate layout, like a prefab. </p></figcaption></figure>

To open a dialog, you must call the <mark style="color:green;">**Open Dialog**</mark> action from the [Smart UI plugin](/framework-addons/smart-ui-plugin.md). This action is analogous to the <mark style="color:blue;">**Create Object**</mark> action from the system plugin. The main difference is that **Open Dialog** triggers the events to animate the dialog opening, using any of the custom easings. Dialogs support templates, so you can reuse the same components to compose a dialog with different functionality.

\
Being able to create dialogs with the <mark style="color:blue;">**Create Object**</mark> action provides an additional level of control over how they are presented. You can customize the animations to suit your needs.

{% hint style="warning" %}
Please be aware that all the children of the <mark style="color:orange;">**component must have change propagation enabled for all attributes**</mark>: visible, opacity, x, y, width, height, etc. Otherwise, you will need to manually control the children's attributes.
{% endhint %}

<figure><img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2FLG7wPMMADuggH5RmlCNk%2Fimage.png?alt=media&amp;token=c6cf5652-a4b4-47ba-87d9-9682331183d9" alt="" width="235"><figcaption><p>Properties transformation should be enabled to render children correctly.</p></figcaption></figure>

## Modal Dialogs

Modal dialogs are capable of locking interactions of other SmartUI components to only the components that belong to them. This is a convenient way to focus users' attention on a particular interaction. For instance, notification windows, opening a reward chest, or character dialogs are examples of such uses. The SmartUI Dialog behavior offers this capability, which is commonly available in all UI frameworks.

When this feature is enabled, the dialog will restrict interaction to only its children. Any SmartUI component below the dialog will not be interactable until the dialog closes.

{% hint style="info" %}
Modal dialogs are stackable in the Smart UI framework. The top-most visible dialog will be the one in control.
{% endhint %}

<details>

<summary>Download</summary>

<https://store.pixelperfectstudio.mx/product/smart-ui-ncbeta/>

</details>

## :tv: Video Demo&#x20;

{% embed url="<https://youtu.be/wTzRdk7EbD0>" %}

## :tv: Basic Setup - Tutorial Video

{% embed url="<https://youtu.be/uYTKQy8nwh8>" %}

## Properties

| **Property**             | **Description**                                                                                                                                                                                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Enabled`                | Enables or Disables the dialog and all its children.                                                                                                                                                                                                       |
| `Index`                  | Index of the dialog within layout. Used for focusing the elements in the sequence order.                                                                                                                                                                   |
| `Invisible Component`    | Turns the component opacity to 0 while rendering it to allow invisible interactions.                                                                                                                                                                       |
| `Focusable`              | Marks if the component can have the focus.                                                                                                                                                                                                                 |
| `Automatic-Color`        | Enables the component to darken a bit when its state is Disabled or when it's focused. Auto-Color is meant to provide a quick identification of the component state. For more specialized customizations, use the component events and disable this check. |
| `Name`                   | Unique name string for identifying the dialog                                                                                                                                                                                                              |
| `Auto-focus Child`       | Upon receiving focus, it transfers the focus to the immediately available child component. If no valid component is found, it will navigate through the available inner containers to locate the next valid element.                                       |
| `Modal`                  | Sets the dialog to modal-dialog, locking the interactions with any of the UI components underneath.                                                                                                                                                        |
| `Auto-close`             | Closes the dialog automatically whenever a touch is registered outside the collision polygon of the dialog.                                                                                                                                                |
| `Minimized Icon`         | Container object name that represents the minimized dialog.                                                                                                                                                                                                |
| `Close Button Name`      | Button's name to reference from the dialog.                                                                                                                                                                                                                |
| `Maximize Button Name`   | Button's name to reference from the dialog.                                                                                                                                                                                                                |
| `Max.Mode`               | Scale mode when maximizing the Dialog                                                                                                                                                                                                                      |
| `Minimize Button Name`   | Button's name to reference from the dialog.                                                                                                                                                                                                                |
| `Open Animation`         | Opening animation                                                                                                                                                                                                                                          |
| `Open Animation Easing`  | Easing function for the opening animation.                                                                                                                                                                                                                 |
| `Open Animation time`    | Time in seconds to complete the animation.                                                                                                                                                                                                                 |
| `Close Animation`        | Closing animation                                                                                                                                                                                                                                          |
| `Close Animation Easing` | Easing function for the closing animation.                                                                                                                                                                                                                 |
| `Close Animation time`   | Time in seconds to complete the animation.                                                                                                                                                                                                                 |

## <img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2Fx4yaWHHTfoEqERUehPYj%2Ficon.svg?alt=media&amp;token=92ca7ead-243b-4d75-8359-56403751f4c2" alt="" data-size="line"> Smart UI Dialog Behavior ACEs

Smart UI Dialog behavior groups UI components, provides focusing abilities and default interactions to navigate within the dialog and its children components that uses Smart UI behaviors, and handles cascading Enabling/Disabling events. It also responds to pointer interactions prioritizing by zIndex.&#x20;

## Actions

***

### `Close`

Closes the dialog.

### `Focus First Element`

Request the focus for the first interactable element of the dialog.

### `Focus Last Element`

Request the focus for the last interactable element of the dialog.

### `Maximize`

Maximize the dialog.

### `Minimize`

Minimizes the dialog.

### `Restore`

Restores the dialog.

### `Set Auto-focus Child`

Indicates if the focus should be passed to the first available child, upon receiving focus.

| **Parameter** | **Description**  |
| ------------- | ---------------- |
| `Enabled`     | Enabled/Disabled |

### `Set Enabled`

Disable/Enable the Button

| **Parameter** | **Description**  |
| ------------- | ---------------- |
| `Enabled`     | Enabled/Disabled |

### `Set Focus`

Request the focus for this dialog

### `Set Focusable`

Disable/Enable the Button

| **Parameter** | **Description**                            |
| ------------- | ------------------------------------------ |
| `Focusable`   | Flag to allow the component to be focused. |

### `Set Invisible Component`

Turns the component opacity to 0 while rendering it to allow invisible interactions.

| **Parameter**         | **Description**                                                   |
| --------------------- | ----------------------------------------------------------------- |
| `Invisible Component` | Set if the component processed even if it's invisible: True/False |

### `Set Name`

Sets the name of the component.

| **Parameter** | **Description**       |
| ------------- | --------------------- |
| `Name`        | Name of the component |

### `Set Sequence`

Sets the sequence index to influence the selection of components.

| **Parameter** | **Description**                                                                                |
| ------------- | ---------------------------------------------------------------------------------------------- |
| `Index`       | Sequence index value. E.g. Indexes values of 0 are processed before indexes values of 1 and 2. |

## Conditions

***

### `Has Control`

True if the dialog has the control to navigate over components.

### `Compare Name`

Returns true if the radio button components name equals the parameter

| **Parameter** | **Description**                            |
| ------------- | ------------------------------------------ |
| `Name`        | Name to compare with the component picked. |

### `Is Enabled`

Returns true if the dialog is enabled

### `Is Focused`

Returns true if the Button has the focus

### `Is Invisible Component`

Returns true if the Button is configured as an invisible component.

### `Is Maximized`

Returns true if the dialog is Maximized

### `Is Minimized`

Returns true if the dialog is Minimized

### `Is Open`

Returns true if the dialog is Open

### `On Close`

Triggered when the dialog closes. If it's animated, it triggers when the animation finishes.

### `On Focus`

Triggered when the dialog gets the focus

### `On Focus Lost`

Triggered when the dialog loses focus

### `On Maximize`

Triggered when the dialog maximizes

### `On Minimize`

Triggered when the dialog minimizes

### `On Open`

Triggered when the dialog opens. If it's animated, it triggers when the animation finishes.

### `On Restore`

Triggered when the dialog restores back to its original state.

## Expressions

***

### `Name`

Component name

**(c) Pixel Perfect Studio 2025**

[^1]: Prefabs do not exist in Construct, but we use this concept to categorize pre-fabricated objects.