> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/~/changes/eYCCpn9cCBKOYnZA6a8f/building-apps/ui-widgets-and-elements.md).

# UI widgets & elements

Learn how to build user interfaces and what widgets are.

The user interface can be built with three main components:

1. [Dynamic widgets](#dynamic-widgets) that capture data or display data.
2. [Button ](/~/changes/eYCCpn9cCBKOYnZA6a8f/building-apps/ui-widgets-and-elements/buttons.md)widget that captures user clicks as events.
3. Static widgets (elements) like [text boxes](/~/changes/eYCCpn9cCBKOYnZA6a8f/building-apps/ui-widgets-and-elements/text-box.md), [icons](/~/changes/eYCCpn9cCBKOYnZA6a8f/building-apps/ui-widgets-and-elements/icons.md) and [images](/~/changes/eYCCpn9cCBKOYnZA6a8f/building-apps/ui-widgets-and-elements/images.md).

{% hint style="info" %}
Building an actual user interface is optional. Apps consisting of pure logic work, too.
{% endhint %}

## Dynamic widgets

Dynamic widgets are the key elements to build interactive user interfaces. There are [input widgets](/~/changes/eYCCpn9cCBKOYnZA6a8f/building-apps/ui-widgets-and-elements/input-widgets.md) to capture data, [display widgets](/~/changes/eYCCpn9cCBKOYnZA6a8f/building-apps/ui-widgets-and-elements/display-widgets.md) to visualize data and [buttons](/~/changes/eYCCpn9cCBKOYnZA6a8f/building-apps/ui-widgets-and-elements/buttons.md) to capture user events.

### Managing widgets

To place a widget, navigate to the widget bar (<img src="https://3495989837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE5Ketpww1s7TauSAJrJ8%2Fuploads%2FQviskkPfhgRVHeWUatJo%2Fimage.png?alt=media&amp;token=fe23dde4-914a-4d2a-b45a-69eadd7fbb6c" alt="" data-size="line">), pick a widget and click in the UI editor to place it.

<figure><img src="https://3495989837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE5Ketpww1s7TauSAJrJ8%2Fuploads%2FAJwr6RFvGL6I67Gci32p%2FAnimation.gif?alt=media&amp;token=6ea1357d-e4cd-419c-8a91-85cbed28ae30" alt="" width="563"><figcaption><p>Placing a widget</p></figcaption></figure>

Moving, resizing and rotating a widget works as known from other tools. Select the widgets first and simply move it, or grab and move one of the grab markers.

<figure><img src="https://3495989837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE5Ketpww1s7TauSAJrJ8%2Fuploads%2FIxO7yCRxt4xdjV36DW7o%2FWidget.gif?alt=media&amp;token=4bd8954f-e36b-40a5-b967-d6cfd8600a4a" alt="" width="563"><figcaption><p>Moving, resizing and rotating a widget</p></figcaption></figure>

{% hint style="warning" %}
Changing position, size, or rotation of widgets may or may not affect the widget on other [screens sizes](/~/changes/eYCCpn9cCBKOYnZA6a8f/building-apps/app-appearance/screens-and-devices.md). You are advised to check each preview individually.
{% endhint %}

### Configuring widget interactions

Widgets are “stupid” and contain no logic of their own. However, some can receive **commands**, some can send **events**, some have **properties** that they can pass to the logic and some have properties that can be set by the logic. Each widget is different and allows different interactions.

#### Properties

A widgets property represents a state that a widget can hold and persist until changed again. This state can either be set by the application logic with a `set` property or by the user, typically then passed back to the logic with a  `get` property.

Most widgets are limited to either setting or getting properties, while others, like the [data grid](/~/changes/eYCCpn9cCBKOYnZA6a8f/building-apps/ui-widgets-and-elements/display-widgets/data-grid-wip.md), support both directions. For example, the data grid can display data (via `set` from the logic) and also transfer data that a user adds or modifies within the grid via `get` to the logic.

To set a property from the logic, you must connect an output or a modifier to the widget. To receive a property in the logic, you need to connect a widget to an an input.

The following table provides an overview of properties:

<table><thead><tr><th width="123">Interaction</th><th width="177">Links</th><th width="224">Description</th><th width="244">Examples</th></tr></thead><tbody><tr><td><code>set</code> property</td><td>Function output or modifier with widget</td><td>Provides a property to a widget to change the data shown. The widget will keep the property until it is set again.</td><td><code>set value</code>, <code>set subValue</code>, <code>set message</code></td></tr><tr><td><code>get</code> property </td><td>Widget with function input</td><td>Receives a property from a widget to work with it in the logic.</td><td><code>get data</code>, <code>get validationResult</code></td></tr></tbody></table>

{% hint style="warning" %}
It can happen that instead of `get`, `from` is used. We are currently changing it.
{% endhint %}

#### Commands and events

In contrast to properties, commands cause a non-persistent change in the state of a widget, e.g. to trigger a loading animation. The widget returns to its initial state when the app is reloaded.

User clicks on widgets can be recorded as events and transferred to the logic in order to trigger an action there, e.g. triggering a function.

To send a command to a widget, you must connect an output to a widget. To capture a click as event, you need to connect a widget to an input or trigger.

The following table provides an overview of commands and events:

<table><thead><tr><th width="122">Interaction</th><th width="166">Links</th><th width="224">Description</th><th width="244">Examples</th></tr></thead><tbody><tr><td><code>call</code> command</td><td>Function output with widget</td><td>Sends a command to a widget so it takes an action.</td><td><code>call done</code>, <code>call enable</code>, <code>call clear</code></td></tr><tr><td><code>on</code> event</td><td>Widget with function input</td><td>Captures a click from a widget to trigger an action in the logic.</td><td><code>on click</code>, <code>on select</code>, <code>on delete</code> </td></tr></tbody></table>

#### Example

The image below shows a function thats input, trigger and output are connected to widets.&#x20;

* **`from formData`** receives a property from a (form) widget to become the functions input.
* **`on button click`** caputres a user click on a button to trigger the function.
* **`set value`** sends the value (in this case data from a form) to a (value box) widget.

<div align="center"><figure><img src="https://3495989837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE5Ketpww1s7TauSAJrJ8%2Fuploads%2FBXaurpNBu7uViGN7hiXL%2Fimage.png?alt=media&amp;token=76bf3399-2b45-456e-b41a-095e4a9e055f" alt="" width="495"><figcaption><p>An echo function displaying the properties to be passed or set.</p></figcaption></figure></div>

#### Switching interactions

To switch between properties, commands or clicks simply click on the interaction to be switched in the linked function and select another one.

<figure><img src="https://3495989837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE5Ketpww1s7TauSAJrJ8%2Fuploads%2FsVN0fBojQUh6oGGzsddD%2Fswitch%20property.gif?alt=media&amp;token=6a774101-1075-435e-ab01-49c87350ad41" alt="" width="563"><figcaption><p>Switch property of a widget to be passed</p></figcaption></figure>

#### Linking widgets with logic

* **To link a function** to a widget, select the widget and drag a part of a function or a modifier onto the widget.
* **To unlink a widget** from a function/modifier, click on the `x` next to the property in the function/modifier or click `Unlink All`  in the widgets [context menu](#context-menu).

<figure><img src="https://3495989837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE5Ketpww1s7TauSAJrJ8%2Fuploads%2FLWD0S3el95gn2NslP7r5%2Flink%20widget.gif?alt=media&amp;token=0822e34c-5857-4787-9796-9d7aa6097334" alt="" width="563"><figcaption><p>Link and unlink a widget and a function</p></figcaption></figure>

#### Linking markers

The color and shape of a widget's grab markers contain information about its links:

* White rectangle: No link
* <mark style="color:blue;">Blue</mark> rectangle: Link to input
* <mark style="color:green;">Green</mark> rectangle: Link to trigger
* <mark style="color:red;">Red</mark> rectangle: Link to output
* <mark style="color:blue;">Blue</mark> or <mark style="color:red;">red</mark> circle: Two or more links
* <mark style="color:yellow;">Yellow</mark> rectangle or circle: Hover effect when before dropping a function

One widget can have various links with functions and modifiers. A light shadow on a function indicated existing links if a widget is selected.&#x20;

### Widget styling and settings

Each widget offers different configuration options, settings, and presets. These can be accessed using the icons that appear in the top bar as soon as the widget is selected. The specific options and capabilities are explained on the respective subpages of the individual widgets.

<figure><img src="https://3495989837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE5Ketpww1s7TauSAJrJ8%2Fuploads%2F8YztA3MFXp6v5AHV8Xip%2Fimage.png?alt=media&amp;token=1a05758e-2990-4731-8027-f7afee47a34b" alt="" width="498"><figcaption><p>Styling and settings icons (in this case of the form widget)</p></figcaption></figure>

### Context menu

Each widget provides a context menu on right-click.&#x20;

<figure><img src="https://3495989837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE5Ketpww1s7TauSAJrJ8%2Fuploads%2FeAyJLBvRe85TvroM6ZfX%2Fimage.png?alt=media&amp;token=602ae297-77ce-4408-821f-dadd43aff147" alt="" width="309"><figcaption><p>Widget context menu</p></figcaption></figure>

The options in the context menu are:

* **Delete** a widget&#x20;
* **Copy** a widget. To paste it, right-click somewhere in the UI editor and click `paste`.
* **Export widget:** Export the widget as a `.json` file. To import it, right-click somewhere in the UI editor and click `import`.
* **Unlink all** connections to functions.
* **Toggle multi-tenancy**: By default, apps and widgets support multi-tenancy. Sometimes it is required, though, that a widgets content, defined by one user, appears the same for all users. In such a case, toggle multi-tenancy to define a widget as shared.
* **Widget info**: Shows you the widget ID and potential links to functions (executor ID).

{% hint style="danger" %}
Deleting a widget can't be undone.
{% endhint %}

{% hint style="info" %}
Duplicating widgets works with `Ctrl+C` and `Ctrl+V`, too. The copied widget must be moved a little to become visibile.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.heisenware.com/~/changes/eYCCpn9cCBKOYnZA6a8f/building-apps/ui-widgets-and-elements.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.