### GObject Introspection Import Example

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/document_root.md

Imports classes and types from namespaces other than GTK. Requires the GIR name and version, and installed typelib files.

```blueprint
// Import libadwaita
using Adw 1;
```

--------------------------------

### Build Documentation

Source: https://github.com/gnome/blueprint-compiler/blob/main/CONTRIBUTING.md

Install necessary documentation tools and build the project's documentation using Meson and Ninja. Serve the documentation locally for preview.

```sh
pip install -U sphinx furo

meson -Ddocs=true build
# or
Meson --reconfigure -Ddocs=true build

ninja -C build docs/en

python -m http.server 2310 --bind 127.0.0.1 --directory build/docs/en/
xdg-open http://127.0.0.1:2310/
```

--------------------------------

### Blueprint Document Structure Example

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/document_root.md

Illustrates the basic structure of a Blueprint document, including GTK declaration, imports, and an object definition.

```blueprint
// Gtk Declaration
using Gtk 4.0;

// Import Statement
using Adw 1;

// Object
Window my_window {}
```

--------------------------------

### Blueprint Version Conflict Example

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/diagnostics.md

This example demonstrates a version conflict where two different versions of the same namespace are imported. Ensure only one version of a namespace is imported to avoid this error.

```blueprint
using Gtk 4.0;
using Gtk 3.0;
```

```blueprint
using Gtk 4.0;
using Handy 1;
```

--------------------------------

### Create Simple Property Binding

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/values.md

Use `bind` to link properties, keeping them synchronized. This example shows a label's visibility bound to a switch's active state.

```blueprint
Switch show_label {}

Label {
  visible: bind show_label.active;
  label: _("I'm a label that's only visible when the switch is enabled!");
}
```

--------------------------------

### Example Blueprint UI Definition

Source: https://github.com/gnome/blueprint-compiler/blob/main/README.md

This snippet demonstrates the syntax for defining a GTK application window with various widgets, including header bars, overlays, and custom components like Shumate.Map and Shumate.Compass. It showcases nested layouts and property bindings.

```blueprint
using Gtk 4.0;
using Shumate 1.0;

template ShumateDemoWindow : Gtk.ApplicationWindow {
  can-focus: yes;
  title: _("Shumate Demo");
  default-width: 800;
  default-height: 600;

  [titlebar]
  Gtk.HeaderBar {
    Gtk.DropDown layers_dropdown {
      notify::selected => on_layers_dropdown_notify_selected() swapped;
    }
  }

  Gtk.Overlay overlay {
    vexpand: true;
    Shumate.Map map {}

    [overlay]
    Shumate.Scale scale {
      halign: start;
      valign: end;
    }

    [overlay]
    Gtk.Box {
      orientation: vertical;
      halign: end;
      valign: end;

      Shumate.Compass compass {
        halign: end;
        map: map;
      }
      Shumate.License license {
        halign: end;
      }
    }
  }
}
```

--------------------------------

### Blueprint: Missing User-Facing Text Properties (Correct)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This example demonstrates correct Blueprint code, providing appropriate human-readable text properties for Button and Entry elements, adhering to GNOME HIG typography.

```blueprint
Button {
   label: _("Submit");
}
Entry {
   placeholder-text: _("Enter username");
}
```

--------------------------------

### Define Initial Composite Widget Structure

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/templates.md

An example of an initial composite widget structure where child components are defined directly within the parent widget's blueprint. This approach is contrasted with using separate template files for better organization.

```blueprint
using Gtk 4.0;

$MapsApplicationWindow window {
  $MapsHeaderBar {
    /* probably a lot of buttons ... */
  }

  $MapsMainView {
    /* a lot more UI definitions ... */
  }
}
```

--------------------------------

### Import GObject Introspection Namespaces in Blueprint

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/packaging.md

Use this syntax in your Blueprint files to import GObject Introspection namespaces. Ensure the corresponding .typelib files are installed for compilation.

```blueprint
using Gtk 4.0;
using Adw 1;
```

--------------------------------

### Setting Image Widget as Presentation Role

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/diagnostics.md

