pgwidgets-python 0.2.1__tar.gz → 0.2.3__tar.gz

{pgwidgets_python-0.2.1 → pgwidgets_python-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgwidgets-python
-Version: 0.2.1
+Version: 0.2.3
 Summary: Python bindings for the pgwidgets JavaScript widget library
 Author: PGWidgets Developers
 License: BSD-3-Clause

{pgwidgets_python-0.2.1 → pgwidgets_python-0.2.3}/docs/WhatsNew.rst

@@ -1,13 +1,76 @@
 What's New
 ==========
 
-Significant changes since the last tagged release (``v0.1.3``).
+Recent changes — since ``v0.2.1``
+---------------------------------
+
+Reliable ``get_size()`` / ``get_position()`` on every visual widget
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The auto-sync layer that backs widget getters has been reworked so
+``widget.get_size()`` (and ``get_position()`` where supported)
+returns the current layout-determined value for any visual widget,
+not just ones that opted into the ``resizable`` / ``moveable``
+options.  The binding now installs a *passive* resize listener on
+every visual widget — the value is captured into local state for
+the getter, but it is **not** pushed to other connected browsers or
+replayed on reconstruction.  Explicit ``widget.resize(w, h)`` calls
+are still replayed, as is interactive resize on widgets that opted
+into active sync.
+
+The user-visible upshot: code that calls ``image.get_size()`` on an
+``Image`` placed in a flex container now returns the real pixel
+size the browser laid the widget out at, instead of ``None`` or a
+stale value.  And widgets like ``Image`` with
+``set_expanding(True, True)`` no longer get pinned to pixel
+dimensions on reconnect (a regression in earlier auto-sync work).
+
+The same guard now applies in both reconstruction paths
+(top-level state replay AND ``_transfer_proxy`` for factory-created
+widgets like ``ToolBarAction``), which fixes a "toolbar items
+drift farther apart after each reconnect" bug.
+
+``map`` callback survives reconstruction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Python side now forwards ``map`` callbacks during a reconstruct
+window instead of suppressing them along with the rest of the
+state-replay echoes.  ``map`` is a one-shot lifecycle event tied to
+the widget first becoming visually present; missing it on the
+Python side meant a user's map handler stayed un-fired until the
+window happened to be resized.  Pairs with the JS-side reliability
+work for the same callback.
+
+Sensible defaults for more getters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Getters now return useful zero-value defaults before any state has
+been set or reported from the browser, instead of ``None``:
+
+- ``get_scroll_position()`` → ``(0.0, 0.0)``
+- ``get_scroll_percent()`` → ``(0.0, 0.0)`` (or ``0.0`` on
+  ``ScrollBar``, which uses a single-axis API)
+- ``get_thumb_percent()`` → ``(0.0, 0.0)`` (or ``0.0`` on
+  ``ScrollBar``)
+- ``get_expanding()`` → ``(False, False)``
+- ``get_enabled()`` → ``True``
+- ``get_state()`` → ``False``
+- ``get_volume()`` → ``1.0`` (HTMLMediaElement convention: 0.0
+  muted, 1.0 full).
+
+Configured in ``STATE_KEY_DEFAULTS`` / ``STATE_DEFAULTS`` in
+``method_types.py``.
+
+----
+
+Earlier — since ``v0.1.3``
+--------------------------
 
 Major changes
--------------
+~~~~~~~~~~~~~
 
 TreeView / TableView: dict-tree model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Mirroring the JS-side rewrite, ``TreeView`` and ``TableView`` now
 work with hierarchies of dicts keyed by stable string identifiers.
@@ -63,7 +126,7 @@ Highlights:
 See :doc:`widgets` for the full reference.
 
 Window controls (TopLevel) and shade (MDISubWindow)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``TopLevel`` gains the same window controls that ``MDISubWindow``
 has, plus a "shade" (roll up to title bar) state on both.
@@ -96,7 +159,7 @@ Maximize, Close).  The menu supports both click-release and
 press-drag-release, like a menubar.
 
 Image: binary-frame protocol
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 New method ``Image.set_binary_image(data, format='jpeg')`` sends raw
 bytes (``bytes`` / ``bytearray`` / ``memoryview``) via a WebSocket
