Extensions#

Properties are the main way to set values on objects, but they are limited by the GObject type system in what values they can accept. Some classes, therefore, have specialized syntax for certain features.

Note

Extensions are a feature of Gtk.Buildable–see Gtk.Buildable.custom_tag_start() for internal details.

Because they aren’t part of the type system, they aren’t present in typelib files like properties and signals are. Therefore, if a library adds a new extension, syntax for it must be added to Blueprint manually. If there’s a commonly used extension that isn’t supported by Blueprint, please file an issue.

Accessibility Properties#

ExtAccessibility = ‘accessibility’ ‘{’ ExtAccessibilityProp* ‘}’ ExtAccessibilityProp = <name:IDENT> ‘:’ Value ‘;’

Valid in any Gtk.Widget.

The accessibility block defines values relevant to accessibility software. The property names and acceptable values are described in the Gtk.AccessibleRelation, Gtk.AccessibleState, and Gtk.AccessibleProperty enums.

Adw.Breakpoint#

ExtAdwBreakpointCondition = ‘condition’ ‘(’ <condition:QUOTED> ‘)’ ExtAdwBreakpoint = ‘setters’ ‘{’ ExtAdwBreakpointSetter* ‘}’ ExtAdwBreakpointSetter = <object:IDENT> ‘.’ <property:IDENT> ‘:’ Value ‘;’

Valid in Adw.Breakpoint.

Defines the condition for a breakpoint and the properties that will be set at that breakpoint. See the documentation for Adw.Breakpoint.

Note

The Adw.Breakpoint:condition property has type Adw.BreakpointCondition, which GtkBuilder doesn’t know how to parse from a string. Therefore, the condition syntax is used instead.

Adw.AlertDialog Responses#

ExtAdwAlertDialog = ‘responses’ ‘[’ (ExtAdwAlertDialogResponse),* ‘]’ ExtAdwAlertDialogResponse = <id:IDENT> ‘:’ StringValue ExtAdwAlertDialogFlag* ExtAdwAlertDialogFlag = ‘destructive’ | ‘suggested’ | ‘disabled’

Valid in Adw.AlertDialog.

The responses block defines the buttons that will be added to the dialog. The destructive or suggested flag sets the appearance of the button, and the disabled flag can be used to disable the button.

using Adw 1;

Adw.AlertDialog {
  responses [
    cancel: _("Cancel"),
    delete: _("Delete") destructive,
    save: "Save" suggested,
    wipeHardDrive: "Wipe Hard Drive" destructive disabled,
  ]
}

Adw.MessageDialog Responses#

ExtAdwMessageDialog = ‘responses’ ‘[’ (ExtAdwMessageDialogResponse),* ‘]’ ExtAdwMessageDialogResponse = <id:IDENT> ‘:’ StringValue ExtAdwMessageDialogFlag* ExtAdwMessageDialogFlag = ‘destructive’ | ‘suggested’ | ‘disabled’

Valid in Adw.MessageDialog.

using Adw 1;

Adw.MessageDialog {
  responses [
    cancel: _("Cancel"),
    delete: _("Delete") destructive,
    save: "Save" suggested,
    wipeHardDrive: "Wipe Hard Drive" destructive disabled,
  ]
}

Gtk.ComboBoxText Items#

ExtComboBoxItems = ‘items’ ‘[’ (ExtComboBoxItem),* ‘]’ ExtComboBoxItem = ( <id:IDENT> ‘:’ )? StringValue

Valid in Gtk.ComboBoxText, which is deprecated as of Gtk 4.10.

The items block defines the items that will be added to the combo box. The optional ID can be used to refer to the item rather than its label.

ComboBoxText {
  items [
    item1: "Item 1",
    item2: "Item 2",
    item3: "Item 3",
  ]
}

Gtk.FileFilter Filters#

ExtFileFilterMimeTypes = ‘mime-types’ ‘[’ (ExtFileFilterItem),* ‘]’ ExtFileFilterPatterns = ‘patterns’ ‘[’ (ExtFileFilterItem),* ‘]’ ExtFileFilterSuffixes = ‘suffixes’ ‘[’ (ExtFileFilterItem),* ‘]’ ExtFileFilterItem = <item:QUOTED>

Valid in Gtk.FileFilter.

