Siklos/blueprint-compiler
1
0
Fork 0
mirror of https://gitlab.gnome.org/jwestman/blueprint-compiler.git synced 2025-05-04 15:59:08 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Remove the examples page

Browse source 
It has been replaced with the new syntax reference, and it was out of
date anyway.
This commit is contained in:
James Westman 2023-04-14 14:09:30 -05:00
parent a9f6bf8d89
commit 4d62df0068
2 changed files with 0 additions and 479 deletions
Download patch file Download diff file Expand all files Collapse all files

478
docs/examples.rst
View file

@ -1,478 +0,0 @@
========
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;
}
Referencing a template object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to use a template object elsewhere in your blueprint, you can use
the template class name as the object ID:
.. code-block::
template MyAppWindow : ApplicationWindow { }
Gtk.Label {
visible: bind MyAppWindow.visible;
}
Properties
----------
Translations
~~~~~~~~~~~~
Use ``_("...")`` to mark strings as translatable. You can put a comment for
translators on the line above if needed.
.. code-block::
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.
.. code-block::
Gtk.Label label {
/* Translators: This is a section in the preferences window */
label: C_("preferences window", "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.
Type Literals
~~~~~~~~~~~~~
Some properties have the type `GObject.Type <https://docs.gtk.org/gobject/alias.Type.html>`_, that is, their value is
itself a description of a type in the GObject type system. An example is
`Gio.ListStore:item-type <https://docs.gtk.org/gio/property.ListStore.item-type.html>`_. Such properties can be
specified with the ``typeof()`` operator:
.. code-block::
Gio.ListStore {
item-type: typeof(.MyDataModel);
}
.. note::
Though it looks like a function, ``typeof()`` is actually a special operator. This is an important syntactic
distinction because the argument to ``typeof()`` is interpreted at the grammar level as a type, not a value or
expression.
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 ``no-sync-create`` keyword to only update the target value when the
source value changes, not when the binding is first created.
.. code-block::
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.
.. code-block::
// 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.
.. code-block::
// 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
~~~~~~~~~~~
.. 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;
}
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.
.. code-block::
Gtk.Entry {
activate => grab_focus(another_entry);
}
Gtk.Entry another_entry {
}
CSS Styles
----------
Basic Usage
~~~~~~~~~~~
.. code-block::
Gtk.Label {
styles ["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")
}
Layout Properties
-----------------
Basic Usage
~~~~~~~~~~~
.. code-block::
Gtk.Grid {
Gtk.Label {
layout {
row: 0;
column: 1;
}
}
}
Accessibility Properties
------------------------
Basic Usage
~~~~~~~~~~~
.. code-block::
Gtk.Widget {
accessibility {
orientation: vertical;
labelled-by: my_label;
checked: true;
}
}
Gtk.Label my_label {}
Widget-Specific Items
---------------------
Gtk.ComboBoxText
~~~~~~~~~~~~~~~~
.. code-block::
Gtk.ComboBoxText {
items [
item1: "Item 1",
item2: _("Items can be translated"),
"The item ID is not required",
]
}
Gtk.FileFilter
~~~~~~~~~~~~~~
.. code-block::
Gtk.FileFilter {
mime-types ["image/jpeg", "video/webm"]
patterns ["*.txt"]
suffixes ["png"]
}
Gtk.SizeGroup
~~~~~~~~~~~~~
.. code-block::
Gtk.SizeGroup {
mode: both;
widgets [label1, label2]
}
Gtk.Label label1 {}
Gtk.Label label2 {}
Gtk.BuilderListItemFactory
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block::
Gtk.ListView {
factory: Gtk.BuilderListItemFactory {
template {
child: Label {
label: "Hello";
};
}
};
}
Gtk.StringList
~~~~~~~~~~~~~~
.. code-block::
Gtk.StringList {
strings ["Hello, world!", _("Translated string")]
}
Gtk.Dialog and Gtk.InfoBar
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block::
Gtk.Dialog {
[action response=ok]
Gtk.Button ok_response {}
[action response=cancel]
Gtk.Button cancel_response {}
[action response=9]
Gtk.Button app_defined_response {}
}
Gtk.Label
~~~~~~~~~
Blueprint does not have syntax for `attributes` on `Gtk.Label`.
Instead, you should use `platform classes <https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/style-classes.html>`_, `CSS <https://docs.gtk.org/gtk4/css-properties.html>`_, `Pango Markup <https://docs.gtk.org/Pango/pango_markup.html>`_ or `Gtk.Label.set_attributes <https://docs.gtk.org/gtk4/method.Label.set_attributes.html>`_.
Examples
.. code-block::
Gtk.Label {
label: "Hello, World!";
styles ["title-1"]
}
.. code-block::
Gtk.Label {
label: "<b>Hello, World!</b>";
use-markup: true;
}

1
docs/index.rst
View file

@ -19,7 +19,6 @@ Blueprint is a markup language and compiler for GTK 4 user interfaces.
translations translations
flatpak flatpak
reference/index reference/index
examples
packaging packaging