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

<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

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 <= 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 for all allowed values. Example:

<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 < in XML attributes. See Functions and TypeScript 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.

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

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

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

Element overview

Category	Elements	Docs
Root	`Widget`	Widget
Contract	`Widget.Inputs` `Widget.Outputs`	Widget.Using
Layout	`Container` `Row` `Column` `Grid`	Layout
Tabs	`Tabs` `TabItem`	Tabs
List	`List` `ListItem`	List
Conditional	`If`	If
Spacing	`Divider` `Spacer`	Divider
Content	`Text` `Button` `Link` `Image` `Media`	Text
Input	`TextBox` `CheckBox` `Slider` `Select`	TextBox
Display	`Progress` `FilePicker` `ColorPicker`	Progress
Data	`Data`	Data
Resources	`Resources` `String` `Bool` `Number` `Binary` `Resource`	Resources
Events	`Triggers` `Trigger`	Triggers
Functions	`Function` `Struct` `Field`	Function
Nesting	`Widget.Using`	Widget.Using

Actions

Buttons, links, and triggers use OnClick / OnChange / Action: Launch, SetDefaultInstance, OpenInstance, Navigate, OpenUrl, OpenFolder, Copy, SelectAccount, Install, Refresh, CallFunction, RunCommand, PluginApi. See Actions.

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.

Launcher guide

Plugin development

Library plugin docs

Plugin store usage

QWidget XML syntax