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. this is to be available in the kv language for your app (some of them are implemented exclusively in pure kv lang within the widgets.kv file of this portion):

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

• FlowButton: the class to create button instances changing the application flow.

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

• FlowInput: text input widget based on TextInput with application flow support.

• FlowPopup: 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.

• IconButton: extended FlowButton with an icon image, which can be placed relatively to the button screen coordinates.

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

• MessageShowPopup: a simple message box widget based on FlowPopup.

• OptionalButton: dynamically hideable button widget based on FlowButton.

• PopupTitleBar: a FlowButton automatically displaying long button texts with a horizontal auto-scroll (with the help of the SimpleAutoTickerBehavior).

• PopupQueryBox: a StackLayout supporting the dynamic creation of child widgets (with the help of DynamicChildrenBehavior).

• ReliefBox: a kivy.uix.boxlayout.BoxLayout providing relief decorations (with the help of the ae.kivy_relief_canvas.ReliefCanvas mixin class).

• ShortenedButton: button widget based on FlowButton, which is automatically shortening a long button text.

• StopTourButton: a simple image button with relief canvas (with the help of the ae.kivy_relief_canvas.ReliefCanvas mixin class).

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

• SwitchPageButton: simple button with relief canvas (provided by the ae.kivy_relief_canvas.ReliefCanvas mixin class) and OpenGL shader (via ShadersMixin).

• TourPageTexts: a kivy.uix.boxlayout.BoxLayout providing relief decorations (with the help of the ae.kivy_relief_canvas.ReliefCanvas mixin class) and OpenGL shader (via ShadersMixin).

• UserNameEditorPopup: a FlowPopup widget used to enter a username, to be 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 deactivation

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 showing 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. to animate help layout (see Tooltip widget) .
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 your app's main kv file

Functions

sv_children(parent)

determine ScrollView instances in the children tree of the specified parent widget.

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.
ConfirmationShowPopup(**kwargs)	flow popup to display information and/or messages to be confirmed by the user.
EmbeddingScrollView(**kwargs)	temporary ScrollView class for verbose touch down debugging.
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)	an attachable popup used for dynamic elliptic auto-spreading menus and toolbars.
FlowToggler(**kwargs)	toggle button changing flow id.
HelpLayout(**kwargs)	the help tooltip window to show contextual help text.
HelpMenu(**kwargs)	menu to allow user to de-/activate help and/or tour mode.
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.
InputShowPopup(**kwargs)	flow popup to allow the user to input a string.
MessageShowPopup(**kwargs)	flow popup to display info or error messages.
PopupQueryBox(**kwargs)	container used by FlowPopup to display dynamically created button/input widgets.
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 your app’s main kv file

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. call the method unbind() to remove the change propagation.

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 the window size changes.

relatives: list[Widget]

_pos_attributes: list[tuple[Any, str, Callable[[Widget, list[float]], Any] | None]]

_size_attributes: list[tuple[Any, str, Callable[[Widget, list[float]], Any] | None]]

_pos_callbacks: list[Callable[[Widget, list[float]], Any]]

_size_callbacks: list[Callable[[Widget, list[float]], Any]]

_bound_wid_properties: list[tuple[Widget, str, int]]

_bound_rel_properties: list[tuple[Widget, str, int]]

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

ellipse_fill_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float]

ink used to fill the Ellipse canvas instruction.

ellipse_fill_ink is a ColorProperty and defaults to the color COLOR_WHITE with an alpha of zero (to fully hide the ellipse).

ellipse_fill_pos

position (x, y) list/tuple of the Ellipse canvas instruction. specify to not use the pos of this widget.

ellipse_fill_pos is a ListProperty and defaults to an empty list.

ellipse_fill_size

size (width, height) tuple of the Ellipse canvas instruction. specify to not use the size of the widget.

ellipse_fill_size is a ListProperty and defaults to an empty list.

image_offset

offset position (delta-x, delta-y) list/tuple of the Image, relative to the pos of the widget.

image_offset is a ListProperty and defaults to [0, 0] (no offset).

image_pos

position (x, y) list/tuple of the Image. specify to not use the pos of the widget.

image_pos is a ListProperty and defaults to an empty list.

image_size

size (width, height) tuple of the Image. specify to not use the size of the widget.

image_size is a ListProperty and defaults to an empty list.

square_fill_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float]

ink used to fill the Rectangle canvas instruction.

square_fill_ink is a ColorProperty and defaults to the color COLOR_WHITE with an alpha of zero (to fully hide the square).

square_fill_pos

position (x, y) list/tuple of the Rectangle canvas instruction. specify to not use the pos of the widget.

square_fill_pos is a ListProperty and defaults to an empty list.

square_fill_size

size (width, height) tuple of the Rectangle canvas instruction. specify to not use the size of the widget.

square_fill_size is a ListProperty and defaults to an empty list.

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

icon_name

