bec_widgets.utils.guided_tour#

Module providing a guided help system for creating interactive GUI tours.

Classes#

GuidedTour

A guided help system for creating interactive GUI tours.

MainWindow

TourStep

Type definition for a tour step.

TutorialOverlay

Module Contents#

class GuidedTour(main_window: qtpy.QtWidgets.QWidget, *, enforce_visibility: bool = True)#

Bases: qtpy.QtCore.QObject

A guided help system for creating interactive GUI tours.

Allows developers to register widgets with help text and create guided tours.

_action_highlight_rect(action: qtpy.QtGui.QAction) → qtpy.QtCore.QRect | None#

Try to find the QRect in main_window coordinates that should be highlighted for the given QAction. Returns None if not found (e.g. not visible).

_advance_past_invalid_step(step_title: str, *, reason: str, direction: Literal['next'] | Literal['prev'] = 'next')#

Skip the current step (or stop the tour) when the target cannot be visualised.

_get_highlight_rect(main_window: qtpy.QtWidgets.QWidget, target: qtpy.QtWidgets.QWidget | qtpy.QtGui.QAction | qtpy.QtCore.QRect, step_title: str, direction: Literal['next'] | Literal['prev'] = 'next') → qtpy.QtCore.QRect | None#

Get the QRect in main_window coordinates to highlight for the given target.

Parameters:

  • main_window (QWidget) – The main window containing the target.

  • target (QWidget | QAction) – The target widget or action to highlight.

  • step_title (str) – The title of the current step (for logging purposes).

Returns:

The rectangle to highlight, or None if not found/visible.

Return type:

QRect | None

_resolve_step_target(step: TourStep) → tuple[qtpy.QtWidgets.QWidget | qtpy.QtGui.QAction | qtpy.QtCore.QRect | None, str]#

Resolve the target widget/action for the given step.

Parameters:

step (TourStep) – The tour step to resolve.

Returns:

The resolved target, optional QRect, and the step text.

Return type:

tuple[QWidget | QAction | QRect | None, str]

_show_current_step(direction: Literal['next'] | Literal['prev'] = 'next')#

Display the current step.

clear_registrations()#

Clear all registered widgets.

create_tour(step_ids: List[str] | None = None) → bool#

Create a tour from registered widget IDs.

Parameters:

step_ids (List[str], optional) – List of registered widget IDs to include in the tour. If None, all registered widgets will be included.

Returns:

True if the tour was created successfully, False if any step IDs were not found

Return type:

bool

eventFilter(obj, event)#

Handle window resize/move events to update step positioning.

get_registered_widgets() → Dict[str, TourStep]#

Get all registered widgets.

next_step()#

Move to next step or finish tour if on last step.

prev_step()#

Move to previous step.

register_widget(*, widget: qtpy.QtWidgets.QWidget | qtpy.QtGui.QAction | qtpy.QtCore.QRect | Callable[[], tuple[qtpy.QtWidgets.QWidget | qtpy.QtGui.QAction | qtpy.QtCore.QRect, str | None]], text: str = '', title: str = '') → str#

Register a widget with help text for tours.

Parameters:

  • widget (QWidget | QAction | QRect | Callable[[], tuple[QWidget | QAction | QRect, str | None]]) – The target widget or a callable that returns the widget and its help text.

  • text (str) – The help text for the widget. This will be shown during the tour.

  • title (str, optional) – A title for the widget (defaults to its class name or action text).

Returns:

The unique ID for the registered widget.

Return type:

str

set_visibility_enforcement(enabled: bool)#

Enable or disable visibility checks when highlighting widgets.

start_tour()#

Start the guided tour.

stop_tour()#

Stop the current tour.

unregister_widget(step_id: str) → bool#

Unregister a previously registered widget.

Parameters:

step_id (str) – The unique ID of the registered widget.

Returns:

True if the widget was unregistered, False if not found.

Return type:

bool

property main_window: qtpy.QtWidgets.QWidget | None#

Get the main window from weak reference.

main_window_ref#
overlay = None#
step_changed#
tour_finished#
tour_started#
class MainWindow#

Bases: qtpy.QtWidgets.QMainWindow

_init_menu_bar()#
_init_toolbar()#
_setup_tools_menu()#
btn1#
btn2#
guided_help#
start_tour_btn#
status_label#
tour_step_ids#
class TourStep#

Bases: TypedDict

Type definition for a tour step.

Initialize self. See help(type(self)) for accurate signature.

text: str#
title: str#
widget_ref: louie.saferef.BoundMethodWeakref | weakref.ReferenceType[qtpy.QtWidgets.QWidget | qtpy.QtGui.QAction | qtpy.QtCore.QRect | Callable[[], tuple[qtpy.QtWidgets.QWidget | qtpy.QtGui.QAction | qtpy.QtCore.QRect, str | None]]] | Callable[[], tuple[qtpy.QtWidgets.QWidget | qtpy.QtGui.QAction | qtpy.QtCore.QRect, str | None]] | None#
class TutorialOverlay(parent=None)#

Bases: qtpy.QtWidgets.QWidget

_create_message_box()#
eventFilter(obj, event)#
paintEvent(event)#
show_step(rect: qtpy.QtCore.QRect, title: str, text: str, current_step: int = 1, total_steps: int = 1)#

rect must already be in the overlay’s coordinate space (i.e. mapped). This method positions the message box so it does not overlap the rect.

Parameters:

  • rect (QRect) – rectangle to highlight

  • title (str) – Title text for the step

  • text (str) – Main content text for the step

  • current_step (int) – Current step number

  • total_steps (int) – Total number of steps in the tour

current_rect#
message_box#