diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 60a3542..3111f6f 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -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 `_ 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 `_ for more details. \ No newline at end of file +See `translations `_ for more details.