Basic syntax¶
This page explains what a .sil file consists of, how nodes and properties are written, how values are classified, and the rules for numbers, colors, strings and comments.
Document structure¶
A document consists of two kinds of content:
- Top-level definitions:
Var,Style,Component,@keyframes. They do not create widgets directly; later nodes only reference them. - UI nodes: one or more top-level widgets. The most common case is a tree rooted at a
Container.
// Top-level definitions
Var accent: #5CD65C;
Style Card {
background: #171B1F;
border: 1 solid #2A3036;
padding: 8;
}
// UI nodes
Container {
name: root;
layout: vertical;
width: 360;
height: 200;
Container {
class: "card";
height: 60;
Label { text: "Styles and variables"; height: 16; color: $accent; }
}
}
Definitions may appear before or after the UI nodes; references are resolved at compile time, so no declaration first is required. A document must have at least one top-level node, otherwise compilation fails with the document does not define any component.
If you write more than one top-level node, Silica puts them into a vertical Container in order, so they do not all stack at (0, 0). When you need precise control, it is best to always keep a single root node.
Nodes¶
Node syntax:
Type parameter-list? { property; child nodes... }
- Type: a built-in widget name (
Container,Panel,Label,Button,Image,ScrollView,Checkbox,Slider,TextBox,Dropdown,ForEach,Part), or the name of aComponentdefined in the document. - Parameter list: used only by
ForEachandComponent, in the form(data: @rows, item: @row). A parameter list on an ordinary widget has no meaning. - Properties:
key: value;, written inside the braces. - Child nodes: write the next node directly after the properties; no comma is needed.
Container {
layout: horizontal;
height: 28;
Label { text: "Name"; width: 80; height: 16; margin-top: 6; }
Button { text: "OK"; width: 72; height: 24; onClick: "confirm"; }
}
When a node type is neither a built-in widget nor a defined component, compilation produces the error unknown component '...' and the node is not created.
Classifying properties and values¶
The same key: value; line falls into one of four categories depending on how the value is written, and each behaves differently:
| Syntax | Category | Example | Behavior |
|---|---|---|---|
Starts with @ |
Reactive binding | text: @health; |
Parsed as an expression; re-evaluated when the related DataStore key changes |
Contains {{ ... }} |
Template | text: "Health: {{@health}}" |
Only the expressions inside the braces are replaced, the rest of the text is kept as written |
The value is { ... } |
Event script | onClick: { @health = 100; } |
Bound to the event name; the statements run when it fires |
| Anything else | Literal property | width: 120; |
Passed straight to the widget's property handler |
Only event properties can carry scripts
Scripts must be written on an event property, such as onClick, onChange or onSubmit. Writing text: { ... } produces the warning: scripts attach to an event property (...). Scripts do not support $variable substitution; inside a script, $ denotes a local variable of the current run.
$name in a literal property is replaced by the value of the Var at compile time:
Var gap: 8;
Var accent: #5CD65C;
Container {
padding: $gap;
background: #171B1F;
Label { text: "Compile-time substitution"; color: $accent; }
}
Strings¶
- Enclosed in double quotes:
text: "Save and close"; - Escapes are supported:
\",\\,\n,\t. - Characters such as
;,:and{inside text are only treated as syntax symbols when they appear outside quotes. - To show a double quote inside text, write
\".
Label {
text: "Notice: press \"OK\" to continue";
height: 16;
}
Numbers and sizes¶
Numbers are interpreted in GUI units and may carry the px, em, pt or dp suffix; the suffix is only a convenience for writing and does not change the value:
width: 120;
height: 24px;
padding: 8dp;
font-size: 0.9;
Negative values are not valid on most size properties (they are treated as invalid and produce a warning). A negative margin-* value means "fall back to the default value of margin", not a negative margin.
0 has a special meaning that depends on the property:
width: 0/height: 0: the size is left to the layout or to the widget itself. Perpendicular to the layout direction, a value of 0 is stretched by the parent container; along the layout direction a child widget with 0 counts as 0, and only a container itself that is 0 along the layout direction is sized automatically from its content; widgets with a default size (Button,Slider...) fall back to that default (see Layout).x: 0/y: 0: absolute coordinates of zero, only meaningful in absolute layout.
Colors¶
The following forms are supported:
| Form | Example | Notes |
|---|---|---|
#RGB |
#5C5 |
Each digit expands to two |
#RGBA |
#5C58 |
The last digit is alpha |
#RRGGBB |
#5CD65C |
The common form |
#RRGGBBAA |
#0F1215F2 |
The last two digits are alpha; F2 is nearly opaque |
| Color names | white, black, red, green, blue, yellow, orange, purple, pink, cyan, magenta, gray / grey |
Fixed shades |
| Transparent | transparent, none |
Fully transparent; none also clears optional effects such as shadows and borders |
Alpha multiplies with the opacity property: a widget with #FFFFFF80 and opacity: 0.5 is drawn at about 25% alpha in the end.
Booleans¶
Besides true / false, 1 / 0, yes / no and on / off also work as booleans, case-insensitively. They are common on properties such as visible, disabled, wrap and smooth.
Comments¶
Two kinds of comments are supported:
// Single-line comment
/*
Multi-line comment
/* nesting is not supported */
*/
Comments may appear at the top level, inside a node, between properties, and between statements in an event script.
The name property¶
name (also accepted as id) gives a node an identifier, so that C++ can find it with FindByName, or so that tests and logs can recognize it:
Container {
name: settings_panel;
// ...
}
Names do not take part in layout and do not automatically become data keys. Keep them unique across the whole tree; duplicates do not raise an error, but lookup only returns the first match.
Property override order¶
A single property may come from several places. The effective order is (later overrides earlier):
- Widget defaults.
Stylebase styles (the bottom of theextendschain).- Derived styles.
- Inline properties / bindings / templates in the node.
Styles and bindings override by "key", and margin-left and marginLeft are compared as the same key for precedence. When actually applying properties, however, still write the canonical margin-left form, otherwise the widget does not recognize it.
Common syntax errors¶
| Log message | Cause | Fix |
|---|---|---|
expected ':' after ... |
Missing colon after the property name | Add : |
missing ';' after property '...' |
Missing semicolon before a new property on the next line | End every property with ; |
expected '{' after ... |
Missing braces after a node or definition | Add { ... } |
property '...' expects a value, not a block |
{ ... } written on a non-event property |
Use a literal value or a binding |
unknown component '...' |
The type name is misspelled, or the component is not defined | Check case and the definition |
unknown property '...' on '...' |
The widget has no such property | See the widget reference |
Errors versus warnings
Syntax errors keep a document from compiling; unknown properties, unknown styles, missing component parameters and the like are only warnings, and the rest of the UI is still built. The log distinguishes them with error: / warning:.