bec_widgets.utils.guided_tour ============================= .. py:module:: bec_widgets.utils.guided_tour .. autoapi-nested-parse:: Module providing a guided help system for creating interactive GUI tours. Classes ------- .. autoapisummary:: bec_widgets.utils.guided_tour.GuidedTour bec_widgets.utils.guided_tour.MainWindow bec_widgets.utils.guided_tour.TourStep bec_widgets.utils.guided_tour.TutorialOverlay Module Contents --------------- .. py:class:: GuidedTour(main_window: qtpy.QtWidgets.QWidget, *, enforce_visibility: bool = True) Bases: :py:obj:`qtpy.QtCore.QObject` A guided help system for creating interactive GUI tours. Allows developers to register widgets with help text and create guided tours. .. py:method:: _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). .. py:method:: _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. .. py:method:: _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. :param main_window: The main window containing the target. :type main_window: QWidget :param target: The target widget or action to highlight. :type target: QWidget | QAction :param step_title: The title of the current step (for logging purposes). :type step_title: str :returns: The rectangle to highlight, or None if not found/visible. :rtype: QRect | None .. py:method:: _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. :param step: The tour step to resolve. :type step: TourStep :returns: The resolved target, optional QRect, and the step text. :rtype: tuple[QWidget | QAction | QRect | None, str] .. py:method:: _show_current_step(direction: Literal['next'] | Literal['prev'] = 'next') Display the current step. .. py:method:: clear_registrations() Clear all registered widgets. .. py:method:: create_tour(step_ids: List[str] | None = None) -> bool Create a tour from registered widget IDs. :param step_ids: List of registered widget IDs to include in the tour. If None, all registered widgets will be included. :type step_ids: List[str], optional :returns: True if the tour was created successfully, False if any step IDs were not found :rtype: bool .. py:method:: eventFilter(obj, event) Handle window resize/move events to update step positioning. .. py:method:: get_registered_widgets() -> Dict[str, TourStep] Get all registered widgets. .. py:method:: next_step() Move to next step or finish tour if on last step. .. py:method:: prev_step() Move to previous step. .. py:method:: 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. :param widget: The target widget or a callable that returns the widget and its help text. :type widget: QWidget | QAction | QRect | Callable[[], tuple[QWidget | QAction | QRect, str | None]] :param text: The help text for the widget. This will be shown during the tour. :type text: str :param title: A title for the widget (defaults to its class name or action text). :type title: str, optional :returns: The unique ID for the registered widget. :rtype: str .. py:method:: set_visibility_enforcement(enabled: bool) Enable or disable visibility checks when highlighting widgets. .. py:method:: start_tour() Start the guided tour. .. py:method:: stop_tour() Stop the current tour. .. py:method:: unregister_widget(step_id: str) -> bool Unregister a previously registered widget. :param step_id: The unique ID of the registered widget. :type step_id: str :returns: True if the widget was unregistered, False if not found. :rtype: bool .. py:property:: main_window :type: qtpy.QtWidgets.QWidget | None Get the main window from weak reference. .. py:attribute:: main_window_ref .. py:attribute:: overlay :value: None .. py:attribute:: step_changed .. py:attribute:: tour_finished .. py:attribute:: tour_started .. py:class:: MainWindow Bases: :py:obj:`qtpy.QtWidgets.QMainWindow` .. py:method:: _init_menu_bar() .. py:method:: _init_toolbar() .. py:method:: _setup_tools_menu() .. py:attribute:: btn1 .. py:attribute:: btn2 .. py:attribute:: guided_help .. py:attribute:: start_tour_btn .. py:attribute:: status_label .. py:attribute:: tour_step_ids .. py:class:: TourStep Bases: :py:obj:`TypedDict` Type definition for a tour step. Initialize self. See help(type(self)) for accurate signature. .. py:attribute:: text :type: str .. py:attribute:: title :type: str .. py:attribute:: widget_ref :type: 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 .. py:class:: TutorialOverlay(parent=None) Bases: :py:obj:`qtpy.QtWidgets.QWidget` .. py:method:: _create_message_box() .. py:method:: eventFilter(obj, event) .. py:method:: paintEvent(event) .. py:method:: 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. :param rect: rectangle to highlight :type rect: QRect :param title: Title text for the step :type title: str :param text: Main content text for the step :type text: str :param current_step: Current step number :type current_step: int :param total_steps: Total number of steps in the tour :type total_steps: int .. py:attribute:: current_rect .. py:attribute:: message_box