@@ -106,7 +169,7 @@ Useful for animation/streaming.  ``format`` is one of ``"jpeg"``,
 widget state and replayed on reconnect.
 
 Callbacks base class
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
 
 New module ``pgwidgets.callbacks`` exposes ``Callbacks``, a small
 base class that provides the same callback API (``add_callback``,
@@ -121,7 +184,7 @@ supports both ``add_callback("activated", ...)`` and
 See :ref:`callbacks-base`.
 
 Robustness improvements
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 - ``Session._send`` and ``_send_binary`` no longer hang when the
   asyncio loop refuses a coroutine (loop closed mid-call,
@@ -139,7 +202,7 @@ Robustness improvements
   internal ``ScrollBar`` widgets in its constructor.
 
 Other notable changes
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 - ``ColorDialog`` now exposes ``popup``, ``set_position``,
   ``set_modal``, and the ``move`` / ``close`` callbacks (inherited
@@ -160,3 +223,7 @@ Other notable changes
   though the JS side preserves columns on clear).
 - ``FileBrowser`` migrated to the new dict-tree ``TableView`` API
   internally and now subclasses ``Callbacks``.
+- ``FixedLayout`` container added (auto-generated from the JS
+  definition).  Use ``W.FixedLayout()`` and
+  ``layout.add_widget(child, x, y)`` to place children at fixed
+  pixel offsets; ``remove(child)`` works as on any other container.

{pgwidgets_python-0.2.1 → pgwidgets_python-0.2.3}/docs/widgets.rst

@@ -140,6 +140,17 @@ Grid layout.
   ``append_column(widgets)``, ``delete_column(index)``
 - **Callbacks:** ``child-added``, ``child-removed``
 
+FixedLayout
+~~~~~~~~~~~
+
+Absolute-positioning container.  Each child is placed at a fixed
+``(x, y)`` pixel offset within the container and renders at its
+natural size unless ``resize()`` has been called on it.
+
+- **Options:** *(none)*
+- **Methods:** ``add_widget(child, x, y)``
+- **Callbacks:** ``child-added``, ``child-removed``
+
 Splitter
 ~~~~~~~~
 
@@ -415,24 +426,58 @@ TextSource
 
 Source code editor with line numbers, syntax tags, and gutter icons.
 
+Positions in the buffer are expressed as ``TextBufferRef`` instances —
+live references that track edits.  ``create_ref(offset, gravity)`` is
+the only place a caller deals in raw integer offsets; all other
+position-taking and position-returning methods on the public API use
+refs.
+
+.. note::
+
+   Refs are JS-side live objects.  When using ``TextSource`` over the
+   remote interface (pgwidgets-python proper), refs cannot currently
+   round-trip across the wire — a ref-handle protocol is planned for
+   a future release.  In the meantime, the ref-based API is fully
+   usable from JS-direct and pyodide contexts.
+
 - **Args:** ``text``
 - **Options:** ``wrap``, ``line_numbers``, ``icon_gutter``, ``editable``,
   ``font_family``, ``font_size``
 - **Methods:** ``set_text(text)``, ``get_text()``, ``get_length()``,
-  ``insert_text(offset, text, tags)``, ``delete_range(start, end)``,
+  ``get_text_range(start_ref, end_ref)``,
+  ``insert_text(ref, text, tags)``, ``delete_range(start_ref, end_ref)``,
   ``clear()``, ``set_editable(tf)``, ``set_wrap(mode)``,
   ``set_line_numbers(tf)``, ``set_icon_gutter(tf)``,
-  ``set_icon(line, icon_url)``, ``get_cursor()``, ``set_cursor(offset)``,
-  ``get_selection()``, ``set_selection(start, end)``,
+  ``set_icon(ref, icon_url)``, ``get_cursor()``, ``set_cursor(ref)``,
+  ``get_selection_range()``, ``set_selection_range(start_ref, end_ref)``,
   ``create_tag(name, attrs)``, ``remove_tag_def(name)``,
-  ``apply_tag(name, start, end)``, ``remove_tag(name, start, end)``,
-  ``get_tags_at(offset)``, ``create_ref(offset, gravity)``,
-  ``remove_ref(ref)``, ``undo()``, ``redo()``, ``can_undo()``,
-  ``can_redo()``, ``find(query, opts)``, ``find_all(query, opts)``,
-  ``replace(query, replacement, opts)``, ``scroll_to(ref_or_offset)``,
+  ``has_tag(name)``,
+  ``apply_tag(name, start_ref, end_ref)``,
+  ``remove_tag(name, start_ref, end_ref)``,
+  ``get_tags_at(ref)``, ``get_tags_range(start_ref, end_ref)``,
+  ``create_ref(offset, gravity)``, ``remove_ref(ref)``,
+  ``create_named_ref(name, offset, gravity)``,
+  ``get_named_ref(name)``, ``remove_named_ref(name)``,
+  ``get_ref_start()``, ``get_ref_end()``, ``get_ref_bounds()``,
+  ``get_ref_line_start(lineno)``, ``get_ref_line_end(lineno)``,
+  ``undo()``, ``redo()``, ``can_undo()``, ``can_redo()``,
+  ``find(query, opts)``, ``find_all(query, opts)``,
+  ``replace(query, replacement, opts)``, ``scroll_to_ref(ref)``,
   ``scroll_to_cursor()``
-- **Callbacks:** ``changed``, ``cursor_moved``, ``line_clicked``,
-  ``icon_clicked``
+- **Callbacks:** ``changed``, ``cursor_moved`` (fires with a fresh
+  ref), ``line_clicked``, ``icon_clicked`` (fires with
+  ``(line, ref)``)
+
+A ``TextBufferRef`` itself supports the following methods:
+
+- **Inspection:** ``get_offset()``, ``get_gravity()``, ``is_valid()``,
+  ``get_line()``, ``get_line_column()``
+- **Absolute position:** ``set_offset(offset)``, ``set_line(lineno)``,
+  ``to_ref(other)``, ``copy()``
+- **Relative movement:** ``to_line_start()``, ``to_line_end()``,
+  ``to_next_line()``, ``to_prev_line()``, ``to_next_char()``,
+  ``to_prev_char()`` (movement methods clamp at buffer boundaries
+  and are no-ops past them; mutating an invalidated ref raises)
 
 Selectors
 ---------

{pgwidgets_python-0.2.1 → pgwidgets_python-0.2.3}/pgwidgets/async_/application.py

@@ -91,6 +91,13 @@ class Session:
     _STATE_KEY_TO_SETTER = {v: k for k, v in SPECIAL_SETTERS.items()}
     # e.g. {"size": "resize"}
 
+    # Reverse map: state_key -> callback action that auto-syncs it
+    # (e.g. "size" -> "resize", "position" -> "move").  Used during
+    # state replay to skip keys that weren't actively opted into via
+    # _auto_sync_actions — those were captured passively for getter
+    # support but must not be replayed (would pin layout).
+    _STATE_KEY_TO_SYNC_ACTION = {v: k for k, v in STATE_SYNC_CALLBACKS.items()}
+
     # State keys handled by fixed-value methods (show/hide)
     _FIXED_STATE_KEYS = {}
     for _mname, (_key, _val) in FIXED_SETTERS.items():
@@ -300,30 +307,46 @@ class Session:
 
     def _dispatch_callback(self, wid, action, *args):
         """Dispatch a callback through the configured concurrency mode."""
-        if self._reconstructing:
-            return  # suppress callbacks during reconstruction
+        # Suppress callbacks during reconstruction — they are side
+        # effects of state replay, not user actions.  Exception: 'map'
+        # is a one-shot lifecycle event that the JS-side observers fire
+        # when a widget first gains a visible layout box; the timing
+        # can land inside the reconstruction window, and dropping it
+        # means the user's map handler never runs until a later layout
+        # change (e.g. window resize) triggers a re-fire.
+        if self._reconstructing and action != 'map':
+            return
 
         # Auto-sync: some callbacks carry state that should be reflected
         # in the Python-side widget (e.g. move -> position, resize -> size).
+        # We always *capture* the value so get_size()/get_position() return
+        # current values, but only *push* it to other browsers (and replay
+        # it on reconstruction) when the widget opted in via auto-sync.
+        # Otherwise a layout-determined size would replay as a literal
+        # resize(W, H) — pinning the widget to pixel dimensions and
+        # killing flex growth.
         state_key = STATE_SYNC_CALLBACKS.get(action)
         if state_key is not None:
             widget = self._widget_map.get(wid)
             if widget is not None:
+                auto = action in widget._auto_sync_actions
                 if len(args) == 1 and isinstance(args[0], dict):
                     d = args[0]
                     if "width" in d and "height" in d:
                         new_val = (d["width"], d["height"])
                         if widget._state.get(state_key) != new_val:
                             widget._state[state_key] = new_val
-                            self._push(wid, "resize",
-                                       d["width"], d["height"])
+                            if auto:
+                                self._push(wid, "resize",
+                                           d["width"], d["height"])
                 else:
                     new_val = tuple(args)
                     if widget._state.get(state_key) != new_val:
                         widget._state[state_key] = new_val
-                        setter = (self._STATE_KEY_TO_SETTER.get(state_key)
-                                  or f"set_{state_key}")
-                        self._push(wid, setter, *args)
+                        if auto:
+                            setter = (self._STATE_KEY_TO_SETTER.get(state_key)
+                                      or f"set_{state_key}")
+                            self._push(wid, setter, *args)
                 # If this widget wraps a child (e.g. MDISubWindow),
                 # propagate geometry into the parent's children options
                 # so reconstruction replays with the current pos/size.
@@ -735,17 +758,37 @@ class Session:
             cls = self._widget_classes.get(cls_name, Widget) if cls_name else Widget
             widget = cls._from_existing(self, wid, cls_name or "Widget")
             self._widget_map[wid] = widget
-            # Auto-listen for state-syncing callbacks (move, resize)
-            # so position/size changes are tracked for reconstruction.
+            # Auto-listen for state-syncing callbacks (move, resize).
             # Register locally (sync) and send the listen message as
             # true fire-and-forget (no result awaited) since
-            # _resolve_return is not async.
+            # _resolve_return is not async.  For visual widgets we
+            # always listen for 'resize' so get_size() can return a
+            # current value, but we only mark the action as
+            # auto-syncing (which triggers push-to-peers and
+            # replay-on-reconstruction) when the widget defn opts in.
+            # Non-visual Callback-base objects (Timer, TextBufferRef,
+            # …) get nothing.
+            defn = WIDGETS.get(cls_name, {}) if cls_name else {}
+            opt_names_set = set(defn.get("options", []))
+            all_callbacks = defn.get("callbacks", [])
+            is_visual = defn.get("base") != "callback"
             for action in STATE_SYNC_CALLBACKS:
-                key = f"{wid}:{action}"
-                if key not in self._callbacks:
-                    self._callbacks[key] = [lambda wid, *a: None]
-                    self._fire_and_forget_listen(wid, action)
-                widget._auto_sync_actions.add(action)
+                req_opt = STATE_SYNC_REQUIRES_OPTION.get(action)
+                if req_opt is not None:
+                    opted_in = req_opt in opt_names_set
+                else:
+                    opted_in = action in all_callbacks
+                if not is_visual:
+                    continue
+                if action == "resize" or opted_in:
+                    key = f"{wid}:{action}"
+                    if key not in self._callbacks:
+                        self._callbacks[key] = [lambda wid, *a: None]
+                        self._fire_and_forget_listen(wid, action)
+                if opted_in:
+                    widget._auto_sync_actions.add(action)
+                elif action == "resize":
+                    widget._passive_sync_actions.add(action)
             return widget
         if isinstance(val, list):
             return [self._resolve_return(v) for v in val]
@@ -839,12 +882,23 @@ class Session:
                 await self._listen(new_widget._wid, act,
                                    lambda wid, *a: None)
                 new_widget._auto_sync_actions.add(act)
-        # Replay any state the proxy accumulated (e.g. set_tooltip)
+        # Replay any state the proxy accumulated (e.g. set_tooltip).
+        # Skip passively-captured auto-sync state (size, position): we
+        # capture those from callbacks so getters work, but replaying
+        # would pin the widget to layout-determined pixel dimensions
+        # (same logic as _reconstruct_widget).
+        user_set = getattr(old_widget, "_user_set_state", set())
+        auto = getattr(old_widget, "_auto_sync_actions", set())
         for key, value in old_widget._state.items():
             if key.startswith("_"):
                 continue
             if key in sync_keys:
                 continue
+            sync_action = self._STATE_KEY_TO_SYNC_ACTION.get(key)
+            if (sync_action is not None
+                    and key not in user_set
+                    and sync_action not in auto):
+                continue
             method_name = (self._STATE_KEY_TO_SETTER.get(key)
                            or f"set_{key}")
             if isinstance(value, tuple):
@@ -852,6 +906,13 @@ class Session:
             else:
                 await self._call(new_widget._wid, method_name, value)
             new_widget._state[key] = value
+            # Propagate user-set / auto-sync membership to the new
+            # widget so subsequent reconstructions replay consistently.
+            if sync_action is not None:
+                if key in user_set:
+                    new_widget._user_set_state.add(key)
+                if sync_action in auto:
+                    new_widget._auto_sync_actions.add(sync_action)
 
     async def _ensure_reconstructed(self, widget):
         """Ensure a widget has been created on the JS side."""
@@ -1003,6 +1064,20 @@ class Session:
             if key.startswith("_"):
                 continue
 
+            # Skip auto-sync state (size, position) that came in
+            # passively via a callback (e.g. layout-determined size).
+            # We capture those so getters like get_size()/
+            # get_position() work, but replaying them would pin the
+            # widget to pixel dimensions and override flex/expanding
+            # layout.  Replay only if the user explicitly set the
+            # value, or if the widget opted into the sync action
+            # (e.g. an interactively-resizable widget).
+            sync_action = self._STATE_KEY_TO_SYNC_ACTION.get(key)
+            if (sync_action is not None
+                    and key not in widget._user_set_state
+                    and sync_action not in widget._auto_sync_actions):
+                continue
+
             # Binary-payload state (e.g. set_binary_image) replays via
             # _send_binary so the bytes go in a raw frame, not embedded
             # as base64 in JSON.
@@ -1047,10 +1122,13 @@ class Session:
         # _listen calls treat them as first-time registrations and
         # actually send the "listen" message to the browser.
         wid = widget._wid
+        passive = getattr(widget, "_passive_sync_actions", set())
         for action in list(saved_cbs.keys()):
             self._callbacks.pop(f"{wid}:{action}", None)
         for action in widget._auto_sync_actions:
             self._callbacks.pop(f"{wid}:{action}", None)
+        for action in passive:
+            self._callbacks.pop(f"{wid}:{action}", None)
 
         for action, entries in saved_cbs.items():
             for handler, extra_args, extra_kwargs, style in entries:
@@ -1067,6 +1145,13 @@ class Session:
             if action not in widget._registered_callbacks:
                 await self._listen(widget._wid, action,
                                    lambda wid, *a: None)
+        # Passive listeners (e.g. 'resize' for getter support on
+        # widgets that didn't opt into auto-sync).
+        for action in passive:
+            if (action not in widget._registered_callbacks
+                    and action not in widget._auto_sync_actions):
+                await self._listen(widget._wid, action,
+                                   lambda wid, *a: None)
 
     async def reconstruct(self):
         """Replay the entire widget tree to all connected browsers.

{pgwidgets_python-0.2.1 → pgwidgets_python-0.2.3}/pgwidgets/async_/widget.py

@@ -79,6 +79,16 @@ class Widget:
         self._constructor_options = {}
         self._registered_callbacks = {}
         self._auto_sync_actions = set()
+        # Actions we listen to passively for getter support
+        # (e.g. 'resize' on every visual widget so get_size() returns
+        # a current value), but that aren't in _auto_sync_actions and
+        # therefore don't push to peers or replay on reconstruction.
+        self._passive_sync_actions = set()
+        # State keys the user explicitly set via a setter call.
+        # Used during reconstruction to decide whether a state key
+        # should be replayed: passively-captured callback state
+        # (e.g. layout-determined size) is NOT in this set.
+        self._user_set_state = set()
         self._replay_calls = []
         self._add_seq = 0
 
@@ -196,6 +206,8 @@ class Widget:
         obj._constructor_options = {}
         obj._registered_callbacks = {}
         obj._auto_sync_actions = set()
+        obj._passive_sync_actions = set()
+        obj._user_set_state = set()
         obj._replay_calls = []
         obj._stale = False
         return obj
@@ -212,15 +224,31 @@ class Widget:
         opt_names_set = set(defn.get("options", []))
         all_callbacks = defn.get("callbacks", [])
 
-        # State-sync callbacks (move -> position, resize -> size)
+        # State-sync callbacks (move -> position, resize -> size).
+        # For visual widgets we always *listen* so getters like
+        # get_size() / get_position() can return current values.
+        # But we only add the action to _auto_sync_actions — which
+        # controls push-to-peers and replay-on-reconstruction — when
+        # the widget actually opted in (e.g. via the 'resizable' option
+        # or by declaring the callback in its defn).  This keeps
+        # layout-determined sizes from being replayed as literal
+        # resize() calls that would pin flex/expanding widgets.
+        is_visual = defn.get("base") != "callback"
         for action in STATE_SYNC_CALLBACKS:
             req_opt = STATE_SYNC_REQUIRES_OPTION.get(action)
-            if req_opt and req_opt not in opt_names_set:
-                continue
-            if req_opt is None and action not in all_callbacks:
+            opted_in = False
+            if req_opt is not None:
+                opted_in = req_opt in opt_names_set
+            else:
+                opted_in = action in all_callbacks
+            if not is_visual:
                 continue
-            await session._listen(wid, action, lambda wid, *a: None)
-            self._auto_sync_actions.add(action)
+            if action == "resize" or opted_in:
+                await session._listen(wid, action, lambda wid, *a: None)
+            if opted_in:
+                self._auto_sync_actions.add(action)
+            elif action == "resize":
+                self._passive_sync_actions.add(action)
 
         # Per-widget-class state sync (e.g. Slider "activated" -> value)
         cls_sync = WIDGET_CALLBACK_SYNC.get(js_class, {})
@@ -461,6 +489,9 @@ def _make_setter(method_name, param_names, state_key):
             self._state[state_key] = args[0]
         else:
             self._state[state_key] = args
+        # Mark as user-set so reconstruction knows to replay this key
+        # (callback-captured values for the same key don't get marked).
+        self._user_set_state.add(state_key)
         return await self._call(method_name, *args)
     method.__name__ = method_name
     method.__qualname__ = f"Widget.{method_name}"
@@ -473,6 +504,7 @@ def _make_fixed_setter(method_name, state_key, fixed_value):
     """Create a no-arg async method that sets a fixed state value (show/hide)."""
     async def method(self):
         self._state[state_key] = fixed_value
+        self._user_set_state.add(state_key)
         return await self._call(method_name)
     method.__name__ = method_name
     method.__qualname__ = f"Widget.{method_name}"

{pgwidgets_python-0.2.1 → pgwidgets_python-0.2.3}/pgwidgets/method_types.py

@@ -235,6 +235,10 @@ STATE_DEFAULTS = {
     "TabWidget": {"index": -1},
     "StackWidget": {"index": -1},
     "MDIWidget": {"index": -1},
+    # ScrollBar uses 1-arg set_scroll_percent / set_thumb_percent,
+    # so a scalar default is correct (not the (0.0, 0.0) tuple used
+    # by the 2-arg scroll widgets in STATE_KEY_DEFAULTS).
+    "ScrollBar": {"scroll_percent": 0.0, "thumb_percent": 0.0},
 }
 
 # Cross-widget default values for state keys, used as a fallback when
@@ -245,6 +249,17 @@ STATE_KEY_DEFAULTS = {
     "size": (0, 0),
     "position": (0, 0),
     "index": -1,
+    # Scroll widgets that take (h_pct, v_pct).  ScrollBar overrides
+    # these in STATE_DEFAULTS with scalar 0.0.
+    "scroll_position": (0.0, 0.0),
+    "scroll_percent": (0.0, 0.0),
+    "thumb_percent": (0.0, 0.0),
+    # set_expanding(horizontal, vertical) → tuple of bools
+    "expanding": (False, False),
+    "enabled": True,
+    "state": False,
+    # HTMLMediaElement convention: 0.0 (muted) to 1.0 (full).
+    "volume": 1.0,
 }
 
 # Widgets with incrementally-built item lists.

{pgwidgets_python-0.2.1 → pgwidgets_python-0.2.3}/pgwidgets/sync/application.py

@@ -384,18 +384,28 @@ class Session:
 
     def _dispatch_callback(self, wid, action, *args):
         """Dispatch a callback through the configured concurrency mode."""
-        # widget = self._widget_map.get(wid)
-        # cls_name = widget._js_class if widget is not None else "<missing>"
-        # print(f"[PY-CB] receive wid={wid} action={action} "
-        #       f"registered_class={cls_name}", flush=True)
-        if self._reconstructing:
-            return  # suppress callbacks during reconstruction
+        # Suppress callbacks during reconstruction — they are side
+        # effects of state replay, not user actions.  Exception: 'map'
+        # is a one-shot lifecycle event that fires when a widget first
+        # gains a visible layout box; the JS-side observers may fire
+        # it during the reconstruction window and we MUST forward it
+        # or the user's map handler never runs until something later
+        # triggers a re-fire (e.g. a window resize).
+        if self._reconstructing and action != 'map':
+            return
         # Auto-sync: some callbacks carry state that should be reflected
         # in the Python-side widget (e.g. move -> position, resize -> size).
+        # We always *capture* the value so get_size()/get_position() return
+        # current values, but only *push* it to other browsers (and replay
+        # it on reconstruction) when the widget opted in via auto-sync.
+        # Otherwise a layout-determined size would replay as a literal
+        # resize(W, H) — pinning the widget to pixel dimensions and
+        # killing flex growth.
         state_key = STATE_SYNC_CALLBACKS.get(action)
         if state_key is not None:
             widget = self._widget_map.get(wid)
             if widget is not None:
+                auto = action in widget._auto_sync_actions
                 # Normalize: resize sends {width, height} dict, move
                 # sends (x, y) as separate args.  Store as a flat tuple
                 # matching the corresponding setter's signature.
@@ -405,15 +415,17 @@ class Session:
                         new_val = (d["width"], d["height"])
                         if widget._state.get(state_key) != new_val:
                             widget._state[state_key] = new_val
-                            self._push(wid, "resize",
-                                       d["width"], d["height"])
+                            if auto:
+                                self._push(wid, "resize",
+                                           d["width"], d["height"])
                 else:
                     new_val = tuple(args)
                     if widget._state.get(state_key) != new_val:
                         widget._state[state_key] = new_val
-                        setter = (self._STATE_KEY_TO_SETTER.get(state_key)
-                                  or f"set_{state_key}")
-                        self._push(wid, setter, *args)
+                        if auto:
+                            setter = (self._STATE_KEY_TO_SETTER.get(state_key)
+                                      or f"set_{state_key}")
+                            self._push(wid, setter, *args)
                 # If this widget wraps a child (e.g. MDISubWindow),
                 # propagate geometry into the parent's children options
                 # so reconstruction replays with the current pos/size.
@@ -804,13 +816,33 @@ class Session:
             cls = self._widget_classes.get(cls_name, Widget) if cls_name else Widget
             widget = cls._from_existing(self, wid, cls_name or "Widget")
             self._widget_map[wid] = widget
-            # Auto-listen for state-syncing callbacks (move, resize)
-            # so position/size changes are tracked for reconstruction.
+            # Auto-listen for state-syncing callbacks (move, resize).
+            # For visual widgets we always listen for 'resize' so that
+            # get_size() can return a current value, but we only mark
+            # the action as auto-syncing (which triggers push-to-peers
+            # and replay-on-reconstruction) when the widget defn
+            # actually opts in.  Non-visual Callback-base objects (e.g.
+            # TextBufferRef, Timer) get nothing.
+            defn = WIDGETS.get(cls_name, {}) if cls_name else {}
+            opt_names_set = set(defn.get("options", []))
+            all_callbacks = defn.get("callbacks", [])
+            is_visual = defn.get("base") != "callback"
             for action in STATE_SYNC_CALLBACKS:
-                key = f"{wid}:{action}"
-                if key not in self._callbacks:
-                    self._listen(wid, action, lambda wid, *a: None)
-                widget._auto_sync_actions.add(action)
+                req_opt = STATE_SYNC_REQUIRES_OPTION.get(action)
+                if req_opt is not None:
+                    opted_in = req_opt in opt_names_set
+                else:
+                    opted_in = action in all_callbacks
+                if not is_visual:
+                    continue
+                if action == "resize" or opted_in:
+                    key = f"{wid}:{action}"
+                    if key not in self._callbacks:
+                        self._listen(wid, action, lambda wid, *a: None)
+                if opted_in:
+                    widget._auto_sync_actions.add(action)
+                elif action == "resize":
+                    widget._passive_sync_actions.add(action)
             return widget
         if isinstance(val, list):
             return [self._resolve_return(v) for v in val]
@@ -907,6 +939,13 @@ class Session:
     _STATE_KEY_TO_SETTER = {v: k for k, v in SPECIAL_SETTERS.items()}
     # e.g. {"size": "resize"}
 
+    # Reverse map: state_key -> callback action that auto-syncs it
+    # (e.g. "size" -> "resize", "position" -> "move").  Used during
+    # state replay to skip keys that weren't actively opted into via
+    # _auto_sync_actions — those were captured passively for getter
+    # support but must not be replayed (would pin layout).
+    _STATE_KEY_TO_SYNC_ACTION = {v: k for k, v in STATE_SYNC_CALLBACKS.items()}
+
     # State keys handled by fixed-value methods (show/hide)
     _FIXED_STATE_KEYS = {}
     for _mname, (_key, _val) in FIXED_SETTERS.items():
@@ -952,12 +991,23 @@ class Session:
                 self._listen(new_widget._wid, act,
                              lambda wid, *a: None)
                 new_widget._auto_sync_actions.add(act)
-        # Replay any state the proxy accumulated (e.g. set_tooltip)
+        # Replay any state the proxy accumulated (e.g. set_tooltip).
+        # Skip passively-captured auto-sync state (size, position): we
+        # capture those from callbacks so getters work, but replaying
+        # would pin the widget to layout-determined pixel dimensions
+        # (same logic as _reconstruct_widget).
+        user_set = getattr(old_widget, "_user_set_state", set())
+        auto = getattr(old_widget, "_auto_sync_actions", set())
         for key, value in old_widget._state.items():
             if key.startswith("_"):
                 continue
             if key in sync_keys:
                 continue
+            sync_action = self._STATE_KEY_TO_SYNC_ACTION.get(key)
+            if (sync_action is not None
+                    and key not in user_set
+                    and sync_action not in auto):
+                continue
             method_name = (self._STATE_KEY_TO_SETTER.get(key)
                            or f"set_{key}")
             if isinstance(value, tuple):
@@ -965,6 +1015,13 @@ class Session:
             else:
                 self._call(new_widget._wid, method_name, value)
             new_widget._state[key] = value
+            # Propagate user-set / auto-sync membership to the new
+            # widget so subsequent reconstructions replay consistently.
+            if sync_action is not None:
+                if key in user_set:
+                    new_widget._user_set_state.add(key)
+                if sync_action in auto:
+                    new_widget._auto_sync_actions.add(sync_action)
 
     def _ensure_reconstructed(self, widget):
         """Ensure a widget has been created on the JS side.
@@ -1147,6 +1204,20 @@ class Session:
             if key.startswith("_"):
                 continue
 
+            # Skip auto-sync state (size, position) that came in
+            # passively via a callback (e.g. layout-determined size).
+            # We capture those so getters like get_size()/
+            # get_position() work, but replaying them would pin the
+            # widget to pixel dimensions and override flex/expanding
+            # layout.  Replay only if the user explicitly set the
+            # value, or if the widget opted into the sync action
+            # (e.g. an interactively-resizable widget).
+            sync_action = self._STATE_KEY_TO_SYNC_ACTION.get(key)
+            if (sync_action is not None
+                    and key not in widget._user_set_state
+                    and sync_action not in widget._auto_sync_actions):
+                continue
+
             # Binary-payload state (e.g. set_binary_image) replays via
             # _send_binary so the bytes go in a raw frame, not embedded
             # as base64 in JSON.
@@ -1193,10 +1264,13 @@ class Session:
         # _listen calls treat them as first-time registrations and
         # actually send the "listen" message to the browser.
         wid = widget._wid
+        passive = getattr(widget, "_passive_sync_actions", set())
         for action in list(saved_cbs.keys()):
             self._callbacks.pop(f"{wid}:{action}", None)
         for action in widget._auto_sync_actions:
             self._callbacks.pop(f"{wid}:{action}", None)
+        for action in passive:
+            self._callbacks.pop(f"{wid}:{action}", None)
 
         for action, entries in saved_cbs.items():
             for handler, extra_args, extra_kwargs, style in entries:
@@ -1211,6 +1285,12 @@ class Session:
         for action in widget._auto_sync_actions:
             if action not in widget._registered_callbacks:
                 self._listen(widget._wid, action, lambda wid, *a: None)
+        # Passive listeners (e.g. 'resize' for getter support on
+        # widgets that didn't opt into auto-sync).
+        for action in passive:
+            if (action not in widget._registered_callbacks
+                    and action not in widget._auto_sync_actions):
+                self._listen(widget._wid, action, lambda wid, *a: None)
 
     def _child_method_for(self, parent):
         """Determine which child method a container uses."""

{pgwidgets_python-0.2.1 → pgwidgets_python-0.2.3}/pgwidgets/sync/widget.py

@@ -75,6 +75,16 @@ class Widget:
         self._constructor_options = {}
         self._registered_callbacks = {}
         self._auto_sync_actions = set()
+        # Actions we listen to passively for getter support
+        # (e.g. 'resize' on every visual widget so get_size() returns
+        # a current value), but that aren't in _auto_sync_actions and
+        # therefore don't push to peers or replay on reconstruction.
+        self._passive_sync_actions = set()
+        # State keys the user explicitly set via a setter call.
+        # Used during reconstruction to decide whether a state key
+        # should be replayed: passively-captured callback state
+        # (e.g. layout-determined size) is NOT in this set.
+        self._user_set_state = set()
         self._replay_calls = []
         self._add_seq = 0  # insertion order across _children + _replay_calls
 
@@ -160,6 +170,8 @@ class Widget:
         obj._constructor_options = {}
         obj._registered_callbacks = {}
         obj._auto_sync_actions = set()
+        obj._passive_sync_actions = set()
+        obj._user_set_state = set()
         obj._replay_calls = []
         obj._add_seq = 0
         obj._stale = False
@@ -177,15 +189,35 @@ class Widget:
         opt_names_set = set(defn.get("options", []))
         all_callbacks = defn.get("callbacks", [])
 
-        # State-sync callbacks (move -> position, resize -> size)
+        # State-sync callbacks (move -> position, resize -> size).
+        # For visual widgets we always *listen* so getters like
+        # get_size() / get_position() can return current values.
+        # But we only add the action to _auto_sync_actions — which
+        # controls push-to-peers and replay-on-reconstruction — when
+        # the widget actually opted in (e.g. via the 'resizable' option
+        # or by declaring the callback in its defn).  This keeps
+        # layout-determined sizes from being replayed as literal
+        # resize() calls that would pin flex/expanding widgets.
+        is_visual = defn.get("base") != "callback"
         for action in STATE_SYNC_CALLBACKS:
             req_opt = STATE_SYNC_REQUIRES_OPTION.get(action)
-            if req_opt and req_opt not in opt_names_set:
-                continue
-            if req_opt is None and action not in all_callbacks:
+            opted_in = False
+            if req_opt is not None:
+                opted_in = req_opt in opt_names_set
+            else:
+                opted_in = action in all_callbacks
+            # Visual widgets get the listen unconditionally for resize
+            # (it's a universal base-class callback) and for any move
+            # they declare.  Non-visual Callback-base objects get
+            # nothing here.
+            if not is_visual:
                 continue
-            session._listen(wid, action, lambda wid, *a: None)
-            self._auto_sync_actions.add(action)
+            if action == "resize" or opted_in:
+                session._listen(wid, action, lambda wid, *a: None)
+            if opted_in:
+                self._auto_sync_actions.add(action)
+            elif action == "resize":
+                self._passive_sync_actions.add(action)
 
         # Per-widget-class state sync (e.g. Slider "activated" -> value)
         cls_sync = WIDGET_CALLBACK_SYNC.get(js_class, {})
@@ -432,6 +464,9 @@ def _make_setter(method_name, param_names, state_key):
             self._state[state_key] = args[0]
         else:
             self._state[state_key] = args
+        # Mark as user-set so reconstruction knows to replay this key
+        # (callback-captured values for the same key don't get marked).
+        self._user_set_state.add(state_key)
         return self._call(method_name, *args)
     method.__name__ = method_name
     method.__qualname__ = f"Widget.{method_name}"
@@ -444,6 +479,7 @@ def _make_fixed_setter(method_name, state_key, fixed_value):
     """Create a no-arg method that sets a fixed state value (show/hide)."""
     def method(self):
         self._state[state_key] = fixed_value
+        self._user_set_state.add(state_key)
         return self._call(method_name)
     method.__name__ = method_name
     method.__qualname__ = f"Widget.{method_name}"

{pgwidgets_python-0.2.1 → pgwidgets_python-0.2.3}/pgwidgets_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgwidgets-python
-Version: 0.2.1
+Version: 0.2.3
 Summary: Python bindings for the pgwidgets JavaScript widget library
 Author: PGWidgets Developers
 License: BSD-3-Clause