> ## 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 XML syntax

## QWidget XML syntax

A QWidget is a single XML file. The root element is always `Widget`; other elements cover layout, controls, data/resources, triggers, functions, and nested references.

## Root element

```xml theme={null}
<Widget Name="Daily news" Version="1.0.0" Author="Example"
        Description="Optional"
        UpdateUrl="https://example.com/news.qwidget"
        LauncherVersion="1.4.0">
  ...
</Widget>
```

| Attribute | Required | Description |
| :- | :- | :- |
| `Name` | Yes | Display name, ≤64 characters |
| `Version` | Yes | Widget version, used for update notices |
| `Author` | No | Author |
| `Description` | No | Description |
| `UpdateUrl` | No | Update source, https:443; import URL is used if omitted |
| `LauncherVersion` | No | Minimum launcher version, see [Version requirements](https://docs.qomicex.top/en/guide/custom-widget/reference/version.md) |

## Naming

All elements, attributes, and enum values use PascalCase:

* Elements: `Container`, `Text`, `TextBox`, `Widget.Using`
* Attributes: `Value`, `Size`, `OnClick`, `EmptyText`
* Enums: `Lg`, `Bold`, `Center`, `Json`, `Binary`

## Common node attributes

Except for the `Widget` root and non-visual elements such as `Data`, `Resources`, `Function`, and `Triggers`, every visual node supports:

| Attribute | Required | Description |
| :- | :- | :- |
| `Target` | No | Script target key, unique within the widget; used by `Host.SetProperty` / `Host.GetProperty` / `Host.Invoke` |
| `Visible` | No | Default `True`; when `False` the node is not rendered and scripts can toggle it |
| `When` | No | Size condition such as `Size.Width &lt;= 1`; the node is not rendered when false |

`Target` and an input control's `Name` are separate namespaces: `Name` still drives `{Inputs.Name}` and `Trigger Control="Name"`, while `Target` only addresses the UI from scripts. See [Attribute values](https://docs.qomicex.top/en/guide/custom-widget/reference/values.md) for all allowed values. Example:

```xml theme={null}
<Text Target="Status" Value="Idle" />
<Button Target="Refresh" Text="Refresh" OnClick="CallFunction" Function="Refresh" />
<Text When="Size.Width &lt;= 1" Value="Narrow" />
```

`When` supports `Size.Width` / `Size.Height` / `Size.PixelWidth` / `Size.PixelHeight`, operators `<`, `<=`, `>`, `>=`, `==`, `!=`, joined by `and` / `or`; write `<` as `&lt;` in XML attributes.

See [Functions and TypeScript](https://docs.qomicex.top/en/guide/custom-widget/advanced/functions.md#host) for script examples.

## Three equivalent syntaxes

The same property can be written as attribute syntax, content syntax, or property-element syntax. Setting the same property twice is an error.

```xml theme={null}
<!-- Attribute syntax -->
<Text Value="Hello" />

<!-- Content syntax (ContentProperty) -->
<Text>Hello</Text>

<!-- Property-element syntax -->
<Text><Text.Value>Hello</Text.Value></Text>
```

ContentProperty mapping:

| Element | Content property |
| :- | :- |
| `Text` | `Value` |
| `Button` / `Link` / `CheckBox` / `FilePicker` | `Text` |
| `TextBox` / `ColorPicker` / `Progress` / `Slider` | `Value` |
| `Select` | `Options` (JSON) |
| `Media` | `Source` |
| `Image` | `Src` |
| `Spacer` | `Size` |
| `Data` | `Url` |
| `String` / `Bool` / `Number` / `Binary` / `Resource` | Text content |
| Layout/container elements | Child elements |

Property elements can be combined with content:

```xml theme={null}
<Text>
  <Text.Size>Lg</Text.Size>
  <Text.Weight>Bold</Text.Weight>
  Hello Qomicex
</Text>
```

### Attached properties

Direct children of `Grid` support `Grid.Row`, `Grid.Column`, `Grid.RowSpan`, and `Grid.ColumnSpan`:

```xml theme={null}
<Grid Columns="2" Gap="2">
  <Button Grid.Column="1" Text="Right" />
  <Button>
    <Grid.Row>1</Grid.Row>
    <Button.Text>Next row</Button.Text>
  </Button>
</Grid>
```

## Bindings

String attributes support `{path}` interpolation. When the whole value is a binding, the original type is preserved.

| Namespace | Example | Description |
| :- | :- | :- |
| `Data` | `{Data.News.Title}` | Data source; unnamed source is `{Data.Title}` |
| `Resources` | `{Resources.AppName}` | Named resource |
| `Inputs` | `{Inputs.Keyword}` | Current control values |
| `Results` | `{Results.Search.Items}` | Function/command/plugin results |
| `Children` | `{Children.Weather.Inputs.City}` | Read-only nested state |
| `State` | `{State.Loading}` / `{State.Error}` | Widget runtime state |

See [Data binding](https://docs.qomicex.top/en/guide/custom-widget/reference/binding.md).

## Element overview

| Category | Elements | Docs |
| :- | :- | :- |
| Root | `Widget` | [Widget](https://docs.qomicex.top/en/guide/custom-widget/reference/components/widget.md) |
| Contract | `Widget.Inputs` `Widget.Outputs` | [Widget.Using](https://docs.qomicex.top/en/guide/custom-widget/reference/components/using.md#as-a-pure-data-source) |
| Layout | `Container` `Row` `Column` `Grid` | [Layout](https://docs.qomicex.top/en/guide/custom-widget/advanced/layout.md) |
| Tabs | `Tabs` `TabItem` | [Tabs](https://docs.qomicex.top/en/guide/custom-widget/reference/components/tabs.md) |
| List | `List` `ListItem` | [List](https://docs.qomicex.top/en/guide/custom-widget/reference/components/list.md) |
| Conditional | `If` | [If](https://docs.qomicex.top/en/guide/custom-widget/reference/components/if.md) |
| Spacing | `Divider` `Spacer` | [Divider](https://docs.qomicex.top/en/guide/custom-widget/reference/components/divider.md) |
| Content | `Text` `Button` `Link` `Image` `Media` | [Text](https://docs.qomicex.top/en/guide/custom-widget/reference/components/text.md) |
| Input | `TextBox` `CheckBox` `Slider` `Select` | [TextBox](https://docs.qomicex.top/en/guide/custom-widget/reference/components/text-box.md) |
| Display | `Progress` `FilePicker` `ColorPicker` | [Progress](https://docs.qomicex.top/en/guide/custom-widget/reference/components/progress.md) |
| Data | `Data` | [Data](https://docs.qomicex.top/en/guide/custom-widget/reference/components/data.md) |
| Resources | `Resources` `String` `Bool` `Number` `Binary` `Resource` | [Resources](https://docs.qomicex.top/en/guide/custom-widget/reference/components/resources.md) |
| Events | `Triggers` `Trigger` | [Triggers](https://docs.qomicex.top/en/guide/custom-widget/reference/components/triggers.md) |
| Functions | `Function` `Struct` `Field` | [Function](https://docs.qomicex.top/en/guide/custom-widget/reference/components/function.md) |
| Nesting | `Widget.Using` | [Widget.Using](https://docs.qomicex.top/en/guide/custom-widget/reference/components/using.md) |

## Actions

Buttons, links, and triggers use `OnClick` / `OnChange` / `Action`:

`Launch`, `SetDefaultInstance`, `OpenInstance`, `Navigate`, `OpenUrl`, `OpenFolder`, `Copy`, `SelectAccount`, `Install`, `Refresh`, `CallFunction`, `RunCommand`, `PluginApi`.

See [Actions](https://docs.qomicex.top/en/guide/custom-widget/reference/actions.md).

## Limits

* XML ≤256KB, depth ≤16, elements ≤1000.
* Data sources ≤8; rendered list items ≤200.
* Online text ≤1MB, binary ≤8MB; local binary ≤8MB.
* Nesting depth ≤5; ≤20 nested instances per parent.
* Function scripts ≤64KB; default timeout 3 seconds, max 10 seconds.
* `DOCTYPE` / `ENTITY` are rejected; unknown elements/attributes and duplicate properties fail validation.


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