ae.kivy.tours

ae.kivy.tours module

this module provides the following classes to augment the user interface of your apps with animated product tours, tutorials, walkthroughs and user onboarding/welcome features:

• AnimatedTourMixin

• AnimatedOnboardingTour

• TourOverlay

the class TourOverlay is implementing an overlay layout widget to display the animations, shaders, tour page texts, tooltip text and the navigation buttons of an active/running app tour.

the AnimatedTourMixin can be mixed-into a tour class that inherits from TourBase to extend it with animation and GLSL shader features.

the class AnimatedOnboardingTour is based on OnboardingTour and AnimatedTourMixin to extend the generic app onboarding tour class with animations. it provides a generic app onboarding tour that covers the core features that can be easily extended with app-specific tour pages.

to integrate a more app-specific onboarding tour into your app, declare a class with a name composed by the name of your app (app_name) in camel-case, followed by the suffix ‘OnboardingTour’.

Module Attributes

PageAnimationType	tuple of a widget id string and an Animation instance/evaluation-expression.
PageAnimationsType	tuple of PageAnimationType items
WidgetValues	a key of this dict specifies the name, the dict value the value of a widget property/attribute.
DEF_FADE_OUT_APP	default of tour layout fade out app screen factor

Functions

ani_start_check(ani, wid)	start animation if needed, else skip animation start.
animated_widget_values(wid, ani)	determine from a widget the attribute/property values animated/changed by an animation.
restore_widget_values(wid, values)	restore property values of a widget.

Classes

AnimatedOnboardingTour(main_app)	onboarding tour, extended with animations and GLSL shaders.
AnimatedTourMixin(main_app)	tour class mixin to add individual shaders to the tour layout and their child widgets.
TourOverlay(main_app[, tour_class])	tour layout/view overlay singleton class to display an active/running modal app tour with optional GLSL shaders.

PageAnimationType

tuple of a widget id string and an Animation instance/evaluation-expression.

if the first character of the widget id is a @ then the repeat attribute of the Animation instance will be set to True. the rest of the widget id string specifies the widget to be animated which is either:

• one of the widgets of the TourOverlay layout class, identified by the on of the following strings: ‘next_but’, ‘page_lbl’, ‘tap_pointer’, ‘prev_but’, ‘title_lbl’, ‘tooltip’, ‘tour_page_texts’.

• the explained widget if an empty string is given.

• the TourOverlay layout class instance for any other string (e.g. ‘layout’ or ‘overlay’).

alternative to an animation instance, a evaluation string can be specified. these evaluations allow to use the following globals: Animation (also abbreviated as A), Clock, layout, sp, Window and a reference to the instance of this app tour via tour.

alias of tuple[str, Animation | str]

PageAnimationsType

tuple of PageAnimationType items

alias of tuple[tuple[str, Animation | str], …]

WidgetValues

a key of this dict specifies the name, the dict value the value of a widget property/attribute.

alias of dict[str, list | tuple | dict | float]

DEF_FADE_OUT_APP = 0.39

default of tour layout fade out app screen factor

ani_start_check(ani, wid)

start animation if needed, else skip animation start.

Parameters:

• ani (Animation) – Animation instance.

• wid (Widget) – widget to start/skip the animation for.

animated_widget_values(wid, ani)

determine from a widget the attribute/property values animated/changed by an animation.

Parameters:

• wid (Widget) – widget of which the animation property values will get retrieved.

• ani (Union[Animation, CompoundAnimation]) – Animation/kivy.animation.CompoundAnimation instance.

Return type:

dict[str, Union[list, tuple, dict, float]]

Returns:

dict with widget property names and values.

restore_widget_values(wid, values)

restore property values of a widget.

Parameters:

• wid (Widget) – widget of which the animation property values will get restored.

• values (dict[str, Union[list, tuple, dict, float]]) – attribute/property values to restore on the widget.

class AnimatedTourMixin(main_app)

Bases: object

tour class mixin to add individual shaders to the tour layout and their child widgets.

layout: Widget

main_app: Any

page_ids: list[str]

page_idx: int

setup_texts: Callable

__init__(main_app)

_added_animations: list[tuple[Widget, Animation, dict[str, list | tuple | dict | float]]]

_added_shaders: list[tuple[Widget, Dict[str, Any]]]

pages_animations: dict[str | None, tuple[tuple[str, Animation | str], ...]]

dict of compound animation instances of the pages of this tour.

the key of this dict is the page id or None (for animations available in all pages of this tour). each value of this dict is of the type PageAnimationsType.

pages_shaders: dict[str | None, tuple[tuple[str, Dict[str, Any]], ...]]

dict of widget shaders for the pages of this tour.

the key of this dict is the page id or None (for shaders available in all pages of this tour). each value of this dict is a tuple of tuples of widget id and add_shader()-kwargs.

the widget id string specifies the widget to which a shader will be added, which is either:

• one of the widgets of the TourOverlay layout class, identified by the on of the following strings: ‘next_but’, ‘page_lbl’, ‘tap_pointer’, ‘prev_but’, ‘title_lbl’, ‘tooltip’, ‘tour_page_texts’.

• the explained widget if an empty string is given.

• the TourOverlay layout class instance for any other string (e.g. ‘layout’ or ‘overlay’).

before the add_shader()-kwargs dict will be passed to the add_shader() method, all their non-string values, specifying as strings, will be evaluated/converted automatically. the evaluation provides the following globals: layout, sp, Clock, Window and the tour instance.

