> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qomicex.top/llms.txt
> Use this file to discover all available pages before exploring further.

# QWidget functions and TypeScript

## QWidget functions and TypeScript

`Function` lets you write TypeScript logic inside a widget. Scripts run in an isolated sandbox iframe with no DOM, network, localStorage, or `import`; they can read inputs, return a plain object, and read/write the current widget's visual properties through `Host`.

## Minimal example

```xml theme={null}
<Function Name="Greet" Timeout="3000">
  <Function.Interface>
    <Struct Name="GreetInput">
      <Field Name="Name" Type="String" />
    </Struct>
  </Function.Interface>
  <Function.Input Type="GreetInput">Input</Function.Input>
  <Function.Output Type="String">Message</Function.Output>
  <Function.Script><![CDATA[
    return { Message: "Hello " + (Input.Name || "guest") };
  ]]></Function.Script>
</Function>
```

Call it:

```xml theme={null}
<TextBox Name="Name" />
<Button Text="Greet" OnClick="CallFunction" Function="Greet" />
<Text Value="{Results.Greet.Message}" />
```

## Structure

### Function

| Attribute | Description |
| :- | :- |
| `Name` | Required, unique |
| `Timeout` | 100–10000 ms, default 3000 |

### Function.Interface

```xml theme={null}
<Function.Interface>
  <Struct Name="UserInput">
    <Field Name="name" Type="String" />
    <Field Name="age" Type="Number" />
  </Struct>
</Function.Interface>
```

Field types: `String` / `Number` / `Bool` / `DateTime` / `Json` / `Binary`, or another Struct name.

### Function.Input

```xml theme={null}
<Function.Input Type="UserInput">Input</Function.Input>
```

The element text is the script variable name (default `Input`).

### Function.Output

```xml theme={null}
<Function.Output Type="String">Message</Function.Output>
<Function.Output Type="Json">Items</Function.Output>
```

Results become `{Results.<Function>.<Output>}`.

### Function.Script

TypeScript source; CDATA is recommended:

```xml theme={null}
<Function.Script><![CDATA[
  const list = [1, 2, 3].map((n) => n * 2);
  return { Items: list };
]]></Function.Script>
```

Scripts must return JSON-serializable values; `Date` is serialized as an ISO string. Top-level `await` is supported, so scripts can wait for `Host` calls directly.

## Input sources

`Input` is built in this order:

1. `Arguments` JSON from `CallFunction` (supports binding interpolation).
2. Otherwise, values from `Inputs` matched to the input Struct field names.

```xml theme={null}
<Button Text="Search"
        OnClick="CallFunction"
        Function="Search">
  <Button.Arguments><![CDATA[{"Keyword":"{Inputs.Keyword}"}]]></Button.Arguments>
</Button>
```

## Script globals

| Variable | Content |
| :- | :- |
| `Input` | Values assembled from `Function.Input` |
| `Inputs` | Current values of all input controls |
| `Resources` | Named resources; Binary resources expose `Base64` / `Url` / `Mime` / `Size` |
| `Data` | All data sources; unnamed fields are merged into `Data` |
| `Results` | Previous function/command/plugin results |
| `Size` | `Width` / `Height` (grid) and `PixelWidth` / `PixelHeight` |
| `Host` | Host APIs |

## Host

All `Host` methods are asynchronous and return a `Promise`; you may `await` them or ignore the result.

| Method | Description |
| :- | :- |
| `Host.Notify(message, type?)` | Show a notification (`info` / `success` / `error`) |
| `Host.OpenUrl(url)` | Open an https URL in the system browser |
| `Host.Navigate(path)` | Navigate inside the launcher |
| `Host.Log(message)` | Write to developer logs |
| `Host.GetSize()` | Read `{ Width, Height, PixelWidth, PixelHeight }` |
| `Host.SetProperty(Target, Property, Value)` | Write a visual property and return the stored value |
| `Host.GetProperty(Target, Property)` | Read the current visual property |
| `Host.Invoke(Target, Method, Args?)` | Invoke a component method; `Args` may be an array or a single value |

### Writable properties

Every visual node addressed by `Target` exposes its XML visual attributes, for example:

* `Text`: `Value`, `Size`, `Weight`, `Color`, `Clamp`, `Align`
* `Button` / `Link`: `Text`, `Variant`, `Size`, `Url`
* `TextBox` / `CheckBox` / `Slider` / `Select` / `ColorPicker` / `FilePicker`: `Value`, `Checked`, `Options`, etc.
* `List`: `Items` (an array is accepted directly), `Gap`, `EmptyText`
* `Container` / `Row` / `Column` / `Grid`: `Gap`, `Padding`, `Border`, `Background`, `Radius`, `Align`, `Justify`
* `Image` / `Media`: `Src`, `Alt`, `Source`, `Volume`, `Muted`, etc.
* All visual nodes: `Visible`, plus the content alias `Content` (Text → Value, Button → Text, List → Items, etc.)

`Host.SetProperty` cannot change structural or action attributes such as `Target`, `Name`, `OnClick`, `OnChange`, `Function`, `Arguments`, `Command`, `WorkingDirectory`, `Timeout`, `PluginId`, or `Method`.

### Invoke methods

| Method | Applies to | Description |
| :- | :- | :- |
| `Click` | `Button` / `Link` | Runs the same action and `Click` trigger as a user click |
| `SetValue` | Any writable node | Same as `Host.SetProperty(Target, "Value", Args)` |
| `Toggle` | `CheckBox` | Flips the checked state |
| `Refresh` | Any node | Reloads the current widget's data sources |
| `Focus` / `Blur` | Inputs, buttons, links | Focus or blur the element |

### Example

```xml theme={null}
<Text Target="Status" Value="Idle" />
<List Target="ResultList" Items="Items" As="Item" EmptyText="No results">
  <ListItem><Text Value="{Item.Title}" /></ListItem>
</List>
<Button Target="RefreshButton" Text="Refresh"
        OnClick="CallFunction" Function="Refresh" />

<Function Name="Refresh" Timeout="5000">
  <Function.Output Type="String">Message</Function.Output>
  <Function.Script><![CDATA[
    const previous = await Host.GetProperty("Status", "Value");
    await Host.SetProperty("Status", "Content", "Loading");
    const items = await Host.GetProperty("ResultList", "Items");
    await Host.SetProperty("ResultList", "Items", [
      { Title: "Result A" },
      { Title: "Result B" },
    ]);
    await Host.SetProperty("RefreshButton", "Visible", true);
    // await Host.Invoke("RefreshButton", "Click");
    return { Message: previous + " -> " + items.length };
  ]]></Function.Script>
</Function>
```

`Host.Invoke("RefreshButton", "Click")` runs the button's action again; invoking the button from its own script recurses, so only invoke other buttons or guard with a condition.

Scripts still cannot execute commands or call plugin APIs directly; those remain button/trigger actions.

## Triggers

```xml theme={null}
<Triggers>
  <Trigger Event="Loaded" Function="Init" />
  <Trigger Event="DataChanged" Data="News" Function="RenderNews" />
  <Trigger Event="Click" Control="SearchButton" Function="Search" />
  <Trigger Event="Timer" Interval="60000" Function="Tick" Once="False" />
  <Trigger Event="Resize" Function="OnResize" />
</Triggers>
```

* `Loaded`: once after mount.
* `DataChanged`: after the named data source loads.
* `Click`: when a control with the matching `Name` is clicked.
* `Timer`: every `Interval` ms, minimum 1000.
* `Resize`: 150ms after the grid or pixel size changes; use `Loaded` for the initial layout.
* Rate limit: 20 executions per second.

## Run in the editor

Open the **Functions** tab, select a function, and click **Run**:

* Executes with current `Inputs` and sample data.
* Shows returned JSON below the editor.
* Syntax errors are reported from sucrase.
* Run only verifies inputs/outputs; `Host.SetProperty` / `Host.Invoke` UI changes apply when the widget runs on the dashboard, not to the editor preview.

## Sandbox and security

* Scripts run in a sandbox iframe with CSP blocking network, images, media, frames, and workers.
* No `window`, `document`, `localStorage`, `fetch`, `XMLHttpRequest`, `import`, or `require`.
* On timeout the iframe is destroyed and recreated.
* Outputs are validated against `Function.Output`.
* Remote widgets can contain scripts and update silently; only use widgets you trust.

## Debugging

1. Use **Run** to verify inputs/outputs.
2. Put intermediate values into outputs or `Host.Log`.
3. Avoid infinite loops; the sandbox is destroyed on timeout.
4. Fetch external data with `Data` first; scripts only process loaded data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.