### AdwNavigationView Example

Source: https://github.com/gnome/libadwaita/blob/main/doc/migrating-to-breakpoints.md

An equivalent AdwNavigationView setup with two pages, using AdwNavigationPage and AdwHeaderBar.

```xml
<object class="AdwNavigationView">
  <child>
    <object class="AdwNavigationPage">
      <property name="title" translatable="yes">Page 1</property>
      <property name="tag">page-1</property>
      <property name="child">
        <object class="AdwToolbarView">
          <child type="top">
            <object class="AdwHeaderBar"/>
          </child>
          <property name="content">
            <!-- ... -->
          </property>
        </object>
      </property>
    </object>
  </child>
  <child>
    <object class="AdwNavigationPage">
      <property name="title" translatable="yes">Page 2</property>
      <property name="tag">page-2</property>
      <property name="child">
        <object class="AdwToolbarView">
          <child type="top">
            <object class="AdwHeaderBar"/>
          </child>
          <property name="content">
            <!-- ... -->
          </property>
        </object>
      </property>
    </object>
  </child>
</object>
```

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

### Setup and Build Libadwaita with Documentation

Source: https://github.com/gnome/libadwaita/blob/main/README.md

Commands to set up the build environment and compile libadwaita with documentation enabled.

```sh
meson setup _build -Ddocumentation=true
ninja -C _build
```

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

### Setup and Build Libadwaita

Source: https://github.com/gnome/libadwaita/blob/main/README.md

Basic commands to set up the build environment and compile libadwaita.

```sh
meson setup _build
ninja -C _build
ninja -C _build install
```

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

### AdwLeaflet Example

Source: https://github.com/gnome/libadwaita/blob/main/doc/migrating-to-breakpoints.md

A typical AdwLeaflet setup with two pages, demonstrating its structure and properties.

```xml
<object class="AdwLeaflet">
  <property name="can-unfold">False</property>
  <property name="can-navigate-back">True</property>
  <child>
    <object class="AdwLeafletPage">
      <property name="name">page-1</property>
      <property name="child">
        <object class="AdwToolbarView">
          <child type="top">
            <object class="GtkHeaderBar">
              <property name="title-widget">
                <object class="AdwWindowTitle">
                  <property name="title" translatable="yes">Page 1</property>
                </object>
              </property>
            </object>
          </child>
          <property name="content">
            <!-- ... -->
          </property>
        </object>
      </property>
    </object>
  </child>
  <child>
    <object class="AdwLeafletPage">
      <property name="name">page-2</property>
      <property name="child">
        <object class="AdwToolbarView">
          <child type="top">
            <object class="GtkHeaderBar">
              <child type="start">
                <object class="GtkButton">
                  <property name="icon-name">go-previous-symbolic</property>
                  <property name="tooltip-text" translatable="yes">Back</property>
                  <signal name="clicked" handler="back_clicked_cb" swapped="yes"/>
                </object>
              </child>
              <property name="title-widget">
                <object class="AdwWindowTitle">
                  <property name="title" translatable="yes">Page 2</property>
                </object>
              </property>
            </object>
          </child>
          <property name="content">
            <!-- ... -->
          </property>
        </object>
      </property>
    </object>
  </child>
</object>
```

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

### Run Libadwaita C Example

Source: https://github.com/gnome/libadwaita/blob/main/README.md

Command to execute a compiled C example application for libadwaita.

```sh
_build/run _build/demo/adwaita-1-demo
```

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

### Example Widget UI File

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Create an IMAGE.ui file to define a widget for screenshot generation. Ensure the widget has the 'widget' ID.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<interface>
  <requires lib="gtk" version="4.0"/>
  <requires lib="libadwaita" version="1.0"/>
  <object class="GtkButton" id="widget">
    <property name="label">Example</property>
  </object>
</interface>
```

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

### Install Build Dependencies on macOS with Homebrew

Source: https://github.com/gnome/libadwaita/blob/main/doc/build-howto.md

Install necessary build tools like pkg-config, gtk4, meson, gobject-introspection, and vala using Homebrew on macOS.

```bash
brew install pkg-config gtk4 meson gobject-introspection vala
```

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

### Replacing AdwSqueezer with GtkBox and Breakpoint

Source: https://github.com/gnome/libadwaita/blob/main/doc/migrating-to-breakpoints.md

This example demonstrates replacing an AdwSqueezer with a GtkBox and using an AdwBreakpoint to toggle the box's orientation.

```xml
<object class="AdwSqueezer">
  <property name="homogeneous">False</property>
  <child>
    <object class="GtkBox">
      <property name="spacing">6</property>
      <child>
        <object class="GtkButton">
          <property name="label">Button 1</property>
        </object>
      </child>
      <child>
        <object class="GtkButton">
          <property name="label">Button 2</property>
        </object>
      </child>
    </object>
  </child>
  <child>
    <object class="GtkBox">
      <property name="orientation">vertical</property>
      <property name="spacing">6</property>
      <child>
        <object class="GtkButton">
          <property name="label">Button 1</property>
        </object>
      </child>
      <child>
        <object class="GtkButton">
          <property name="label">Button 2</property>
        </object>
      </child>
    </object>
  </child>
</object>
```

```xml
<object class="GtkBox" id="box">
  <property name="spacing">6</property>
  <child>
    <object class="GtkButton">
      <property name="label">Button 1</property>
    </object>
  </child>
  <child>
    <object class="GtkButton">
      <property name="label">Button 2</property>
    </object>
  </child>
</object>

<!-- ... -->

<object class="AdwBreakpoint">
  <condition>max-width: 400sp</condition>
  <setter object="box" property="orientation">vertical</setter>
</object>
```

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

### C Function Prototypes and Availability (Good Example)

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Shows the correct way to format C function prototypes, including grouping, alignment, parameter handling, and specifying availability with ADW_AVAILABLE_IN_ALL.

```c
ADW_AVAILABLE_IN_ALL
AdwFoo *adw_foo_new (void) G_GNUC_WARN_UNUSED_RESULT;

ADW_AVAILABLE_IN_ALL
AdwBar *adw_foo_get_bar (AdwFoo *self);
ADW_AVAILABLE_IN_ALL
void    adw_foo_set_bar (AdwFoo *self,
                         AdwBar *bar);

ADW_AVAILABLE_IN_ALL
gboolean adw_foo_get_bit (AdwFoo   *self);
ADW_AVAILABLE_IN_ALL
void     adw_foo_set_bit (AdwFoo   *self,
                          gboolean  bit);

ADW_AVAILABLE_IN_ALL
void adw_foo_add_baz    (AdwFoo *self,
                         AdwBaz *baz);
ADW_AVAILABLE_IN_ALL
void adw_foo_remove_baz (AdwFoo *self,
                         AdwBaz *baz);

ADW_AVAILABLE_IN_ALL
void adw_foo_frobnicate (AdwFoo *self);
```

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

### C Function Prototypes with Resource Transfer (Good Example)

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Illustrates the correct usage of G_GNUC_WARN_UNUSED_RESULT for functions that transfer ownership of a resource, preventing potential leaks.

```c
ADW_AVAILABLE_IN_ALL
AdwFoo *adw_foo_new (void) G_GNUC_WARN_UNUSED_RESULT;
ADW_AVAILABLE_IN_ALL
AdwFoo *adw_foo_ref (AdwFoo *self);

ADW_AVAILABLE_IN_ALL
char *adw_foo_to_string (AdwFoo *self) G_GNUC_WARN_UNUSED_RESULT;
```

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

### GTK Style Function Argument Indentation (Bad Example)

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Illustrates the incorrect way to format function arguments, which is discouraged due to reduced readability compared to the GTK style.

```c
static gboolean
key_press_event_cb (GtkWidget *widget, GdkEvent *event, gpointer data)
```

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

### AdwWrapBox Widget Example

Source: https://github.com/gnome/libadwaita/blob/main/doc/adaptive-layouts.md

Employ AdwWrapBox for layouts similar to Gtk.Box, but with the ability to wrap children onto new lines when they exceed available space. Children are not arranged in a grid.

```xml
<object class="AdwWrapBox">
  <property name="line-spacing">6</property>
  <property name="child-spacing">6</property>
  <!-- children -->
</object>
```

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

### GTK Style Function Argument Indentation (Good Example)

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Demonstrates the preferred GTK style for function argument indentation in C code. This style improves readability for complex function signatures.

```c
static gboolean
key_press_event_cb (GtkWidget *widget,
                    GdkEvent  *event,
                    gpointer   data)
```

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

### Link Libadwaita with GCC on macOS

Source: https://github.com/gnome/libadwaita/blob/main/doc/build-howto.md

Use pkg-config to get compiler flags for GTK4 and libadwaita-1 when linking your C application with GCC.

```bash
gcc $(pkg-config --cflags --libs gtk4) $(pkg-config --cflags --libs libadwaita-1) main.c -o main
```

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

### Basic Boxed List Example

Source: https://github.com/gnome/libadwaita/blob/main/doc/boxed-lists.md

This XML defines a basic GtkListBox styled as a boxed list, containing three ActionRows. Use this as a foundation for creating simple lists of items.

```xml
<object class="GtkListBox">
  <property name="selection-mode">none</property>
  <style>
    <class name="boxed-list"/>
  </style>
  <child>
    <object class="AdwActionRow">
      <property name="title">Item 1</property>
    </object>
  </child>
  <child>
    <object class="AdwActionRow">
      <property name="title">Item 2</property>
    </object>
  </child>
  <child>
    <object class="AdwActionRow">
      <property name="title">Item 3</property>
    </object>
  </child>
</object>
```

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

### Sidebar Structure Example

Source: https://github.com/gnome/libadwaita/blob/main/doc/migrating-to-breakpoints.md

This XML snippet demonstrates the basic structure of a sidebar within an AdwToolbarView, including a header bar and content area.

```xml
<property name="title" translatable="yes">Content</property>
          <property name="child">
            <object class="AdwToolbarView">
              <child type="top">
                <object class="AdwHeaderBar"/>
              </child>
              <property name="content">
                <!-- content -->
              </property>
            </object>
          </property>
        </object>
      </property>
    </object>
  </property>
</object>
```

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

### AdwFlap Utility Pane Example

Source: https://github.com/gnome/libadwaita/blob/main/doc/migrating-to-breakpoints.md

This XML snippet shows a common use case for AdwFlap as a utility pane within an AdwWindow. It includes a toggle button to reveal/hide the pane.

```xml
<object class="AdwWindow">
  <property name="content">
    <object class="AdwToolbarView">
      <property name="top-bar-style">raised</property>
      <child type="top">
        <object class="AdwHeaderBar">
          <object class="GtkToggleButton" id="toggle_pane_button">
            <property name="icon-name">sidebar-show-symbolic</property>
            <property name="active">True</property>
          </object>
        </object>
      </child>
      <property name="content">
        <object class="AdwFlap">
          <property name="reveal-flap"
                    bind-source="toggle_pane_button"
                    bind-property="active"
                    bind-flags="sync-create|bidirectional"/>
          <property name="flap">
            <!-- utility pane -->
          </property>
          <property name="separator">
            <object class="GtkSeparator"/>
          </property>
          <property name="content">
            <!-- main view -->
          </property>
        </object>

      </property>
    </object>
  </property>
</object>
```

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

### C Function Prototypes with Resource Transfer (Bad Example)

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Shows incorrect usage of G_GNUC_WARN_UNUSED_RESULT, where it is either omitted for functions transferring resources or incorrectly applied to reference counting methods.

```c
ADW_AVAILABLE_IN_ALL
AdwFoo *adw_foo_new (void);
ADW_AVAILABLE_IN_ALL
AdwFoo *adw_foo_ref (AdwFoo *self) G_GNUC_WARN_UNUSED_RESULT;

ADW_AVAILABLE_IN_ALL
char *adw_foo_to_string (AdwFoo *self);
```

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

### AdwMultiLayoutView Example

Source: https://github.com/gnome/libadwaita/blob/main/doc/adaptive-layouts.md

This XML snippet demonstrates how to use AdwMultiLayoutView to create a responsive layout. It defines two layouts, 'sidebar' and 'bottom-sheet', and uses AdwBreakpoint to switch between them based on screen width. The 'primary' and 'secondary' slots are used to place child elements.

```xml
<object class="AdwWindow">
  <child>
    <object class="AdwBreakpoint">
      <condition>max-width: 400sp</condition>
      <setter object="multi_layout_view" property="layout-name">bottom-sheet</setter>
    </object>
  </child>
  <property name="content">
    <object class="AdwMultiLayoutView" id="multi_layout_view">
      <child>
        <object class="AdwLayout">
          <property name="name">sidebar</property>
          <property name="content">
            <object class="AdwOverlaySplitView">
              <property name="sidebar-position">end</property>
              <property name="sidebar">
                <object class="AdwLayoutSlot">
                  <property name="id">secondary</property>
                </object>
              </property>
              <property name="content">
                <object class="AdwLayoutSlot">
                  <property name="id">primary</property>
                </object>
              </property>
            </object>
          </property>
        </object>
      </child>
      <child>
        <object class="AdwLayout">
          <property name="name">bottom-sheet</property>
          <property name="content">
            <object class="AdwBottomSheet">
              <property name="open">True</property>
              <property name="content">
                <object class="AdwLayoutSlot">
                  <property name="id">primary</property>
                </object>
              </property>
              <property name="sheet">
                <object class="AdwLayoutSlot">
                  <property name="id">secondary</property>
                </object>
              </property>
            </object>
          </property>
        </object>
      </child>
      <child type="primary">
        <!-- primary child -->
      </child>
      <child type="secondary">
        <!-- secondary child -->
      </child>
    </object>
  </property>
</object>
```

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

### CSS Font Usage Example

Source: https://github.com/gnome/libadwaita/blob/main/doc/css-variables.md

Use these variables together to apply system fonts for document or monospace text. Ensure the font family and size variables are correctly referenced.

```css
.my-content {
  font-family: var(--monospace-font-family);
  font-size: var(--monospace-font-size);
}
```

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

### Property Row Example

Source: https://github.com/gnome/libadwaita/blob/main/doc/boxed-lists.md

Demonstrates using AdwActionRow with the 'property' style class to display read-only properties. The title is deemphasized, and the subtitle is emphasized, making it suitable for displaying key-value pairs.

```xml
<object class="AdwActionRow">
  <property name="title" translatable="yes">Property Name</property>
  <property name="subtitle">Value</property>
  <property name="subtitle-selectable">True</property>
  <style>
    <class name="property"/>
  </style>
</object>
```

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

### AdwClamp Widget Example

Source: https://github.com/gnome/libadwaita/blob/main/doc/adaptive-layouts.md

Use AdwClamp to constrain a child widget's maximum size, adding padding when space is ample and removing it when constrained. This is often used for patterns like boxed lists.

```xml
<object class="AdwClamp">
  <property name="child">
    <object class="GtkBox">
      <property name="orientation">vertical</property>
      <property name="margin-top">24</property>
      <property name="margin-bottom">24</property>
      <property name="margin-start">12</property>
      <property name="margin-end">12</property>
      <property name="spacing">24</property>
      <child>
        <object class="GtkListBox">
          <property name="selection-mode">none</property>
          <style>
            <class name="boxed-list"/>
          </style>
          <!-- rows -->
        </object>
      </child>
      <!-- more lists -->
    </object>
  </property>
</object>
```

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

### Initialize Libadwaita with AdwApplication

Source: https://github.com/gnome/libadwaita/blob/main/doc/initialization.md

Use AdwApplication instead of Gtk.Application for automatic Libadwaita initialization. This is the recommended approach.

```c
#include <adwaita.h>

static void
activate_cb (GtkApplication *app)
{
  GtkWidget *window = gtk_application_window_new (app);
  GtkWidget *label = gtk_label_new ("Hello World");

  gtk_window_set_title (GTK_WINDOW (window), "Hello");
  gtk_window_set_default_size (GTK_WINDOW (window), 200, 200);
  gtk_window_set_child (GTK_WINDOW (window), label);
  gtk_window_present (GTK_WINDOW (window));
}

int
main (int   argc,
      char *argv[])
{
  g_autoptr (AdwApplication) app = NULL;

  app = adw_application_new ("org.example.Hello", G_APPLICATION_DEFAULT_FLAGS);

  g_signal_connect (app, "activate", G_CALLBACK (activate_cb), NULL);

  return g_application_run (G_APPLICATION (app), argc, argv);
}

```

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

### Run a Manual Test

Source: https://github.com/gnome/libadwaita/blob/main/tests/manual/README.md

Navigate to the build directory and execute a specific manual test executable.

```sh
cd build
./tests/manual/test-button-states
```

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

### Generate Screenshots

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Run the screenshot tool from the build directory to generate PNG images for documentation. Specify input data directory, output image directory, and an image name prefix.

```bash
./doc/tools/screenshot ../doc/tools/data/ ../doc/images/ -i IMAGE
```

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

### Build Libadwaita on macOS

Source: https://github.com/gnome/libadwaita/blob/main/doc/build-howto.md

Clone the libadwaita repository, set up the build environment with Meson, and compile the library using ninja.

```bash
git clone https://gitlab.gnome.org/GNOME/libadwaita.git
cd libadwaita
meson setup _build
ninja -C _build
ninja -C _build install
```

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

### Configure Libadwaita as a Meson Subproject

Source: https://github.com/gnome/libadwaita/blob/main/doc/build-howto.md

Create a wrap file to use libadwaita as a Meson subproject. This is an alternative to Flatpak bundling.

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

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

### Override Accent Background Color in CSS

Source: https://github.com/gnome/libadwaita/blob/main/doc/styles-and-appearance.md

Customize the accent background color in CSS by overriding the --accent-bg-color variable. This example forces the use of green.

```css
:root {
  --accent-bg-color: var(--accent-green);
}
```

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

### Initialize Libadwaita with adw_init()

Source: https://github.com/gnome/libadwaita/blob/main/doc/initialization.md

Call adw_init() if using Gtk.Application is not feasible. This function can be used as a replacement for Gtk.init().

```c
#include <adwaita.h>

int
main (int   argc,
      char *argv[])
{
  GtkWidget *window, *label;

  adw_init ();

  window = gtk_window_new ();
  label = gtk_label_new ("Hello World");

  gtk_window_set_title (GTK_WINDOW (window), "Hello");
  gtk_window_set_default_size (GTK_WINDOW (window), 200, 200);
  gtk_window_set_child (GTK_WINDOW (window), label);
  gtk_window_present (GTK_WINDOW (window));

   while (g_list_model_get_n_items (gtk_window_get_toplevels ()) > 0)
    g_main_context_iteration (NULL, TRUE);

  return 0;
}

```

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

### Good GTK-doc Syntax Usage

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Use gi-docgen's preferred syntax for linking to types, methods, and constants. This ensures better parsing and rendering.

```markdown
`TRUE`
[class@Dialog]
[method@Dialog.present]
```

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

### Apply .background for Default Window Colors

Source: https://github.com/gnome/libadwaita/blob/main/doc/style-classes.md

Use the .background style class on any widget to apply the default window background and foreground colors. This is useful for ensuring a widget has an opaque background.

```css
.background {
  background-color: var(--window-bg-color);
  color: var(--window-fg-color);
}
```

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

### Include Image in Documentation

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Use HTML <picture> and <img> tags to display generated screenshots, with support for dark mode using srcset.

```html
<picture>
  <source srcset="IMAGE-dark.png" media="(prefers-color-scheme: dark)">
  <img src="IMAGE.png" alt="IMAGE">
</picture>
```

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

### Override Accent Color with Dark Foreground

Source: https://github.com/gnome/libadwaita/blob/main/doc/styles-and-appearance.md

When overriding the accent background color, adjust the foreground color to ensure legibility if the background is too bright. This example uses a dark foreground for a yellow background.

```css
:root {
  --accent-bg-color: var(--yellow-3);
  --accent-fg-color: rgb(0 0 0 / 80%);
}
```

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

### AdwNavigationSplitView with Breakpoint

Source: https://github.com/gnome/libadwaita/blob/main/doc/migrating-to-breakpoints.md

This XML demonstrates migrating to AdwNavigationSplitView and configuring a breakpoint. The breakpoint collapses the split view when the maximum width is 400sp, adapting the layout for smaller screens.

```xml
<object class="AdwWindow">
  <child>
    <object class="AdwBreakpoint">
      <condition>max-width: 400sp</condition>
      <setter object="split_view" property="collapsed">True</setter>
    </object>
  </child>
  <property name="content">
    <object class="AdwNavigationSplitView" id="split_view">
      <property name="sidebar">
        <object class="AdwNavigationPage">
          <property name="title" translatable="yes">Sidebar</property>
          <property name="child">
            <object class="AdwToolbarView">
              <child type="top">
                <object class="AdwHeaderBar"/>
              </child>
              <property name="content">
                <!-- sidebar -->
              </property>
            </object>
          </property>
        </object>
      </property>
      <property name="content">
        <object class="AdwNavigationPage">

```

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

### Add Libadwaita Dependency in Meson Build File

Source: https://github.com/gnome/libadwaita/blob/main/doc/build-howto.md

Include this in your meson.build file to use libadwaita as a dependency, with fallback and default options specified.

```meson
libadwaita = dependency(
  'libadwaita-1',
  version: '>= 1.0.0',
  fallback: ['libadwaita', 'libadwaita_dep'],
  default_options: [
    'examples=false',
    'introspection=disabled',
    'tests=false',
    'vapi=false',
  ]
)
```

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

### Replacing AdwViewSwitcherTitle with ViewSwitcher

Source: https://github.com/gnome/libadwaita/blob/main/doc/migrating-to-breakpoints.md

This snippet demonstrates replacing AdwViewSwitcherTitle with AdwViewSwitcher and configuring its policy. It also shows the necessary adjustments to AdwViewSwitcherBar.

```xml
<object class="AdwHeaderBar" id="header_bar">
  <!-- ... -->
  <property name="title-widget">
    <object class="AdwViewSwitcher">
      <property name="policy">wide</property>
      <property name="stack">stack</property>
    </object>
  </property>
  <!-- ... -->
</object>
<!-- ... -->
<object class="AdwViewSwitcherBar" id="switcher_bar">
  <property name="stack">stack</property>
</object>
```

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

### Bundle Libadwaita using Flatpak Manifest

Source: https://github.com/gnome/libadwaita/blob/main/doc/build-howto.md

Add these modules to your Flatpak manifest to bundle libadwaita and its dependencies. This is useful for older GNOME SDK versions or different SDKs.

```json
{
    "name" : "libadwaita",
    "buildsystem" : "meson",
    "config-opts" : [
        "-Dexamples=false",
        "-Dtests=false"
    ],
    "sources" : [
        {
            "type" : "git",
            "url" : "https://gitlab.gnome.org/GNOME/libadwaita.git",
            "branch" : "main"
        }
    ],
    "modules" : [
        {
            "name" : "libsass",
            "buildsystem" : "meson",
            "cleanup" : [
                "*"
            ],
            "sources" : [
                {
                    "type" : "git",
                    "url" : "https://github.com/lazka/libsass.git",
                    "branch" : "meson"
                }
            ]
        },
        {
            "name" : "sassc",
            "buildsystem" : "meson",
            "cleanup" : [
                "*"
            ],
            "sources" : [
                {
                    "type" : "git",
                    "url" : "https://github.com/lazka/sassc.git",
                    "branch" : "meson"
                }
            ]
        }
    ]
}
```

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

### Migrate GtkBox to AdwToolbarView

Source: https://github.com/gnome/libadwaita/blob/main/doc/migrating-to-breakpoints.md

Replace GtkBox with AdwToolbarView for header bars and toolbars. Use add_top_bar and add_bottom_bar for toolbars, and content for the main widget. Remove vexpand from the content widget.

```xml
<object class="GtkBox">
  <property name="orientation">vertical</property>
  <child>
    <object class="AdwHeaderBar">
      <!-- ... -->
    </object>
  </child>
  <child>
    <object class="...">
      <property name="vexpand">True</property>
      <!-- ... -->
    </object>
  </child>
</object>
```

```xml
<object class="AdwToolbarView">
  <child type="top">
    <object class="AdwHeaderBar">
      <!-- ... -->
    </object>
  </child>
  <property name="content">
    <object class="...">
      <!-- ... -->
    </object>
  </property>
</object>
```

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

### Bad GTK-doc Syntax Usage

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Avoid legacy gtk-doc syntax like '%' for constants or function names without the '@' prefix. Stick to the recommended gi-docgen syntax.

```markdown
%TRUE
%AdwDialog
adw_dialog_present()
```

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

### Run Tests Before Pull Request

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Before submitting a pull request, ensure all tests pass by running the provided command. This helps maintain code quality and stability.

```sh
ninja -C _build test
```

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

### XML Property Name Style

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Use minus signs instead of underscores in property names within UI files. This is the standard for GTK/Adwaita UI definitions.

```xml
<property name="margin-start">12</property>
```

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

### Menu Popover Appearance

Source: https://github.com/gnome/libadwaita/blob/main/doc/style-classes.md

Use the .menu style class with a Gtk.Popover containing a Gtk.ListBox or Gtk.ListView to achieve a menu-like appearance.

```xml
<object class="GtkPopover">
  <style>
    <class name="menu"/>
  </style>
  <child>
    <object class="GtkListBox"/>
  </child>
</object>
```

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

### Apply .osd with .toolbar for Floating Toolbars

Source: https://github.com/gnome/libadwaita/blob/main/doc/style-classes.md

Combine .osd with the .toolbar style class on a box to create floating toolbars. This adds padding and round corners, suitable for controls like video player interfaces.

```css
.osd.toolbar {
  /* Additional padding and round corners for toolbars */
}
```

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

### Regenerate All Screenshots

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Execute the screenshot tool without an image prefix to regenerate all screenshots from the data directory. Ensure correct document and monospace fonts are set.

```c
./doc/tools/screenshot ../doc/tools/data/ ../doc/images/
```

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

### Typical AdwLeaflet Sidebar Layout

Source: https://github.com/gnome/libadwaita/blob/main/doc/migrating-to-breakpoints.md

This XML defines a typical adaptive sidebar layout using AdwLeaflet. It includes a window with a leaflet containing a toolbar view for the sidebar and another for the content.

```xml
<object class="AdwWindow">
  <property name="content">
    <object class="AdwLeaflet" id="leaflet">
      <property name="can-navigate-back">True</property>
      <child>
        <object class="AdwToolbarView">
          <child type="top">
            <object class="AdwHeaderBar">
              <property name="show-end-title-buttons"
                              bind-object="leaflet"
                              bind-property="folded"
                              bind-flags="sync-create"/>
              <property name="title-widget">
                <object class="AdwWindowTitle">
                  <property name="title" translatable="yes">Sidebar</property>
                </object>
              </property>
            </object>
          </child>
          <property name="content">
            <!-- sidebar -->
          </property>
        </object>
      </child>
      <child>
        <object class="AdwLeafletPage">
          <property name="navigatable">False</property>
          <property name="child">
            <object class="GtkSeparator"/>
          </property>
        </object>
      </child>
      <child>
        <object class="AdwToolbarView">
          <property name="hexpand">True</property>
          <child type="top">
            <object class="AdwHeaderBar">
              <property name="show-start-title-buttons"
                              bind-object="leaflet"
                              bind-property="folded"
                              bind-flags="sync-create"/>
              <child type="start">
                <object class="GtkButton">
                  <property name="visible"
                                  bind-object="leaflet"
                                  bind-property="folded"
                                  bind-flags="sync-create"/>
                  <property name="icon-name">go-previous-symbolic</property>
                </object>
              </child>
              <property name="title-widget">
                <object class="AdwWindowTitle">
                  <property name="title" translatable="yes">Content</property>
                </object>
              </property>
            </object>
          </child>
          <property name="content">
            <!-- content -->
          </property>
        </object>
      </child>
    </object>
  </property>
</object>
```

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

### Original AdwViewSwitcherTitle Usage

Source: https://github.com/gnome/libadwaita/blob/main/doc/migrating-to-breakpoints.md

This snippet shows the typical usage of AdwViewSwitcherTitle within an AdwWindow and AdwToolbarView.

```xml
<object class="AdwWindow">
  <property name="content">
    <object class="AdwToolbarView">
      <child type="top">
        <object class="AdwHeaderBar">
          <property name="centering-policy">strict</property>
          <property name="title-widget">
            <object class="AdwViewSwitcherTitle" id="title">
              <property name="stack">stack</property>
              <property name="title" translatable="yes">Title</property>
            </object>
          </property>
        </object>
      </child>
      <property name="content">
        <object class="AdwViewStack" id="stack">
          <!-- ... -->
        </object>
      </property>
      <child type="bottom">
        <object class="AdwViewSwitcherBar">
          <property name="stack">stack</property>
          <property name="reveal"
                    bind-source="title"
                    bind-property="title-visible"
                    bind-flags="sync-create"/>
        </object>
      </child>
    </object>
  </property>
</object>
```

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

### Inline Text View Style

Source: https://github.com/gnome/libadwaita/blob/main/doc/style-classes.md

Use the .inline style class with Gtk.TextView to allow it to adopt styles for contexts like being placed within a card.

```xml
<object class="GtkTextView">
  <style>
    <class name="inline"/>
  </style>
</object>
```

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

### Implementing Split Buttons with AdwSplitButton

Source: https://github.com/gnome/libadwaita/blob/main/doc/migrating-libhandy-1-4-to-libadwaita.md

Replaces a GtkBox-based split button implementation with the dedicated AdwSplitButton widget. Use this when you need a button with a primary action and a dropdown menu.

```xml
<object class="AdwSplitButton">
  <property name="menu-model">some_menu</property>
  <property name="icon-name">view-list-symbolic</property>
</object>
```

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

### Apply .icon-dropshadow and .lowres-icon for App Icons

Source: https://github.com/gnome/libadwaita/blob/main/doc/style-classes.md

Apply .icon-dropshadow or .lowres-icon to Gtk.Image widgets for GNOME application icons. Use .lowres-icon for icons 32x32 or smaller, and .icon-dropshadow for larger icons to ensure legibility.

```css
.icon-dropshadow {
  /* Provides shadow for larger icons */
}
```

```css
.lowres-icon {
  /* Provides shadow for 32x32 or smaller icons */
}
```

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

### Good Parameter Description

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Provide clear and concise descriptions for parameters, omitting type information as it's usually inferred. Focus on the parameter's role or constraints.

```markdown
 * @self: a window
 * @breakpoint: (transfer full): the breakpoint to add
```

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

### Replacing GtkContainer API for Widgets with Children

Source: https://github.com/gnome/libadwaita/blob/main/doc/migrating-libhandy-1-4-to-libadwaita.md

Widgets that previously subclassed GtkBin now have a 'child' property. Window and ApplicationWindow use a 'content' property. Other widgets have specific add/remove method replacements.

```c
expr = gtk_property_expression_new (GTK_TYPE_ENUM_LIST_ITEM, NULL, "nick");
model = G_LIST_MODEL (gtk_enum_list_model_new (GTK_TYPE_ORIENTATION));

adw_combo_row_set_expression (row, expr);
adw_combo_row_set_model (row, model);
```

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

### Adaptive Navigation Split View Configuration

Source: https://github.com/gnome/libadwaita/blob/main/doc/adaptive-layouts.md

Configures an AdwNavigationSplitView to collapse into a sidebar-only view on smaller screens. The sidebar is set to 'page' mode and the split view collapses when the maximum width is 400 pixels.

```xml
<object class="AdwWindow">
  <child>
    <object class="AdwBreakpoint">
      <condition>max-width: 400sp</condition>
      <setter object="split_view" property="collapsed">True</setter>
      <setter object="sidebar" property="mode">page</setter>
    </object>
  </child>
  <property name="content">
    <object class="AdwNavigationSplitView" id="split_view">
      <property name="sidebar">
        <object class="AdwNavigationPage">
          <property name="title" translatable="yes">Sidebar</property>
          <property name="tag">sidebar</property>
          <property name="child">
            <object class="AdwToolbarView">
              <child type="top">
                <object class="AdwHeaderBar">
                  <child type="end">
                    <object class="GtkMenuButton">
                      <property name="icon-name">open-menu-symbolic</property>
                      <property name="primary">True</property>
                      <!-- specify the menu model -->
                    </object>
                  </child>
                </object>
              </child>
              <property name="content">
                <object class="AdwSidebar" id="sidebar">
                  <signal name="activated" handler="sidebar_activated_cb" swapped="yes"/>
                  <!-- sidebar contents -->
                </object>
              </property>
            </object>
          </property>
        </object>
      </property>
      <property name="content">
        <object class="AdwNavigationPage">
          <property name="title" translatable="yes">Content</property>
          <property name="tag">content</property>
          <property name="child">
            <object class="AdwToolbarView">
              <child type="top">
                <object class="AdwHeaderBar"/>
              </child>
              <property name="content">
                <!-- content -->
              </property>
            </object>
          </property>
        </object>
      </property>
    </object>
  </property>