This example shows how to set an Image widget's accessibility role to 'presentation'. This is used for purely decorative images that do not need to be conveyed to accessibility software.

```blueprint
Image {
  accessible-role: presentation;
}
```

--------------------------------

### Blueprint: Missing User-Facing Text Properties (Incorrect)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This example shows incorrect Blueprint code where user-facing elements like Button and Entry are declared without essential text properties.

```blueprint
Button {
}
Entry {
}
```

--------------------------------

### Adw.AlertDialog Responses Example

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/extensions.md

Defines buttons for an Adw.AlertDialog, specifying their text, and optional flags like 'destructive', 'suggested', or 'disabled'. Use this to customize dialog button behavior and appearance.

```blueprint
using Adw 1;

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

--------------------------------

### Incorrect Scrollable Parent for ListView

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/diagnostics.md

This example shows an incorrect setup where a ListView is placed inside an Adw.Clamp, which does not provide scrolling. This can lead to incorrect behavior as the parent widget must handle scrolling.

```blueprint
ScrolledWindow {
  Adw.Clamp {
    ListView {}
  }
}
```

--------------------------------

### Define Child Types for HeaderBar

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/objects.md

Illustrates using child type annotations '[start]' and '[end]' to position Label and Button widgets within a HeaderBar.

```blueprint
HeaderBar {
  [start]
  Label {
  }

  [end]
  Button {
  }
}
```

--------------------------------

### Run Test Suite

Source: https://github.com/gnome/blueprint-compiler/blob/main/CONTRIBUTING.md

Execute the project's test suite using Python's unittest module. Ensure you are in the project's root directory.

```sh
python -m unittest
```

--------------------------------

### GTK Declaration Syntax

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/document_root.md

Specifies the target GTK version for the Blueprint file. Tools should verify support for the declared version.

```blueprint
using Gtk 4.0;
```

--------------------------------

### Blueprint Compiler Meson Subproject Configuration

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/setup.md

Configure blueprint-compiler as a meson subproject by saving this content to `subprojects/blueprint-compiler.wrap`. This specifies the Git repository, revision, and provides the program name.

```cfg
[wrap-git]
directory = blueprint-compiler
url = https://gitlab.gnome.org/GNOME/blueprint-compiler.git
revision = main
depth = 1

[provide]
program_names = blueprint-compiler
```

--------------------------------

### Basic GTK Window in Blueprint

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/index.md

This snippet defines a simple GTK 4 application window using Blueprint syntax. It includes setting the default size, title, and a label with a bound text property.

```blueprint
using Gtk 4.0;

template $MyAppWindow: ApplicationWindow {
  default-width: 600;
  default-height: 300;
  title: _("Hello, Blueprint!");

  [titlebar]
  HeaderBar {}

  Label {
    label: bind template.main_text;
  }
}
```

--------------------------------

### Define a Menu with Submenus and Items

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/menus.md

Use the `menu` keyword to define a menu structure. Submenus can contain nested children and attributes. Menu items can specify labels, actions, and icons.

```blueprint
menu my_menu {
  submenu {
    label: _("File");
    item {
      label: _("New");
      action: "app.new";
      icon: "document-new-symbolic";
    }
  }
}

MenuButton {
  menu-model: my_menu;
}
```

--------------------------------

### Blueprint: Translatable Display Strings (Correct)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This correct Blueprint code snippet demonstrates marking all user-visible strings with the _(...) function, ensuring they are properly flagged for translation.

```blueprint
Label {
   label: _("foo");
}
Button {
   tooltip-text: _("foo");
}
Window {
   title: _("foobar");
}
```

--------------------------------

### Define Dialog/InfoBar Action Responses

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/extensions.md

Use the 'action response' child extension to set the action and response type for children of Gtk.Dialog or Gtk.InfoBar. The 'default' flag can be applied to one child.

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

 [action response=cancel]
 Button {}

 [action response=1]
 Button {}
}
```

--------------------------------

### Blueprint: Promote Styles Over CSS Classes (Correct)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This correct Blueprint code snippet utilizes the `styles` array to apply visual styling, which is the recommended approach over using `css-classes`.

```blueprint
Box {
   orientation: vertical;
   overflow: hidden;
   styles [
      "Card",
      "translation-side-box",
   ]
}
```

--------------------------------

### Menu Item Shorthand Syntax

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/menus.md

Blueprint offers a shorthand for defining menu items with common properties like label, action, and icon. This reduces boilerplate for frequently used item configurations.

```blueprint
menu {
  item ("label")
  item ("label", "action")
  item ("label", "action", "icon")
}
```

--------------------------------

### Define Gtk.StringList Strings

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/extensions.md

Use the 'strings' block to populate a Gtk.StringList with a list of string values. Labels can be translated using the '_' function.

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

--------------------------------

### Define Blueprint Objects

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/objects.md

Define basic UI elements like Labels with their properties. Object IDs must be unique within their scope.

```blueprint
Label label1 {
  label: "Hello, world!";
}
Label label2 {
  label: bind-property file.name;
}
```

--------------------------------

### Blueprint: Correct Gtk.Adjustment Property Order

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This correct Blueprint code snippet demonstrates the proper order for Gtk.Adjustment properties: lower, upper, and then value, ensuring clarity and consistency.

```blueprint
Scale one {
   width-request: 130;
   adjustment: Adjustment {
      lower: 0;
      upper: 100;
      value: 50;
   };
}
```

--------------------------------

### Lint a Single Blueprint File

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

Use this command to lint a single Blueprint file. Ensure the blueprint-compiler.py script is accessible in your PATH or specify its full path.

```default
python blueprint-compiler.py lint <file1.blp>
```

--------------------------------

### Include Compiled Blueprints in GResource Compilation

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/setup.md

Add the compiled blueprints as a dependency to your `gnome.compile_resources` command in `meson.build` to include them in your application's resources.

```meson
dependencies: blueprints,

```

--------------------------------

### Integrate Gettext Translations with Meson

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/translations.md

Use Meson's i18n module with the 'glib' preset for seamless integration of gettext translation tools.

```meson
i18n.gettext('package name', preset: 'glib')
```

--------------------------------

### Lint Multiple Blueprint Files

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

To lint multiple Blueprint files, list them as arguments after the lint command. This allows for batch checking of several files simultaneously.

```default
python blueprint-compiler.py lint <file1.blp> <file2.blp> <file3.blp>
```

--------------------------------

### Gtk.FileFilter Filters

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/extensions.md

Configures filters for Gtk.FileFilter, specifying mime types, glob patterns, or file extensions.

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

--------------------------------

### Mark Strings for Translation

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/values.md

Use `_("...")` to mark strings for translation. Add translator comments above the line.

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

--------------------------------

### Add Children to a Container

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/objects.md

Demonstrates nesting a Button within an Image, creating a simple hierarchical structure for a UI element.

```blueprint
Button {
  Image {}
}
```

--------------------------------

### Compile Blueprints with Meson

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/setup.md

Integrate blueprint compilation into your project's meson build process. This custom target uses `blueprint-compiler batch-compile` to process blueprint files before GResource compilation.

```meson
blueprints = custom_target('blueprints',
  input: files(
    # LIST YOUR BLUEPRINT FILES HERE
  ),
  output: '.',
  command: [find_program('blueprint-compiler'), 'batch-compile', '--minify', '@OUTPUT@', '@CURRENT_SOURCE_DIR@', '@INPUT@'])

```

--------------------------------

### Gtk.BuilderListItemFactory Templates

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/extensions.md

Defines a template for creating list items using Gtk.BuilderListItemFactory. The template must be a Gtk.ListItem, Gtk.ColumnViewRow, or Gtk.ColumnViewCell.

```blueprint
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" ]
    };
  };
}
```

--------------------------------

### Lint an Entire Directory

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

Scan all Blueprint files within a specified directory by providing the directory path to the lint command. This is useful for checking an entire project or module.

```default
python blueprint-compiler.py lint test/directory/location/
```

--------------------------------

### Blueprint: Avoid All Caps (Correct)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This correct Blueprint code snippet uses standard casing for the label text, avoiding all caps for better readability and adherence to best practices.

```blueprint
Button {
  label: _("Submit");
}
```

--------------------------------

