ae.kivy.behaviors

ae.kivy.behaviors module

this module provides the following behavior classes:

• HelpBehavior extends and prepares any Kivy widget to show an individual help text for it.

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

• SlideSelectBehavior: quickly navigate in elliptically shaped sub-/menus, alternatively starting with a long touch, then slide to the menu item to select and release.

• TouchableBehavior: extends toggle-/touch-behavior of ButtonBehavior.

help behavior mixin

to show an i18n translatable help text for a Kivy widget, create a subclass of the widget and add the mixin-/behavior-class HelpBehavior. the following example is attaching a help text to the Kivy Button widget:

from kivy.uix.button import Button
from ae.kivy.widgets 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.

modal behavior mixin

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_esc_key_close()
        self.activate_modal()

    def close(self):
        self.deactivate_esc_key_close()
        self.deactivate_modal()

calling the method activate_esc_key_close() in the open method of a container class allows the user to close the popup by pressing the Escape key (or Back on Android). this optional feature can be reverted by calling the deactivate_esc_key_close() method in your close method.

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

after activating the modal mode, most of the user interactions (like touches, or mouse and keyboard events) will be consumed or filtered. 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.

Module Attributes

TOUCH_VIBRATE_PATTERN

very short/~0.3s vibrate pattern for button and toggler touch.

Functions

grab_touch(touch, widget[, exclusive, main_app])

temporal helper function to debug occasionally happening exclusive grab conflicts

Classes

HelpBehavior()	behavior mixin class for widgets providing help texts.
ModalBehavior()	mix-in to allow close on press of the Escape/Back key, to optionally provide a modal mode to a container widget.
SlideSelectBehavior(**kwargs)	quickly navigate in sub-/menus, starting with a long touch, then slide to the menu item to select and release.
TouchableBehavior(**kwargs)	touch-/toggle-button mix-in class with shaders, animations and additional events for double/triple/long touches.

TOUCH_VIBRATE_PATTERN = (0.0, 0.09, 0.09, 0.06, 0.03, 0.03)

very short/~0.3s vibrate pattern for button and toggler touch.

grab_touch(touch, widget, exclusive=False, main_app=None)

temporal helper function to debug occasionally happening exclusive grab conflicts

Return type:

bool

class HelpBehavior

Bases: object

behavior 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 ae.kivy.widgets 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)

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:

a boolean True value if the event got processed/used, else False.

class ModalBehavior

Bases: object

mix-in to allow close on press of the Escape/Back key, to optionally provide a modal mode to a container widget.

to make the container widget’s modal state more obvious, add in your container widget an overlay color with an alpha between 0.3 and 0.9, together with the following canvas instructions:

canvas:

Color:

rgba: root.my_overlay_color[:3] + [root.my_overlay_color[3] if self.is_modal else 0]

Rectangle:

size: Window.size if self.is_modal else (0, 0)

two rectangles will be needed to not overlay/fade-out the help activator button:

canvas:
    Color:
        rgba: self.my_overlay_color[:3] + [self.my_overlay_color[-1] if self.is_modal else 0]
    Rectangle:
        size:
            Window.width if self.is_modal else 0,                     Window.height - app.main_app.help_activator.height if self.is_modal else 0
    Rectangle:
        pos: app.main_app.help_activator.right, app.main_app.help_activator.y
        size:
            Window.width - app.main_app.help_activator.width if self.is_modal else 0,                     app.main_app.help_activator.height

center: list

center position of Widget

close: Callable

method to dismiss the container widget (provided by self/container-widget)

collide_point: Callable

method to detect collisions with other widgets of Widget

disabled: bool

disabled property of Widget

fbind: Callable

fast binding method of Widget

funbind: Callable

fast unbinding method of Widget

unbind_uid: Callable

the faster unbinding method of Widget

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.

is_modal

flag if modal mode is active. use activate_modal() and deactivate_modal() to change this value.

is_modal is a BooleanProperty and defaults to False.

_center_aligned: bool = False

True if self will be repositioned to the Window center

_fast_bound_center_uid: int = 0

fbind/unbind_uid of the center property (pos and size)

_touch_started_inside: bool | None = None

flag if touch started inside this widget or group

_align_center(*_args)

reposition the container to the center of the app window.

Parameters:

_args – unused (passed only on bound window resize events)

_on_key_down(_window, key, _scancode, _codepoint, _modifiers)

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

Return type:

Optional[bool]

activate_esc_key_close()

activate the key press handler, calling self.close() if Escape/Back key get pressed.

activate_modal(align_center=True)

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

Parameters:

align_center (bool) – pass False to prevent the automatic alignment of center to center on reposition or resize of self or on resize of Window.

deactivate_esc_key_close()

deactivate the keyboard event handler, activated via activate_esc_key_close().

deactivate_modal()

deactivate modal mode for the mixing-in container.

on_touch_down(touch)

a 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:

a boolean True value if the event got processed/used, else False.

on_touch_move(touch)

touch move event handler.

Return type:

bool

on_touch_up(touch)

touch up event handler.

Return type:

bool

touch_pos_is_inside(pos)

check if the touch pos is inside this widget or a group of sub-widgets.

Parameters:

pos (list[float]) – touch position (x, y) in window coordinates.

Return type:

bool

Returns:

a boolean value True if this widget or group processes a touch event at the touch position specified in the pos argument.

class SlideSelectBehavior(**kwargs)

Bases: object

quickly navigate in sub-/menus, starting with a long touch, then slide to the menu item to select and release.

the slide-select feature of this class allows quicker selections of any menu item, by opening any popup via the on_long_tap() event, then move the pointer/finger onto the menu item to select to finally release the touch. to enable this feature, specify the touch event in the touch_event key of the popup_kwargs dict in the change_flow() call, e.g., by adding the following lines in your kv code onto the FlowButton/FlowToggler that is opening the popup:

on_long_tap:
    app.main_app.change_flow(id_of_flow('open', 'my_menu'),
    **update_tap_kwargs(self, popup_kwargs=dict(touch_event=args[1])))

Note

has to be inherited (to be in the MRO) before ButtonBehavior, respectively ToggleButtonBehavior, for the touch event gets grabbed properly.

attach_to: Widget | None

close: Callable

collide_point: Callable

dispatch: Callable

to_widget: Callable

__init__(**kwargs)

set normal pressed state shader on widget initialization.

_layout_finished: bool

_opened_item: Widget | None

_touch_moved_outside: bool

static _cancel_slide_select_closer(touch)

static _cancel_slide_select_opener(touch)

_grab_and_open(touch, item, first_close, *_args)

static _ungrab_and_close(touch, popup, *_args)

on_touch_move(touch)

disable long touch on mouse/finger moves.

Parameters:

touch (MotionEvent) – motion/touch event data.

Return type:

bool

Returns:

a boolean True value if the event got processed/used.

on_touch_up(touch)

disable long touch on mouse/finger up.

Parameters:

touch (MotionEvent) – motion/touch event data.

Return type:

bool

Returns:

boolean True value if the event got processed/used.

class TouchableBehavior(**kwargs)

Bases: object

touch-/toggle-button mix-in class with shaders, animations and additional events for double/triple/long touches.

Events:

on_double_tap:

fired with the touch-down MotionEvent instance arg when a button gets tapped twice within a short time.

on_triple_tap:

fired with the touch-down MotionEvent instance arg when a button gets tapped three times within a short time.

on_long_tap:

fired with the touch-down MotionEvent instance arg when a button gets tapped more than 2.4 seconds.

on_alt_tap:

fired with the touch-down MotionEvent instance arg when a button gets either double, triple or long tapped.

Note

has to be inherited (to be in the MRO) before the class ButtonBehavior, respectively ToggleButtonBehavior, for the touch event gets grabbed properly.

add_shader: Callable

center_x: float

center_y: float

collide_point: Callable

del_shader: Callable

disabled: bool

dispatch: Callable

state: str

_touch_anim

widget-got-touched-animation

_touch_x

x pos moving in touch animation from initial touch to center pos

_touch_y

y pos moving in touch animation from initial touch to center pos

__events__ = ('on_alt_tap', 'on_double_tap', 'on_long_tap', 'on_triple_tap')

__init__(**kwargs)

set normal pressed state shader on widget initialization.

_state_shader_id: Dict[str, Any]

down_shader

shader running if button is in pressed state ‘down’.

down_shader is a DictProperty and defaults to the firestorm shader. set to None to not render the default shader on button press/down.

normal_shader

shader running if button is in pressed state ‘normal’.

normal_shader is a DictProperty and defaults to the plunge wave shader. set to None to not render a shader on button release/up.

static _cancel_long_touch_clock(touch)

Return type:

bool

on_alt_tap(touch)

default handler for alternative tap (double, triple or long tap/click).

Parameters:

touch (MotionEvent) – motion/touch event data with the touched widget in touch.grab_current.

on_double_tap(touch)

default event handler for double tap/click events.

Parameters:

touch (MotionEvent) – motion/touch event data with the touched widget in touch.grab_current.

on_down_shader(*_args)

event handler called when button down state shader changed.

on_long_tap(touch)

long tap/click default handler.

Parameters:

touch (MotionEvent) – motion/touch event data with the touched widget in touch.grab_current.

on_normal_shader(*_args)

button normal state shader changed event handler.

on_state(_widget, _value)

the button press-state-changed event handler, switching between ‘normal’ and ‘down’ state shader.

Parameters:

• _widget (Any) – button widget (is self).

• _value (str) – new state value (either ‘normal’ or ‘down’).

on_touch_down(touch)

add sound, vibration and animation, check for a running tour and additional double/triple/alt touch events.

Parameters:

touch (MotionEvent) – motion/touch event data.

Return type:

bool

Returns:

a boolean True if the event got processed/used.

on_touch_move(touch)

disable long touch on mouse/finger moves.

Parameters:

touch (MotionEvent) – motion/touch event data.

Return type:

bool

Returns:

a boolean True if the event got processed/used.

on_touch_up(touch)

disable long touch on mouse/finger up.

Parameters:

touch (MotionEvent) – motion/touch event data.

Return type:

bool

Returns:

True if the event got processed/used.

on_triple_tap(touch)

the triple tap/click default handler.

Parameters:

touch (MotionEvent) – motion/touch event data with the touched widget in touch.grab_current.

_update_shader()

update shader on changed shader or button state.