ae.kivy.widgets

ae.kivy.widgets module

this module provides constants and widgets for your multi-platform apps.

the generic constants for animations and vibration patterns (mostly used on mobile platforms).

most of the widgets provided by this module are based on the widgets of the Kivy framework, extended to work with app state variables, e.g. to support app styles and theming (dark or light) and user definable font sizes. some of them also change the application flow.

by importing this module the following generic widgets will be registered in the kivy widget class factory maps, to be available in the kv language for your app:

• AppStateSlider: extended version of Slider, changing the value of app state variables.

• FlowButton: button to change the application flow.

• FlowDropDown: attachable menu-like popup, based on DropDown.

• FlowInput: dynamic kivy widget based on TextInput with application flow support.

• FlowPopup: dynamic auto-content-sizing popup to query user input or to show messages.

• FlowSelector: attachable popup used for dynamic elliptic auto-spreading menus and toolbars.

• FlowToggler: toggle button based on ImageLabel and ToggleButtonBehavior to change the application flow or any flag or application state.

• HelpToggler is a toggle button widget that switches the app’s help and tour mode on and off.

• ImageLabel: dynamic kivy widget extending the Kivy Label widget with an image.

• MessageShowPopup: simple message box widget based on FlowPopup.

• OptionalButton: dynamic kivy widget based on FlowButton which can be dynamically hidden.

• ShortenedButton: dynamic kivy widget based on FlowButton shortening the button text.

• Tooltip displays text blocks that are automatically positioned next to any widget to providing e.g. i18n context help texts or app tour/onboarding info.

• UserNameEditorPopup: popup window used e.g. to enter new user, finally registered in the app config files.

tooltip popup to display context-sensitive help and app tour texts

the tooltip popup widget class Tooltip allows you to target 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 activation and de-activation

use the widget class HelpToggler provided by this module to toggle the active state of the help mode.

Hint

the HelpToggler class 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, without closing/dismissing them.

to attach help texts to your widget instances add the behavior class HelpBehavior.

Module Attributes

ANI_SINE_DEEPER_REPEAT3	sine 3 x deeper repeating animation, used e.g.
CRITICAL_VIBRATE_PATTERN	very long/~2.4s vibrate pattern for critical error notification (sending SOS to the mobile world;)
ERROR_VIBRATE_PATTERN	long/~2s vibrate pattern for error notification.
LOVE_VIBRATE_PATTERN	short/~1.2s vibrate pattern for fun/love notification.
MAIN_KV_FILE_NAME	default file name of the main kv file of your app

Classes

AbsolutePosSizeBinder(*widgets[, ...])	propagate changes of pos/size properties of one or more widgets plus their parents to attributes/callbacks.
AppStateSlider(**kwargs)	slider widget with help text to change app state value.
ExtTextInputCutCopyPaste(**kwargs)	overwrite/extend kivy.uix.textinput.TextInputCutCopyPaste w/ translatable and autocomplete options.
FlowButton(**kwargs)	button to change the application flow.
FlowDropDown(**kwargs)	flow based widget class to implement dynamic menu-like user selections and toolbars.
FlowInput(**kwargs)	text input/edit widget with optional autocompletion.
FlowPopup(**kwargs)	popup for dynamic and auto-sizing dialogs and other top-most or modal windows.
FlowSelector(**kwargs)	attachable popup used for dynamic elliptic auto-spreading menus and toolbars.
FlowToggler(**kwargs)	toggle button changing flow id.
HelpToggler(**kwargs)	widget to activate and deactivate the help mode.
ImageLabel(**kwargs)	base label used for all labels and buttons - declared in widgets.kv and also in this module to inherit from.
MessageShowPopup(**kwargs)	flow popup to display info or error messages.
Tooltip(**kwargs)	semi-transparent and optional click-through container to display help and tour page texts.

ANI_SINE_DEEPER_REPEAT3 = <kivy.animation.Sequence object>

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

CRITICAL_VIBRATE_PATTERN = (0.0, 0.12, 0.12, 0.12, 0.12, 0.12, 0.12, 0.24, 0.12, 0.24, 0.12, 0.24, 0.12, 0.12, 0.12, 0.12, 0.12, 0.12)

very long/~2.4s vibrate pattern for critical error notification (sending SOS to the mobile world;)

ERROR_VIBRATE_PATTERN = (0.0, 0.09, 0.09, 0.18, 0.18, 0.27, 0.18, 0.36, 0.27, 0.45)

long/~2s vibrate pattern for error notification.

LOVE_VIBRATE_PATTERN = (0.0, 0.12, 0.12, 0.21, 0.03, 0.12, 0.12, 0.12)

short/~1.2s vibrate pattern for fun/love notification.

MAIN_KV_FILE_NAME = 'main.kv'

default file name of the main kv file of your app

class AbsolutePosSizeBinder(*widgets, bind_window_size=False)

Bases: object

propagate changes of pos/size properties of one or more widgets plus their parents to attributes/callbacks.

create an instance of this class passing the widget(s) to observe on change of their pos/size. then call the methods pos_to_attribute(), pos_to_callback(), size_to_attribute() and size_to_callback() to specify the propagation of the changed pos and/or size. to remove the change propagation call the method unbind().

Note

the pos attribute/callback propagations are providing absolute window coordinates.

__init__(*widgets, bind_window_size=False)

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()

_propagate(wid, value, attributes, callbacks)

_wid_pos_changed(wid, new_pos)

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)

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)

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)

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)

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, returning the final value assigned to the attribute.

pos_to_callback(callback)

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)

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, returning the final value assigned to the attribute.

size_to_callback(callback)

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()

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 AppStateSlider(**kwargs)

Bases: HelpBehavior, ShadersMixin, Slider

slider widget with help text to change app state value.

app_state_name

name of the app state to be changed by this slider value

__str__()

added for easier debugging.

on_value(*args)

value changed event handler.

Parameters:

args – tuple of instance and new value.

class HelpToggler(**kwargs)

Bases: ReliefCanvas, Image

widget to activate and deactivate the help mode.

To prevent 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 an 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)

initialize an instance of this class and also help_activator.

ani_start()

start animation of this button.

ani_stop()

stop animation of this button.

on_touch_down(touch)

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

class ImageLabel(**kwargs)

Bases: ReliefCanvas, ShadersMixin, Label

base label used for all labels and buttons - declared in widgets.kv and also in this module to inherit from.

Note

hide-able label needs extra handling, because even setting width/height to zero the text can still be visible, especially in dark mode and even with having the text-color-alpha==0. to fully hide the texture in all cases, set either the text to an empty string or the opacity to zero.

__repr__()

added for easier debugging of FlowButton and FlowToggler widgets.

class FlowButton(**kwargs)

Bases: HelpBehavior, SlideSelectBehavior, TouchableBehavior, ButtonBehavior, ImageLabel

button to change the application flow.

long_tap_flow_id

flow id that will be set when this button gets long tap event

tap_flow_id

the new flow id that will be set when this button get tapped

tap_kwargs

kwargs dict passed to event handler (change_flow) when button get tapped

__init__(**kwargs)

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_release()

overridable touch release event handler.

class FlowDropDown(**kwargs)

Bases: ContainerChildrenAutoWidthBehavior, DynamicChildrenBehavior, SlideSelectBehavior, ReliefCanvas, DropDown

flow based widget class to implement dynamic menu-like user selections and toolbars.

close_kwargs

kwargs passed to all close action flow change event handlers

content

layout container

menu_items

container/content children, like buttons, text inputs or sliders

parent_popup_to_close

parent popup widget instance to be closed if this dropdown closes

__init__(**kwargs)

__repr__()

added for easier debugging.

_real_dismiss(*_args)

overridden to ensure that return value of on_dismiss-dispatch get recognized.

dismiss(*args)

override DropDown method to prevent dismiss of any dropdown/popup while clicking on activator widget.

Parameters:

args – args to be passed to DropDown.dismiss().

close(*args)

override DropDown method to prevent dismiss of any dropdown/popup while clicking on activator widget.

Parameters:

args – args to be passed to DropDown.dismiss().

on_container(instance, value)

sync content widget and menu_items list with container widget.

Parameters:

• instance (Widget) – self.

• value (Widget) – new/changed container widget.

on_dismiss()

default dismiss/close default event handler.

Return type:

Optional[bool]

Returns:

True to prevent/cancel the dismiss/close.

on_touch_down(touch)

prevent the processing of a touch on the help activator widget by this dropdown.

Parameters:

touch (MotionEvent) – motion/touch event data.

Return type:

bool

Returns:

True if event got processed/used.

_reposition(*args)

fixing Dropdown bug - see issue #7382 and PR #7383. TODO: remove if PR gets merged and distributed.

class ExtTextInputCutCopyPaste(**kwargs)

Bases: TextInputCutCopyPaste

overwrite/extend kivy.uix.textinput.TextInputCutCopyPaste w/ translatable and autocomplete options.

__init__(**kwargs)

create Bubble instance to display the cut/copy/paste options.

the monkey patch of TextInputCutCopyPaste which was done in FlowInput._show_cut_copy_paste() has to be temporarily reset before the super() call below, to prevent endless recursion because else the other super(cls, instance) call (in python2 style within TextInputCutCopyPaste.__init__()) results in the same instance (instead of the overwritten instance).

on_parent(instance, value)

overwritten to translate BubbleButton texts and to add extra menus to add/delete ac texts.

Parameters:

• instance (Widget) – self.

• value (Widget) – kivy main window.

class FlowInput(**kwargs)

Bases: HelpBehavior, ShadersMixin, TextInput

text input/edit widget with optional autocompletion.

until version 0.1.43 of this portion the background and text color of FlowInput did automatically get switched by a change of the light_theme app state. now all colors left unchanged (before only the ones with <unchanged>):

* background_color: Window.clearcolor            # default: 1, 1, 1, 1
* cursor_color: app.font_color                   # default: 1, 0, 0, 1
* disabled_foreground_color: <unchanged>         # default: 0, 0, 0, .5
* foreground_color: app.font_color               # default: 0, 0, 0, 1
* hint_text_color: <unchanged>                   # default: 0.5, 0.5, 0.5, 1.0
* selection_color: <unchanged>                   # default: 0.1843, 0.6549, 0.8313, .5

to implement a dark background for the dark theme we would need also to change the images in the properties:

background_active, background_disabled_normal and self.background_normal.

the images/colors of the bubble that is showing e.g. on long press of the TextInput widget (cut/copy/paste/…) kept unchanged - only the font_size get adapted and the bubble button texts get translated. for that the class ExtTextInputCutCopyPaste provided by this portion inherits from the original bubble class TextInputCutCopyPaste.

the original bubble class is getting monkey patched shortly/temporarily in the moment of the instantiation to translate the bubble menu options, change the font sizes and add additional menu options to memorize/forget auto-completion texts.

focus_flow_id

flow id that will be set when this widget get focus

unfocus_flow_id

flow id that will be set when this widget lost focus

auto_complete_texts: List[str]

list of autocompletion texts

auto_complete_selector_index_ink: Union[Tuple[float, float, float], List[float], Tuple[float, float, float, float]]

color and alpha used to highlight the currently selected text of all matching autocompletion texts

_ac_dropdown: Any = None

singleton FlowDropDown instance for all TextInput instances

_matching_ac_texts: List[str] = []

one list instance for all TextInput instances is enough

_matching_ac_index: int = 0

index of selected text in the dropdown matching texts list

__init__(**kwargs)

__repr__()

added for easier debugging.

_change_selector_index(delta)

change/update/set the index of the matching texts in the opened autocompletion dropdown.

Parameters:

delta (int) – index delta value between old and new index (e.g. pass +1 to increment index). set index to zero if the old/last index was on the last item in the matching list.

_delete_ac_text(ac_text='')

delete_text_from_ac(*_args)

check if current text is in autocompletion list and if yes then remove it.

called by FlowInput kbd event handler and from menu button added by ExtTextInputCutCopyPaste.on_parent().

Parameters:

_args – unused event args.

extend_ac_with_text(*_args)

add non-empty text to autocompletion texts.

Parameters:

_args – unused event args.

keyboard_on_key_down(window, keycode, text, modifiers)

overwritten TextInput/FocusBehavior kbd event handler.

Parameters:

• window (Any) – keyboard window.

• keycode (Tuple[int, str]) – pressed key as tuple of (numeric key code, key name string).

• text (str) – pressed key value string.

• modifiers (List[str]) – list of modifier keys (pressed or locked).

Return type:

bool

Returns:

True if key event get processed/used by this method.

keyboard_on_textinput(window, text)

overridden to suppress any user input if tour is running/active.

on_focus(_self, focus)

change flow on text input change of focus.

Parameters:

• _self (Widget) – unused dup ref to self.

• focus (bool) – True if this text input got focus, False on unfocus.

on_text(_self, text)

TextInput.text change event handler.

Parameters:

• _self (Widget) – unneeded duplicate reference to TextInput/self.

• text (str) – new/current text property value.

_select_ac_text(selector)

put selected autocompletion text into text input and close _ac_dropdown

_show_cut_copy_paste(*args, **kwargs)

Show a bubble with cut copy and paste buttons

class FlowPopup(**kwargs)

Bases: ModalBehavior, DynamicChildrenBehavior, SlideSelectBehavior, ReliefCanvas, BoxLayout

popup for dynamic and auto-sizing dialogs and other top-most or modal windows.

the scrollable container (a ScrollView instance) can only have one child, referenced by the content attribute, which can be any widget (e.g. a label). use a layout for content to display multiple widgets. set optimal_content_width and/or optimal_content_height to make the popup size as small as possible, using e.g. minimum_width respectively minimum_height if content is a layout that is providing and updating this property, or text_size_guess() if it is a label or button widget.

Hint

texture_size could provide a more accurate size than text_size_guess(), but should be used with care to prevent recursive property change loops.

this class is very simular to Popup and can be used as replacement, incompatible are the following attributes of Popup and ModalView:

• background: FlowPopup has no BorderImage.

• border: FlowPopup is using a RoundedRectangle.

• title_align: is ‘center’ and could be changed via the title_bar id.

• title_color is the app.font_color.

• title_font is the default font.

• title_size is the default button height (button_height).

Events:

on_pre_open:

fired before the FlowPopup is opened and got added to the main window.

on_open:

fired when the FlowPopup is opened.

on_pre_dismiss:

fired before the FlowPopup is closed.

on_dismiss:

fired when the FlowPopup is closed. if the callback returns True, the popup will stay opened.

close_kwargs

kwargs passed to all close action flow change event handlers.

close_kwargs is a DictProperty. the default depends the action of the penultimate flow id in the ae.gui_app.flow_path: is empty or ‘enter’ dict then it defaults to an empty flow, else to an empty dict.

container: Widget

popup scrollable layout underneath the title bar and the parent of the content container.

container is an ObjectProperty and is read-only.

content

popup main content container, displayed as a child of the scrollable layout container.

content is an ObjectProperty and has to be specified either in the kv language as children or via the content kwarg.

menu_items

sequence of the content widgets and close button.

menu_items is an ObjectProperty and includes by default the content widgets as well as the close button of this popup.

optimal_content_width

width of the content to be fully displayed/visible.

optimal_content_width is a NumericProperty. if 0 or None or not explicitly set then it defaults to the main window width and - in landscape orientation - minus the side_spacing and the width needed by the query_data_maps widgets.

optimal_content_height

height of the content to be fully displayed/visible.

optimal_content_height is a NumericProperty. if 0 or None or not explicitly set then it defaults to the main window height minus the height of title and - in portrait orientation - minus the side_spacing and the height needed by the query_data_maps widgets.

parent_popup_to_close

parent popup widget instance to be closed if this popup closes.

parent_popup_to_close is a ObjectProperty and defaults to None.

query_data_maps: List[Dict[str, Any]]

list of child data dicts to instantiate the query widgets (most likely FlowButton) of this popup.

query_data_maps is a ListProperty and defaults to an empty list.

separator_height

height of the separator.

separator_height is a NumericProperty and defaults to 3sp.

side_spacing

padding in pixels from Window.width in landscape-orientation, and from Window.height in portrait-orientation.

side_spacing is a NumericProperty and defaults to 192sp.

title

title string of the popup.

title is a StringProperty and defaults to an empty string.

_anim_alpha

internal opacity/alpha for fade-in/-out animations

_anim_duration

internal time in seconds for fade-in/-out animations

_max_height

popup max height (calculated from Window/side_spacing)

_max_width

popup max width (calculated from Window/side_spacing)

__events__ = ('on_pre_open', 'on_open', 'on_pre_dismiss', 'on_dismiss')

__init__(**kwargs)

background_color

background ink tuple in the format (red, green, blue, alpha).

the background_color is a ColorProperty and defaults to clearcolor.

overlay_color

ink (color + alpha) tuple in the format (red, green, blue, alpha) used for dimming of the main window.

overlay_color is a ColorProperty and defaults to the current color value clearcolor with an alpha of 0.6 (set in __init__()).

separator_color

color used by the separator between title and the content-/container-layout.

separator_color is a ColorProperty and defaults to the current value of the font_color property.

__repr__()

added for easier debugging.

add_widget(widget, index=0, canvas=None)

add container and content widgets.

first call set container from kv rule, 2nd the content, 3rd raise error.

Parameters:

• widget (Widget) – widget instance to be added.

• index (int) – index kwarg of kivy.uix.widget.Widget().

• canvas (Optional[str]) – canvas kwarg of kivy.uix.widget.Widget().

close(*_args, **kwargs)

close/dismiss container/layout (ae.gui_app popup handling compatibility for all GUI frameworks).

Note

prevents close/dismiss of any dropdown/popup while clicking on help activator widget.

Parameters:

• _args – arguments (to have compatible signature for DropDown/Popup/ModalView widgets).

• kwargs – keyword arguments (compatible signature for DropDown/Popup/ModalView widgets).

dismiss(*_args, **kwargs)

alias method of close()

on__anim_alpha(_instance, value)

_anim_alpha changed event handler.

on_content(_instance, value)

optional single widget (to be added to the container layout) set directly or via FlowPopup kwargs.

on_dismiss()

default dismiss/close event handler.

Return type:

Optional[bool]

Returns:

return True to prevent/cancel the dismiss/close.

on_open()

open default event handler.

on_pre_dismiss()

pre close/dismiss event handler.

on_pre_open()

pre open default event handler.

open(*_args, **kwargs)

start optional open animation after calling open method if exists in inheriting container/layout widget.

Parameters:

• _args – unused argument (to have compatible signature for Popup/ModalView and DropDown widgets passing the parent widget).

• kwargs –

  extra arguments that are removed before to be passed to the inheriting open method:

  • ’animation’: False will disable the fade-in-animation (default=True).

class FlowSelector(**kwargs)

Bases: ModalBehavior, DynamicChildrenBehavior, FlowButton

attachable popup used for dynamic elliptic auto-spreading menus and toolbars.

this app flow based menu-like popup consists of a central button and animated elliptic-auto-spreading menu items.

any widget class can be used for the menu items of this class, although ShortenedButton instances are best-prepared to auto-shorten the text property.

Events:

on_pre_open:

fired before the FlowSelector is opened and got added to the main window.

on_open:

fired when the FlowSelector is opened.

on_pre_dismiss:

fired before the FlowSelector is closed.

on_dismiss:

fired when the FlowSelector is closed. if the callback returns True, the menu will stay opened.

inspired by https://github.com/kivy-garden/garden.modernmenu

attached_widget

widget from which this instance got opened.

The open() method will automatically set this property whilst close() will set it back to None.

close_kwargs

kwargs passed to all close action flow change event handlers.

close_kwargs is a DictProperty. the default depends the action of the penultimate flow id in the ae.gui_app.flow_path: is empty or ‘enter’ dict then it defaults to an empty flow, else to an empty dict.

is_open

True if the open() method of this instance got called. close() sets this value to False.

is_open is a BooleanProperty and defaults to False.

parent_popup_to_close

parent menu/popup widget instance to be closed if this menu closes.

parent_popup_to_close is a ListProperty and defaults to an empty list.

radian_offset

start/end angle offset (in radians) for the elliptically positioned items of an elliptic menu.

radian_offset is a NumericProperty and defaults to 9 degrees (as radian, respectively tau * 9.0 / 360.0).

separator_height

line width of the border of the menu-back-button and of the connectors between the menu and its items.

separator_height is a NumericProperty and defaults to 1sp.

scale_x

spread/widen factor of the menu item ellipse in x direction.

scale_x is a NumericProperty and defaults to 1.0.

scale_y

spread/widen factor of the menu item ellipse in y direction.

scale_y is a NumericProperty and defaults to 1.0.

_anim_alpha

internal opacity/alpha for fade-in/-out animations

_anim_duration

internal time in seconds for fade-in/-out animations

_creation_direction = 1.0

creation-ellipse-direction of the menu buttons/items

_start_radian = 0.0

angle of the first menu item

