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, simply 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 children 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, Union[Animation, str]]

PageAnimationsType

tuple of PageAnimationType items

alias of Tuple[Tuple[str, Union[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, Union[list, tuple, dict, float]]

DEF_FADE_OUT_APP = 0.39: default of tour layout fade out app screen factor

ani_start_check(ani, wid)[source]

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)[source]

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)[source]

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)[source]

Bases: object

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

layout: Widget

main_app: Any

page_ids: List[str]

page_idx: int

setup_texts: Callable

__init__(main_app)[source]

pages_animations: Dict[Optional[str], Tuple[Tuple[str, Union[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[Optional[str], 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[Optional[str], Tuple[Tuple[str, Union[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)[source]

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

Parameters:: animations¶ (Tuple[Tuple[str, Union[Animation, str]], ...]) – tuple of tuples of widget id and animation instance/evaluation-string.
Returns:: length of the longest animation added (in seconds).

next_page()[source]: overridden to add demo animations before/on switch to the next tour page.

setup_explained_widget()[source]

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()[source]

setup shaders and animations of the current page.

specified in pages_shaders and pages_animations.

setup_layout()[source]: 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))[source]

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. 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)[source]

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()[source]: teardown all added shaders and animations of current tour page (including switch next page animations).

teardown_app_flow()[source]: overridden to teardown the animations of the current/last-shown tour page.

class AnimatedOnboardingTour(main_app)[source]

Bases: AnimatedTourMixin, OnboardingTour

onboarding tour, extended with animations and glsl shaders.

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

next_page()[source]: overriding to remove next button size animation only visible in the first tour after app re/start.

setup_layout()[source]: overridden to update layout texts if app window/screen orientation (app.landscape) changes.

teardown_shaders_and_animations()[source]: overridden to unbind setup_texts() on leaving the responsible_layout tour page.

layout: Widget: tour overlay layout instance

main_app: Any: shortcut to main app instance

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)

_added_animations: List[Tuple[Widget, Animation, WidgetValues]]

_added_shaders: List[Tuple[Widget, ShaderIdType]]

pages_animations: Dict[Optional[str], PageAnimationsType]

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[Optional[str], Tuple[Tuple[str, ShaderIdType], ...]]

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[Optional[str], PageAnimationsType]

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.

class TourOverlay(main_app, tour_class=None, **kwargs)[source]

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.

close: Callable: method to dismiss the container widget (provided by self/container-widget)

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)[source]

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

Parameters:

main_app¶ (HelpAppBase) – 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()[source]: switch to next tour page.

on_navigation_disabled(*_args)[source]: navigation button disabled change event, used to hide page texts (blend-in-anim in page_updated()).

page_updated()[source]: callback from setup_layout() for UI-specific patches, after tour layout/overlay setup.

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

start_tour(tour_cls=None)[source]

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:: True if tour exists and got started.

stop_tour()[source]: stop tour and restore the initially backed-up app state.