ae.kivy_help

enhance your app with context help, user onboarding, product tours, walkthroughs and tutorials

this ae namespace portion integrates context-sensitive help, user onboarding, product tours, walkthroughs and tutorials into your kivy app.

the generic class Tooltip of this portion displays text blocks that are automatically positioned next to any widget to providing e.g. i18n context help texts or app tour/onboarding info.

ModalBehavior is a generic mix-in class that provides modal behavior to any container widget.

the mixin class HelpBehavior provided by this namespace portion extends and prepares any Kivy widget to show an individual help text for it. the HelpToggler toggle button widget switches the app’s help mode on and off.

the other classes of this portion are used to overlay or augment the app’s user interface with product tours, tutorials, walkthroughs and user onboarding/welcome features.

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 providing an app onboarding tour that covers the core features and can be easily extended with app-specific tour pages.

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

mixing-in modal behavior

to convert a container widget into a modal dialog, add the ModalBehavior mix-in class, provided by this ae namespace portion.

the following code snippet demonstrates a typical implementation:

class MyContainer(ModalBehavior, BoxLayout):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)

    def open(self):
        self.activate_modal()

    def close(self):
        self.deactivate_modal()

to activate the modal mode call the method activate_modal(). the modal mode can be deactivated by calling the deactivate_modal() method.

all touch, mouse and keyboard user interactions will be consumed or filtered after activating the modal mode. therefore it is recommended to also visually change the GUI while in the modal mode, which has to be implemented by the mixing-in container widget.

Hint

usage examples of the ModalBehavior mix-in are e.g. the classes TourOverlay and FlowPopup.

generic widget to display help and tour texts

the tooltip class Tooltip is targeting any widget by pointing with an arrow to it. the position and size of this widget gets automatically calculated from the targeted widget position and size and the tooltip text size. and if the screen/window size is not big enough then the tooltip texts get scrollable.

Hint

use cases of the class Tooltip are e.g. the help texts prepared and displayed by the method help_display() as well as the “explaining widget” tooltips in an app tour.

help behaviour mixin

to show a i18n translatable help text for a Kivy widget create either a sub-class of the widget. the following example allows to attach a help text to a Kivy Button:

from kivy.uix.button import Button
from ae.kivy_help import HelpBehavior

class ButtonWithHelpText(HelpBehavior, Button):
    ...

alternatively you can archive this via the definition of a new kv-lang rule, like shown underneath:

<ButtonWithHelpText@HelpBehavior+Button>

Note

to automatically lock and mark the widget you want to add help texts for, this mixin class has to be specified as the first inheriting class in the class or rule declaration.

help activation and de-activation

use the widget HelpToggler provided by this namespace portion in your app to toggle the active state of the help mode.

Hint

the HelpToggler is using the low-level touch events to prevent the dispatch of the Kivy events on_press, on_release and on_dismiss to allow to show help texts for opened dropdowns and popups.

animated app tours

the mix-in class AnimatedTourMixin extends any tour class inherited from TourBase with animations and glsl shaders.

the class AnimatedOnboardingTour uses AnimatedTourMixin to extend the generic app onboarding tour class OnboardingTour with animations.

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’.

kivy_help portion dependencies

although this portion depends only on the Kivy framework and the ae namespace portions ae.gui_app, ae.gui_help and ae.kivy_relief_canvas, it is recommended also include and use the portion ae.kivy_app to provide context-help-aware widgets.

this namespace portion is a requirement of the ae.kivy_app module and is tight coupled to it. so when you also include and use the ae.kivy_app for your app, then you only need to specify the ae.kivy_app portion in the requirements.txt files (of the pip package installation tool) to automatically integrate also this module. only for mobile apps built with buildozer you need also to explicitly add this ae.kivy_help portion to the requirements list in your buildozer.spec file.

Module Attributes

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

AbsolutePosSizeBinder(*widgets[, …])

propagate widget(s) pos/size changes to attributes/callback, providing absolute window coordinates.

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.

HelpBehavior()

behaviour mixin class for widgets providing help texts.

HelpToggler(**kwargs)

widget to activate and deactivate the help mode.

ModalBehavior()

mix-in making a container widget modal.

Tooltip(**kwargs)

semi-transparent and optional click-through container to display help and tour page texts.

TourOverlay(main_app[, tour_class])

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

ANI_SINE_DEEPER_REPEAT3 = <kivy.animation.Sequence object>

sine 3 x deeper repeating animation, used e.g. to animate help layout (ae.kivy_help.Tooltip)

