mirror of
https://gitlab.gnome.org/jwestman/blueprint-compiler.git
synced 2025-05-04 15:59:08 -04:00
Tutorial: Fixed .rst rendering issues
This commit is contained in:
Megadash452
parent
14d1892254
commit
0fe58ffc37
1 changed files with 45 additions and 21 deletions
|
|
@ -8,17 +8,18 @@ Read this if you want to learn how to use Blueprint and never used
|
|||
the XML syntax that can be read by GtkBuilder.
|
||||
|
||||
For compatibility with Blueprint IDE extensions, blueprint files
|
||||
should end with `.blp`.
|
||||
should end with ``.blp``.
|
||||
|
||||
|
||||
Namespaces
|
||||
----------
|
||||
|
||||
Blueprint needs the widget library to be imported. These include Gtk,
|
||||
Libadwaita, Shumate, etc. To import a namespace, write `using` followed
|
||||
Libadwaita, Shumate, etc. To import a namespace, write ``using`` followed
|
||||
by the library and version number.
|
||||
|
||||
.. code-block::
|
||||
|
||||
using Gtk 4.0;
|
||||
using Adw 1;
|
||||
|
||||
|
|
@ -32,6 +33,7 @@ Comments
|
|||
Blueprint has inline or multi-line comments
|
||||
|
||||
.. code-block::
|
||||
|
||||
// This is an inline comment
|
||||
/* This is
|
||||
a multiline
|
||||
|
|
@ -42,6 +44,7 @@ will interpret the inner comment's closing token as the outer comment's
|
|||
closing token. For example, the following will not compile:
|
||||
|
||||
.. code-block::
|
||||
|
||||
// Bad comment below:
|
||||
/* Outer comment
|
||||
/* Inner comment */
|
||||
|
|
@ -54,6 +57,7 @@ Widgets
|
|||
Create widgets in the following format:
|
||||
|
||||
.. code-block::
|
||||
|
||||
Namespace.WidgetClass {
|
||||
|
||||
}
|
||||
|
|
@ -62,6 +66,7 @@ The Gtk namespace is implied for widgets, so you can just write the
|
|||
widget class
|
||||
|
||||
.. code-block::
|
||||
|
||||
Box {
|
||||
|
||||
}
|
||||
|
|
@ -69,6 +74,7 @@ widget class
|
|||
Other namespaces must be written explicitly.
|
||||
|
||||
.. code-block::
|
||||
|
||||
Adw.Leaflet {
|
||||
|
||||
}
|
||||
|
|
@ -84,13 +90,14 @@ Widgets can be given **name/ID**s so that they can be referenced by other
|
|||
widgets in the blueprint.
|
||||
|
||||
.. code-block::
|
||||
|
||||
Namespace.WidgetClass widget_id {
|
||||
|
||||
}
|
||||
|
||||
Any time you want to use this widget as a property (more about that in the
|
||||
next section) or something else, write the widget's **ID** (e.g.
|
||||
`main_window`).
|
||||
``main_window``).
|
||||
|
||||
|
||||
Properties
|
||||
|
|
@ -102,6 +109,7 @@ For example, the Libadwaita documentation lists the
|
|||
Write properties inside the curly brackets of a widget:
|
||||
|
||||
.. code-block::
|
||||
|
||||
Namespace.WidgetClass {
|
||||
property-name: value;
|
||||
}
|
||||
|
|
@ -113,14 +121,14 @@ Property Types
|
|||
~~~~~~~~~~~~~~
|
||||
|
||||
These are the **types** of values that can be used in properties:
|
||||
- Booleans: `true`, `false`
|
||||
- Numbers: e.g. `1`, `1.5`, `-2`, `-2.5`
|
||||
- Strings (single- or double-quoted): e.g. `"a string"`, `'another string'`
|
||||
- Booleans: ``true``, ``false``
|
||||
- Numbers: e.g. ``1``, ``1.5``, ``-2``, ``-2.5``
|
||||
- Strings (single- or double-quoted): e.g. ``"a string"``, ``'another string'``
|
||||
- Enums
|
||||
- Widgets
|
||||
|
||||
Properties are **strongly typed**, so you can't use, for example, a string
|
||||
for the orientation property, which requires an `Orientation` enum
|
||||
for the orientation property, which requires an ``Orientation`` enum
|
||||
vartiant as its value.
|
||||
|
||||
Enum Properties
|
||||
|
|
@ -138,6 +146,7 @@ In the blueprint, you would only write the *variant* part of the enum in
|
|||
*lowercase*, just like you would in the XML.
|
||||
|
||||
.. code-block::
|
||||
|
||||
Box {
|
||||
orientation: horizontal;
|
||||
}
|
||||
|
|
@ -146,11 +155,12 @@ Widget Properties
|
|||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Some widgets take other widgets as properties. For example, the
|
||||
`Gtk.StackSidebar` has a stack property which takes a `Gtk.Stack` widget.
|
||||
``Gtk.StackSidebar`` has a stack property which takes a ``Gtk.Stack`` widget.
|
||||
You can create a new widget for the value, or you can reference another
|
||||
widget by its **ID**.
|
||||
|
||||
.. code-block::
|
||||
|
||||
StackSidebar {
|
||||
stack: Stack { };
|
||||
}
|
||||
|
|
@ -158,6 +168,7 @@ widget by its **ID**.
|
|||
OR
|
||||
|
||||
.. code-block::
|
||||
|
||||
StackSidebar {
|
||||
stack: my_stack;
|
||||
}
|
||||
|
|
@ -174,12 +185,13 @@ Property Bindings
|
|||
-----------------
|
||||
|
||||
If you want a widget's property to have the same value as another widget's
|
||||
property (without hard-coding the value), you could `bind` two widgets'
|
||||
property (without hard-coding the value), you could ``bind`` two widgets'
|
||||
properties of the same type. Bindings must reference a *source* widget by
|
||||
**ID**. As long as the two properties have the same type, you can bind
|
||||
properties of different names and of widgets with different widget classes.
|
||||
|
||||
.. code-block::
|
||||
|
||||
Box my_box {
|
||||
halign: fill; // Source
|
||||
}
|
||||
|
|
@ -197,6 +209,7 @@ changed to the *Source*'s value when the binding is created and when the
|
|||
*Source* value changes.
|
||||
|
||||
.. code-block::
|
||||
|
||||
Box my_box {
|
||||
hexpand: true; // Source
|
||||
}
|
||||
|
|
@ -214,13 +227,13 @@ no-sync-create
|
|||
bidirectional
|
||||
When either the *Source* or *Target* value is modified, the other's
|
||||
value will be updated. For example, if the logic of the program
|
||||
changes the Button's vexpand value to `false`, then the Box's halign
|
||||
value will also be updated to `false`.
|
||||
changes the Button's vexpand value to ``false``, then the Box's halign
|
||||
value will also be updated to ``false``.
|
||||
|
||||
inverted
|
||||
If the property is a boolean, the value of the bind can be negated
|
||||
with this flag. For example, if the Box's hexpand property is `true`,
|
||||
the Button's vexpand property will be `false` in the code above.
|
||||
with this flag. For example, if the Box's hexpand property is ``true``,
|
||||
the Button's vexpand property will be ``false`` in the code above.
|
||||
|
||||
|
||||
Signals
|
||||
|
|
@ -239,6 +252,7 @@ To register a handler with the application, consult the documentation for
|
|||
your language's bindings of Gtk.
|
||||
|
||||
.. code-block::
|
||||
|
||||
WidgetClass {
|
||||
event_name => handler_name() flags;
|
||||
}
|
||||
|
|
@ -251,6 +265,7 @@ widget that is passed to the handler by referencing its **id** inside the
|
|||
parenthesis.
|
||||
|
||||
.. code-block::
|
||||
|
||||
Label my_label {
|
||||
label: "Hide me";
|
||||
}
|
||||
|
|
@ -265,7 +280,7 @@ Custom Widget Classes
|
|||
|
||||
Some programs have custom widgets defined in their logic, and so blueprint
|
||||
won't know that they exist. Writing widgets not defined in the GIR will
|
||||
result in an error. Prepend a custom widget with a `.` to prevent the
|
||||
result in an error. Prepend a custom widget with a ``.`` to prevent the
|
||||
compiler from trying to validate the widget. This is essentially leaving
|
||||
out the *namespace*.
|
||||
|
||||
|
|
@ -273,6 +288,7 @@ To register a custom widget with the application consult the documentation
|
|||
for your language's bindings of Gtk.
|
||||
|
||||
.. code-block::
|
||||
|
||||
.MyCustomWidget {
|
||||
|
||||
}
|
||||
|
|
@ -291,6 +307,7 @@ Widgets can be given style classes that can be used with your CSS or
|
|||
in libraries like Libadwaita.
|
||||
|
||||
.. code-block::
|
||||
|
||||
Button {
|
||||
label: "Click me";
|
||||
styles ["my-style", "pill"]
|
||||
|
|
@ -309,9 +326,10 @@ Some widgets will have elements which are not properties, but they sort
|
|||
of act like properties. Most of the time they will be specific only to a
|
||||
certain widget. *Styles* is one of these elements, except that styles can
|
||||
be used for any widget. Similarly to how every widget has styles,
|
||||
`Gtk.ComboBoxText` has *items*:
|
||||
``Gtk.ComboBoxText`` has *items*:
|
||||
|
||||
.. code-block::
|
||||
|
||||
Gtk.ComboBoxText {
|
||||
items [
|
||||
item1: "Item 1",
|
||||
|
|
@ -329,17 +347,18 @@ Menus
|
|||
|
||||
Menus are usually the widgets that are placed along the top-bar of a
|
||||
window, or pop up when you right-click some other widget. In Blueprint a
|
||||
`menu` is a `Gio.MenuModel` that can be shown by MenuButtons or other
|
||||
``menu`` is a ``Gio.MenuModel`` that can be shown by MenuButtons or other
|
||||
widgets.
|
||||
|
||||
In Blueprint, `menu`s have *items*, *sections*, and *submenus*.
|
||||
Like widgets, `menu`s can also be given a **ID**.
|
||||
In Blueprint, ``menu``s have *items*, *sections*, and *submenus*.
|
||||
Like widgets, ``menu``s can also be given a **ID**.
|
||||
The `Menu Model section of the Gtk.PopoverMenu documentation <https://docs.gtk.org/gtk4/class.PopoverMenu.html#menu-models>`_
|
||||
has complete details on the menu model.
|
||||
|
||||
Here is an example of a menu:
|
||||
|
||||
.. code-block::
|
||||
|
||||
menu my_menu {
|
||||
section {
|
||||
label: "File";
|
||||
|
|
@ -368,16 +387,18 @@ There is a shorthand for *items*. Items require at least a label. The
|
|||
action and icon-name are optional.
|
||||
|
||||
.. code-block::
|
||||
|
||||
menu {
|
||||
item ( "Item 2" )
|
||||
item ( "Item 2", "app.action", "icon-name" )
|
||||
}
|
||||
|
||||
A widget that uses a `menu` is `Gtk.MenuButton`. It has the *menu-model*
|
||||
A widget that uses a ``menu`` is ``Gtk.MenuButton``. It has the *menu-model*
|
||||
property, which takes a menu. Write the menu at the root of the blueprint
|
||||
(meaning not inside any widgets) and reference it by **ID**.
|
||||
|
||||
.. code-block::
|
||||
|
||||
MenuButton {
|
||||
menu-model: my_menu;
|
||||
}
|
||||
|
|
@ -398,6 +419,7 @@ the child the type is for.
|
|||
The following blueprint code...
|
||||
|
||||
.. code-block::
|
||||
|
||||
HeaderBar {
|
||||
[start]
|
||||
Button {
|
||||
|
|
@ -414,6 +436,7 @@ The following blueprint code...
|
|||
And the following blueprint code...
|
||||
|
||||
.. code-block::
|
||||
|
||||
HeaderBar {
|
||||
[end]
|
||||
Button {
|
||||
|
|
@ -431,15 +454,16 @@ And the following blueprint code...
|
|||
Translatable Strings
|
||||
--------------------
|
||||
|
||||
Mark any string as translatable using this syntax: `_("...")`.
|
||||
Mark any string as translatable using this syntax: ``_("...")``.
|
||||
|
||||
Two strings that are the same in English could be translated in different
|
||||
ways in other languages because of different *contexts*. Translatable
|
||||
strings with context look like this: `C_("context", "...")`. An example
|
||||
strings with context look like this: ``C_("context", "...")``. An example
|
||||
where a context is needed is the word "have", which in Spanish could
|
||||
translate to "tener" or "haber".
|
||||
|
||||
.. code-block::
|
||||
|
||||
Label {
|
||||
label: C_("1st have", "have");
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue