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 ofButtonBehavior
.
help behaviour mixin
to show a 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.
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
.
Module Attributes
very short/~0.3s vibrate pattern for button and toggler touch. |
Classes
behaviour mixin class for widgets providing help texts. |
|
mix-in to allow close on Escape/Back key and to optionally provide a modal mode to a container widget. |
|
|
quickly navigate in sub-/menus, starting with a long touch, then slide to the menu item to select and release. |
|
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.
- 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 moduleae.kivy.widgets
by converting the app flow or app state of these widgets into a help id (see e.g. the implementation of the classFlowButton
).help_id
is aStringProperty
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 aBooleanProperty
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 aDictProperty
and defaults to an empty dict.
- _shader_args
shader internal data / id
- 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:
- Returns:
True if event got processed/used.
- class ModalBehavior[source]
Bases:
object
mix-in to allow close on Escape/Back key and 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[-1] 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 width: Window.width - app.main_app.help_activator.width if self.is_modal else 0 height: app.main_app.help_activator.height
- auto_dismiss
determines if the container is automatically dismissed when the user hits the Esc/Back key or clicks outside it.
auto_dismiss
is aBooleanProperty
and defaults to True.
- is_modal
flag if modal mode is active. use
activate_modal()
anddeactivate_modal()
to change this value.is_modal
is aBooleanProperty
and defaults to False.
- _align_center(*_args)[source]
reposition container to Window center.
- Parameters:
_args¶ – unused (passed only on bound window resize events)
- _on_key_down(_window, key, _scancode, _codepoint, _modifiers)[source]
close/dismiss this popup if back/Esc key get pressed - allowing stacking with DropDown/FlowDropDown.
- activate_esc_key_close()[source]
activate key press handler, calling self.close() if Escape/Back key get pressed.
- activate_modal(align_center=True)[source]
activate or renew modal mode for the mixing-in container widget.
- deactivate_esc_key_close()[source]
deactivate keyboard event handler, activated via
activate_esc_key_close()
.
- 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:
- Returns:
True if event got processed/used.
- class SlideSelectBehavior(**kwargs)[source]
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 a quicker select 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 thechange_flow()
call, e.g. by adding the following lines in your kv code onto theFlowButton
/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
, respectivelyToggleButtonBehavior
, for the touch event get grabbed properly.- on_touch_move(touch)[source]
disable long touch on mouse/finger moves.
- Parameters:
touch¶ (
MotionEvent
) – motion/touch event data.- Return type:
- Returns:
True if event got processed/used.
- on_touch_up(touch)[source]
disable long touch on mouse/finger up.
- Parameters:
touch¶ (
MotionEvent
) – motion/touch event data.- Return type:
- Returns:
True if event got processed/used.
- class TouchableBehavior(**kwargs)[source]
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 get tapped twice within short time.
- on_triple_tap:
fired with the touch-down MotionEvent instance arg when a button get tapped three times within short time.
- on_long_tap:
fired with the touch-down MotionEvent instance arg when a button get tapped more than 2.4 seconds.
- on_alt_tap:
fired with the touch-down MotionEvent instance arg when a button get either double, triple or long tapped.
Note
has to be inherited (to be in the MRO) before
ButtonBehavior
, respectivelyToggleButtonBehavior
, for the touch event get grabbed properly.- _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')
- down_shader
shader running if button is in pressed state ‘down’.
down_shader
is aDictProperty
and defaults to thefirestorm 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 aDictProperty
and defaults to theplunge wave shader
. set to None to not render a shader on button release/up.
- on_alt_tap(touch)[source]
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)[source]
double tap/click default handler.
- Parameters:
touch¶ (
MotionEvent
) – motion/touch event data with the touched widget in touch.grab_current.
- on_long_tap(touch)[source]
long tap/click default handler.
- Parameters:
touch¶ (
MotionEvent
) – motion/touch event data with the touched widget in touch.grab_current.
- on_state(_widget, _value)[source]
button pressed state changed event handler, switching between ‘normal’ and ‘down’ state shader.
- on_touch_down(touch)[source]
add sound, vibration and animation, check if tour is running and additional double/triple/alt touch events.
- Parameters:
touch¶ (
MotionEvent
) – motion/touch event data.- Return type:
- Returns:
True if event got processed/used.
- on_touch_move(touch)[source]
disable long touch on mouse/finger moves.
- Parameters:
touch¶ (
MotionEvent
) – motion/touch event data.- Return type:
- Returns:
True if event got processed/used.
- on_touch_up(touch)[source]
disable long touch on mouse/finger up.
- Parameters:
touch¶ (
MotionEvent
) – motion/touch event data.- Return type:
- Returns:
True if event got processed/used.
- on_triple_tap(touch)[source]
triple tap/click default handler.
- Parameters:
touch¶ (
MotionEvent
) – motion/touch event data with the touched widget in touch.grab_current.