file stem name of the icon to be searched in the image app resources and if found then the image will be displayed next to the button text. if not specified then the tap_flow_id string without the flow key will be searched in the image resources as icon_name.

icon_name is a StringProperty and defaults to an empty string.

long_tap_flow_id

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

unfocus_flow_id is a StringProperty and defaults to an empty string.

tap_flow_id

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

tap_flow_id is a StringProperty and defaults to an empty string.

tap_kwargs

kwargs dict passed to event handler (change_flow) on a button tap.

tap_kwargs is a ObjectProperty and defaults to None.

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

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

content

popup main content layout 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 container/content widgets, like buttons, text inputs, sliders or the close button.

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

__init__(**kwargs)

__repr__()

added for easier debugging.

_real_dismiss(*_args)

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

dismiss(*args)

override method to prevent dismissing of any dropdown/popup while clicking on the activator widget.

Parameters:

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

close(*args)

override method to prevent dismissing of any dropdown/popup while clicking on the activator widget.

Parameters:

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

on_container(instance, value)

sync content widget and menu_items list with the 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:

boolean True value if the event got processed/used.

_reposition(*args)

ensure animated small x coordinate displacement after reposition of the attach_to-widget/popup/dropdown.

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, ReliefCanvas, 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 are showing e.g., on long press of the TextInput widget (cut/copy/paste/…) are kept unchanged - only the font_size gets 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 gets focus.

focus_flow_id is a StringProperty and defaults to an empty string.

unfocus_flow_id

flow id that will be set when this widget lost focus.

unfocus_flow_id is a StringProperty and defaults to an empty string.

auto_complete_texts: list[str]

list of autocompletion texts.

auto_complete_texts is a ListProperty and defaults to an empty list.

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

title is a ColorProperty and defaults to COLOR_LIGHT_GREY.

_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 the current text is in an autocompletion list and if yes, then remove it.

called by FlowInput kbd event handler and from the 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) – the pressed keys value string.

• modifiers (list[str]) – list of modifier keys (pressed or locked like numlock and capslock).

Return type:

bool

Returns:

boolean True if the key event gets processed/used by this method.

keyboard_on_textinput(window, text)

overridden to suppress any user input if a 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) – boolean True if this text input got focus, False on unfocusing.

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

Bases: DynamicChildrenBehavior, StackLayout

container used by FlowPopup to display dynamically created button/input widgets.

close(*args, **kwargs)

forward close/dismiss to a parent FlowPopup instance for popups_to_close-‘replace_with_data_map_popup’ refs

Parameters:

• args – forwarded arguments (providing compatible signature for DropDown/Popup/ModalView/…).

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

dismiss(*args, **kwargs)

alias method of close()

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 similar to Popup and can be used as a 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.utils.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.

open_close_duration

time in seconds for fade-in/-out animations on opening/closing of this menu.

open_close_duration is a NumericProperty and defaults to 0.3 seconds.

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.

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

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

the 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 popup handling compatibility for all GUI frameworks).

Note

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

Parameters:

• args – arguments (providing a compatible signature for DropDown/Popup/ModalView/ModalBehavior). some like ModalBehavior passing the MotionEvent of the closing touch event.

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

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

default open event handler.

on_pre_dismiss()

pre close/dismiss event handler.

on_pre_open()

pre open default event handler.

on_touch_up(touch)

touch up event handler.

Return type:

bool

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 –

  optional arguments:

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

class FlowSelector(**kwargs)

Bases: ModalBehavior, DynamicChildrenBehavior, FlowButton

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

this app flow-based menu-like popup consists of a central menu/close button with elliptic-auto-spreading menu items. the layout of the menu items gets automatically calculated. on opening this menu, the menu items get animated to spread from the center to its position. the menu layout gets calculated by the function _layout_items() and can be controlled via the widget properties item_angles, item_inclination, item_spacing and scale_radius.

any widget class can be used for the menu items of this class. in most cases you would use a button-like widget. the ShortenedButton widget can be used if the menu item caption/text is dynamic and has to be auto-shortened.

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 on the action of the previous flow id in the ae.gui.utils.flow_path: if it is empty or contains an ‘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.

item_angles

list of menu item angles relative to the menu center. will be automatically calculated/guessed if not set.

item_angles is a ListProperty. an angle of 0 degree signifies to the right. negative angles are in clock-wise direction. each angle has to be in the range between -360 and +360 degrees.

item_inclination

inclination angle of all the menu items, used to minimize menu item overlaps, especially if the menu is having wide items, that get spread to the left and right of the center menu button..

item_inclination is a NumericProperty and defaults to 9.0 degrees. this property value gets ignored if the item_angles property is specified.

item_spacing

optionally fine-tune spacing between the menu items: positive values are interpreted as y-spacing pixels, and negative values as angle between the menu items, overwriting the calculated angle.

item_spacing is a NumericProperty and defaults to 0 (inactive). this property is ignored if the item_angles property is specified.

open_close_duration

time in seconds for fade-in/-out animations on opening/closing of this menu.

