Values

Values

Value = Translated | Flags | Literal

Literals

Literal = TypeLiteral | QuotedLiteral | NumberLiteral | IdentLiteral QuotedLiteral = <value:QUOTED> NumberLiteral = ( ‘-’ | ‘+’ )? <value:NUMBER> IdentLiteral = <ident:IDENT>

Literals are used to specify values for properties. They can be strings, numbers, references to objects, types, boolean values, or enum members.

Type Literals

TypeLiteral = ‘typeof’ ‘<’ TypeName ‘>’

Sometimes, you need to specify a type as a value. For example, when creating a list store, you may need to specify the type of the items in the list store. This is done using a typeof<> literal.

The type of a typeof<> literal is GType, GObject’s “meta-type” for type information.

Example

Gio.ListStore {
  item-type: typeof<GObject.Object>;
}

Flags

Flags = <first:IDENT> ‘|’ ( <rest:IDENT> )|+

Flags are used to specify a set of options. One or more of the available flag values may be specified, and they are combined using |.

Example

Adw.TabView {
  shortcuts: control_tab | control_shift_tab;
}

Translated Strings

Translated = ( ‘_’ ‘(’ <string:QUOTED> ‘)’ ) | ( ‘C_’ ‘(’ <context:QUOTED> ‘,’ <string:QUOTED> ‘)’ )

Use _("...") to mark strings as translatable. You can put a comment for translators on the line above if needed.

Gtk.Label label {
  /* Translators: This is the main text of the welcome screen */
  label: _("Hello, world!");
}

Use C_("context", "...") to add a message context to a string to disambiguate it, in case the same string appears in different places. Remember, two strings might be the same in one language but different in another depending on context.

Gtk.Label label {
  /* Translators: This is a section in the preferences window */
  label: C_("preferences window", "Hello, world!");
}

Bindings

Binding = ‘bind’ Expression (BindingFlag)* BindingFlag = ‘inverted’ | ‘bidirectional’ | ‘sync-create’

Bindings keep a property updated as other properties change. They can be used to keep the UI in sync with application data, or to connect two parts of the UI.

The simplest bindings connect to a property of another object in the blueprint. When that other property changes, the bound property updates as well. More advanced bindings can do multi-step property lookups and can even call application code to compute values. See the expressions page.

Simple Bindings

A binding that consists of a source object and a single lookup is called a “simple binding”. These are implemented using GObject property bindings and support a few flags:

• bidirectional: The binding is two-way, so changes to the target property will also update the source property.

• inverted: For boolean properties, the target is set to the inverse of the source property.

• no-sync-create: Normally, when a binding is created, the target property is immediately updated with the current value of the source property. This flag disables that behavior, and the bound property will be updated the next time the source property changes.

Complex Bindings

Bindings with more complex expressions are implemented with Gtk.Expression. These bindings do not support flags.

Example

/* Use bindings to show a label when a switch
 * is active, without any application code */

Switch advanced_feature {}

Label warning {
  visible: bind advanced_feature.active;
  label: _("This is an advanced feature. Use with caution!");
}

Object Values

ObjectValue = Object

The value of a property can be an object, specified inline. This is particularly useful for widgets that use a child property rather than a list of child widgets. Objects constructed in this way can even have IDs and be referenced in other places in the blueprint.

Such objects cannot have child annotations because they aren’t, as far as blueprint is concerned, children of another object.

String Values

StringValue = Translated | QuotedLiteral

Menus, as well as some extensions, have properties that can only be string literals or translated strings.

Array Values

ArrayValue = ‘[’ (StringValue),* ‘]’

For now, it only supports Strings. This is because Gtk.Builder only supports string arrays.