Properties and Values

A property is name=value, or a bare name where the value is a flag.

new button caption="Save" default !enabled
new panel layout=vbox
new label caption="Warning" fg=bright_yellow

---

Four kinds of value

The parser recognises four lexical shapes. Which one a property wants is the property's business, and the wrong shape is refused rather than converted.

Shape	Written	Example
word	a bare token	vbox, green, auto
number	digits, optionally signed and fractional	10, -1, 2.5
string	quotes required	"Save"
block	statements in braces	children={ … }

Nothing is coerced

A property that wants a string wants a string; a word that looks like one will not do:

new label caption=hello
  ->  caption: expected a quoted string

And the reverse — a property that wants a word refuses a quoted one, even with identical characters:

new panel layout="vbox"
  ->  layout: expected a bare word

Integers are integers:

new listview selected=2.5    ->  selected: expected an integer
new listview selected="2"    ->  selected: expected an integer
new listview selected=two    ->  selected: expected an integer

This is deliberate. A value's shape is part of what it means, so a client that sends the wrong one hears about it at the point of the mistake rather than getting a silently different result.

Flags have three states

A flag is written as a bare name. ! negates it, ? asserts indeterminate:

new checkbox caption="Ready" checked      # true
new checkbox caption="Ready" !checked     # false
new checkbox caption="Ready" ?checked     # indeterminate

? is meaningful only where a type has a third state — a tri-state checkbox. Everywhere else it is an error, not a synonym for off:

new listview ?ledger
  ->  ledger: indeterminate is not meaningful for this property

=true and =false also parse, as bare words, and are the long form of the same thing:

new listview ledger=true
new listview ledger=false

Nothing else does. A flag is not a number and not a string:

new listview ledger=1         ->  ledger: expected a flag
new listview ledger="true"    ->  ledger: expected a flag

Prefer the bare form. It reads as the assertion it is, and it is what the rest of the vocabulary uses.

Strings

Double quotes, with backslash escapes:

new label caption="two words"
new label caption="say \"hi\""
new label caption="a\nb"
new label caption=""

An empty string is a legal value and is not the same as omitting the property. Omitting it leaves whatever the default is; "" sets it to nothing.

Enums

An enum is a word from a fixed set, and an unknown one is refused with the set named where the type bothers to:

new panel layout=nosuch
  ->  layout: unknown value "nosuch" (grid arrives later)

new messagebox icon=nosuch
  ->  icon: unknown value "nosuch"

The generated property tables in this wiki spell the accepted words out in the Type column, as `left` | `center` | `right`, so the set is always at hand.

Colors

A named color is a bare word. A hex color is a quoted string:

new label caption="x" fg=green
new panel bg="#1e1e2e"

The quotes on the hex form are not optional, because # begins a comment. Unquoted, the rest of the line is discarded and the parser reaches the end of the statement looking for a value it never finds:

new label caption="x" fg=#1e1e2e
  ->  1:33: expected a value

An unknown color name is refused:

new label caption="x" fg=chartreuse
  ->  fg: unknown color "chartreuse"

The named set is the terminal sixteen plus default. Prefer the names — they follow a theme change and mean something on a surface with sixteen colors. Common Properties has the full list and the inheritance rule.

Comments

# runs to end of line, anywhere a statement could continue:

new button caption="OK"   # the default action

Which is the whole reason a hex color needs its quotes.

Order matters

Properties apply left to right, and a property that refers to children has to come after them:

new listview selected=2 children={ … }   # selected lands on 0
new listview children={ … } selected=2   # selected lands on 2

Neither errors. See ListView for the full account and the template that settles it permanently.

Unknown properties are refused

new button nosuchthing=1
  ->  property "nosuchthing" is not supported by this type

So a property that appears to have had no effect did not fail. If no error came back, it was applied — look at what it does rather than whether it arrived.

The exception is Editor's rich properties, which are accepted and ignored by a build that cannot honour them. That page says which.

Units

min_width, max_height, column_units and row_units are counted in units, a sub-cell quantity whose size is set by the nearest ancestor that declares one. A number alone does not mean a fixed size — see Common Properties.

See also

Common Properties — what every trinket accepts · Protocol Overview — statements and keys · Object Model · Templates and Aliases