Examples#

Namespaces and libraries#

GTK declaration#

// Required in every blueprint file. Defines the major version
// of GTK the file is designed for.
using Gtk 4.0;

Importing libraries#

// Import Adwaita 1. The name given here is the GIR namespace name, which
// might not match the library name or C prefix.
using Adw 1;

Objects#

Defining objects with properties#

Gtk.Box {
  orientation: vertical;

  Gtk.Label {
    label: "Hello, world!";
  }
}

Referencing an object in code#

// Your code can reference the object by `my_window`
Gtk.Window my_window {
  title: "My window";
}

Using classes defined by your app#

Use a leading . to tell the compiler that the class is defined in your app, not in the GIR, so it should skip validation.

.MyAppCustomWidget my_widget {
  my-custom-property: 3.14;
}

Templates#

Defining a template#

Many language bindings have a way to create subclasses that are defined both in code and in the blueprint file. Check your language’s documentation on how to use this feature.

In this example, we create a class called MyAppWindow that inherits from Gtk.ApplicationWindow.

template MyAppWindow : Gtk.ApplicationWindow {
  my-custom-property: 3.14;
}

Properties#

Translations#

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!");
}

Referencing objects by ID#

Gtk.Range range1 {
  adjustment: my_adjustment;
}
Gtk.Range range2 {
  adjustment: my_adjustment;
}

Gtk.Adjustment my_adjustment {
}

Defining object properties inline#

Gtk.Range  {
  adjustment: Gtk.Adjustment my_adjustment {
    value: 10;
  };
}

Gtk.Range range1 {
  // You can even still reference the object by ID
  adjustment: my_adjustment;
}

Note

Note the semicolon after the closing brace of the Gtk.Adjustment. It is required.

Bindings#

Use the bind keyword to bind a property to another object’s property in the same file.

Gtk.ProgressBar bar1 {
}

Gtk.ProgressBar bar2 {
  value: bind bar1.value;
}

Binding Flags#

Use the no-sync-create keyword to only update the target value when the source value changes, not when the binding is first created.

Gtk.ProgressBar bar1 {
  value: 10;
}

Gtk.ProgressBar bar2 {
  value: bind bar1.value no-sync-create;
}

Use the bidirectional keyword to bind properties in both directions.

// Text of entry1 is bound to text
// of entry2 and vice versa

Gtk.Entry entry1 {
  text: bind entry2.text bidirectional;
}

Gtk.Entry entry2 {

}

Use the inverted keyword to invert to bind a boolean property to inverted value of another one.

// When switch1 is on, switch2 will be off
Gtk.Switch switch1 {
  active: bind switch2.active inverted bidirectional;
}

// When switch2 is on, switch1 will be off
Gtk.Switch switch2 {

}

Signals#

Basic Usage#

Gtk.Button {
  // on_button_clicked is defined in your application
  clicked => on_button_clicked();
}

Flags#

Gtk.Button {
  clicked => on_button_clicked() swapped;
}

Object#

By default the widget is passed to callback as first argument. However, you can specify another object to use as first argument of callback.

Gtk.Entry {
  activate => grab_focus(another_entry);
}

Gtk.Entry another_entry {

}

CSS Styles#

Basic Usage#

Gtk.Label {
  styles ["dim-label", "title"]
}

Menus#

Basic Usage#

menu my_menu {
  section {
    label: _("File");
    item {
      label: _("Open");
      action: "win.open";
    }
    item {
      label: _("Save");
      action: "win.save";
    }
    submenu {
      label: _("Save As");
      item {
        label: _("PDF");
        action: "win.save_as_pdf";
      }
    }
  }
}

Item Shorthand#

For menu items with only a label, action, and/or icon, you can define all three on one line. The action and icon are optional.

menu {
  item (_("Copy"), "app.copy", "copy-symbolic")
}

Layout Properties#

Basic Usage#

Gtk.Grid {
  Gtk.Label {
    layout {
      row: 0;
      column: 1;
    }
  }
}

Accessibility Properties#

Basic Usage#

Gtk.Widget {
  accessibility {
    orientation: vertical;
    labelled_by: my_label;
    checked: true;
  }
}

Gtk.Label my_label {}

Widget-Specific Items#

Gtk.ComboBoxText#

Gtk.ComboBoxText {
  items [
    item1: "Item 1",
    item2: _("Items can be translated"),
    "The item ID is not required",
  ]
}

Gtk.FileFilter#

Gtk.FileFilter {
  mime-types ["image/jpeg", "video/webm"]
  patterns ["*.txt"]
  suffixes ["png"]
}

Gtk.SizeGroup#

Gtk.SizeGroup {
  mode: both;
  widgets [label1, label2]
}

Gtk.Label label1 {}
Gtk.Label label2 {}

Gtk.StringList#

Gtk.StringList {
  strings ["Hello, world!", _("Translated string")]
}

Gtk.Dialog and Gtk.InfoBar#

Gtk.Dialog {
  [action response=ok]
  Gtk.Button ok_response {}

  [action response=cancel]
  Gtk.Button cancel_response {}

  [action response=9]
  Gtk.Button app_defined_response {}
}