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

Tutorial: changed terminology *name* to *id*

Browse source
This commit is contained in:
Megadash452 2022-10-19 02:22:51 +00:00
parent 9e293a31e6
commit c74c5ac232
1 changed files with 28 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

60
docs/tutorial.rst
View file

@ -80,17 +80,17 @@ A good place to start is
Naming Widgets
~~~~~~~~~~~~~~
Widgets can be given **name**s so that they can be referenced by other
Widgets can be given **name/ID**s so that they can be referenced by other
widgets in the blueprint.
.. code-block::
Namespace.WidgetClass widget-name {
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 **name** (e.g.
`main-window`).
next section) or something else, write the widget's **ID** (e.g.
`main_window`).
Properties
@ -106,7 +106,7 @@ Write properties inside the curly brackets of a widget:
property-name: value;
}
Properties are *all lowercase* (except strings) and must end with a
Properties values are *all lowercase* (except strings) and must end with a
semicolon (;).
Property Types
@ -148,7 +148,7 @@ Widget Properties
Some widgets take other widgets as properties. For example, the
`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 **name**.
widget by its **ID**.
.. code-block::
StackSidebar {
@ -159,10 +159,10 @@ OR
.. code-block::
StackSidebar {
stack: my-stack;
stack: my_stack;
}
Stack my-stack {
Stack my_stack {
}
@ -176,16 +176,16 @@ 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'
properties of the same type. Bindings must reference a *source* widget by
**name**. As long as the two properties have the same type, you can bind
**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 {
Box my_box {
halign: fill; // Source
}
Button {
valign: bind my-box.halign; // Target
valign: bind my_box.halign; // Target
}
Binding Flags
@ -195,12 +195,12 @@ Modify the behavior of bindings with flags. Flags are written after the
binding.
.. code-block::
Box my-box {
hexpand: true; // Source
Box my_box {
hexpand: true; // Source
}
Button {
vexpand: bind my-box.hexpand inverted bidirectional; // Target
vexpand: bind my_box.hexpand inverted bidirectional; // Target
}
no-sync-create
@ -217,7 +217,7 @@ bidirectional
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 below.
the Button's vexpand property will be `false` in the code above.
Signals
@ -237,23 +237,23 @@ your language's bindings of Gtk.
.. code-block::
WidgetClass {
event-name => handler_name() flags;
event_name => handler_name() flags;
}
.. TODO: add a list of flags and their descriptions
By default, signals in the blueprint will pass the widget that the signal
is for as an argument to the *handler*. However, you can specify the
widget that is passed to the handler by referencing its name inside the
widget that is passed to the handler by referencing its **id** inside the
parenthesis.
.. code-block::
Label my-label {
Label my_label {
label: "Hide me";
}
Button {
clicked => hide_widget(my-label);
clicked => hide_widget(my_label);
}
@ -297,14 +297,10 @@ Note the lack of a *colon* after "styles" and a *semicolon* at the end of
the line. This syntax looks like the properties syntax, but it compiles to
XML completely different from properties.
The syntax may change to `styles! [...]` in the future so that it is not
confused with the properties syntax.
Consult your language's bindings of Gtk to use a CSS file.
Non-property Elements
~~~~~~~~~~~~~~~~~~~~~
.. TODO: ^^^ should it be called that?
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
@ -334,14 +330,14 @@ window, or pop up when you right-click some other widget. In Blueprint a
widgets.
In Blueprint, `menu`s have *items*, *sections*, and *submenus*.
Like widgets, `menu`s can also be given a **name**.
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 {
menu my_menu {
section {
label: "File";
item {
@ -375,12 +371,12 @@ action and icon-name are optional.
}
A widget that uses a `menu` is `Gtk.MenuButton`. It has the *menu-model*
property, which takes a menu. You can write the menu inline with the
property, or write the menu separately and reference it by **name**.
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;
menu-model: my_menu;
}
@ -436,17 +432,17 @@ 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_("have", "1st have");
label: C_("1st have", "have");
}
Label {
label: C_("have", "2nd have");
label: C_("2nd have", "have");
}
See `translations <translations.html>`_ for more details.
See `translations <translations.html>`_ for more details.