From bc798c544c28ba392b71cc143d9435a588eb66aa Mon Sep 17 00:00:00 2001 From: James Westman Date: Wed, 27 Sep 2023 10:51:48 -0500 Subject: [PATCH] docs: Fix grammar for bindings Binding flags were missing from the documented grammar. Also added prose documentation about the available flags. --- docs/reference/values.rst | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/docs/reference/values.rst b/docs/reference/values.rst index a50293d..7c61d78 100644 --- a/docs/reference/values.rst +++ b/docs/reference/values.rst @@ -104,17 +104,32 @@ Use ``C_("context", "...")`` to add a *message context* to a string to disambigu .. _Syntax Binding: -Expression Bindings -------------------- +Bindings +-------- .. rst-class:: grammar-block - Binding = 'bind' :ref:`Expression` + Binding = 'bind' :ref:`Expression` (BindingFlag)* + BindingFlag = 'inverted' | 'bidirectional' | '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. The simplest bindings connect to a property of another object in the blueprint. When that other property changes, the bound property updates as well. More advanced bindings can do multi-step property lookups and can even call application code to compute values. See :ref:`the expressions page`. +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. +- ``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 +~~~~~~~~~~~~~~~~ + +Bindings with more complex expressions are implemented with `Gtk.Expression `_. These bindings do not support flags. + Example ~~~~~~~ @@ -126,13 +141,10 @@ Example Switch advanced_feature {} Label warning { - visible: bind-property advanced_feature.active; + visible: bind advanced_feature.active; label: _("This is an advanced feature. Use with caution!"); } -.. code-block: blueprintui - - .. _Syntax ObjectValue: