Introduce ValueChangeEventArguments.previous_value (#4456)

Inspired by discussion #4410, this PR introduces a `previous_value`
field for `ValueChangeEventArguments`. This change is pretty
straightforward and only requires adjustments for two mixins and two
elements.

Right now it is lacking backward-compatibility though. If user code
derives custom `ValueChangeEventArguments`, they are now missing the
`previous_value` field. Should we add a default value? But it should be
clear that this default is _not_ the previous value, but "not set". We
might need a sentinel...

And in 3.0 I'd like to enforce the `previous_value` field. A deprecation
warning for the default value would be great, but probably hard to
achieve.

Author: falkoschindler

nicegui/elements/mixins/selectable_element.py

@@ -102,8 +102,9 @@ def _handle_selection_change(self, selected: bool) -> None:
 
         :param selected: The new selection state.
         """
+        previous_value = self._props.get('selected')
         self._props['selected'] = selected
         self.update()
-        args = ValueChangeEventArguments(sender=self, client=self.client, value=self._props['selected'])
+        args = ValueChangeEventArguments(sender=self, client=self.client, value=selected, previous_value=previous_value)
         for handler in self._selection_change_handlers:
             handle_event(handler, args)

nicegui/elements/mixins/value_element.py

@@ -108,10 +108,13 @@ def set_value(self, value: Any) -> None:
         self.value = value
 
     def _handle_value_change(self, value: Any) -> None:
+        previous_value = self._props.get(self.VALUE_PROP)
         self._props[self.VALUE_PROP] = self._value_to_model_value(value)
         if self._send_update_on_value_change:
             self.update()
-        args = ValueChangeEventArguments(sender=self, client=self.client, value=self._value_to_event_value(value))
+        args = ValueChangeEventArguments(sender=self, client=self.client,
+                                         value=self._value_to_event_value(value),
+                                         previous_value=self._value_to_event_value(previous_value))
         for handler in self._change_handlers:
             handle_event(handler, args)
 

nicegui/elements/table.py

@@ -90,9 +90,11 @@ def handle_selection(e: GenericEventArguments) -> None:
         self.on('selection', handle_selection, ['added', 'rows', 'keys'])
 
         def handle_pagination_change(e: GenericEventArguments) -> None:
+            previous_value = self.pagination
             self.pagination = e.args
             self.update()
-            arguments = ValueChangeEventArguments(sender=self, client=self.client, value=self.pagination)
+            arguments = ValueChangeEventArguments(sender=self, client=self.client,
+                                                  value=self.pagination, previous_value=previous_value)
             for handler in self._pagination_change_handlers:
                 handle_event(handler, arguments)
         self.on('update:pagination', handle_pagination_change)

nicegui/elements/tree.py

@@ -63,21 +63,30 @@ def update_prop(name: str, value: Any) -> None:
                 self.update()
 
         def handle_selected(e: GenericEventArguments) -> None:
+            previous_value = self._props.get('selected')
             update_prop('selected', e.args)
+            args = ValueChangeEventArguments(sender=self, client=self.client,
+                                             value=e.args, previous_value=previous_value)
             for handler in self._select_handlers:
-                handle_event(handler, ValueChangeEventArguments(sender=self, client=self.client, value=e.args))
+                handle_event(handler, args)
         self.on('update:selected', handle_selected)
 
         def handle_expanded(e: GenericEventArguments) -> None:
+            previous_value = self._props.get('expanded')
             update_prop('expanded', e.args)
+            args = ValueChangeEventArguments(sender=self, client=self.client,
+                                             value=e.args, previous_value=previous_value)
             for handler in self._expand_handlers:
-                handle_event(handler, ValueChangeEventArguments(sender=self, client=self.client, value=e.args))
+                handle_event(handler, args)
         self.on('update:expanded', handle_expanded)
 
         def handle_ticked(e: GenericEventArguments) -> None:
+            previous_value = self._props.get('ticked')
             update_prop('ticked', e.args)
+            args = ValueChangeEventArguments(sender=self, client=self.client,
+                                             value=e.args, previous_value=previous_value)
             for handler in self._tick_handlers:
-                handle_event(handler, ValueChangeEventArguments(sender=self, client=self.client, value=e.args))
+                handle_event(handler, args)
         self.on('update:ticked', handle_ticked)
 
     def on_select(self, callback: Handler[ValueChangeEventArguments]) -> Self:

nicegui/events.py

@@ -134,6 +134,13 @@ class MultiUploadEventArguments(UiEventArguments):
 @dataclass(**KWONLY_SLOTS)
 class ValueChangeEventArguments(UiEventArguments):
     value: Any
+    previous_value: Any = ...
+
+    def __post_init__(self):
+        # DEPRECATED: previous_value will be required in NiceGUI 4.0
+        if self.previous_value is ...:
+            helpers.warn_once('The new event argument `ValueChangeEventArguments.previous_value` is not set. '
+                              'In NiceGUI 4.0 this will raise an error.')
 
 
 @dataclass(**KWONLY_SLOTS)

tests/test_events.py

@@ -206,3 +206,15 @@ def test_delegated_event_with_argument_filtering(screen: Screen) -> None:
     screen.click('Item B')
     screen.click('Item C')
     assert ids == ['A', 'B', 'C']
+
+
+def test_value_change_event_arguments(screen: Screen):
+    events = []
+    ui.checkbox('Checkbox', on_change=lambda e: events.append((e.value, e.previous_value)))
+
+    screen.open('/')
+    screen.click('Checkbox')
+    assert events == [(True, False)]
+
+    screen.click('Checkbox')
+    assert events == [(True, False), (False, True)]