class AbsolutePosSizeBinder(*widgets, bind_window_size=False)[source]

Bases: object

propagate widget(s) pos/size changes to attributes/callback, providing absolute window coordinates.

__init__(*widgets, bind_window_size=False)[source]

instantiate binder specifying the monitored widget(s).

Parameters
  • widgets (Widget) – widget(s) to observe changes of their pos and size properties. if specified more than one widget then the pos/size coordinates of the rectangle that is enclosing all specified widgets are propagated.

  • bind_window_size (bool) – pass True to propagate pos and size changes if window size changes.

_bind()[source]
_propagate(wid, value, attributes, callbacks)[source]
_wid_pos_changed(wid, new_pos)[source]

propagate pos property change to target attributes and subscribed observers.

Parameters
  • wid (Widget) – bound widget or a ScrollView that is embedding the bound widget, which pos changed.

  • new_pos (List[float]) – new position of the bound widget/ScrollView (unused).

_wid_size_changed(wid, new_size)[source]

propagate size property change to target attributes and subscribed observers.

Parameters
  • wid (Widget) – bound widget or a ScrollView that is embedding the bound widget, which pos changed.

  • new_size (List[float]) – new position of the bound widget/ScrollView (unused).

_rel_pos_changed(_rel, _new_pos)[source]

propagate pos property change of relative/scrollable layout/container.

Parameters
  • _rel (Widget) – relative layout or a scroll view, embedding bound widget(s), which pos changed.

  • _new_pos (list) – new position of the RelativeLayout/ScrollView (unused).

_rel_size_changed(_rel, _new_size)[source]

propagate size change of relative/scrollable layout/container.

Parameters
  • _rel (Widget) – relative layout or a scroll view, embedding bound widget(s), which size changed.

  • _new_size (list) – new size of the RelativeLayout/ScrollView (unused).

pos_to_attribute(target, attribute, converter=None)[source]

request the propagation of the changed (absolute) widget(s) position to an object attribute.

Parameters
  • target (Any) – the object which attribute will be changed on change of pos.

  • attribute (str) – the name of the attribute to assign the new/changed absolute position.

  • converter (Optional[Callable[[Widget, List[float]], Any]]) – optional pos value converter, return the finally value assigned to the attribute.

pos_to_callback(callback)[source]

bind callable to pos change event.

Parameters

callback (Callable[[Widget, List[float]], Any]) – callable to be called when pos changed with the changed widget and pos as arguments.

size_to_attribute(target, attribute, converter=None)[source]

request the propagation of the changed widget(s) size to an object attribute.

Parameters
  • target (Any) – the object which attribute will be changed on change of size.

  • attribute (str) – the name of the attribute to assign the new/changed size.

  • converter (Optional[Callable[[Widget, List[float]], Any]]) – optional pos value converter, return the finally value assigned to the attribute.

size_to_callback(callback)[source]

bind callable to size change event.

Parameters

callback (Callable[[Widget, List[float]], Any]) – callable to be called when size changed with the changed widget and size as arguments.

unbind()[source]

unbind the widget(s) of this binder instance.

Note

this instance can be destroyed after the call of this method. for new bindings create a new instance.

class ModalBehavior[source]

Bases: object

mix-in making a container widget modal.

center: List
close: Callable
collide_point: Callable
disabled: bool
fbind: Callable
funbind: Callable
auto_dismiss

determines if the container is automatically dismissed when the user hits the Esc/Back key or clicks outside it.

auto_dismiss is a BooleanProperty and defaults to True.

_fast_bound: List = []

list of arg tuples for fbind/funbind

_touch_started_inside: Optional[bool] = None

flag if touch started inside of the container widget

_window

internal flag to store main window instance if open

activate_modal()[source]

activate or renew modal mode for the mixing-in container.

_align_center(*_args)[source]

reposition container on window resize.

deactivate_modal()[source]

de-activate modal mode for the mixing-in container.

_on_key_down(_window, key, _scancode, _codepoint, _modifiers)[source]

close/dismiss this popup if back/Esc key get pressed - allowing stacking with DropDown/FlowDropDown.

on_touch_down(touch)[source]

touch down event handler, prevents the processing of a touch on the help activator widget by this popup.

Parameters

touch (MotionEvent) – motion/touch event data.

Return type

bool

Returns

True if event got processed/used.

on_touch_move(touch)[source]

touch move event handler.

on_touch_up(touch)[source]

touch up event handler.

class Tooltip(**kwargs)[source]

Bases: kivy.uix.scrollview.ScrollView

semi-transparent and optional click-through container to display help and tour page texts.

