ae.gui_help

main app base class with context help for flow and app state changes

the class HelpAppBase provided by this namespace portion is extending your application with a context-sensitive help functionality.

the data-driven approach allows ad-hoc-changes of your app’s help texts without the need of code changes or recompilation. this gets achieved within HelpAppBase by overriding the main app class methods change_flow() and change_app_state().

so to add help support to the widgets of your app you only need to add/provide the help texts with a help id that is matching the value of the help_id attribute of the widget you need help for.

additionally, you can provide a separate i18n translation message file for each of the supported languages to make your help texts multilingual.

help layout implementation example

HelpAppBase inherits from MainAppBase while still being independent of the used GUI framework/library.

Note

the user interface for this help system has to be provided externally on top of this module. it can either be implemented directly in your app project or in a separate framework-specific module.

use HelpAppBase as base class of the GUI framework specific main application class and implement the abstract methods init_app() and ensure_top_most_z_index():

from ae.gui_help import HelpAppBase

class MyMainApp(HelpAppBase):
    def init_app(self, framework_app_class=None):
        self.framework_app = framework_app_class()
        ...
        return self.framework_app.run, self.framework_app.stop

    def ensure_top_most_z_index(self, widget):
        framework_method_to_push_widget_to_top_most(widget)
        ...

to activate the help mode the widget to display the help texts have to be assigned to the main app attribute help_layout and to the framework app property help_layout via the change_observable() method:

main_app.change_observable('help_layout', HelpScreenContainerOrWindow())

the help_layout property is also used as a flag of the help mode activity. by assigning None to these attributes the help mode will be deactivated:

main_app.change_observable('help_layout', None)

use the attribute help_activator to provide and store a widget that allows the user to toggle the help mode activation. the help_display() is using it as fallback widget if no help target (or widget to be explained) got found.

Hint

the de-/activation method help_activation_toggle() together with the classes HelpBehavior, HelpToggler and Tooltip are demonstrating a typical implementation of help activator and help text tooltip widgets.

additional helper functions

the helper functions anchor_layout_x(), anchor_layout_y(), anchor_points() and anchor_spec() are calculating framework-independent the position and direction of the targeting tooltip anchor arrow and its layout box.

flow change context message id

the message id to identify the help texts for each flow button is composed by the id_of_flow_help(), using the prefix marker string defined by the module variable FLOW_HELP_ID_PREFIX followed by the flow id of the flow widget.

for example the message id for a flow button with the flow action ‘open’, the object ‘item’ and the (optional) flow key ‘123456’ is resulting in the following help text message id:

'help_flow#open_item:123456'

if there is no need for a detailed message id that is taking the flow key into account, then simply create a help text message id without the flow key.

the method help_display() does first search for a message id including the flow key in the available help text files and if not found it will automatically fall back to use a message id without the flow key:

'help_flow#open_item'

Hint

more information regarding the flow id you find in the doc string of the module ae.gui_app in the section application flow.

application state change context message id

the message ids for app state change help texts are using the prefix marker string defined by the module variable APP_STATE_HELP_ID_PREFIX, followed by the name of the app state and are composed via the method id_of_state_help().

pluralize-able help texts

each message id can optionally have several help texts for their pluralization. for that simply add a count item to the help_vars property of the help target widget and then define a help text for the all the possible count cases in your message text file like shown in the following example:

{
    'message_id': {
                   'zero':      "help text if {count} == 0",    # {count} will be replaced with `'0'`
                   'one':       "help text if count == 1",
                   'many':      "help text if count > 1",
                   'negative':  "help text if count < 0",
                   '':          "fallback help text if count is None",
                   },
   ...
}

the provided count value can also be included/displayed in the help text, like shown in the ‘zero’ count case of the example.

pre- and post-change help texts

to display a different help message before and after the change of the flow id or the app state define a message dict with the keys ‘’ (an empty string) and ‘after’ like shown in the following example:

{
    'message_id': {
                   '':      "help text displayed before the flow/app-state change.",
                   'after': "help text displayed after the flow/app-state change",
                   },
   ...
}

if you want to move/change the help target to another widget after a change, then use instead of ‘after’ the ‘next_help_id’ message dict key:

{
    'message_id': {
                   '':              "help text before the change",
                   'next_help_id':  "help_flow#next_flow_id",
                   },
   ...
}

in this case the help target will automatically change to the widget specified by the flow id in the ‘next_help_id’ key, if the user was tapping the second time on the first/initial help target widget.

i18n help texts

the displayed help messages related to the message id will automatically get translated into the default language of the current system/environment.

the declaration and association of message ids and their related help messages is done with the help of the namespace portion ae.i18n.

Hint

more details on these and other features of this help system, e.g. the usage of f-strings in the help texts, is documented in the doc string of the ae.i18n module.

a more complex example app demonstrating the features of this context help system can be found in the repository of the kivy lisz demo app.

app tours

the following classes provided by this portion building a solid fundament to implement tours for your app:

TourBase - abstract base class of all app tours.

TourDropdownFromButton - abstract base class for tours on dropdowns.

OnboardingTour - minimal app onboarding tour, extendable with app specific tour pages.

UserPreferencesTour - minimal user preferences dropdown tour.

app tour start and stop events

the following main app event methods get called (if they exist) in relation to the start/stop of an app tour:

on_tour_init: fired when the app tour instance got initialized and the app states backup got saved.
on_tour_start: fired after tour start() method get called; delay id configurable via tour_start_delay page data.
on_tour_exit: fired after an app tour got finished and the app states got restored to the values of the tour start. fired delayed letting UI events get processed; delay seconds configurable via the tour_exit_delay page data value.

UI-specific implementation

to complete the implementation of the app tours, the UI-specific framework has to provide a tour layout class, which is highlighting the widget explained and to display a tooltip and the tour page texts.

Hint

the TourOverlay class is a quite complete implementation of a tour layout class.

optionally for the ‘user_registration’ page of the OnboardingTour an open username editor flow has to be implemented.

Module Attributes

`CLOSE_POPUP_FLOW_ID`	flow id to close opened dropdown/popup
`APP_STATE_HELP_ID_PREFIX`	message id prefix for app state change help texts
`FLOW_HELP_ID_PREFIX`	message id prefix for flow change help texts
`TOUR_PAGE_HELP_ID_PREFIX`	message id prefix of tour page text/dict
`TOUR_START_DELAY_DEF`	default value of tour start delay in seconds
`TOUR_EXIT_DELAY_DEF`	default value of tour exit delay in seconds
`IGNORED_HELP_FLOWS`	tuple of flow ids never search/show help text for
`IGNORED_HELP_STATES`	tuple of app state names never searched help for
`REGISTERED_TOURS`	map(name: class) of all registered tour classes
`AnchorSpecType`	(see return value of `anchor_spec()`)
`ExplainedMatcherType`	single explained widget matcher type

Functions

`anchor_layout_x`(anchor_spe, layout_width, ...)	calculate x position of the layout box of an anchor.
`anchor_layout_y`(anchor_spe, layout_height, ...)	calculate y position of the layout box of an anchor.
`anchor_points`(font_size, anchor_spe)	recalculate points of the anchor triangle drawing.
`anchor_spec`(wid_x, wid_y, wid_width, ...)	calculate anchor center pos (x, y) and anchor direction to the targeted widget.
`help_id_tour_class`(help_id)	determine the tour class if passed help id has attached tour pages.
`help_sub_id`(help_id)	determine sub id (flow id, tour id or app state name) of the current/specified/passed help id.
`id_of_flow_help`(flow_id)	compose help id for specified flow id.
`id_of_state_help`(app_state_name)	compose help id for app state name/key.
`id_of_tour_help`(page_id)	compose help id for specified tour page id.
`register_tour_class`(tour_class)	register app tour class.
`tour_help_translation`(page_id)	determine help translation for the passed page id (flow id or app state name).
`tour_id_class`(tour_id)	determine the tour class of the passed tour id.
`translation_short_help_id`(help_id)	check if a help text exists for the passed help id.
`widget_page_id`(wid)	determine tour page id of passed widget.

Classes