### Try Expression for Fallback Values

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/expressions.md

Uses a try expression to attempt multiple expressions in order, returning the value of the first one that succeeds. Useful for providing fallback values.

```blueprint
Label {
  label: bind try { template.account.username, "Guest" };
}
```

--------------------------------

### Apply CSS Styles to Widgets

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/extensions.md

The 'styles' block allows you to apply CSS classes to a widget, which can then be styled using a separate CSS file. This is valid for any Gtk.Widget.

```blueprint
Button {
  styles ["suggested-action"]
}
```

--------------------------------

### Mark Strings for Translation in Blueprint

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/translations.md

Use the `_()` function to mark strings for translation. Ensure double quotes are used for the translated strings.

```blueprint
_("translated string")
```

--------------------------------

### Disambiguate Translations with Context in Blueprint

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/translations.md

Use `C_()` with a context string as the first argument to disambiguate identical English strings that appear in different contexts.

```blueprint
C_("shortcuts window", "Quit")
```

--------------------------------

### Define Object Properties

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/objects.md

Specify object details using properties. Properties can be static values or bound to data models. Inline objects are allowed for property values.

```blueprint
Label {
  label: "text";
}

Button {
  /* Inline object value. Notice the semicolon after the object. */
  child: Image {
    /* ... */
  };
}
```

--------------------------------

### Accessibility Description for Image Widget

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/diagnostics.md

Use this snippet to provide a descriptive text for an Image widget, which is crucial for screen readers and accessibility software. This ensures the purpose of the image is conveyed to users with disabilities.

```blueprint
Image {
  accessibility {
    description: _("A cat jumping into a box");
  }
}
```

--------------------------------

### Blueprint: Avoid All Caps (Incorrect)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This incorrect Blueprint code snippet uses all capital letters for the label text, which is discouraged for user-facing strings.

```blueprint
Button {
  label: _("SUBMIT");
}
```

--------------------------------

### Define Gtk.Scale Marks

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/extensions.md

Use the 'marks' block to define custom marks on a Gtk.Scale. Each mark can have a value, an optional position (left, right, top, bottom), and an optional label.

```blueprint
Scale {
  marks [
    mark (-1, bottom),
    mark (0, top, _("Origin")),
    mark (2),
  ]
}
```

--------------------------------

### Gtk.ComboBoxText Items

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/extensions.md

Defines items for Gtk.ComboBoxText. An optional ID can be provided for each item.

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

--------------------------------

### Add Message Context for Translations

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/values.md

Use `C_("context", "...")` to add a message context for disambiguation, especially when the same string appears in different parts of the UI.

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

--------------------------------

### Blueprint: Invalid Child Count for Label (Incorrect)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This incorrect Blueprint code demonstrates passing a child Button to a Label, which does not accept children and will not render the child, potentially confusing beginners.

```blueprint
// No child allowed
Label {
   label: "Hello";
      Button {
         label: "World";
      }
}
```

--------------------------------

### Define Child Extensions for Dialog

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/objects.md

Shows how to use a child extension annotation '[action response=cancel]' to specify the response type for a Button child of a Dialog.

```blueprint
Dialog {
  [action response=cancel]
  Button {}
}
```

--------------------------------

### Bind Label to Username Expression

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/expressions.md

Binds the label property to an expression that re-evaluates when the account or its username changes.

```blueprint
label: bind template.account.username;
/*     ^             ^       ^
       |             creates lookup expressions that are re-evaluated when
       |             the account's username *or* the account itself changes
       |
       binds the `label` property to the expression's output
 */
```

--------------------------------

### xgettext Flags for Blueprint Translations

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/translations.md

These flags are necessary for xgettext to correctly parse Blueprint files and extract translatable strings.

```bash
--from-code=UTF-8
--add-comments
--keyword=_ 
--keyword=C_:1c,2
```

--------------------------------

### Widget Layouts

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/extensions.md

Defines widget positioning within a parent. Properties like 'column', 'row', and 'row-span' are dependent on the parent's layout manager.

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

--------------------------------

### Blueprint: Untranslated Display Strings (Incorrect)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This incorrect Blueprint code shows user-visible strings in Label, Button, and Window elements that are not marked as translatable using the _(...) function.

```blueprint
Label {
   label: "foo";
}
Button {
   tooltip-text: "foo";
}
Window {
   title: "foobar";
}
```

--------------------------------

### Define Signal Handlers

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/objects.md

Connect UI events to application code using signal handlers. The handler name is prefixed with '$' to indicate an external symbol.

```blueprint
Button {
  clicked => $on_button_clicked();
}
```

--------------------------------

### Adw.MessageDialog Responses

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/extensions.md

Defines buttons for Adw.MessageDialog. Use flags like 'destructive', 'suggested', or 'disabled' to control button appearance and behavior.

```blueprint
using Adw 1;

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

--------------------------------

### Define Gtk.SizeGroup Widgets

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/extensions.md

The 'widgets' block within a Gtk.SizeGroup definition specifies which widgets should be managed by the size group for consistent sizing.

```blueprint
Box {
  Button button1 {}
  Button button2 {}
}

SizeGroup {
  widgets [button1, button2]
}
```

--------------------------------

### Gtk.LevelBar Offsets

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/extensions.md

Defines offsets for Gtk.LevelBar, each specified with a CSS class name and a non-negative value.

```blueprint
LevelBar {
  offsets [
    offset ("low-class-name", 0.3),
    offset ("medium-class-name", 0.5),
    offset ("high-class-name", 0.7),
  ]
}
```

--------------------------------

### Add Blueprint Compiler Directory to Gitignore

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/setup.md

Ensure the blueprint-compiler subproject directory is ignored by Git to prevent accidental commits.

```default
/subprojects/blueprint-compiler
```

--------------------------------

### Blueprint: Valid Single Child for Adw.StatusPage

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This correct Blueprint code demonstrates the proper usage of Adw.StatusPage by providing a single child element, as intended by the widget.

```blueprint
// Single child allowed
Adw.StatusPage {
   Button {
      label: "a";
   }
}
```

--------------------------------

### Reference Template Object in Binding

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/templates.md

Use the `template` keyword within a blueprint to reference the template object itself, enabling bindings to its properties. This is useful for creating reactive UI elements.

```blueprint
template $MyTemplate {
  prop1: "Hello, world!";
  prop2: bind template.prop1;
}
```

--------------------------------

### Specify Item Type with Type Literal

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/values.md

Use `typeof<>` to specify the GType for items in collections like Gio.ListStore.

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

--------------------------------

### Blueprint: Incorrect Gtk.Adjustment Property Order

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This incorrect Blueprint code snippet shows Gtk.Adjustment properties declared out of the recommended order (lower, upper, then value), which can lead to confusion.

```blueprint
Scale one {
   width-request: 130;
   adjustment: Adjustment {
      lower: 0;
      value: 50;
      upper: 100;
   };
}
```

--------------------------------

### Define Composite Widget Structure

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/templates.md

Use a blueprint to define the internal structure of a composite widget, such as a custom header bar. This blueprint specifies the widget's type and its child components.

```blueprint
using Gtk 4.0;

template $MapsHeaderBar : Gtk.HeaderBar {
  /* probably a lot of buttons ... */
}

Gio.ListStore bookmarked_places_store {
  /* This isn't the object being instantiated, just an auxillary object. GTK knows this because it isn't the
     one marked with 'template'. */
}
```

--------------------------------

### Combine Flags with '|'

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/values.md

Combine multiple flag values for a property using the '|' operator.

```blueprint
Adw.TabView {
  shortcuts: control_tab | control_shift_tab;
}
```

--------------------------------

### Warn on Incorrect Widget Placement (Blueprint)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This rule flags widgets that are declared but not added to an appropriate parent widget, making them invisible and unused. Ensure all declared widgets are part of a renderable hierarchy.

```blueprint
// If this widget is declared but never added to a container (Box, Window, etc.). It's invisible and unused.

Label {
   label: _("Info")
}
```

```blueprint
// Label is part of a Box and Window which is rendered on a screen.

@template Window
window ApplicationWindow {
   default-width: 300
   default-height: 100
   title: _("Used widget")

   Box {
      orientation: vertical
      spacing: 6

      Label {
         label: _("Info")
      }
   }
}
```

--------------------------------

### Blueprint: Discourage CSS Classes Usage (Incorrect)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This incorrect Blueprint code uses the `css-classes` property, which is discouraged in favor of the `styles` array for applying visual styles.

```blueprint
Box {
   orientation: vertical;
   overflow: hidden;
   css-classes: ["shadowed"];
}
```

--------------------------------

### Blueprint: Prefer Unicode Characters (Correct)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This correct Blueprint code snippet utilizes Unicode characters for the string literal, demonstrating the preferred approach over ASCII characters for user-facing text.

```blueprint
// Using Unicode
Label {
   label: _("Click “OK”");
}
```

--------------------------------

### Reference Composite Widget in Parent

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/templates.md

Include a composite widget, defined in its own template blueprint, within the blueprint of a parent widget. The parent widget's blueprint does not need to define the composite widget's children.

```blueprint
using Gtk 4.0;

ApplicationWindow {
  $MapsHeaderBar {
    /* Nothing needed here, the widgets are in the MapsHeaderBar template. */
  }
}
```

--------------------------------

### Blueprint: Invalid Child Count for Adw.StatusPage (Incorrect)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This incorrect Blueprint code shows multiple children passed to Adw.StatusPage, which only allows a single child. Only the last child will be rendered, leading to unexpected behavior.

```blueprint
// Single child allowed
Adw.StatusPage {
   Button {
      label: "a";
   }

   Button {
      label: "b";
   }
}
```

--------------------------------

### Correct Scrollable Parent for ListView

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/diagnostics.md

This snippet illustrates the correct way to parent a ListView that implements Scrollable. It must be a direct child of a widget that provides scrolling, such as Adw.ClampScrollable, not Adw.Clamp.

```blueprint
ScrolledWindow {
  Adw.ClampScrollable {
    ListView {}
  }
}
```

--------------------------------

### Blueprint: Prefer Unicode Characters (Incorrect)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This incorrect Blueprint code uses ASCII characters within a string literal, where Unicode characters are preferred for better internationalization and character support.

```blueprint
// Using ASCII characters
Label {
   label: _("Click "OK"");
}
```

--------------------------------

### Blueprint: Valid Child Count for Label

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This correct Blueprint code shows a Label element used appropriately without any children, as Labels do not support child elements.

```blueprint
// No child allowed
Label {
   label: "Hello";
}
```

--------------------------------

### Define Internal Children for Dialog

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/objects.md

Explains the use of '[internal-child content_area]' to modify an existing object provided by the parent, such as the 'content_area' of a Dialog, rather than creating a new one.

```blueprint
Dialog {
  [internal-child content_area]
  Box {
    // Unlike most objects in a blueprint, this internal-child widget
    // represents the properties, signal handlers, children, and extensions
    // of an existing Box created by the Dialog, not a new Box created by
    // the blueprint.
  }
}
```

--------------------------------

### Cast Closure Result to String

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/expressions.md

Casts the result of a closure expression to a string, allowing Blueprint to determine the return type.

```blueprint
label: bind $format_bytes(template.file-size) as <string>
```

--------------------------------

### Clamp in ScrolledWindow Warning (Blueprint)

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/linter.md

This rule enforces the correct usage of Adw.Clamp as a child property of ScrolledWindow for proper scroll behavior. Incorrect placement can lead to unexpected scrolling issues.

```blueprint
ScrolledWindow {
   child: Adw.Clamp {
      child: Box {
         Label {
         label: _("This is incorrect");
         }
      }
   }
}
```

```blueprint
Adw.Clamp {
   child: ScrolledWindow {
      child: Box {
         Label {
         label: _("This is correct");
         }
      }
   }
}
```

--------------------------------

### Expression Value for Filtering

Source: https://github.com/gnome/blueprint-compiler/blob/main/docs/reference/expressions.md

Defines an expression for a property that accepts an expression itself, using 'expr' and 'item' to refer to the evaluated item. The item must be cast to its correct type.

```blueprint
BoolFilter {
  expression: expr item as <$UserAccount>.active;
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.