open_close_duration is a NumericProperty and defaults to 0.69 seconds.

scale_radius

spread/widen factor of the radius/distance between this menu button and its menu items.

scale_radius is a NumericProperty and defaults to 1.0.

_anim_alpha

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

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

__init__(**kwargs)

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 all the items specified via the child_data_maps property, as well as the children widgets declared via the kv language.

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

dash_color

color of the dash/line drawn between the center/back menu button and each of the menu item buttons.

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

_attached_pos(widget, _pos)

_attached_size(widget, _size)

_finalize_close(*_args)

final unbinding/closing after animations are finished.

_item_moved(_anim, item, progress)

draw an animated dash/line from the menu-center to the item-center.

_layout_items(*_args)

calculate the window positions of the menu-items.

when the size of all menu items is the same, then a homogenous layout can be easily calculated by placing the menu items with the same distance and the same angle between them around the center menu button.

this method calculates the first menu item angle (start-angle), the angle direction (minus for clock-wise or plus for counter-clock-wise) and the angle/spacing between the menu items. the calculation takes into account the sizes of the window, of the menu center and of the menu items.

given a default tilt angle of 9 degrees (item_inclination), the (start-angle direction menu-item-angle) for the 9 block regions 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

to shortcut/prevent the automatic calculation of the menu item angles, specify the absolute angles in the list property attribute item_angles.

the calculated start and menu angle could result in ugly in the corner regions, and if the sizes of the menu items differ or are wide. in this case use/set the attributes item_spacing and scale_radius to fine-tune the vertical and horizontal spacing/padding between the menu items.

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

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

close(*_args, **kwargs)

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

Note

prevents close/dismiss of any dropdown/popup while clicking on the 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 the 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()

default dismiss/close event handler.

Return type:

Optional[bool]

Returns:

return True to prevent/cancel the dismiss/close.

on_open()

the default event handler when the selector menu items got displayed.

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 (also called opener).

• kwargs (dict[str, Any]) –

  optional arguments:

  • ’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)

check if touch is inside 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:

boolean True if this menu and its items process a touch event at the touch position specified by the pos argument.

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 a long tap event

tap_flow_id

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

tap_kwargs

kwargs dict passed to event handler (change_flow) on a button tap

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

Bases: FlowPopup

flow popup to display information and/or messages to be confirmed by the user.

message

popup window message text to display

title

popup window title text to display

confirm_flow_id

tap_flow_id of the confirmation button

confirm_kwargs

tap_kwargs dict of the confirmation button

confirm_text

confirm button text

class InputShowPopup(**kwargs)

Bases: FlowPopup

flow popup to allow the user to input a string.

message

popup window message text to display

title

popup window title text to display

input_default

initial/default input string

enter_confirms

if enter key closes the popup confirming the input (default=True)

confirm_flow_id

tap_flow_id of the confirmation button

confirm_kwargs

tap_kwargs dict of the confirmation button

confirm_text

confirm button text

class MessageShowPopup(**kwargs)

Bases: FlowPopup

flow popup to display info or error messages.

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.

ani_value

animate the relief inner color and offset this tooltip window widget.

any_value is a NumericProperty with a float value in the range: 0.0 … 1.0.

tip_text

tooltip text string to display.

tip_text is a StringProperty and defaults to an empty string.

anchor_spe

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

has_tour

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

tap_thru

True if the user can tap widgets behind/covered by this tooltip (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 the toggler pseudo button.

Parameters:

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

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

Return type:

bool

Returns:

boolean True if the user touched the tap through toggler.

collide_tour_start_button(touch_x, touch_y)

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

Parameters:

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

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

Return type:

bool

Returns:

boolean True if the 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:

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

class HelpLayout(**kwargs)

Bases: Tooltip

the help tooltip window to show contextual help text.

ani_start()

start animation of this tooltip.

ani_stop()

stop animation of this tooltip.

stop_help()

stop/exit help mode, started/initiated by ae.kivy.apps.KivyMainApp.help_layout_activation().

class HelpMenu(**kwargs)

Bases: FlowSelector

menu to allow user to de-/activate help and/or tour mode.

on_dismiss()

default dismiss/close event handler.

Return type:

Optional[bool]

Returns:

return True to prevent/cancel the dismiss/close.

class HelpToggler(**kwargs)

Bases: ReliefCanvas, Image

widget to activate and deactivate the help mode.

To prevent dismissing 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 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

animate the relief inner color and offset of this button in help/tour mode.

any_value is a NumericProperty with a float value in the range: 0.0 … 1.0.

__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 dismissing of open dropdowns/popups.

Parameters:

touch (MotionEvent) – touch event.

Return type:

bool

Returns:

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

sv_children(parent)

determine ScrollView instances in the children tree of the specified parent widget.

Return type:

list[Widget]

class EmbeddingScrollView(**kwargs)

Bases: ScrollView

temporary ScrollView class for verbose touch down debugging.

on_touch_down(touch)

touch down event handler