`HelpAppBase`(**console_app_kwargs)	main app help base class.
`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.

CLOSE_POPUP_FLOW_ID = 'close_flow_popup': flow id to close opened dropdown/popup

APP_STATE_HELP_ID_PREFIX = 'help_app_state#': message id prefix for app state change help texts

FLOW_HELP_ID_PREFIX = 'help_flow#': message id prefix for flow change help texts

TOUR_PAGE_HELP_ID_PREFIX = 'tour_page#': message id prefix of tour page text/dict

TOUR_START_DELAY_DEF = 0.15: default value of tour start delay in seconds

TOUR_EXIT_DELAY_DEF = 0.45: default value of tour exit delay in seconds

IGNORED_HELP_FLOWS = ('close_flow_popup',): tuple of flow ids never search/show help text for

IGNORED_HELP_STATES = ('flow_id', 'flow_path', 'win_rectangle'): tuple of app state names never searched help for

REGISTERED_TOURS = {'AnimatedOnboardingTour': <class 'ae.kivy.tours.AnimatedOnboardingTour'>, 'OnboardingTour': <class 'ae.gui_help.OnboardingTour'>, 'SideloadingMenuTour': <class 'ae.kivy_sideloading.SideloadingMenuTour'>, 'TourDropdownFromButton': <class 'ae.gui_help.TourDropdownFromButton'>, 'UserPreferencesTour': <class 'ae.gui_help.UserPreferencesTour'>}: map(name: class) of all registered tour classes

AnchorSpecType

(see return value of anchor_spec())

alias of Tuple[float, float, str]

ExplainedMatcherType

single explained widget matcher type

alias of Union[Callable[[Any], bool], str]

anchor_layout_x(anchor_spe, layout_width, win_width)[source]

calculate x position of the layout box of an anchor.

Parameters:

anchor_spe¶ (Tuple[float, float, str]) – AnchorSpecType instance (anchor_spec() return) with anchor position/direction.
layout_width¶ (float) – anchor layout width.
win_width¶ (float) – app window width.

Return type:

float

Returns:

absolute x coordinate within the app window of anchor layout.

anchor_layout_y(anchor_spe, layout_height, win_height)[source]

calculate y position of the layout box of an anchor.

Parameters:

anchor_spe¶ (Tuple[float, float, str]) – AnchorSpecType tuple with anchor position and direction.
layout_height¶ (float) – anchor layout height.
win_height¶ (float) – app window height.

Return type:

float

Returns:

absolute y coordinate in the app window of anchor layout.

anchor_points(font_size, anchor_spe)[source]

recalculate points of the anchor triangle drawing.

Parameters:

font_size¶ (float) – font_size to calculate size (radius == hypotenuse / 2) of the anchor triangle.
anchor_spe¶ (Tuple[float, float, str]) – anchor specification tuple: x/y coordinates and direction - see anchor_spec() return.

Return type:

Tuple[float, ...]

Returns:

tuple of the three x and y coordinates of the anchor triangle edges.

anchor_spec(wid_x, wid_y, wid_width, wid_height, win_width, win_height)[source]

calculate anchor center pos (x, y) and anchor direction to the targeted widget.

Parameters:

wid_x¶ (float) – absolute x coordinate in app window of targeted widget.
wid_y¶ (float) – absolute y coordinate in app window of targeted widget.
wid_width¶ (float) – width of targeted widget.
wid_height¶ (float) – height of targeted widget.
win_width¶ (float) – app window width.
win_height¶ (float) – app window height.

Return type:

Tuple[float, float, str]

Returns:

tooltip anchor specification tuple (AnchorSpecType) with the three items:

anchor_x (anchor center absolute x coordinate in window),
anchor_y (anchor center absolute y coordinate in window) and
anchor_dir (anchor direction: ‘r’=right, ‘i’=increase-y, ‘l’=left, ‘d’=decrease-y)

Note

the direction in the y-axis got named increase for higher y values and decrease for lower y values to support different coordinate systems of the GUI frameworks.

e.g. Kivy has the y-axis zero value at the bottom of the app window, whereas in enaml/Qt it is at the top.

help_id_tour_class(help_id)[source]

determine the tour class if passed help id has attached tour pages.

Parameters:: help_id¶ (str) – help id to determine the tour class from.
Return type:: Optional[Any]
Returns:: tour class of an existing tour for the passed help id or None if no associated tour exists.

help_sub_id(help_id)[source]

determine sub id (flow id, tour id or app state name) of the current/specified/passed help id.

opposite of id_of_flow_help() / id_of_state_help() / id_of_tour_help().

Parameters:: help_id¶ (str) – help id to extract the sub id from.
Return type:: str
Returns:: flow id, tour id, app state name or empty string if help id does not contain a sub id.

id_of_flow_help(flow_id)[source]

compose help id for specified flow id.

Parameters:: flow_id¶ (str) – flow id to make help id for.
Return type:: str
Returns:: help id for the specified flow id.

id_of_state_help(app_state_name)[source]

compose help id for app state name/key.

Parameters:: app_state_name¶ (str) – name of the app state variable.
Return type:: str
Returns:: help id for the specified app state.

id_of_tour_help(page_id)[source]

compose help id for specified tour page id.

Parameters:: page_id¶ (str) – tour page id to make help id for.
Return type:: str
Returns:: help id for the specified tour page.

register_tour_class(tour_class)[source]

register app tour class.

Parameters:: tour_class¶ (Type[TourBase]) – tour class to register.

tour_help_translation(page_id)[source]

determine help translation for the passed page id (flow id or app state name).

Parameters:: page_id¶ (str) – tour page id.
Return type:: Union[str, Dict[str, str], None]
Returns:: help translation text/dict (if exists) or None if translation not found.

tour_id_class(tour_id)[source]

determine the tour class of the passed tour id.

Parameters:: tour_id¶ (str) – tour/flow id to determine tour class for.
Return type:: Optional[Any]
Returns:: tour class of an existing tour for the passed tour id or None if no tour exists.

translation_short_help_id(help_id)[source]

check if a help text exists for the passed help id.

Parameters:: help_id¶ (str) – help id to check if a translation/help texts exists.
Return type:: Tuple[Union[str, Dict[str, str], None], str]
Returns:: tuple of translation text/dict (if exists) and maybe shortened help id(removed detail) or tuple of (None, help_id) if translation not found.

widget_page_id(wid)[source]

determine tour page id of passed widget.

Parameters:: wid¶ (Optional[Any]) – widget to determine tour page id from (can be None).
Return type:: str
Returns:: tour page id or empty string if widget has no page id or is None.

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: Union[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, Union[Callable[[Any], bool], str, Tuple[Union[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: Optional[int]: 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 app simulation)

backup_app_states()[source]: backup 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 last displayed tour page id.

load_page_data()[source]: load page before switching to it (and maybe reload after preparing app flow and before setup of layout).

next_page()[source]: switch to next tour page.

prev_page()[source]: switch to previous tour page.

request_auto_page_switch()[source]: initiate automatic switch to next tour page.

restore_app_states()[source]: restore app states of this app - saved via backup_app_states().

setup_app_flow()[source]: setup 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 dropdown, only close it if opening button get explained).

setup_layout()[source]: prepare layout for all tour pages - first page explains opening dropdown button.

_saved_app_states: Dict[str, Any]

auto_switch_pages: Union[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, Union[Callable[[Any], bool], str, Tuple[Union[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: Optional[int]: last tour page index (None on tour start)

class OnboardingTour(main_app)[source]

Bases: TourBase

onboarding tour for first app start.

__init__(main_app)[source]: overridden to handle onboarding tour starts since app installation.

page_idx: int: index of the current tour page (in page_ids)

setup_app_flow()[source]: overridden to open user preferences dropdown in 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).

_saved_app_states: Dict[str, Any]

auto_switch_pages: Union[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, Union[Callable[[Any], bool], str, Tuple[Union[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.

last_page_idx: Optional[int]: last tour page index (None on tour start)

class UserPreferencesTour(main_app)[source]

Bases: TourDropdownFromButton

user preferences menu tour.

__init__(main_app)[source]

auto_switch_pages: Union[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’.

_saved_app_states: Dict[str, Any]

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, Union[Callable[[Any], bool], str, Tuple[Union[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: Optional[int]: last tour page index (None on tour start)

class HelpAppBase(**console_app_kwargs)[source]

Bases: MainAppBase, ABC

main app help base class.

displayed_help_id: str = '': message id of currently explained/focused target widget in help mode

help_activator: Any = None: help mode de-/activator button widget

help_layout: Optional[Any] = None: help text container widget in active help mode else None

tour_layout: Optional[Any] = None: tour layout/overlay widget in active tour mode else None

tour_overlay_class: Optional[Type] = None: UI-framework-specific tour overlay class, set by main app subclass

_next_help_id: str = '': last app-state/flow change to show help text on help mode activation

_closing_popup_open_flow_id: str = '': flow id of just closed popup

abstract call_method_delayed(delay, callback, *args, **kwargs)[source]

delayed call of passed callable/method with args/kwargs catching and logging exceptions preventing app exit.

Parameters:

delay¶ (float) – delay in seconds before calling the callable/method specified by callback.
callback¶ (Union[Callable, str]) – either callable or name of the main app method to call.
args¶ – args passed to the callable/main-app-method to be called.
kwargs¶ – kwargs passed to the callable/main-app-method to be called.

Return type:

Any

Returns:

delayed call event object instance, providing a cancel method to allow the cancellation of the delayed call within the delay time.

abstract ensure_top_most_z_index(widget)[source]

ensure visibility of the passed widget to be the top most in the z index/order.

Parameters:: widget¶ (Any) – the popup/dropdown/container widget to be moved to the top.

abstract help_activation_toggle()[source]: button tapped event handler to switch help mode between active and inactive (also inactivating tour).

change_app_state(app_state_name, state_value, send_event=True, old_name='')[source]

change app state via change_app_state(), show help text in active help mode.

all parameters are documented in the overwritten method change_app_state().

change_flow(new_flow_id, **event_kwargs)[source]

change/switch flow id - overriding change_flow().

more detailed documentation of the parameters you find in the overwritten method change_app_state().

this method returns True if flow changed and got confirmed by a declared custom event handler (either event method or Popup class) of the app, if the help mode is not active or the calling widget is selected in active help mode, else False.

Return type:: bool

help_app_state_display(help_vars, changed=False)[source]

actualize the help layout if active, before and after the change of the app state.

Parameters:

help_vars¶ (Dict[str, Any]) –
locals (args/kwargs) of overwritten change_flow() method.
items passed to the help text formatter:
- count: optional number used to render a pluralized help text for this app state change.
changed¶ (bool) – False before change of the app state, pass True if app state got just/already changed.

Return type:

bool

Returns:

True if help mode and layout is active and found target widget is locked, else False.

help_display(help_id, help_vars, key_suffix='', must_have=False)[source]

display help text to the user in activated help mode.

Parameters:

help_id¶ (str) – help id to show help text for.
help_vars¶ (Dict[str, Any]) – variables used in the conversion of the f-string expression to a string. optional items passed to the help text formatter: * count: optional number used to render a pluralized help text. * self: target widget to show help text for.
key_suffix¶ (str) – suffix to the key used if the translation is a dict.
must_have¶ (bool) – pass True to display error help text and console output if no help text exists.

Return type:

bool

Returns:

True if help text got found and displayed.

help_flow_display(help_vars, changed=False)[source]

actualize the help layout if active, exclusively called by change_flow().

Parameters:

help_vars¶ (Dict[str, Any]) – locals (args/kwargs) of overwritten change_flow() method.
changed¶ (bool) – False before change to new flow, pass True if flow got changed already.

Return type:

bool

Returns:

True if help layout is active and found target widget is locked, else False.

help_is_inactive(help_id)[source]

check if help mode is inactive and reserve/note-down current help id for next help mode activation.

Parameters:: help_id¶ (str) – help id to be reserved for next help activation with empty help id.
Return type:: bool
Returns:: True if help mode is inactive, else False.

help_target_and_id(help_vars)[source]

find help widget/target and help id on help mode activation.

Parameters:: help_vars¶ (Dict[str, Any]) – optional help vars.
Return type:: Tuple[Any, str]
Returns:: tuple of help target widget and help id.

help_widget(help_id, help_vars)[source]

ensure/find help target widget via attribute name/value and extend help_vars.

Parameters:

help_id¶ (str) – widget.help_id attribute value to detect widget and call stack locals.
help_vars¶ (Dict[str, Any]) – help env variables, to be extended with event activation stack frame locals and a ‘self’ key with the help target widget.

Return type:

Any

Returns:

found help target widget or self.help_activator if not found.

key_press_from_framework(modifiers, key)[source]

overwritten ae.gui_app.MainAppBase method to suppress key press events in help or app tour mode.

Parameters:

modifiers¶ (str) – modifier keys.
key¶ (str) – key character.

Return type:

bool

Returns:

True if key got consumed/used else False.

on_app_started()[source]: app initialization event - the last one on app startup.

on_flow_popup_close(_flow_key, _event_kwargs)[source]

overwritten popup close handler of FlowPopup widget to reset help widget/text.

Parameters:

_flow_key¶ (str) – (unused)
_event_kwargs¶ (Dict[str, Any]) – (unused)

Return type:

bool

Returns:

always True.

save_app_states()[source]

override MainAppBase method to not overwrite app states if app tour is active.

Return type:: str

start_app_tour(tour_class=None)[source]

start new app tour, automatically cancelling a currently running app tour.

Parameters:: tour_class¶ (Optional[Type[TourBase]]) – optional tour (pages) class, default: tour of current help id or OnboardingTour.
Return type:: bool
Returns:: True if UI-framework support tours/has tour_overlay_class set and tour got started.

widget_by_page_id(page_id)[source]

determine the first (top-most) widget having the passed tour page id.

Parameters:: page_id¶ (str) – widgets tour page id from tap_flow_id/focus_flow_id/app_state_name attribute.
Return type:: Optional[Any]
Returns:: widget that has a tap_flow_id/focus_flow_id/app_state_name attribute with the value of the passed page id or None if not found.

widget_tourable_children_page_ids(parent_widget)[source]

determine all visible and tourable children widgets of the passed parent and its child container widgets.

Parameters:: parent_widget¶ (Any) – parent widget to determine all children that are tourable.
Return type:: List
Returns:: list of page ids of tourable children of the passed parent widget.