switch_next_animations: dict[str | None, tuple[tuple[str, Animation | str], ...]]

dict of compound animation instances for the next page switch transition of the pages of this tour.

the key of this dict is the page id or None (for animations available in all pages of this tour). each value of this dict is of the type PageAnimationsType.

_add_animations(animations)

add animations to the tour page currently displayed in the tour layout/overlay.

Parameters:

animations (tuple[tuple[str, Union[Animation, str]], ...]) – tuple of 2-element-tuples having widget id and animation instance/evaluation-string.

Returns:

length of the longest animation added (in seconds).

next_page()

overridden to add demo animations before/on switch to the next tour page.

setup_explained_widget()

overridden to bind pos/size of explained widget(s) to the tour layout/overlay placeholder.

Return type:

list

Returns:

list of explained widget instances.

setup_page_shaders_and_animations()

set up shaders and animations of the current page.

specified in pages_shaders and pages_animations.

setup_layout()

overridden to set up animations and shaders of the current tour page.

simulate_text_input(text_input, text_to_delay, text_to_insert='', deltas=(1.8, 0.6, 0.3))

simulate the typing of texts by a user entered into an explained TextInput widget of a tour page.

Parameters:

• text_input (TextInput) – text input widget, either of type TextInput or FlowInput.

• text_to_delay (str) – text string to be inserted delayed by the seconds specified in deltas[0].

• text_to_insert (str) – text string to be inserted directly into the passed text input widget.

• deltas (tuple[float, ...]) – delay deltas in seconds between each character to simulate text inputted by a user. the first delta default is a bit higher to finish navigation button y-pos-animation.

tap_animation(wid_id='', pos_delay=2.34, press_delay=0.69, release_delay=0.39)

create a compound animation instance simulating a user touch/tap on the specified widget.

Parameters:

• wid_id (str) – specifies the widget to be tap simulated: either a widget id string (first item of the PageAnimationType tuple), or (if prefixed with a column character) tap/focus/ state id of a widget, or an empty string (specifies the currently explained widget).

• pos_delay (float) – time in seconds to position/move the pointer from the next button to the widget.

• press_delay (float) – time in seconds of the button press simulation animation.

• release_delay (float) – time in seconds of the button release simulation animation.

Return type:

tuple[str, Union[Animation, str]]

Returns:

compound animation instance simulating a tap.

Note

use as animation evaluation expression to get the widget values on setup-time of the page (not tour).

teardown_shaders_and_animations()

tear down all added shaders and animations of the current tour page (including switch next page ani).

teardown_app_flow()

overridden to tear down the animations of the current/last-shown tour page.

class AnimatedOnboardingTour(main_app)

Bases: AnimatedTourMixin, OnboardingTour

onboarding tour, extended with animations and GLSL shaders.

__init__(main_app)

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

next_page()

overriding to remove the next button size animation only visible in the first tour after app re/start.

setup_layout()

overridden to update layout texts if app window/screen orientation (app.landscape) changes.

teardown_shaders_and_animations()

overridden to unbind setup_texts() on leaving the responsible_layout tour page.

class TourOverlay(main_app, tour_class=None, **kwargs)

Bases: ModalBehavior, ShadersMixin, FloatLayout

tour layout/view overlay singleton class to display an active/running modal app tour with optional GLSL shaders.

ani_value

animated float value between 0.0 and 1.0, used e.g. by AnimatedTourMixin.pages_animations.

ani_value is a NumericProperty and is read-only.

explained_pos

window position (absolute x, y window coordinates) of the targeted/explained/highlighted widget.

explained_pos is a ListProperty and is read-only.

explained_size

widget size (width, height) of the targeted/explained/highlighted widget.

explained_size is a ListProperty and is read-only.

fade_out_app

fade out app screen factor: 0.0 prevents fade out of the areas around TourPageTexts and the explained widget.

1.0 results in maximum app screen fade out. configurable for individual tour page via page_data[‘fade_out_app’].

fade_out_app is a NumericProperty and defaults to 0.39.

label_height

height in pixels of the page text labels and text lines.

label_height is a NumericProperty and is read-only.

navigation_disabled

if this flag is True then the back/next buttons in the tour layout/overlay are disabled.

navigation_disabled is a BooleanProperty and is read-only.

tour_instance

holding the TourBase instance of the current tour, initialized by start_tour().

tour_instance is a ObjectProperty and is read-only.

__init__(main_app, tour_class=None, **kwargs)

prepare app and tour overlay (singleton instance of this class) to start tour.

Parameters:

• main_app (MainAppBase) – main app instance.

• tour_class (Optional[Type[TourBase]]) – optional tour (pages) class, default: tour class of current help id or OnboardingTour.

explained_widget

explained widget instance on actual tour (page).

explained_widget is a ObjectProperty and is read-only.

next_page()

switch to the next tour page.

on_navigation_disabled(*_args)

handle the navigation button disable change event to hide page texts (blend-in-anim in page_updated()).

page_updated()

callback from setup_layout() for UI-specific patches, after tour layout/overlay setup.

prev_page()

switch to the previous tour page.

start_tour(tour_cls=None)

reset app state and prepare tour to start.

Parameters:

tour_cls (Optional[Type[TourBase]]) – optional tour (pages) class, default: tour of currently shown help id or OnboardingTour.

Return type:

bool

Returns:

a boolean True value if tour exists and got started, else False.

stop_tour()

stop tour and restore the initially backed-up app state.