From 80f2ca40cba5b7a13460abfd8879f82a90bfe1b2 Mon Sep 17 00:00:00 2001 From: wyzula-jan Date: Wed, 14 Jan 2026 16:07:54 +0100 Subject: [PATCH] fix(advanced_dock_area): CLI API adjustments docs + names --- bec_widgets/cli/client.py | 43 ++++++++++++----- .../advanced_dock_area/advanced_dock_area.py | 48 ++++++++++++++----- .../toolbar_components/workspace_actions.py | 4 +- tests/unit_tests/test_advanced_dock_area.py | 28 +++++------ 4 files changed, 82 insertions(+), 41 deletions(-) diff --git a/bec_widgets/cli/client.py b/bec_widgets/cli/client.py index e130919c..a284a1f5 100644 --- a/bec_widgets/cli/client.py +++ b/bec_widgets/cli/client.py @@ -105,21 +105,46 @@ class AdvancedDockArea(RPCBase): movable: "bool" = True, start_floating: "bool" = False, where: "Literal['left', 'right', 'top', 'bottom'] | None" = None, - on_close: "Callable[[CDockWidget, QWidget], None] | None" = None, tab_with: "CDockWidget | QWidget | str | None" = None, relative_to: "CDockWidget | QWidget | str | None" = None, - return_dock: "bool" = False, show_title_bar: "bool | None" = None, title_buttons: "Mapping[str, bool] | Sequence[str] | str | None" = None, show_settings_action: "bool | None" = None, promote_central: "bool" = False, object_name: "str | None" = None, **widget_kwargs, - ) -> "QWidget | CDockWidget | BECWidget": + ) -> "QWidget | BECWidget": """ - Override the base helper so dock settings are available by default. + Create a new widget (or reuse an instance) and add it as a dock. - The flag remains user-configurable (pass ``False`` to hide the action). + Args: + widget(QWidget | str): Instance or registered widget type string. + closable(bool): Whether the dock is closable. + floatable(bool): Whether the dock is floatable. + movable(bool): Whether the dock is movable. + start_floating(bool): Whether to start the dock floating. + where(Literal["left", "right", "top", "bottom"] | None): Dock placement hint relative to the dock area (ignored when + ``relative_to`` is provided without an explicit value). + tab_with(CDockWidget | QWidget | str | None): Existing dock (or widget/name) to tab the new dock alongside. + relative_to(CDockWidget | QWidget | str | None): Existing dock (or widget/name) used as the positional anchor. + When supplied and ``where`` is ``None``, the new dock inherits the + anchor's current dock area. + show_title_bar(bool | None): Explicitly show or hide the dock area's title bar. + title_buttons(Mapping[str, bool] | Sequence[str] | str | None): Mapping or iterable describing which title bar buttons should + remain visible. Provide a mapping of button names (``"float"``, + ``"close"``, ``"menu"``, ``"auto_hide"``, ``"minimize"``) to booleans, + or a sequence of button names to hide. + show_settings_action(bool | None): Control whether a dock settings/property action should + be installed. Defaults to ``False`` for the basic dock area; subclasses + such as `AdvancedDockArea` override the default to ``True``. + promote_central(bool): When True, promote the created dock to be the dock manager's + central widget (useful for editor stacks or other root content). + object_name(str | None): Optional object name to assign to the created widget. + **widget_kwargs: Additional keyword arguments passed to the widget constructor + when creating by type name. + + Returns: + BECWidget: The created or reused widget instance. """ @rpc_call @@ -136,7 +161,7 @@ class AdvancedDockArea(RPCBase): @property @rpc_call - def lock_workspace(self) -> "bool": + def workspace_is_locked(self) -> "bool": """ Get or set the lock state of the workspace. @@ -214,12 +239,6 @@ class AdvancedDockArea(RPCBase): Useful for determining the keys to use in `set_layout_ratios(splitter_overrides=...)`. """ - @rpc_call - def print_layout_structure(self) -> "None": - """ - Pretty-print the current splitter paths to stdout. - """ - @property @rpc_call def mode(self) -> "str": diff --git a/bec_widgets/widgets/containers/advanced_dock_area/advanced_dock_area.py b/bec_widgets/widgets/containers/advanced_dock_area/advanced_dock_area.py index cb5279b4..3072c2c3 100644 --- a/bec_widgets/widgets/containers/advanced_dock_area/advanced_dock_area.py +++ b/bec_widgets/widgets/containers/advanced_dock_area/advanced_dock_area.py @@ -98,13 +98,12 @@ class AdvancedDockArea(DockAreaWidget): "new", "widget_map", "widget_list", - "lock_workspace", + "workspace_is_locked", "attach_all", "delete_all", "remove_widget", "set_layout_ratios", "describe_layout", - "print_layout_structure", "mode", "mode.setter", "save_profile", @@ -263,21 +262,46 @@ class AdvancedDockArea(DockAreaWidget): movable: bool = True, start_floating: bool = False, where: Literal["left", "right", "top", "bottom"] | None = None, - on_close: Callable[[CDockWidget, QWidget], None] | None = None, tab_with: CDockWidget | QWidget | str | None = None, relative_to: CDockWidget | QWidget | str | None = None, - return_dock: bool = False, show_title_bar: bool | None = None, title_buttons: Mapping[str, bool] | Sequence[str] | str | None = None, show_settings_action: bool | None = None, promote_central: bool = False, object_name: str | None = None, **widget_kwargs, - ) -> QWidget | CDockWidget | BECWidget: + ) -> QWidget | BECWidget: """ - Override the base helper so dock settings are available by default. + Create a new widget (or reuse an instance) and add it as a dock. - The flag remains user-configurable (pass ``False`` to hide the action). + Args: + widget(QWidget | str): Instance or registered widget type string. + closable(bool): Whether the dock is closable. + floatable(bool): Whether the dock is floatable. + movable(bool): Whether the dock is movable. + start_floating(bool): Whether to start the dock floating. + where(Literal["left", "right", "top", "bottom"] | None): Dock placement hint relative to the dock area (ignored when + ``relative_to`` is provided without an explicit value). + tab_with(CDockWidget | QWidget | str | None): Existing dock (or widget/name) to tab the new dock alongside. + relative_to(CDockWidget | QWidget | str | None): Existing dock (or widget/name) used as the positional anchor. + When supplied and ``where`` is ``None``, the new dock inherits the + anchor's current dock area. + show_title_bar(bool | None): Explicitly show or hide the dock area's title bar. + title_buttons(Mapping[str, bool] | Sequence[str] | str | None): Mapping or iterable describing which title bar buttons should + remain visible. Provide a mapping of button names (``"float"``, + ``"close"``, ``"menu"``, ``"auto_hide"``, ``"minimize"``) to booleans, + or a sequence of button names to hide. + show_settings_action(bool | None): Control whether a dock settings/property action should + be installed. Defaults to ``False`` for the basic dock area; subclasses + such as `AdvancedDockArea` override the default to ``True``. + promote_central(bool): When True, promote the created dock to be the dock manager's + central widget (useful for editor stacks or other root content). + object_name(str | None): Optional object name to assign to the created widget. + **widget_kwargs: Additional keyword arguments passed to the widget constructor + when creating by type name. + + Returns: + BECWidget: The created or reused widget instance. """ if show_settings_action is None: show_settings_action = True @@ -288,10 +312,8 @@ class AdvancedDockArea(DockAreaWidget): movable=movable, start_floating=start_floating, where=where, - on_close=on_close, tab_with=tab_with, relative_to=relative_to, - return_dock=return_dock, show_title_bar=show_title_bar, title_buttons=title_buttons, show_settings_action=show_settings_action, @@ -496,7 +518,7 @@ class AdvancedDockArea(DockAreaWidget): self.toolbar.components.get_action("screenshot").action.triggered.connect(self.screenshot) def _set_editable(self, editable: bool) -> None: - self.lock_workspace = not editable + self.workspace_is_locked = not editable self._editable = editable if self._profile_management_enabled: @@ -510,7 +532,7 @@ class AdvancedDockArea(DockAreaWidget): # Workspace Management ################################################################################ @SafeProperty(bool) - def lock_workspace(self) -> bool: + def workspace_is_locked(self) -> bool: """ Get or set the lock state of the workspace. @@ -519,8 +541,8 @@ class AdvancedDockArea(DockAreaWidget): """ return self._locked - @lock_workspace.setter - def lock_workspace(self, value: bool): + @workspace_is_locked.setter + def workspace_is_locked(self, value: bool): """ Set the lock state of the workspace. Docks remain resizable, but are not movable or closable. diff --git a/bec_widgets/widgets/containers/advanced_dock_area/toolbar_components/workspace_actions.py b/bec_widgets/widgets/containers/advanced_dock_area/toolbar_components/workspace_actions.py index 88940c0e..9f7fd758 100644 --- a/bec_widgets/widgets/containers/advanced_dock_area/toolbar_components/workspace_actions.py +++ b/bec_widgets/widgets/containers/advanced_dock_area/toolbar_components/workspace_actions.py @@ -147,8 +147,8 @@ class WorkspaceConnection(BundleConnection): self.bundle_name = "workspace" self.components = components self.target_widget = target_widget - if not hasattr(self.target_widget, "lock_workspace"): - raise AttributeError("Target widget must implement 'lock_workspace'.") + if not hasattr(self.target_widget, "workspace_is_locked"): + raise AttributeError("Target widget must implement 'workspace_is_locked'.") self._connected = False def connect(self): diff --git a/tests/unit_tests/test_advanced_dock_area.py b/tests/unit_tests/test_advanced_dock_area.py index 26f3a8e2..d7abcefa 100644 --- a/tests/unit_tests/test_advanced_dock_area.py +++ b/tests/unit_tests/test_advanced_dock_area.py @@ -606,7 +606,7 @@ class TestAdvancedDockAreaInit: "new", "widget_map", "widget_list", - "lock_workspace", + "workspace_is_locked", "attach_all", "delete_all", ] @@ -760,32 +760,32 @@ class TestWorkspaceLocking: """Test workspace locking functionality.""" def test_lock_workspace_property_getter(self, advanced_dock_area): - """Test lock_workspace property getter.""" + """Test workspace_is_locked property getter.""" # Initially unlocked - assert advanced_dock_area.lock_workspace is False + assert advanced_dock_area.workspace_is_locked is False # Set locked state directly advanced_dock_area._locked = True - assert advanced_dock_area.lock_workspace is True + assert advanced_dock_area.workspace_is_locked is True def test_lock_workspace_property_setter(self, advanced_dock_area, qtbot): - """Test lock_workspace property setter.""" + """Test workspace_is_locked property setter.""" # Create a dock first advanced_dock_area.new("DarkModeButton") qtbot.wait(200) # Initially unlocked - assert advanced_dock_area.lock_workspace is False + assert advanced_dock_area.workspace_is_locked is False # Lock workspace - advanced_dock_area.lock_workspace = True + advanced_dock_area.workspace_is_locked = True assert advanced_dock_area._locked is True - assert advanced_dock_area.lock_workspace is True + assert advanced_dock_area.workspace_is_locked is True # Unlock workspace - advanced_dock_area.lock_workspace = False + advanced_dock_area.workspace_is_locked = False assert advanced_dock_area._locked is False - assert advanced_dock_area.lock_workspace is False + assert advanced_dock_area.workspace_is_locked is False class TestDeveloperMode: @@ -799,22 +799,22 @@ class TestDeveloperMode: # Toggle developer mode advanced_dock_area._on_developer_mode_toggled(True) assert advanced_dock_area._editable is True - assert advanced_dock_area.lock_workspace is False + assert advanced_dock_area.workspace_is_locked is False advanced_dock_area._on_developer_mode_toggled(False) assert advanced_dock_area._editable is False - assert advanced_dock_area.lock_workspace is True + assert advanced_dock_area.workspace_is_locked is True def test_set_editable(self, advanced_dock_area): """Test _set_editable functionality.""" # Test setting editable to True advanced_dock_area._set_editable(True) - assert advanced_dock_area.lock_workspace is False + assert advanced_dock_area.workspace_is_locked is False assert advanced_dock_area._editable is True # Test setting editable to False advanced_dock_area._set_editable(False) - assert advanced_dock_area.lock_workspace is True + assert advanced_dock_area.workspace_is_locked is True assert advanced_dock_area._editable is False