ae.gui.tours

app tour base classes

Classes

OnboardingTour(main_app)

onboarding tour for first app start.

TourBase(main_app)

abstract tour base class, automatically registering subclasses as app tours.

TourDropdownFromButton(main_app)

generic tour base class to auto-explain a dropdown menu, starting with the button opening the dropdown.

UserPreferencesTour(main_app)

user preferences menu tour.
class TourBase(main_app)[source]

Bases: object

abstract tour base class, automatically registering subclasses as app tours.

subclass this generic, UI-framework-independent base class to bundle pages of a tour and make sure that the attr:~TourBase.page_ids and page_data attributes are correctly set. a UI-framework-dependent tour overlay/layout instance, created and assigned to main_app.tour_layout, will automatically create an instance of your tour-specific subclass on tour start.

classmethod __init_subclass__(**kwargs)[source]

register tour class; called on declaration of tour subclass.

__init__(main_app)[source]
auto_switch_pages: bool | int

enable/disable automatic switch of tour pages.

set to True, 1 or -1 to automatically switch tour pages; True and 1 will switch to the next page until the last page is reached, while -1 will switch back to the previous pages until the first page is reached; -1 and 1 automatically toggles at the first/last page the to other value (endless ping-pong until back/next button gets pressed by the user).

the seconds to display each page before switching to the next one can be specified via the item value of the the dict page_data dict with the key ‘next_page_delay’.

page_data: dict[str, Any]

additional/optional help variables (in help_vars key), tour and page text/layout/timing settings.

the class attribute values are default values for all tour pages and get individually overwritten for each tour page by the i18n translations attributes on tour page change via load_page_data().

supported/implemented dict keys:

  • app_flow_delay: time in seconds to wait until app flow change is completed (def=1.2, >0.9 for auto-width).

  • back_text: caption of tour previous page button (def=get_text(‘back’)).

  • fade_out_app: set to 0.0 to prevent the fade out of the app screen (def=1.0).

  • help_vars: additional help variables, e.g. help_translation providing context help translation dict/text.

  • next_text: caption of tour next page button (def=get_text(‘next’)).

  • next_page_delay: time in seconds to read the current page before next request_auto_page_switch() (def=9.6).

  • page_update_delay: time in seconds to wait until tour layout/overlay is completed (def=0.9).

  • tip_text or ‘’ (empty string): tour page tooltip text fstring message text template. alternatively put as first character a ‘=’ character followed by a tour page flow id to initialize the tip_text to the help translation text of the related flow widget, and the self help variable to the related flow widget instance.

  • tour_start_delay: seconds between tour.start() and on_tour_start main app event (def=TOUR_START_DELAY_DEF).

  • tour_exit_delay: seconds between tour.stop() and the on_tour_exit main app event (def=TOUR_EXIT_DELAY_DEF).

pages_explained_matchers: dict[str, Callable[[Any], bool] | str | tuple[Callable[[Any], bool] | str, ...]]

matchers (specified as callable or id-string) to determine the explained widget(s) of each tour page.

each key of this dict is a tour page id (for which the explained widget(s) will be determined).

the value of each dict item is a matcher or a tuple of matchers. each matcher specifies a widget to be explained/targeted/highlighted. for matcher tuples the minimum rectangle enclosing all widgets get highlighted.

the types of matchers, to identify any visible widget, are:

  • find_widget() matcher callable (scanning framework_win.children)

  • evaluation expression resulting in find_widget() matcher callable

  • widget id string, declared via kv lang, identifying widget in framework_root.ids

  • page id string, compiled from widgets app state/flow/focus via widget_page_id() to identify widget

page_ids: list[str]

list of tour page ids, either initialized via this class attribute or dynamically.

page_idx: int

index of the current tour page (in page_ids)

last_page_idx: int | None

last tour page index (None on tour start)

main_app

shortcut to main app instance

layout

tour overlay layout instance

top_popup

top most popup widget (in an app tour simulation)

backup_app_states()[source]

back up the current states of this app, including flow.

cancel_auto_page_switch_request(reset=True)[source]

cancel auto switch callback if requested, called e.g., from tour layout/overlay next/back buttons.

cancel_delayed_setup_layout_call()[source]

cancel delayed setup layout call request.

property last_page_id: str | None

determine the last displayed tour page id.

load_page_data()[source]

load a page before switching to it; maybe reload after preparing app flow and before setup of layout.

next_page()[source]

switch to the next tour page.

prev_page()[source]

switch to the previous tour page.

request_auto_page_switch()[source]

initiate automatic switch to the next tour page.

restore_app_states()[source]

restore app states of this app - saved via backup_app_states().

setup_app_flow()[source]

set up app flow and load page data to prepare a tour page.

setup_explained_widget()[source]

determine and set the explained widget for the actual tour page.

Return type:

list

Returns:

list of explained widget instances.

setup_layout()[source]

setup/prepare tour overlay/layout after switch of tour page.

setup_texts()[source]

setup texts in tour layout from page_data.

start()[source]

prepare app tour start.

stop()[source]

stop/cancel tour.

teardown_app_flow()[source]

restore app flow and app states before tour finishing or before preparing/switching to prev/next page.

update_page_ids()[source]

update/change page ids on app flow setup (before tour page loading and the tour overlay/layout setup).

override this method to dynamically change the page_ids in a running tour. after adding/removing a page, the attribute values of last_page_idx and page_idx have to be corrected accordingly.

class TourDropdownFromButton(main_app)[source]

Bases: TourBase

generic tour base class to auto-explain a dropdown menu, starting with the button opening the dropdown.

determine_page_ids = '_v_'
setup_app_flow()[source]

manage the opening state of the dropdown: open it or close it if the opening button gets explained.

setup_layout()[source]

prepare the layout for all tour pages - first page explains opening dropdown button.

class OnboardingTour(main_app)[source]

Bases: TourBase

onboarding tour for first app start.

__init__(main_app)[source]

count and persistently store in config variable, the onboarding tour starts since app installation.

setup_app_flow()[source]

overridden to open user preferences dropdown in the responsible_layout tour page.

teardown_app_flow()[source]

overridden to close the opened user preferences dropdown on leaving layout_font_size tour page.

update_page_ids()[source]

overridden to remove 2nd-/well-done-page (only showing once on next-page-jump from 1st-/welcome-page).

class UserPreferencesTour(main_app)[source]

Bases: TourDropdownFromButton

user preferences menu tour.

__init__(main_app)[source]