From a529a619553a722536c614287ce9ce69bc6720dc Mon Sep 17 00:00:00 2001 From: James Westman Date: Sun, 3 Nov 2024 14:17:59 -0600 Subject: [PATCH] docs: Corrections, updates, and improvements --- docs/collect-sections.py | 2 +- docs/reference/diagnostics.rst | 2 +- docs/reference/expressions.rst | 14 +++++++------- docs/reference/index.rst | 2 +- docs/reference/templates.rst | 7 ++++--- docs/reference/values.rst | 12 ++++++------ 6 files changed, 20 insertions(+), 19 deletions(-) diff --git a/docs/collect-sections.py b/docs/collect-sections.py index c6e01b3..e6227e7 100755 --- a/docs/collect-sections.py +++ b/docs/collect-sections.py @@ -98,7 +98,7 @@ def rst_to_md(lines: list[str]) -> str: line = lines[i].rstrip() i += 1 if line == ".. rst-class:: grammar-block": - print_block(strip_links=True) + print_block("text", strip_links=True) elif line == ".. code-block:: blueprint": print_block("blueprint") elif line == ".. note::": diff --git a/docs/reference/diagnostics.rst b/docs/reference/diagnostics.rst index 2c0af59..c8774d6 100644 --- a/docs/reference/diagnostics.rst +++ b/docs/reference/diagnostics.rst @@ -21,7 +21,7 @@ The tokenizer encountered an unexpected sequence of characters that aren't part child_not_accepted ------------------ -The parent class does not have child widgets (it does not implement `Gtk.Buildable `_ and is not a subclass of `Gio.ListStore `_). Some classes use properties instead of children to add widgets. Check the parent class's documentation. +The parent class does not have child objects (it does not implement `Gtk.Buildable `_ and is not a subclass of `Gio.ListStore `_). Some classes use properties instead of children to add widgets. Check the parent class's documentation. .. _Diagnostic conversion_error: diff --git a/docs/reference/expressions.rst b/docs/reference/expressions.rst index 1ba50ee..8688ff0 100644 --- a/docs/reference/expressions.rst +++ b/docs/reference/expressions.rst @@ -8,10 +8,10 @@ automatically. .. code-block:: blueprint - label: bind MyAppWindow.account.username; - /* ^ ^ ^ - | creates lookup expressions that are re-evaluated when - | the account's username *or* the account itself changes + label: bind template.account.username; + /* ^ ^ ^ + | creates lookup expressions that are re-evaluated when + | the account's username *or* the account itself changes | binds the `label` property to the expression's output */ @@ -49,7 +49,7 @@ Lookup Expressions LookupExpression = '.' `> -Lookup expressions perform a GObject property lookup on the preceding expression. They are recalculated whenever the property changes, using the `notify signal `_ +Lookup expressions perform a GObject property lookup on the preceding expression. They are recalculated whenever the property changes, using the `notify signal `_. The type of a property expression is the type of the property it refers to. @@ -65,7 +65,7 @@ Closure Expressions Closure expressions allow you to perform additional calculations that aren't supported in blueprint by writing those calculations as application code. These application-defined functions are created in the same way as :ref:`signal handlers`. -Expressions are only reevaluated when their inputs change. Because blueprint doesn't manage a closure's application code, it can't tell what changes might affect the result. Therefore, closures must be *pure*, or deterministic. They may only calculate the result based on their immediate inputs, properties of their inputs or outside variables. +Expressions are only reevaluated when their inputs change. Because blueprint doesn't manage a closure's application code, it can't tell what changes might affect the result. Therefore, closures must be *pure*, or deterministic. They may only calculate the result based on their immediate inputs, not properties of their inputs or outside variables. Blueprint doesn't know the closure's return type, so closure expressions must be cast to the correct return type using a :ref:`cast expression`. @@ -79,7 +79,7 @@ Cast Expressions CastExpression = 'as' '<' :ref:`TypeName` '>' -Cast expressions allow Blueprint to know the type of an expression when it can't otherwise determine it. +Cast expressions allow Blueprint to know the type of an expression when it can't otherwise determine it. This is necessary for closures and for properties of application-defined types. .. code-block:: blueprint diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 7670ba5..d49feb9 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -31,7 +31,7 @@ Tokens IDENT ~~~~~ -An identifier starts with an ASCII underscore ``_`` or letter ``[A-Za-z]`` and consists of ASCII underscores, letters, digits ``[0-9]``, and dashes ``-``. Dashes are included for historical reasons, since GObject properties are traditionally kebab-case. +An identifier starts with an ASCII underscore ``_`` or letter ``[A-Za-z]`` and consists of ASCII underscores, letters, digits ``[0-9]``, and dashes ``-``. Dashes are included for historical reasons, since GObject properties and signals are traditionally kebab-case. .. _Syntax NUMBER: diff --git a/docs/reference/templates.rst b/docs/reference/templates.rst index a1a9968..74e4225 100644 --- a/docs/reference/templates.rst +++ b/docs/reference/templates.rst @@ -90,6 +90,7 @@ To reference the template object in a binding or expression, use the ``template` Language Implementations ------------------------ -- ``gtk_widget_class_set_template ()`` in C: https://docs.gtk.org/gtk4/class.Widget.html#building-composite-widgets-from-template-xml -- ``#[template]`` in gtk-rs: https://gtk-rs.org/gtk4-rs/stable/latest/book/composite_templates.html -- ``GObject.registerClass()`` in GJS: https://gjs.guide/guides/gtk/3/14-templates.html \ No newline at end of file +- **C** ``gtk_widget_class_set_template ()``: https://docs.gtk.org/gtk4/class.Widget.html#building-composite-widgets-from-template-xml +- **gtk-rs** ``#[template]``: https://gtk-rs.org/gtk4-rs/stable/latest/book/composite_templates.html +- **GJS** ``GObject.registerClass()``: https://gjs.guide/guides/gtk/3/14-templates.html +- **PyGObject** ``@Gtk.Template``: https://pygobject.gnome.org/guide/gtk_template.html diff --git a/docs/reference/values.rst b/docs/reference/values.rst index fb63e38..fd414a8 100644 --- a/docs/reference/values.rst +++ b/docs/reference/values.rst @@ -109,7 +109,7 @@ Bindings .. rst-class:: grammar-block Binding = 'bind' :ref:`Expression` (BindingFlag)* - BindingFlag = 'inverted' | 'bidirectional' | 'sync-create' + BindingFlag = 'inverted' | 'bidirectional' | 'no-sync-create' Bindings keep a property updated as other properties change. They can be used to keep the UI in sync with application data, or to connect two parts of the UI. @@ -120,8 +120,8 @@ Simple Bindings A binding that consists of a source object and a single lookup is called a "simple binding". These are implemented using `GObject property bindings `_ and support a few flags: -- ``bidirectional``: The binding is two-way, so changes to the target property will also update the source property. - ``inverted``: For boolean properties, the target is set to the inverse of the source property. +- ``bidirectional``: The binding is two-way, so changes to the target property will also update the source property. - ``no-sync-create``: Normally, when a binding is created, the target property is immediately updated with the current value of the source property. This flag disables that behavior, and the bound property will be updated the next time the source property changes. Complex Bindings @@ -137,11 +137,11 @@ Example /* Use bindings to show a label when a switch * is active, without any application code */ - Switch advanced_feature {} + Switch show_label {} - Label warning { - visible: bind advanced_feature.active; - label: _("This is an advanced feature. Use with caution!"); + Label { + visible: bind show_label.active; + label: _("I'm a label that's only visible when the switch is enabled!"); } .. _Syntax ObjectValue: