> 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/button-behavior.md).

# Button Behavior

SmartUI Button Behavior operation and ACEs.

<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 are the foundation of every interation in SmartUI. Therefore all the button-like components inherit push buttons main features and ACE's. The behavior is applicable for any world object, but setting the animations automatically are only valid for the [Sprite ](https://www.construct.net/en/make-games/manuals/construct-3/plugin-reference/sprite)plugin. Nevertheless, the built-in animations that affect the object properties like: size, position and angle are still applicable for any world object. This gives you the possibility to add the behavior to objects like [9-Patches](https://www.construct.net/en/make-games/manuals/construct-3/plugin-reference/9-patch) and [Tiled-Backgrounds.](https://www.construct.net/en/make-games/manuals/construct-3/plugin-reference/tiled-background)

{% hint style="info" %}
By design, each state of the object can have an animation. Thus, the sprite can be set to a nicely animated sequence. Nevertheless, all the images for all the animations representing each button state must be of the same size in the canvas to render correctly.
{% endhint %}

{% hint style="info" %}
Button behavior handles the following animations: <mark style="color:purple;">**Normal**</mark> <img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2F4Dbx9ZhGozkM60FqdCm9%2Fg232638.png?alt=media&amp;token=e6893e82-8d0e-498d-9920-52ddc5e5cf30" alt="" data-size="line">, <mark style="color:green;">**Focused**</mark> <img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2F7L5p0QOB6HNydkcMGl9c%2Fg2248.png?alt=media&amp;token=4d654404-49f1-4688-9344-f252a447cbbb" alt="" data-size="line">, <mark style="color:yellow;">Hover</mark> <img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2FPvVuMrfW67P4CAHlHcBM%2Fg22538.png?alt=media&amp;token=cf0d42cd-ae63-4be4-8e6f-512c151fd84d" alt="" data-size="line">, <mark style="color:orange;">**Pressed**</mark> <img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2FNAqD6QRKHPuJm7mqSRv4%2Fg22438.png?alt=media&amp;token=17360d2f-b1f3-4b41-b625-71d6962e9aa1" alt="" data-size="line">, and <mark style="color:red;">**Disabled**</mark> <img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2FxDwHEYvMNHLatoVaHeYM%2Fg22638.png?alt=media&amp;token=0b6d536e-ab18-4de9-a645-a479723b5365" alt="" data-size="line">.
{% endhint %}

<figure><img src="https://3242409510-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9bZkqK9vYvPkvVDUO4Tp%2Fuploads%2F21xFsT0O0uXj19nbJ3kL%2Fimage.png?alt=media&amp;token=5496cb26-25c9-475d-8b19-7dc606342ab0" alt="" width="200"><figcaption><p>Sample list fo animations in a Sprite</p></figcaption></figure>

The animations work by delta, meaning they alter the object's properties by a percentage of their original state. For instance, when hovering, the button can move upwards by 5% of its height and then return to its original position.

All animations to represent each state are optional. If none are set, the object's default animation will always be displayed, but you can still apply easings to provide a polished UI.

The button also has simulation capabilities. You can simulate it being clicked or hovered, and the button will react to these actions. The conditions <mark style="color:blue;">**On-Hover**</mark> and <mark style="color:blue;">**On-Click**</mark> will also be triggered as a result of this simulation. This feature is particularly handy in contexts where you need to instruct users to interact with the UI or force an action if needed.

<details>

<summary>Download</summary>

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

</details>

## :tv: Basic Setup - Tutorial Video

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

## Properties

<table data-header-hidden><thead><tr><th width="247"></th><th></th></tr></thead><tbody><tr><td><strong>Property</strong></td><td><strong>Description</strong></td></tr><tr><td><code>Enabled</code></td><td>Enables or Disables the button.</td></tr><tr><td><code>Index</code></td><td>Index of the element within a container. Used for focusing the elements in the sequence order.</td></tr><tr><td><code>Invisible Component</code></td><td>Turns the component opacity to 0 while rendering it to allow invisible interactions.</td></tr><tr><td><code>Automatic-Color</code></td><td>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.</td></tr><tr><td><code>Name</code></td><td>Unique name string for identifying the selected button</td></tr><tr><td><code>On Hover</code></td><td>Animations when hovering</td></tr><tr><td><code>Hover Time</code></td><td>Timelapse to complete the animation in seconds.</td></tr><tr><td><code>Hover Animation</code></td><td>Hover animation Name. Case sensitive, must match the exact name of the animation. [Sprites only]</td></tr><tr><td><code>Hover Change Factor</code></td><td>Percentage to alter the object properties</td></tr><tr><td><code>On Press</code></td><td>Animations when pressing</td></tr><tr><td><code>Press Time</code></td><td>Timelapse to complete the animation in seconds.</td></tr><tr><td><code>Press Animation</code></td><td>Press animation Name. Case sensitive, must match the exact name of the animation. [Sprites only]</td></tr><tr><td><code>Press Change Factor</code></td><td>Percentage to alter the object properties</td></tr><tr><td><code>On Restore</code></td><td>Animations when restoring the button properties</td></tr><tr><td><code>Restore Time</code></td><td>Timelapse to complete the animation in seconds.</td></tr><tr><td><code>Restore Animation</code></td><td>Restore animation Name. Case sensitive, must match the exact name of the animation. [Sprites only]</td></tr><tr><td><code>Disabled Animation</code></td><td>Disabled animation Name. Case sensitive, must match the exact name of the animation. [Sprites only]</td></tr><tr><td><code>Focusable</code></td><td>Marks if the component can have the focus.</td></tr><tr><td><code>On Focus</code></td><td>Animations when focusing the button</td></tr><tr><td><code>Focus Time</code></td><td>Timelapse to complete the animation in seconds.</td></tr><tr><td><code>Focus Animation</code></td><td>Focus animation Name. Case sensitive, must match the exact name of the animation. [Sprites only]</td></tr><tr><td><code>Focus Change Factor</code></td><td>Percentage to alter the object properties</td></tr></tbody></table>

