Merge pull request #2323 from zauberzeug/binding-documentation

Improve binding documentation

nicegui/binding.py

@@ -86,6 +86,7 @@ def bind_to(self_obj: Any, self_name: str, other_obj: Any, other_name: str, forw
     """Bind the property of one object to the property of another object.
 
     The binding works one way only, from the first object to the second.
+    The update happens immediately and whenever a value changes.
 
     :param self_obj: The object to bind from.
     :param self_name: The name of the property to bind from.
@@ -103,6 +104,7 @@ def bind_from(self_obj: Any, self_name: str, other_obj: Any, other_name: str, ba
     """Bind the property of one object from the property of another object.
 
     The binding works one way only, from the second object to the first.
+    The update happens immediately and whenever a value changes.
 
     :param self_obj: The object to bind to.
     :param self_name: The name of the property to bind to.
@@ -121,6 +123,8 @@ def bind(self_obj: Any, self_name: str, other_obj: Any, other_name: str, *,
     """Bind the property of one object to the property of another object.
 
     The binding works both ways, from the first object to the second and from the second to the first.
+    The update happens immediately and whenever a value changes.
+    The backward binding takes precedence for the initial synchronization.
 
     :param self_obj: First object to bind.
     :param self_name: The name of the first property to bind.

nicegui/elements/mixins/content_element.py

@@ -24,6 +24,7 @@ class ContentElement(Element):
         """Bind the content of this element to the target object's target_name property.
 
         The binding works one way only, from this element to the target.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.
@@ -40,6 +41,7 @@ class ContentElement(Element):
         """Bind the content of this element from the target object's target_name property.
 
         The binding works one way only, from the target to this element.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind from.
         :param target_name: The name of the property to bind from.
@@ -57,6 +59,8 @@ class ContentElement(Element):
         """Bind the content of this element to the target object's target_name property.
 
         The binding works both ways, from this element to the target and from the target to this element.
+        The update happens immediately and whenever a value changes.
+        The backward binding takes precedence for the initial synchronization.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.

nicegui/elements/mixins/disableable_element.py

@@ -38,6 +38,7 @@ class DisableableElement(Element):
         """Bind the enabled state of this element to the target object's target_name property.
 
         The binding works one way only, from this element to the target.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.
@@ -54,6 +55,7 @@ class DisableableElement(Element):
         """Bind the enabled state of this element from the target object's target_name property.
 
         The binding works one way only, from the target to this element.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind from.
         :param target_name: The name of the property to bind from.
@@ -71,6 +73,8 @@ class DisableableElement(Element):
         """Bind the enabled state of this element to the target object's target_name property.
 
         The binding works both ways, from this element to the target and from the target to this element.
+        The update happens immediately and whenever a value changes.
+        The backward binding takes precedence for the initial synchronization.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.

nicegui/elements/mixins/filter_element.py

@@ -24,6 +24,7 @@ class FilterElement(Element):
         """Bind the filter of this element to the target object's target_name property.
 
         The binding works one way only, from this element to the target.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.
@@ -40,6 +41,7 @@ class FilterElement(Element):
         """Bind the filter of this element from the target object's target_name property.
 
         The binding works one way only, from the target to this element.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind from.
         :param target_name: The name of the property to bind from.
@@ -57,6 +59,8 @@ class FilterElement(Element):
         """Bind the filter of this element to the target object's target_name property.
 
         The binding works both ways, from this element to the target and from the target to this element.
+        The update happens immediately and whenever a value changes.
+        The backward binding takes precedence for the initial synchronization.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.

nicegui/elements/mixins/name_element.py

@@ -23,6 +23,7 @@ class NameElement(Element):
         """Bind the name of this element to the target object's target_name property.
 
         The binding works one way only, from this element to the target.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.
@@ -39,6 +40,7 @@ class NameElement(Element):
         """Bind the name of this element from the target object's target_name property.
 
         The binding works one way only, from the target to this element.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind from.
         :param target_name: The name of the property to bind from.
@@ -56,6 +58,8 @@ class NameElement(Element):
         """Bind the name of this element to the target object's target_name property.
 
         The binding works both ways, from this element to the target and from the target to this element.
+        The update happens immediately and whenever a value changes.
+        The backward binding takes precedence for the initial synchronization.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.

nicegui/elements/mixins/source_element.py

@@ -27,6 +27,7 @@ class SourceElement(Element):
         """Bind the source of this element to the target object's target_name property.
 
         The binding works one way only, from this element to the target.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.
@@ -43,6 +44,7 @@ class SourceElement(Element):
         """Bind the source of this element from the target object's target_name property.
 
         The binding works one way only, from the target to this element.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind from.
         :param target_name: The name of the property to bind from.
@@ -60,6 +62,8 @@ class SourceElement(Element):
         """Bind the source of this element to the target object's target_name property.
 
         The binding works both ways, from this element to the target and from the target to this element.
+        The update happens immediately and whenever a value changes.
+        The backward binding takes precedence for the initial synchronization.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.

nicegui/elements/mixins/text_element.py

@@ -23,6 +23,7 @@ class TextElement(Element):
         """Bind the text of this element to the target object's target_name property.
 
         The binding works one way only, from this element to the target.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.
@@ -39,6 +40,7 @@ class TextElement(Element):
         """Bind the text of this element from the target object's target_name property.
 
         The binding works one way only, from the target to this element.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind from.
         :param target_name: The name of the property to bind from.
@@ -56,6 +58,8 @@ class TextElement(Element):
         """Bind the text of this element to the target object's target_name property.
 
         The binding works both ways, from this element to the target and from the target to this element.
+        The update happens immediately and whenever a value changes.
+        The backward binding takes precedence for the initial synchronization.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.

nicegui/elements/mixins/value_element.py

@@ -40,6 +40,7 @@ class ValueElement(Element):
         """Bind the value of this element to the target object's target_name property.
 
         The binding works one way only, from this element to the target.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.
@@ -56,6 +57,7 @@ class ValueElement(Element):
         """Bind the value of this element from the target object's target_name property.
 
         The binding works one way only, from the target to this element.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind from.
         :param target_name: The name of the property to bind from.
@@ -73,6 +75,8 @@ class ValueElement(Element):
         """Bind the value of this element to the target object's target_name property.
 
         The binding works both ways, from this element to the target and from the target to this element.
+        The update happens immediately and whenever a value changes.
+        The backward binding takes precedence for the initial synchronization.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.

nicegui/elements/mixins/visibility.py

@@ -32,6 +32,7 @@ class Visibility:
         """Bind the visibility of this element to the target object's target_name property.
 
         The binding works one way only, from this element to the target.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.
@@ -48,6 +49,7 @@ class Visibility:
         """Bind the visibility of this element from the target object's target_name property.
 
         The binding works one way only, from the target to this element.
+        The update happens immediately and whenever a value changes.
 
         :param target_object: The object to bind from.
         :param target_name: The name of the property to bind from.
@@ -70,6 +72,8 @@ class Visibility:
         """Bind the visibility of this element to the target object's target_name property.
 
         The binding works both ways, from this element to the target and from the target to this element.
+        The update happens immediately and whenever a value changes.
+        The backward binding takes precedence for the initial synchronization.
 
         :param target_object: The object to bind to.
         :param target_name: The name of the property to bind to.

website/documentation/content/section_binding_properties.py

@@ -13,6 +13,7 @@ doc.title('*Binding* Properties')
     Each element provides methods like `bind_value` and `bind_visibility` to create a two-way binding with the corresponding property.
     To define a one-way binding use the `_from` and `_to` variants of these methods.
     Just pass a property of the model as parameter to these methods to create the binding.
+    The values will be updated immediately and whenever one of them changes.
 ''')
 def bindings_demo():
     class Demo: