[libadwaita/wip/exalm/docs: 16/17] doc: Add Initialization page

[Alexander Mikhaylenko <alexm src gnome org>]

commit a79faf09a4df34fba4897a295457a005c6a0e90e
Author: Alexander Mikhaylenko <alexm gnome org>
Date:   Mon Dec 27 14:50:03 2021 +0500

    doc: Add Initialization page

 doc/build-howto.md                  |   5 +++
 doc/images/hello-world-dark.png     | Bin 0 -> 7591 bytes
 doc/images/hello-world.png          | Bin 0 -> 7451 bytes
 doc/initialization.md               |  83 ++++++++++++++++++++++++++++++++++++
 doc/libadwaita.toml.in              |   3 ++
 doc/meson.build                     |   1 +
 doc/tools/data/hello-world.ui       |  15 +++++++
 doc/tools/screenshot.gresources.xml |   1 +
 8 files changed, 108 insertions(+)
---
diff --git a/doc/build-howto.md b/doc/build-howto.md
index 503d5ee3..a6e55783 100644
--- a/doc/build-howto.md
+++ b/doc/build-howto.md
@@ -135,3 +135,8 @@ it, use `pkg-config`:
 ```bash
 gcc $(pkg-config --cflags --libs gtk4) $(pkg-config --cflags --libs libadwaita-1) main.c -o main
 ```
+
+# Next Steps
+
+Once libadwaita has been compiled and included into your project, it needs to be
+initialized. See [Initialization](initialization.html).
diff --git a/doc/images/hello-world-dark.png b/doc/images/hello-world-dark.png
new file mode 100644
index 00000000..5c510ab8
Binary files /dev/null and b/doc/images/hello-world-dark.png differ
diff --git a/doc/images/hello-world.png b/doc/images/hello-world.png
new file mode 100644
index 00000000..174cee4c
Binary files /dev/null and b/doc/images/hello-world.png differ
diff --git a/doc/initialization.md b/doc/initialization.md
new file mode 100644
index 00000000..c79d4f77
--- /dev/null
+++ b/doc/initialization.md
@@ -0,0 +1,83 @@
+Title: Initialization
+Slug: initialization
+
+# Initialization
+
+Before using Libadwaita, it must be initialized. There are two ways of doing
+this.
+
+## Using `AdwApplication` (Recommended)
+
+[class@Application] automatically initializes Libadwaita if used instead of
+[class@Gtk.Application].
+
+Example:
+
+```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_FLAGS_NONE);
+
+  g_signal_connect (app, "activate", G_CALLBACK (activate_cb), NULL);
+
+  return g_application_run (G_APPLICATION (app), argc, argv);
+}
+```
+
+After building and running, the application will look like this:
+
+<picture>
+  <source srcset="hello-world-dark.png" media="(prefers-color-scheme: dark)">
+  <img src="hello-world.png" alt="hello-world">
+</picture>
+
+## Using `adw_init()`
+
+If using [class@Application] is not possible, use [func@init] instead. It can be
+called instead of [func Gtk init].
+
+Example:
+
+```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;
+}
+```
diff --git a/doc/libadwaita.toml.in b/doc/libadwaita.toml.in
index b6f01245..14b7db2f 100644
--- a/doc/libadwaita.toml.in
+++ b/doc/libadwaita.toml.in
@@ -39,6 +39,7 @@ file_format = "{filename}#L{line}"
 urlmap_file = "urlmap.js"
 content_files = [
   "build-howto.md",
+  "initialization.md",
 
   "boxed-lists.md",
   "adaptive-layouts.md",
@@ -133,6 +134,8 @@ content_images = [
   "images/header-bar-dark.png",
   "images/header-bar-split.png",
   "images/header-bar-split-dark.png",
+  "images/hello-world.png",
+  "images/hello-world-dark.png",
   "images/leaflet-narrow.png",
   "images/leaflet-narrow-dark.png",
   "images/leaflet-wide.png",
diff --git a/doc/meson.build b/doc/meson.build
index 60ec70bb..b6946c16 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -6,6 +6,7 @@ expand_content_md_files = [
   'adaptive-layouts.md',
   'boxed-lists.md',
   'build-howto.md',
+  'initialization.md',
   'migrating-between-development-versions.md',
   'migrating-libhandy-1-4-to-libadwaita.md',
   'named-colors.md',
diff --git a/doc/tools/data/hello-world.ui b/doc/tools/data/hello-world.ui
new file mode 100644
index 00000000..dee4330c
--- /dev/null
+++ b/doc/tools/data/hello-world.ui
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+  <requires lib="gtk" version="4.0"/>
+  <requires lib="libadwaita" version="1.0"/>
+  <object class="GtkApplicationWindow" id="widget">
+    <property name="default-width">200</property>
+    <property name="default-height">200</property>
+    <property name="title" translatable="yes">Hello</property>
+    <property name="child">
+      <object class="GtkLabel">
+        <property name="label" translatable="yes">Hello World</property>
+      </object>
+    </property>
+  </object>
+</interface>
diff --git a/doc/tools/screenshot.gresources.xml b/doc/tools/screenshot.gresources.xml
index 536029bd..2c2640ba 100644
--- a/doc/tools/screenshot.gresources.xml
+++ b/doc/tools/screenshot.gresources.xml
@@ -43,6 +43,7 @@
     <file preprocess="xml-stripblanks">data/flat-header-bar.ui</file>
     <file preprocess="xml-stripblanks">data/header-bar.ui</file>
     <file preprocess="xml-stripblanks">data/header-bar-split.ui</file>
+    <file preprocess="xml-stripblanks">data/hello-world.ui</file>
     <file preprocess="xml-stripblanks">data/leaflet-narrow.ui</file>
     <file preprocess="xml-stripblanks">data/leaflet-wide.ui</file>
     <file preprocess="xml-stripblanks">data/linked-controls.ui</file>