tip_text

tooltip text string to display.

tip_text is a StringProperty and defaults to an empty string.

anchor_spe

anchor pos and direction, see AnchorSpecType (read-only)

has_tour

True if a tour exists for the current app flow/help context (read-only)

tap_thru

True if user can tap widgets behind/covered by this tooltip win (read-only)

tour_start_pos

screen position of the optionally displayed tour start button (read-only)

tour_start_size

size of the optionally displayed tour start button (read-only)

__init__(**kwargs)[source]
targeted_widget

target widget to display tooltip text for (mostly a button, but could any, e.g. a layout widget).

targeted_widget is a ObjectProperty and defaults to the main app help_activator.

_actual_pos(*_args)[source]
Return type

Tuple[float, float]

collide_tap_thru_toggler(touch_x, touch_y)[source]

check if touch is on the tap thru toggler pseudo button.

Parameters
  • touch_x (float) – window x position of touch.

  • touch_y (float) – window y position of touch.

Return type

bool

Returns

True if user touched the tap through toggler.

collide_tour_start_button(touch_x, touch_y)[source]

check if touch is on the tap thru toggler pseudo button.

Parameters
  • touch_x (float) – window x position of touch.

  • touch_y (float) – window y position of touch.

Return type

bool

Returns

True if user touched the tap thru toggler.

on_size(*_args)[source]

(re-)position help_activator tooltip correctly after help text loading and layout resizing.

on_targeted_widget(*_args)[source]

targeted widget changed event handler.

Parameters

_args – change event args (unused).

on_touch_down(touch)[source]

check for additional events added by this class.

Parameters

touch (MotionEvent) – motion/touch event data.

Return type

bool

Returns

True if event got processed/used.

class HelpBehavior[source]

Bases: object

behaviour mixin class for widgets providing help texts.

help_id

unique help id of the widget.

The correct identification of each help-aware widget presuppose that the attribute help_id has a unique value for each widget instance. This is done automatically for the widgets provided by the module kivy_app by converting the app flow or app state of these widgets into a help id (see e.g. the implementation of the class FlowButton).

help_id is a StringProperty and defaults to an empty string.

help_lock

this property is True if the help mode is active and this widget is not the help target.

help_lock is a BooleanProperty and defaults to the value False.

help_vars

dict of extra data to displayed/render the help text of this widget.

The help_vars is a dict which can be used to provide extra context data to dynamically generate, translate and display individual help texts.

help_vars is a DictProperty and defaults to an empty dict.

_shader_args

shader internal data / id

collide_point: Callable
on_touch_down(touch)[source]

prevent any processing if touch is done on the help activator widget or in active help mode.

Parameters

touch (MotionEvent) – motion/touch event data.

Return type

bool

Returns

True if event got processed/used.

class HelpToggler(**kwargs)[source]

Bases: ae.kivy_relief_canvas.ReliefCanvas, kivy.uix.image.Image

widget to activate and deactivate the help mode.

To prevent the dismiss of opened popups and dropdowns at help mode activation, this singleton instance has to:

  • be registered in its __init__ to the help_activator attribute and

  • have a on_touch_down() method that is eating the activation touch event (returning True) and

  • a on_touch_down() method not passing a activation touch in all DropDown/Popup widgets.

ani_value

float value (range: 0.0 - 1.0) to animate this button in help/tour mode

__init__(**kwargs)[source]

initialize an instance of this class and also help_activator.

ani_start()[source]

start animation of this button.

ani_stop()[source]

stop animation of this button.

on_touch_down(touch)[source]

touch down event handler to toggle help mode while preventing dismiss of open dropdowns/popups.

Parameters

touch (MotionEvent) – touch event.

Return type

bool

Returns

True if touch happened on this button (and will get no further processed => eaten).

DEF_FADE_OUT_APP = 0.39

default of tour layout fade out app screen factor

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[kivy.animation.Animation, str]]

PageAnimationsType

tuple of PageAnimationType items

alias of Tuple[Tuple[str, Union[kivy.animation.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]]

ani_start_check(ani, wid)[source]

start animation if needed else skip animation start.

Parameters
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
class AnimatedTourMixin(main_app)[source]

Bases: object

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

layout: kivy.uix.widget.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[kivy.animation.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[kivy.animation.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 setup 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 an 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: ae.kivy_help.AnimatedTourMixin, ae.gui_help.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: kivy.uix.widget.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: ae.kivy_help.ModalBehavior, ae.kivy_glsl.ShadersMixin, kivy.uix.floatlayout.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.

close: Callable
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)[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.