***

## <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">Smart UI Button ACEs

Smart UI Button behavior covers all the basic functionality of a Push Button, handles event animations, provides built-in animations and easings, and triggers user event interactions.&#x20;

<details>

<summary>Download</summary>

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

</details>

## Actions

***

### `Set Disabled Animation`

Sets the animation when disabling the button

| **Parameter**    | **Description**                                    |
| ---------------- | -------------------------------------------------- |
| `Animation name` | Animation name. Only applicable for Sprite objects |

### `Set Enabled`

Disable/Enable the Button

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

### `Set Focus`

Sets the focus on the component, removing the focus from all the components within the same container.

### `Set Focus Animation`

Sets the animation when focusing the button. Focus animation overrides the normal animation if the button has the focus.

| **Parameter**    | **Description**                                    |
| ---------------- | -------------------------------------------------- |
| `Animation name` | Animation name. Only applicable for Sprite objects |

### `Set Focus Change Factor`

Sets the animation when focusing the button

| **Parameter**   | **Description**                                                        |
| --------------- | ---------------------------------------------------------------------- |
| `Change Factor` | Percentage to alter the object properties. Eg. 0.5 is 50%, 0.1 is 10%. |

### `Set Focus Function`

Sets the animation when focusing the button

| **Parameter**        | **Description**                                   |
| -------------------- | ------------------------------------------------- |
| `Animation Function` | Establishes the animation function when focusing. |

### `Set Focus Time`

Sets the animation duration when focusing the button

| **Parameter** | **Description**               |
| ------------- | ----------------------------- |
| `Duration`    | Animation duration in seconds |

### `Set Focusable`

Sets the component to be able to receive the focus

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

### `Set Hover Animation`

Sets the animation when hovering the button

| **Parameter**    | **Description**                                    |
| ---------------- | -------------------------------------------------- |
| `Animation name` | Animation name. Only applicable for Sprite objects |

### `Set Hover Change Factor`

Sets the animation when hovering the button

| **Parameter**   | **Description**                                                        |
| --------------- | ---------------------------------------------------------------------- |
| `Change Factor` | Percentage to alter the object properties. Eg. 0.5 is 50%, 0.1 is 10%. |

### `Set Hover Function`

Sets the animation when hovering the button

| **Parameter**        | **Description**                                   |
| -------------------- | ------------------------------------------------- |
| `Animation Function` | Establishes the animation function when hovering. |

### `Set Hover Time`

Sets the animation duration when hovering the button

| **Parameter** | **Description**               |
| ------------- | ----------------------------- |
| `Duration`    | Animation duration in seconds |

### `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 radio button.

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

### `Set Normal Animation`

Sets the animation when restoring the button to its normal state

| **Parameter**    | **Description**                                    |
| ---------------- | -------------------------------------------------- |
| `Animation name` | Animation name. Only applicable for Sprite objects |

### `Set Press Animation`

Sets the animation when pressing the button

| **Parameter**    | **Description**                                    |
| ---------------- | -------------------------------------------------- |
| `Animation name` | Animation name. Only applicable for Sprite objects |

### `Set Press Change Factor`

Sets the animation when pressing the button

| **Parameter**   | **Description**                                                        |
| --------------- | ---------------------------------------------------------------------- |
| `Change Factor` | Percentage to alter the object properties. Eg. 0.5 is 50%, 0.1 is 10%. |

### `Set Press Function`

Sets the animation when pressing the button

| **Parameter**        | **Description**                                   |
| -------------------- | ------------------------------------------------- |
| `Animation Function` | Establishes the animation function when pressing. |

### `Set Press Time`

Sets the animation duration when pressing the button

| **Parameter** | **Description**               |
| ------------- | ----------------------------- |
| `Duration`    | Animation duration in seconds |

### `Set Restore Function`

Sets the animation when restoring the button

| **Parameter**        | **Description**                                                                     |
| -------------------- | ----------------------------------------------------------------------------------- |
| `Animation Function` | Establishes the animation function when restoring the button to its original state. |

### `Set Restore Time`

Sets the animation duration when restore the button to its original state

| **Parameter** | **Description**               |
| ------------- | ----------------------------- |
| `Duration`    | Animation duration in seconds |

### `Set Index`

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

### `Click`

Trigger the click event of the plugin, simulating the interaction of the user. Button will be locked for interactions until the animation time is completed.

### `Hover`

Trigger the hover event of the plugin, simulating the interaction of the user.

### `Stop Hover`

Stops simulating the hover state.

## Conditions

***

### `Compare Name`

Returns true if the button components name equals the parameter

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

### `Is Enabled`

Returns true if the Button is enabled

### `Is Focused`

Returns true if the Button has the focus

### `Is Hovered`

Returns true if the Button is hovering

### `Is Invisible Component`

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

### `Is Pressed`

Returns true if the Button is being pressed

### `On Click`

Triggered when the button is clicked

### `On Focus`

Triggered when the button gets the focus

### `On Focus Lost`

Triggered when the button loses focus

### `On Hover`

Triggered when the button starts hovering

### `On Hover Lost`

Triggered when the button ends hovering

### `On Pressed`

Triggered when the button started pressing.

### `On Released`

Triggered when the button is released.

## Expressions

***

### `Name`

Component name

**(c) Pixel Perfect Studio 2024**