_item_radian = 0.0

angle of each menu item

__events__ = ('on_pre_open', 'on_open', 'on_pre_dismiss', 'on_dismiss')

__init__(**kwargs)

overlay_color

ink (color + alpha) tuple in the format (red, green, blue, alpha) used for dimming of the main window.

overlay_color is a ColorProperty and defaults to the current color value clearcolor with an alpha of 0.6 (set in __init__()).

separator_color

color used to draw the border of the menu-back-button.

separator_color is a ColorProperty and defaults to the current value of the font_color property.

container: Widget

parent widget of the menu items (for compatibility with other popups/dropdowns).

container is an ObjectProperty and is read-only.

menu_items

sequence of the menu items widgets (for compatibility with SlideSelectBehavior).

menu_items is an ListProperty and defaults to the items specified via the child_data_maps property and the kv language.

_attached_pos(widget, _pos)

_attached_size(widget, _size)

_finalize_close(*_args)

final real dismiss after animations are finished.

_item_moved(_anim, item, progress)

draw line from menu-center to animated item-center.

_layout_items(*_args)

calculate the radians/angles and positions of the menu-items.

given an offset angle of 9 degrees the (start-angle direction menu-item-angle) for the 9 block regions from top-left … center/middle … bottom-right would be:

Table 1 possibly blocked window regions

	left	center	right
top	0 -72	180+180	180 +72
middle	81-162	90+360	99+162
bottom	72 -72	180-180	108 +72

add_widget(widget, index=0, canvas=None)

manage children added via kv, python and ae.kivy_dyn_chi.DynamicChildrenBehavior.

close(*_args, **kwargs)

close/dismiss menu (ae.gui_app popup handling compatibility for all GUI frameworks).

Note

prevents close/dismiss of any dropdown/popup while clicking on help activator widget.

Parameters:

• _args – arguments (to have compatible signature for DropDown/Popup/ModalView widgets).

• kwargs – keyword arguments (compatible signature for DropDown/Popup/ModalView widgets): force: pass True to force closing, ignoring return value of dispatch(‘on_dismiss’) animation: pass False to close this menu without fade-out animation

dismiss(*_args, **kwargs)

alias method of close()

on_dismiss()

dismiss/close default event handler.

Return type:

Optional[bool]

Returns:

return True to prevent/cancel the dismiss/close.

on_open()

open default event handler.

on_pre_dismiss()

pre close/dismiss event handler.

on_pre_open()

pre open default event handler.

on_release()

touch release default event handler.

open(attach_to, **kwargs)

display flow selector menu items, with animation and as a popup in modal mode.

Parameters:

• attach_to (Widget) – the widget to which this menu gets attached to.

• kwargs (Dict[str, Any]) –

  extra arguments that are removed before to be passed to the inheriting open method:

  • ’animation’: False will disable the fade-in-animation (default=True).

remove_widget(widget)

sync self.menu_items with self.children.

touch_pos_is_inside(pos)

is touch inside of this widget or a group of sub-widgets. overwritten to also include the menu items.

Parameters:

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

Return type:

bool

Returns:

True if this menu and its items would process a touch event at pos.

class FlowToggler(**kwargs)

Bases: HelpBehavior, SlideSelectBehavior, TouchableBehavior, ToggleButtonBehavior, ImageLabel

toggle button changing flow id.

long_tap_flow_id

flow id that will be set when this button gets long tap event

tap_flow_id

the new flow id that will be set when this toggle button get released

tap_kwargs

kwargs dict passed to event handler (change_flow) when button get tapped

__init__(**kwargs)

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_release()

overridable touch release event handler.

class MessageShowPopup(**kwargs)

Bases: FlowPopup

flow popup to display info or error messages.

_container: Widget

attach_to: Optional[Widget]

_layout_finished: bool

_opened_item: Optional[Widget]

_touch_moved_outside: bool

message

popup window message text to display

title

popup window title text to display

class Tooltip(**kwargs)

Bases: 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)

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)

Return type:

Tuple[float, float]

collide_tap_thru_toggler(touch_x, touch_y)

check if touch is on the tap through 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)

check if touch is on the tap through 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.

on_size(*_args)

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

on_targeted_widget(*_args)

targeted widget changed event handler.

Parameters:

_args – change event args (unused).

on_touch_down(touch)

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.