fix(widgets): Add Simput.register_layout() (#15)

* fix(widgets): Add Simput.register_layout()
* docs(widgets): Add basic documentation for Simput widgets

docs/api.md

@@ -12,7 +12,7 @@ widget or get your hand on its **proxymanager** to manage its proxies.
 
 ## Simput manager
 
-The simput manager instance let you do the following:
+The simput manager instance lets you do the following:
 - Access its linked **proxymanager**
 - Reset cached UI layout elements by calling **clear_ui()**
 - Load definitions, language and UI by calling one of the following methods
@@ -298,6 +298,72 @@ def hints(self):
  """Return a set of (level, message) when running the validation for the info level"""
 ```
 
+## UI Widgets
+
+### Simput Widget
+
+The `Simput` widget is a trame component that is used as the UI data management provider.
+This component must be registered as the root of the layout with the `register_layout(layout)` method (preferred method) or by setting `layout.root = simput_widget`.
+
+```python
+@property
+def helper(self):
+ """Simput helper object"""
+
+def apply(self, **kwargs):
+ """Flush modified properties so they can be pushed to their concrete objects"""
+
+def reset(self, **kwargs):
+ """Unapply properties"""
+
+def push(self, id=None, type=None, domains=None, proxy=None, **kwargs):
+ """Ask server to push data, ui, or constraints"""
+
+def update(self, change_set, **kwargs):
+ """
+ List of properties and value to update
+
+ >>> change_set = [
+ ... {"id":"12", "name":"Radius", "value": 0.75},
+ ... {"id": "12", "name":"Resolution", "value": 24}
+ ... ]
+ """
+
+def register_layout(self, layout):
+ """
+ Register self to the root of the layout and
+ clear any previously registered elements (to support hot reloading)
+ """
+
+def refresh(self, id=0, property="", **kwargs):
+ """Refresh the given id's property"""
+
+def reload(self, name):
+ """Reload the given name (data, ui, domain)"""
+
+@property
+def changeset(self):
+ """All unapplied changesets"""
+
+@property
+def has_changes(self):
+ """Does the changeset have content?"""
+
+@property
+def auto_update(self):
+ """Whether to automatically apply changes"""
+```
+
+### SimputItem Widget
+
+`SimputItem` is a trame component that is used to display a Simput item. This must be child of a Simput component to have access to Simput data.
+
+```python
+item_proxy = pxm.create("Item")
+# Create a SimputItem widget to display the item
+simput.SimputItem(item_id=f"{item_proxy.id}")
+```
+
 ## Domains
 
 ### Range

examples/00_AddressBook/app.py

@@ -100,7 +100,7 @@ def entry_ids(self):
 
 with SinglePageWithDrawerLayout(server) as layout:
  layout.title.set_text("SimPut Address Book")
- layout.root = simput_widget
+ simput_widget.register_layout(layout)
 
  with layout.toolbar:
  vuetify.VSpacer()

examples/01_Widgets/app.py

@@ -58,7 +58,7 @@ def update_ui(use_xml_ui, **kwargs):
 # -----------------------------------------------------------------------------
 
 with SinglePageLayout(server) as layout:
- layout.root = simput_widget
+ simput_widget.register_layout(layout)
 
  with layout.toolbar as toolbar:
  layout.title.set_text("SimPut Widgets")

examples/02_Hints/app.py

@@ -45,7 +45,7 @@
 # -----------------------------------------------------------------------------
 
 with SinglePageLayout(server) as layout:
- layout.root = simput_widget
+ simput_widget.register_layout(layout)
 
  with layout.toolbar as toolbar:
  layout.title.set_text("SimPut Widgets")

examples/03_VTK/app.py

@@ -120,7 +120,7 @@ def import_file(import_file, **kwargs):
 ]
 
 with SinglePageWithDrawerLayout(server) as layout:
- layout.root = simput_widget
+ simput_widget.register_layout(layout)
 
  with layout.drawer as drawer:
  with vuetify.VTabs(

examples/04_DynaDomain/app.py

@@ -72,7 +72,7 @@ def update_advanced(ui_advanced, **kwargs):
  ctrl.simput_apply = simput_widget.apply
  ctrl.simput_reset = simput_widget.reset
  ctrl.simput_reload_domain = simput_widget.reload_domain
- layout.root = simput_widget
+ simput_widget.register_layout(layout)
 
  with layout.toolbar as toolbar:
  layout.title.set_text("SimPut Advanced view")

examples/05_ReadonlyDisabled/app.py

@@ -23,7 +23,7 @@
 # -----------------------------------------------------------------------------
 
 with SinglePageLayout(server) as layout:
- layout.root = simput_widget
+ simput_widget.register_layout(layout)
 
  with layout.toolbar as toolbar:
  layout.title.set_text("Simput readonly and disabled example")

trame_simput/widgets/simput.py

@@ -12,7 +12,7 @@ def __init__(self, _elem_name, children=None, **kwargs):
 
 class Simput(HtmlElement):
  """
- Simput data management component. This must be set as the root of a layout to provide children with Simput data.
+ Simput data management component. This must be registered as the root of a layout to provide children with Simput data.
 
  :param ui_manager: See simput docs |simput_link| for more info
  :param domains_manager: See simput docs |simput_link| for more info
@@ -23,7 +23,8 @@ class Simput(HtmlElement):
  :param children: The children nested within this element
  :type children: str | list[trame.html.*] | trame.html.* | None
 
- >>> layout.root = simput.Simput(ui_manager, prefix="myForm")
+ >>> simput_widget = simput.Simput(ui_manager, prefix="myForm")
+ >>> simput_widget.register_layout(layout)
  """
 
  def __init__(self, ui_manager, prefix=None, children=None, **kwargs):
@@ -77,6 +78,14 @@ def update(self, change_set, **kwargs):
  """
  self._helper.update(change_set)
 
+ def register_layout(self, layout):
+ """
+ Register self to the root of the layout and
+ clear any previously registered elements (to support hot reloading)
+ """
+ self.clear()
+ layout.root = self
+
  def refresh(self, id=0, property="", **kwargs):
  self._helper.refresh(id, property)