docs: Add examples

docs/examples.rst

@@ -0,0 +1,245 @@
+========
+Examples
+========
+
+
+Namespaces and libraries
+------------------------
+
+GTK declaration
+~~~~~~~~~~~~~~~
+
+.. code-block::
+
+   // Required in every blueprint file. Defines the major version
+   // of GTK the file is designed for.
+   using Gtk 4.0;
+
+Importing libraries
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+
+   // 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+
+   Gtk.Box {
+     orientation: vertical;
+
+     Gtk.Label {
+       label: "Hello, world!";
+     }
+   }
+
+Referencing an object in code
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+
+   // 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.
+
+.. code-block::
+
+   .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``.
+
+.. code-block::
+
+   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.
+
+.. code-block::
+
+   Gtk.Label label {
+     /* Translators: This is the main text of the welcome screen */
+     label: _("Hello, world!");
+   }
+
+Referencing objects by ID
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+
+   Gtk.Range range1 {
+     adjustment: my_adjustment;
+   }
+   Gtk.Range range2 {
+     adjustment: my_adjustment;
+   }
+
+   Gtk.Adjustment my_adjustment {
+   }
+
+Defining object properties inline
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+
+   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.
+
+.. code-block::
+
+   Gtk.ProgressBar bar1 {
+   }
+
+   Gtk.ProgressBar bar2 {
+     value: bind bar1.value;
+   }
+
+Binding Flags
+~~~~~~~~~~~~~
+
+Use the ``sync-create`` keyword to cause a bound property to be initialized
+when the UI is first constructed.
+
+.. code-block::
+
+   Gtk.ProgressBar bar1 {
+     value: 10;
+   }
+
+   Gtk.ProgressBar bar2 {
+     value: bind bar1.value sync-create;
+   }
+
+
+Signals
+-------
+
+Basic Usage
+~~~~~~~~~~~
+
+.. code-block::
+
+   Gtk.Button {
+     // on_button_clicked is defined in your application
+     clicked => on_button_clicked();
+   }
+
+Flags
+~~~~~
+
+.. code-block::
+
+   Gtk.Button {
+     clicked => on_button_clicked() swapped;
+   }
+
+
+CSS Styles
+----------
+
+Basic Usage
+~~~~~~~~~~~
+
+.. code-block::
+
+   Gtk.Label {
+     style "dim-label", "title";
+   }
+
+
+Menus
+-----
+
+Basic Usage
+~~~~~~~~~~~
+
+.. code-block::
+
+   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.
+
+.. code-block::
+
+   menu {
+     item _("Copy") "app.copy" "copy-symbolic";
+   }