Widget.Using

Embeds another QWidget into the current widget as a node.

Signature

<Widget.Using Name="WeatherCard" As="Weather" />
<Widget.Using Url="https://example.com/weather.qwidget" As="Weather" />
<Widget.Using As="Weather">WeatherCard</Widget.Using>
<Widget.Using As="Weather">https://example.com/weather.qwidget</Widget.Using>

<Widget.Using Name="WeatherCard" As="Weather">
  <Widget.Using.Arguments><![CDATA[{"city":"{Inputs.City}"}]]></Widget.Using.Arguments>
</Widget.Using>

Attributes

Attribute	Type	Description
`Name`	string	Local widget name, exact match
`Url`	https URL	Remote widget
`As`	identifier	Alias of the child widget, unique among siblings
`Refresh`	60–86400	Remote cache TTL in seconds, default 6 hours
`Arguments`	JSON	Initial Inputs, supports binding interpolation

Name and Url are mutually exclusive; the value can also be written as the tag body.

Content

Widget.Using adds no extra container of its own; the child renders in place. The parent decides the outer size.

As a pure data source

A widget can have no layout or visual nodes at all and contain only Data, Resources, Function, Widget.Inputs, Widget.Outputs, and Triggers. When embedded with Widget.Using, it renders nothing but still fetches data and runs triggers/functions.

Input contract

<Widget.Inputs>
  <Input Name="City" Type="String" Required="True" Default="Shanghai" />
  <Input Name="Limit" Type="Number" Default="10" />
</Widget.Inputs>

Attribute	Description
`Name`	Unique input name, used as `{Inputs.Name}`
`Type`	`String` / `Number` / `Bool` / `DateTime` / `Json` / `Binary`
`Required`	Default `False`
`Default`	Used when absent; `Json` / `Binary` are parsed as JSON

The parent passes values through Widget.Using.Arguments:

<Widget.Using Name="Weather data" As="Weather">
  <Widget.Using.Arguments><![CDATA[{"City":"Paris"}]]></Widget.Using.Arguments>
</Widget.Using>

Unknown keys, type mismatches, and missing required inputs show an error placeholder.
Changing Arguments updates child Inputs; child input controls can still change their own values.
Widgets without Widget.Inputs keep the legacy behavior: Arguments go straight into Inputs.

Output contract

<Widget.Outputs>
  <Output Name="Weather" Type="Json" Source="{Data.Weather}" />
  <Output Name="Label" Type="String" Source="{Results.Summary.Text}" />
</Widget.Outputs>

Attribute	Description
`Name`	Unique output name; parent reads `Children.<As>.Outputs.Name`
`Type`	Same type set; values are coerced/validated, invalid values become `undefined`
`Source`	Child scope path; may reference `Data` / `Results` / `Inputs` / `Resources`

When Widget.Outputs is declared, only declared outputs are exposed to the parent; Children.<As>.Data and Results are no longer exposed, forming an output whitelist. Widgets without Widget.Outputs keep exposing the legacy full snapshot.

Full example

<!-- WeatherData.qwidget: a pure data-source widget with no visual nodes -->
<Widget Name="Weather data" Version="1.0.0">
  <Widget.Inputs>
    <Input Name="City" Type="String" Required="True" Default="Shanghai" />
  </Widget.Inputs>
  <Widget.Outputs>
    <Output Name="Weather" Type="Json" Source="{Data.Weather}" />
    <Output Name="Label" Type="String" Source="{Results.Summary.Text}" />
  </Widget.Outputs>
  <Data Name="Weather" Type="Json"
        Url="https://api.example.com/weather?city={Inputs.City}" />
  <Function Name="Summary">
    <Function.Output Type="String">Text</Function.Output>
    <Function.Script><![CDATA[
      return { Text: Data.Weather.temperature + "°C" };
    ]]></Function.Script>
  </Function>
  <Triggers>
    <Trigger Event="DataChanged" Data="Weather" Function="Summary" />
  </Triggers>
</Widget>

<!-- Parent: embed the data source and read its outputs -->
<Widget.Using Name="Weather data" As="Weather">
  <Widget.Using.Arguments><![CDATA[{"City":"Paris"}]]></Widget.Using.Arguments>
</Widget.Using>
<Text Value="{Children.Weather.Outputs.Label}" />
<Text Value="{Children.Weather.Outputs.Weather.temperature}" />

Data.Url / Data.Path support {Inputs.*}. When inputs change, the old request is canceled and data is fetched again. The resolved URL must still be https:443 on a confirmed host; parameterize query values or path segments, not the host. Pure data sources still count toward nesting depth, instance count, and data-source limits.

Scope

The parent can only read:

<Text Value="{Children.Weather.Data.Temp}" />
<Text Value="{Children.Weather.Inputs.City}" />
<Text Value="{Children.Weather.Results.Load.Items.0.Title}" />

Children.<As>.State.Loading / .Error are available too. Without Widget.Outputs, .Data / .Results are also exposed; with declared outputs, only .Outputs is exposed.

Resolution

Local Name: exact match against the custom widget list; a missing or duplicated name shows an error placeholder.
Remote Url: fetched through the backend proxy, silently refreshed every 6 hours.
Export does not inline dependencies; missing local widgets are reported before export.

Limits

Depth ≤5; self-references and A→B→A cycles are detected.
At most 20 instances per parent widget.
Duplicate aliases fail to parse.
When the child unmounts, timers, script sandboxes, and blob URLs are cleaned up.

Example

<Row Gap="2">
  <Widget.Using Name="StatusCard" As="Players" />
  <Widget.Using Name="StatusCard" As="Tps">
    <Widget.Using.Arguments><![CDATA[{"mode":"tps"}]]></Widget.Using.Arguments>
  </Widget.Using>
</Row>
<Text Value="{Children.Players.Data.Value}" />

Gotchas

Name is the display name, not the file name.
Children have their own Inputs/Data/Results; the parent cannot write them.
Remote child data domains are approved in the parent widget’s editor.

Launcher guide

Plugin development

Library plugin docs

Plugin store usage