Extensions - Blueprint documentation

Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# 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.

Extension = ExtAccessibility | ExtAdwAlertDialog | ExtAdwMessageDialog | ExtAdwBreakpoint | ExtComboBoxItems | ExtFileFilterMimeTypes | ExtFileFilterPatterns | ExtFileFilterSuffixes | ExtLayout | ExtListItemFactory | ExtSizeGroupWidgets | ExtStringListStrings | ExtStyles

## Accessibility Properties

ExtAccessibility = ‘accessibility’ ‘{’ ExtAccessibilityProp* ‘}’ ExtAccessibilityProp = <name:IDENT> ‘:’ (Value | (‘[’ (:ref: Value <Syntax 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.

Note

Relations which allow for a list of values, for example labelled-by, must be given as a single relation with a list of values instead of duplicating the relation like done in Gtk.Builder.

## 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.

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.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, Gtk.ColumnViewRow, or Gtk.ColumnViewCell 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 {}
    }