The mime-types, patterns, and suffixes blocks define the items that will be added to the file filter. The mime-types block accepts mime types (including wildcards for subtypes, such as image/*). The patterns block accepts glob patterns, and the suffixes block accepts file extensions.

FileFilter {
  mime-types [ "text/plain", "image/*" ]
  patterns [ "*.txt" ]
  suffixes [ "png", "jpg" ]
}

Widget Layouts#

ExtLayout = ‘layout’ ‘{’ ExtLayoutProp* ‘}’ ExtLayoutProp = <name:IDENT> ‘:’ Value ‘;’

Valid in Gtk.Widget.

The layout block describes how the widget should be positioned within its parent. The available properties depend on the parent widget’s layout manager.

Grid {
  Button {
    layout {
      column: 0;
      row: 0;
    }
  }
  Button {
    layout {
      column: 1;
      row: 0;
    }
  }
  Button {
    layout {
      column: 0;
      row: 1;
      row-span: 2;
    }
  }
}

Gtk.BuilderListItemFactory Templates#

ExtListItemFactory = ‘template’ TypeName ObjectContent

Valid in Gtk.BuilderListItemFactory.

The template block defines the template that will be used to create list items. This block is unique within Blueprint because it defines a completely separate sub-blueprint which is used to create each list item. The sub-blueprint may not reference objects in the main blueprint or vice versa.

The template type must be Gtk.ListItem. The template object can be referenced with the template keyword.

ListView {
  factory: BuilderListItemFactory {
    template ListItem {
      child: Label {
        label: bind template.item as <StringObject>.string;
      };
    }
  };

  model: NoSelection {
    model: StringList {
      strings [ "Item 1", "Item 2", "Item 3" ]
    };
  };
}

Gtk.Scale Marks#

ExtScaleMarks = ‘marks’ ‘[’ (ExtScaleMark),* ‘]’ ExtScaleMark = ‘mark’ ‘(’ ( ‘-’ | ‘+’ )? <value:NUMBER> ( ‘,’ <position:IDENT> ( ‘,’ StringValue )? )? ‘)’

Valid in Gtk.Scale.

The marks block defines the marks on a scale. A single mark has up to three arguments: a value, an optional position, and an optional label. The position can be left, right, top, or bottom. The label may be translated.

Gtk.SizeGroup Widgets#

ExtSizeGroupWidgets = ‘widgets’ ‘[’ (ExtSizeGroupWidget),* ‘]’ ExtSizeGroupWidget = <id:IDENT>

Valid in Gtk.SizeGroup.

The widgets block defines the widgets that will be added to the size group.

Box {
  Button button1 {}
  Button button2 {}
}

SizeGroup {
  widgets [button1, button2]
}

Gtk.StringList Strings#

ExtStringListStrings = ‘strings’ ‘[’ (ExtStringListItem),* ‘]’ ExtStringListItem = StringValue

Valid in Gtk.StringList.

The strings block defines the strings in the string list.

StringList {
  strings ["violin", "guitar", _("harp")]
}

CSS Styles#

ExtStyles = ‘styles’ ‘[’ ExtStylesProp* ‘]’ ExtStylesProp = <name:QUOTED>

Valid in any Gtk.Widget.

The styles block defines CSS classes that will be added to the widget.

Button {
  styles ["suggested-action"]
}

Child Extensions#

ChildExtension = ExtResponse

Child extensions are similar to regular extensions, but they apply to a child of the object rather than the object itself. They are used to add properties to child widgets of a container, such as the buttons in a Gtk.Dialog. The child extension takes the place of a child type inside the square brackets.

Currently, the only child extension is ExtResponse.

Dialog & InfoBar Responses#

ExtResponse = ‘action’ ‘response’ ‘=’ ( <name:IDENT> | <id:NUMBER> ) ‘default’?

Valid as a child extension for children of Gtk.Dialog or Gtk.InfoBar, which are both deprecated as of Gtk 4.10.

The action response extension sets the action child type for the child and sets the child’s integer response type. The response type may be either a member of the Gtk.ResponseType enum or a positive, application-defined integer.

No more than one child of a dialog or infobar may have the default flag.

Dialog {
 [action response=ok default]
 Button {}

 [action response=cancel]
 Button {}

 [action response=1]
 Button {}
}