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

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

<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

<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

<Function.Input Type="UserInput">Input</Function.Input>

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

Function.Output

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

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

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

<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

<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

<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

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

Launcher guide

Plugin development

Library plugin docs

Plugin store usage

QWidget functions and TypeScript