Layout Reference

Every node in the layout tree maps to a RemoteViews-compatible Android view. The Dart type names are intentionally short.

Containers

WColumn

Renders as a vertical LinearLayout.

WColumn(
  children: [...],       // required
  backgroundColor: '#1A1A2E',
  padding: 16,           // uniform padding in dp
  gravity: 'center',     // 'start' | 'center' | 'end' (default: 'start')
  id: 'my_column',       // optional explicit view ID
)

WRow

Renders as a horizontal LinearLayout.

WRow(
  children: [...],
  backgroundColor: '#FFFFFF',
  padding: 8,
  gravity: 'center',
)

WStack

Renders as a FrameLayout. Children stack on top of each other (last child on top).

WStack(
  children: [
    WImage(drawableName: 'bg_gradient'),
    WText('Overlay', textColor: '#FFFFFF'),
  ],
)

Leaf views

WText

Renders as a TextView. Supports data binding with \${key} placeholders.

WText(
  '\${score}',           // text content — can contain \${key} placeholders
  textSize: 24,          // sp units
  textColor: '#FFFFFF',  // hex color
  bold: true,            // android:textStyle="bold" in XML (not runtime-updatable)
  maxLines: 2,           // truncates with ellipsis
  gravity: 'center',     // 'start' | 'center' | 'end'
  padding: 4,
  backgroundColor: '#00000033',
  id: 'score_text',
)

Data binding examples:

WText('\${userName}')                         // simple — full text is the value
WText('Hello, \${name}! Score: \${score}') // template — mixed static + dynamic
WText('No binding here')                     // static text

WButton

Renders as a Button. Sends a broadcast on tap which triggers onUpdate() on the widget.

WButton(
  label: 'Refresh',      // button text (runtime-updatable)
  actionKey: 'refresh',  // unique key — generates ACTION_REFRESH constant
  textSize: 14,
  textColor: '#FFFFFF',
  padding: 8,
  backgroundColor: '#3A3A5E',
)

Every actionKey must be unique across all buttons in all your widgets.

WImage

Renders as an ImageView. References a drawable resource by name.

WImage(
  drawableName: 'ic_weather',    // must exist in res/drawable/
  width: 48,                     // dp
  height: 48,                    // dp
  contentDescription: 'Weather icon',
  padding: 4,
)

WProgressBar

Renders as a horizontal ProgressBar (0–100).

WProgressBar(
  progress: 75,     // default value (0–100), runtime-updatable
  width: 200,       // dp
  height: 8,        // dp
  padding: 4,
)

Common properties

All nodes support:

Property	Type	Description
`id`	`String?`	Explicit Android view ID (auto-generated if omitted)
`padding`	`int?`	Uniform padding in dp
`backgroundColor`	`String?`	Hex color, e.g. `'#1A1A2E'` or `'#80FFFFFF'` (with alpha)

View ID generation

When id is not set, IDs are generated deterministically:

Node type	Generated ID
`WText`	`text_0`, `text_1`, ...
`WButton`	`btn_<actionKey>`
`WImage`	`img_<drawableName>`
`WProgressBar`	`progress_0`, `progress_1`, ...
`WColumn` / `WRow` / `WStack`	`layout_0`, `layout_1`, ...

Nesting example

WColumn(
  backgroundColor: '#0D1117',
  padding: 12,
  children: [
    WText('Stats', textSize: 16, bold: true, textColor: '#FFFFFF'),
    WRow(
      gravity: 'center',
      children: [
        WColumn(children: [
          WText('\${temp}', textSize: 28, textColor: '#4ECDC4'),
          WText('Temperature', textSize: 10, textColor: '#888888'),
        ]),
        WColumn(children: [
          WText('\${humidity}', textSize: 28, textColor: '#45B7D1'),
          WText('Humidity', textSize: 10, textColor: '#888888'),
        ]),
      ],
    ),
    WProgressBar(progress: 60, width: 180, height: 6),
  ],
)

RemoteViews constraints

Android home screen widgets use RemoteViews, which only supports a specific subset of views. The package enforces this — only these view types are used:

Package type	Android view
`WColumn`	`LinearLayout` (vertical)
`WRow`	`LinearLayout` (horizontal)
`WStack`	`FrameLayout`
`WText`	`TextView`
`WButton`	`Button`
`WImage`	`ImageView`
`WProgressBar`	`ProgressBar`

Views like RecyclerView, WebView, or custom views are not usable in widget layouts.

On this page