0.4.7 — Tab Identity Refactor

0.4.7 — Tab Identity Refactor#

Released — current version

Every tab, pane, and window now carries a stable integer ID allocated at creation time from a single process-wide counter. Internal operations that previously looked up tabs by display label now key off tab_id, so multi-split layouts with duplicate screen names no longer confuse focus restoration, merge, or refresh.

Identity Module#

  • New VIStk.Objects._Identity.new_id() returns a fresh, strictly-increasing int; thread-safe.

  • IDs are unique for the lifetime of the Python process but not persisted across runs. Persistence (for “remember open tabs”) will use UUIDs when it lands in 0.6.X settings.

Tab IDs#

  • TabManager.open_tab(name, module, ...) now returns the new tab_id: int (was bool). Hold the ID to address a specific tab instance.

  • TabManager._tabs is keyed by tab_id (was the display label). Each entry carries its own display_name, base_name, and tab_id.

  • Public methods — close_tab, focus_tab, has_tab, force_refresh_tab, set_tab_info — accept either a tab_id (int) or a display label (str). Label lookups return the first match; prefer the tab_id returned by open_tab.

  • TabManager.active is now int | None (was str | None). Use TabManager.display_name(tab_id) to resolve back to a label.

  • Callbacks now pass tab_id first:

    manager.on_tab_activate    = lambda tab_id, module: ...
manager.on_tab_deactivate  = lambda tab_id | None: ...
manager.on_tab_popout      = lambda tab_id: ...
manager.on_tab_detach      = lambda tab_id: ...
manager.on_tab_refresh     = lambda tab_id: ...
manager.on_tab_info_change = lambda tab_id, info: ...
manager.on_tab_split       = lambda tab_id, direction, pane: ...

  • TabBar._tabs is keyed by tab_id with the label in entry["label"]. TabBar.update_tab_label(tab_id, new_label) replaces it.

Pane and Window IDs#

  • TabManager gains self.id: int.

  • _SplitNode gains self.id: int; SplitView._pane_parents is now keyed by .id rather than id(object), avoiding any theoretical memory-address reuse collisions.

  • DetachedWindow gains self.id: int (attribute only — no lookups are keyed off it yet; future “remember open windows” will consume it).

SplitView.remove_pane — Focus Restore Fix#

This is the primary bug fix for 0.4.7.

Previously, when a pane was removed the SplitView rebuilt the surviving subtree under a fresh Tk parent (because ttk.PanedWindow requires direct Tk children). After the rebuild, focus fell back to panes[0] — the first pane in left-to-right order. In multi-split layouts where multiple panes contained tabs with the same base name (for example two Dashboard tabs), the user’s focused pane could be silently lost.

Now:

  • Before destroying the old subtree, the SplitView records the tab_id of the currently active tab inside the surviving pane.

  • _snapshot_subtree captures each tab’s tab_id alongside its module, hooks, icon and info.

  • _rebuild_from_snapshot passes tab_id=... to TabManager.open_tab, so the reopened tabs keep their identities.

  • After rebuild, the SplitView finds whichever new pane now owns the recorded tab_id and restores focus there. If the focused pane was the one removed (or the ID could not be recovered), it falls back to the first surviving pane as before.

SplitView.find_pane_for_tab(tab_id) replaces the former name-based lookup.

Host#

  • _find_tab_by_base(base_name) now returns (tab_manager, tab_id) instead of (tab_manager, display_name).

  • _get_all_tab_names is renamed _get_all_tab_labels; it still collects display labels for _unique_display_name only.

  • _open_counts is retired — tab IDs make multi-instance tracking trivial, label uniqueness is purely a UX concern handled by _unique_display_name.

  • Screen.close() routes through the ID-based close_tab(tab_id).

IPC#

IPC is not being reintroduced. The draft 0.4.7 spec in the changelog mentioned __VIS_CLOSE__ but the in-process _HOST_INSTANCE singleton remains the sole navigation path. If IPC is added later it will use tab IDs natively.

Backward Compatibility#

  • TabManager public methods still accept display labels (str) as the key argument, so existing screen code calling tm.close_tab("Work Orders") continues to work. Prefer holding the tab_id returned by open_tab for deterministic lookup in the presence of duplicates.

  • The TabManager.open_tab return type changed from bool to int | None. Falsy None still indicates failure (tab already exists); non-None truthy int still indicates success — the if tm.open_tab(...): idiom keeps working.

  • TabManager.active is now int | None. Code comparing tm.active == "ScreenName" will need to call tm.display_name(tm.active) for the label.

Out of Scope#

  • Persistent (UUID / cross-process) IDs — deferred to 0.6.X.

  • Deregistering stale TabManager references from Host.registered_tab_managers and DetachedWindow.tab_managers after remove_pane — pre-existing bookkeeping leak, orthogonal to this refactor.