</object>
```

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

### Apply .view for Default View Colors

Source: https://github.com/gnome/libadwaita/blob/main/doc/style-classes.md

Apply the .view style class to any widget to set the default view background and foreground colors. This class ensures the widget uses the standard colors defined for views.

```css
.view {
  background-color: var(--view-bg-color);
  color: var(--view-fg-color);
}
```

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

### C Static Function Naming

Source: https://github.com/gnome/libadwaita/blob/main/CONTRIBUTING.md

Static functions do not require the class prefix. This applies to private helper functions within a file.

```c
static void
selection_changed_cb (AdwViewSwitcher   *self,
                      guint              position,
                      guint              n_items)
```

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

### AdwOverlaySplitView with Adaptive Breakpoints

Source: https://github.com/gnome/libadwaita/blob/main/doc/adaptive-layouts.md

This XML defines an AdwWindow using AdwOverlaySplitView. It includes an AdwBreakpoint to control the collapsed state and visibility of sidebar and menu buttons based on screen width. Use this for creating responsive layouts.

```xml
<object class="AdwWindow">
  <child>
    <object class="AdwBreakpoint">
      <condition>max-width: 400sp</condition>
      <setter object="split_view" property="collapsed">True</setter>
      <setter object="show_sidebar_button" property="visible">True</setter>
      <setter object="sidebar_menu_button" property="visible">False</setter>
      <setter object="content_menu_button" property="visible">True</setter>
    </object>
  </child>
  <property name="content">
    <object class="AdwOverlaySplitView" id="split_view">
      <property name="sidebar">
        <object class="AdwToolbarView">
          <child type="top">
            <object class="AdwHeaderBar">
              <property name="title-widget">
                <object class="AdwWindowTitle">
                  <property name="title">Sidebar</property>
                  <child type="end">
                    <object class="GtkMenuButton" id="sidebar_menu_button">
                      <property name="icon-name">open-menu-symbolic</property>
                      <property name="primary">True</property>
                      <!-- specify the menu model -->
                    </object>
                  </child>
                </object>
              </property>
            </object>
          </child>
          <property name="content">
            <object class="AdwSidebar" id="sidebar">
              <signal name="activated" handler="sidebar_activated_cb" swapped="yes"/>
              <!-- sidebar contents -->
            </object>
          </property>
        </object>
      </property>
      <property name="content">
        <object class="AdwToolbarView" id="content">
          <child type="top">
            <object class="AdwHeaderBar">
              <property name="title-widget">
                <object class="AdwWindowTitle">
                  <property name="title">Content</property>
                </object>
              </property>
              <child type="start">
                <object class="GtkToggleButton" id="show_sidebar_button">
                  <property name="visible">False</property>
                  <property name="icon-name">adw-sidebar-symbolic</property>
                  <property name="active"
                            bind-source="split_view"
                            bind-property="show-sidebar"
                            bind-flags="sync-create|bidirectional"/>
                </object>
              </child>
              <child type="end">
                <object class="GtkMenuButton" id="content_menu_button">
                  <property name="visible">False</property>
                  <property name="icon-name">open-menu-symbolic</property>
                  <property name="primary">True</property>
                  <!-- specify the menu model -->
                </object>
              </child>
            </object>
          </child>
          <property name="content">
            <!-- content -->
          </property>
        </object>
      </property>
    </object>
  </property>
</object>
```

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

### Adaptive View Switcher Layout

Source: https://github.com/gnome/libadwaita/blob/main/doc/adaptive-layouts.md

This XML defines a window with an adaptive view switcher. A Breakpoint is used to switch between a header bar view switcher for wide layouts and a bottom bar view switcher for narrow layouts.

```xml
<object class="AdwWindow">
  <child>
    <object class="AdwBreakpoint">
      <condition>max-width: 550sp</condition>
      <setter object="switcher_bar" property="reveal">True</setter>
      <setter object="header_bar" property="title-widget"/>
    </object>
  </child>
  <property name="content">
    <object class="AdwToolbarView">
      <child type="top">
        <object class="AdwHeaderBar" id="header_bar">
          <property name="title-widget">
            <object class="AdwViewSwitcher">
              <property name="stack">stack</property>
              <property name="policy">wide</property>
            </object>
          </property>
        </object>
      </child>
      <property name="content">
        <object class="AdwViewStack" id="stack"/>
      </property>
      <child type="bottom">
        <object class="AdwViewSwitcherBar" id="switcher_bar">
          <property name="stack">stack</property>
        </object>
      </child>
    </object>
  </property>
</object>
```

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

### Declare Libadwaita Dependency in Meson

Source: https://github.com/gnome/libadwaita/blob/main/doc/build-howto.md

Use this to declare a dependency on libadwaita-1 when using the Meson build system.

```meson
dependency('libadwaita-1')
```