ae.kivy_app

main application classes and widgets for GUIApp-conform Kivy apps

this ae portion is providing additional config variables and some useful constants, various enhanced widget classes, two application classes (FrameworkApp and KivyMainApp) and a i18n wrapper (get_txt()), adding translatable f-strings to the python and kv code of your app.

kivy app constants and config variables

with the optional config variables win_min_width and win_min_height, added by this portion, you can restrict the minimum size of the kivy main window of your app. their default values are set on app startup in the method on_app_start().

more constants provided by this portion are in the constant declaration section starting with MAIN_KV_FILE_NAME.

additionally, all the config variables and app constants inherited from the base app classes are available.

Hint

please see the documentation of the namespace portions/modules ae.console and ae.gui_app for more detailed information on all the inherited config variables, config options, config files and app state constants.

enhanced widget classes

the widgets provided by this portion are based on the kivy widgets and are respecting the app state variables specifying the desired app style (dark or light) and font size. most of them also change automatically the application flow.

the following widgets provided by this portion will be registered in the kivy widget class maps by importing this module to be available for your app:

kivy app classes

the class KivyMainApp is implementing a main app class that is reducing the amount of code needed to create a Python application based on the kivy framework.

KivyMainApp is based on the following classes:

this namespace portion is also encapsulating the Kivy App class within the FrameworkApp class. this Kivy app class instance can be directly accessed from the main app class instance via the framework_app attribute.

kivy application events

this portion is firing application events additional to the ones provided by MainAppBase by redirecting events of Kivy’s App class (the Kivy event/callback-method name is given in brackets). these framework app events get fired after on_app_run() in the following order:

  • on_app_build (kivy.app.App.build, after the main kv file get loaded).

  • on_app_built (kivy.app.App.build, after the root widget get build).

  • on_app_started (kivy.app.App.on_start)

  • on_app_pause (kivy.app.App.on_pause)

  • on_app_resume (kivy.app.App.on_resume)

  • on_app_stopped (kivy.app.App.on_stop)

i18n support

translatable f-strings are provided via the helper function get_txt() and the _GetTextBinder class.

unit tests

unit tests need at least V 2.0 of OpenGL and the kivy framework installed.

Note

unit tests does have 100 % coverage but are currently not passing the gitlab CI tests because we failing in setup a proper running window system on the python image that all ae portions are using.

Module Attributes

MAIN_KV_FILE_NAME

default file name of the main kv file

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.

TOUCH_VIBRATE_PATTERN

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

get_txt(text[, count, language, loc_vars])

instantiate global i18n translation callable and language switcher helper

Classes

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)

drop down widget used for user selections from a list of items (represented by the children-widgets).

FlowInput(**kwargs)

text input/edit widget with optional autocompletion.

FlowPopup(**kwargs)

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

FlowToggler(**kwargs)

toggle button changing flow id.

FrameworkApp(main_app, **kwargs)

kivy framework app class proxy redirecting events and callbacks to the main app class instance.

ImageLabel(**kwargs)

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

KivyMainApp(**console_app_kwargs)

Kivy application

MessageShowPopup(**kwargs)

flow popup to display info or error messages.

TouchableBehavior(**kwargs)

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

MAIN_KV_FILE_NAME = 'main.kv'

default file name of the main kv file

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.

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

Bases: ae.kivy_help.HelpBehavior, kivy.uix.slider.Slider, ae.kivy_glsl.ShadersMixin

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

class ImageLabel(**kwargs)[source]

Bases: ae.kivy_relief_canvas.ReliefCanvas, kivy.uix.label.Label, ae.kivy_glsl.ShadersMixin

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.

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, respectively ToggleButtonBehavior, for the touch event get 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 from touch to center pos

_touch_y

y pos moving from touch to center pos

__events__ = ('on_alt_tap', 'on_double_tap', 'on_long_tap', 'on_triple_tap')
__init__(**kwargs)[source]

set normal pressed state shader on widget initialization.

down_shader

shader running if button is in pressed state ‘down’

normal_shader

shader running if button is in pressed state ‘normal’

static _cancel_long_touch_clock(touch)[source]
Return type

bool

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_down_shader(*_args)[source]

button down state shader changed event handler.

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_normal_shader(*_args)[source]

button normal state shader changed event handler.

on_state(_widget, _value)[source]

button pressed 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)[source]

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

Parameters

touch (MotionEvent) – motion/touch event data.

Return type

bool

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

bool

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

bool

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.

_update_shader()[source]

update shader on changed shader or button state.

class FlowButton(**kwargs)[source]

Bases: ae.kivy_help.HelpBehavior, ae.kivy_app.TouchableBehavior, kivy.uix.behaviors.button.ButtonBehavior, ae.kivy_app.ImageLabel

button to change the application flow.

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)[source]
class FlowDropDown(**kwargs)[source]

Bases: ae.kivy_auto_width.ContainerChildrenAutoWidthBehavior, ae.kivy_dyn_chi.DynamicChildrenBehavior, ae.kivy_relief_canvas.ReliefCanvas, kivy.uix.dropdown.DropDown

drop down widget used for user selections from a list of items (represented by the children-widgets).

close_kwargs

kwargs passed to all close action flow change event handlers

parent_popup_to_close

parent popup widget instance to be closed if this drop down closes

dismiss(*args)[source]

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_touch_down(touch)[source]

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

Parameters

touch (MotionEvent) – motion/touch event data.

Return type

bool

Returns

True if event got processed/used.

_reposition(*args)[source]

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

class ExtTextInputCutCopyPaste(**kwargs)[source]

Bases: kivy.uix.textinput.TextInputCutCopyPaste

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

__init__(**kwargs)[source]

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)[source]

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

Parameters
class FlowInput(**kwargs)[source]

Bases: ae.kivy_help.HelpBehavior, kivy.uix.textinput.TextInput, ae.kivy_glsl.ShadersMixin

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.

also 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. additionally the original bubble class gets 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: 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 drop down matching texts list

__init__(**kwargs)[source]
_change_selector_index(delta)[source]

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='')[source]
delete_text_from_ac(*_args)[source]

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)[source]

add non-empty text to autocompletion texts.

Parameters

_args – unused event args.

keyboard_on_key_down(window, keycode, text, modifiers)[source]

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)[source]

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

on_focus(_self, focus)[source]

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)[source]

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)[source]

put selected autocompletion text into text input and close _ac_dropdown

_show_cut_copy_paste(*args, **kwargs)[source]
class FlowPopup(**kwargs)[source]

Bases: ae.kivy_help.ModalBehavior, ae.kivy_dyn_chi.DynamicChildrenBehavior, ae.kivy_relief_canvas.ReliefCanvas, kivy.uix.boxlayout.BoxLayout

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

the scrollable container (a ScrollView instance) can only have one children, the content. use a layout as content to display multiple widgets. set content_optimal_width and/or content_optimal_height to make the popup size as small as possible, using e.g. minimum_width respectively minimum_height if the content is a layout that is providing and updating this property, or text_size_guess() if the content is a label or button widget.

Hint

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

this class is compatible to Popup and can be used as replacement, unsupported are only the following attributes of Popup and ModalView:

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 dismiss will be canceled.

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 content container (parent widget of content).

container is an ObjectProperty and is read-only.

content

popup main content, displayed in 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.

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

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)[source]
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.

add_widget(widget, index=0, canvas=None)[source]

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)[source]

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)[source]

_anim_alpha changed event handler.

on_content(_instance, value)[source]

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

on_dismiss()[source]

dismiss/close event handler.

Return type

Optional[bool]

on_open()[source]

open default event handler.

on_pre_dismiss()[source]

pre close/dismiss event handler.

on_pre_open()[source]

pre open default event handler.

open(*_args, **kwargs)[source]

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 FlowToggler(**kwargs)[source]

Bases: ae.kivy_help.HelpBehavior, ae.kivy_app.TouchableBehavior, kivy.uix.behaviors.togglebutton.ToggleButtonBehavior, ae.kivy_app.ImageLabel

toggle button changing flow id.

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)[source]
class FrameworkApp(main_app, **kwargs)[source]

Bases: kivy.app.App

kivy framework app class proxy redirecting events and callbacks to the main app class instance.

app_states

duplicate of MainAppBase app state for events/binds

button_height

default button height, dynamically calculated from font size

displayed_help_id

help id of the currently explained/help-target widget

font_color

rgba color of the font used for labels/buttons/…

help_layout

layout widget if help mode is active else None

landscape

True if app win width is bigger than the app win height

max_font_size

maximum font size in pixels bound to window size

min_font_size

minimum - ” -

mixed_back_ink

background color mixed from available back inks

tour_layout

overlay layout widget if tour is active else None

__init__(main_app, **kwargs)[source]

init kivy app

main_app

set reference to KivyMainApp instance

build()[source]

kivy build app callback.

Return type

Widget

Returns

root widget (Main instance) of this app.

key_press_from_kivy(keyboard, key_code, _scan_code, key_text, modifiers)[source]

convert and redistribute key down/press events coming from Window.on_key_down.

Parameters
  • keyboard (Any) – used keyboard.

  • key_code (int) – key code of pressed key.

  • _scan_code (int) – key scan code of pressed key.

  • key_text (Optional[str]) – key text of pressed key.

  • modifiers (List[str]) – list of modifier keys (including e.g. ‘capslock’, ‘numlock’, …)

Return type

bool

Returns

True if key event got processed used by the app, else False.

key_release_from_kivy(keyboard, key_code, _scan_code)[source]

key release/up event.

Return type

bool

Returns

return value of call to on_key_release (True if ke got processed/used).

on_pause()[source]

app pause event automatically saving the app states.

emits the on_app_pause event.

Return type

bool

Returns

True.

on_resume()[source]

app resume event automatically loading the app states.

emits the on_app_resume event.

Return type

bool

Returns

True.

on_start()[source]

kivy app start event.

called after run_app() method and on_app_start() event and after Kivy created the main layout (by calling its build() method) and has attached it to the main window.

emits the on_app_started event.

on_stop()[source]

quit app event automatically saving the app states.

emits the on_app_stopped event whereas the method stop_app() emits the on_app_stop event.

win_pos_size_change(*_)[source]

resize handler updates: win_rectangle, landscape.

class MessageShowPopup(**kwargs)[source]

Bases: ae.kivy_app.FlowPopup

flow popup to display info or error messages.

message

popup window message text to display

title

popup window title text to display

_container: Widget
class _GetTextBinder[source]

Bases: kivy._event.Observable

redirect ae.i18n.get_f_string() to an instance of this class.

kivy currently only support a single one automatic binding in kv files for all function names ending with _ (see watched_keys extension in kivy/lang/parser.py line 201; e.g. f_ would get recognized by the lang_tr re pattern, but kivy will only add the _ symbol to watched_keys and therefore f_ not gets bound.) to allow both - f-strings and simple get_text messages - this module binds ae.i18n.get_f_string() to the get_txt symbol (instead of ae.i18n.get_text()).

get_txt can be used as translation callable, but also to switch the current default language. additionally get_txt is implemented as an observer that automatically updates any translations messages of all active/visible kv rules on switch of the language at app run-time.

inspired by (see also discussion at https://github.com/kivy/kivy/issues/1664):

observers: List[Tuple[Callable, tuple, dict]] = []

list of bound observer tuples (func, args, kwargs)

_bound_uid = -1
fbind(name, func, *args, **kwargs)[source]

override fbind (fast bind) from Observable to collect and separate _ bindings.

Parameters
  • name (str) – attribute name to be bound.

  • func (Callable) – observer notification function (to be called if attribute changes).

  • args – args to be passed to the observer.

  • kwargs – kwargs to be passed to the observer.

Return type

int

Returns

unique id of this binding.

funbind(name, func, *args, **kwargs)[source]

override fast unbind.

Parameters
  • name (str) – bound attribute name.

  • func (Callable) – observer notification function (called if attribute changed).

  • args – args to be passed to the observer.

  • kwargs – kwargs to be passed to the observer.

switch_lang(lang_code)[source]

change language and update kv rules properties.

Parameters

lang_code (str) – language code to switch this app to.

__call__(text, count=None, language='', loc_vars=None, **kwargs)[source]

translate text into the current-default or the passed language.

Parameters
  • text (str) – text to translate.

  • count (Optional[int]) – optional count for pluralization.

  • language (str) – language code to translate the passed text to (def=current default language).

  • loc_vars (Optional[Dict[str, Any]]) – local variables used in the conversion of the f-string expression to a string. the count item of this dict will be overwritten by the value of the count parameter (if this argument got passed).

  • kwargs – extra kwargs (e.g. glo_vars or key_suffix - see get_f_string()).

Return type

str

Returns

translated text.

get_txt(text, count=None, language='', loc_vars=None, **kwargs) = <ae.kivy_app._GetTextBinder object>

instantiate global i18n translation callable and language switcher helper

class KivyMainApp(**console_app_kwargs)[source]

Bases: ae.gui_help.HelpAppBase

Kivy application

documents_root_path: str = '.'

root file path for app documents, e.g. for import/export

get_txt_(text, count=None, language='', loc_vars=None, **kwargs): Any = <ae.kivy_app._GetTextBinder object>

make i18n translations available via main app instance

kbd_input_mode: str = 'scale'

optional app state to set Window[Base].softinput_mode

tour_overlay_class

alias of ae.kivy_help.TourOverlay

_debug_enable_clicks: int = 0
init_app(framework_app_class=<class 'ae.kivy_app.FrameworkApp'>)[source]

initialize framework app instance and prepare app startup.

Parameters

framework_app_class (Type[FrameworkApp]) – class to create app instance (optionally extended by app project).

Return type

Tuple[Optional[Callable], Optional[Callable]]

Returns

callable to start and stop/exit the GUI event loop.

app_env_dict()[source]

collect run-time app environment data and settings.

Return type

Dict[str, Any]

Returns

dict with app environment data/settings.

call_method_delayed(delay, callback, *args, **kwargs)[source]

delayed call of passed callable/method with args/kwargs catching and logging exceptions preventing app exit.

Parameters
  • delay (float) – delay in seconds before calling the callable/method specified by callback.

  • callback (Union[Callable, str]) – either callable or name of the main app method to call.

  • args – args passed to the callable/main-app-method to be called.

  • kwargs – kwargs passed to the callable/main-app-method to be called.

Return type

Any

Returns

delayed call event (in Kivy of Type[ClockEvent]) providing a cancel method to allow the cancellation of the delayed call within the delay time.

change_light_theme(light_theme)[source]

change font and window clear/background colors to match ‘light’/’black’ themes.

Parameters

light_theme (bool) – pass True for light theme, False for black theme.

static class_by_name(class_name)[source]

resolve kv widgets

Return type

Optional[Type]

static dpi_factor()[source]

dpi scaling factor - overridden to use Kivy’s dpi scaling.

Return type

float

ensure_top_most_z_index(widget)[source]

ensure visibility of the passed widget to be the top most in the z index/order.

Parameters

widget (Widget) – widget to check and possibly correct to be the top most one.

if other dropdown/popup opened after the passed widget/layout, then only correct z index/order to show this widget/layout in front (as top-most widget). if the passed widget has a method named activate_modal (like e.g. ae.kivy_help.ModalBehavior.activate_modal()) then its activate_modal method will be called instead.

global_variables(**patches)[source]

overridden to add Kivy-specific globals.

Return type

Dict[str, Any]

help_activation_toggle()[source]

button tapped event handler to switch help mode between active and inactive (also inactivating tour).

load_sounds()[source]

override to pre-load audio sounds from app folder snd into sound file cache.

on_app_build()[source]

kivy App build event handler called at the begin of kivy.app.App.build().

on_app_built()[source]

kivy App build event handler called at the end of kivy.app.App.build().

on_app_pause()[source]

kivy on_pause() event handler.

on_app_resume()[source]

kivy on_resume() event handler.

on_app_start()[source]

app start event handler - used to set the user preference app states and initial window pos and size.

on_app_started()[source]

kivy on_start() event handler (called after on_app_build/on_app_built).

on_app_stopped()[source]

kivy on_stop() event handler (called after on_app_stop).

on_flow_widget_focused()[source]

set focus to the widget referenced by the current flow id.

on_kbd_input_mode_change(mode, _event_kwargs)[source]

language app state change event handler.

Parameters
  • mode (str) – the new softinput_mode string (passed as flow key).

  • _event_kwargs (Dict[str, Any]) – unused event kwargs.

Return type

bool

Returns

True to confirm the language change.

on_lang_code()[source]

language code app-state-change-event-handler to refresh kv rules.

on_light_theme()[source]

theme app-state-change-event-handler.

on_user_preferences_open(_flow_id, _event_kwargs)[source]

enable debug mode after clicking 3 times within 6 seconds.

Parameters
Return type

bool

Returns

False for on_flow_change() get called, opening user preferences popup.

play_beep()[source]

make a short beep sound.

play_sound(sound_name)[source]

play audio/sound file.

play_vibrate(pattern=(0.0, 0.09, 0.09, 0.18, 0.18, 0.27, 0.18, 0.36, 0.27, 0.45))[source]

play vibrate pattern.

popups_opened(classes=())[source]

determine all popup-like container widgets that are currently opened.

Parameters

classes (Tuple[Widget, …]) – optional class filter - if not passed then only the widgets underneath win/root with an open method will be yielded. pass tuple to restrict found popup widgets to certain classes. like e.g. by passing (Popup, DropDown, FlowPopup) to get all popups of an ae/Kivy app.

Return type

List[Widget]

Returns

list of opened/visible popup class instances that are children of either the root layout or the app window, ordered by their z-coordinate (most upfront widget last). overwritten because the children z-order is reversed in Kivy (topmost widget first).

open_popup(popup_class, **popup_kwargs)[source]

open Popup or DropDown using the open method. overwriting the main app class method.

Parameters
  • popup_class (Type[Union[FlowPopup, Popup, DropDown]]) – class of the Popup or DropDown widget.

  • popup_kwargs – args to be set as attributes of the popup class instance plus an optional parent kwarg that will be passed as the popup parent widget arg to the popup.open method; if parent does not get passed then the root widget/layout of self.framework_app will passed into the popup.open method as the widget argument.

Return type

Widget

Returns

created and displayed/opened popup class instance.

text_size_guess(text, font_size=0.0, padding=(0.0, 0.0))[source]

quickly roughly pre-calculate texture size of a multi-line string without rendering.

Parameters
  • text (str) – text string which can contain line feed characters.

  • font_size (float) – the font size to pseudo-render the passed text; using the value of font_size as default if not passed.

  • padding (Tuple[float, float]) – optional padding in pixels for x and y coordinate (totals for left+right/top+bottom).

Return type

Tuple[float, float]

Returns

roughly the size (width, height) to display the string passed into text. more exactly size would need to use internal render methods of Kivy, like e.g. _get_text_width() and get_extents().

widget_children(wid, only_visible=False)[source]

determine the children of widget or its container (if exists) in z-order (top-most last).

Parameters
  • wid (Any) – widget to determine the children from.

  • only_visible (bool) – pass True to only return visible widgets.

Return type

List

Returns

list of children widgets of the passed widget.

static widget_pos(wid)[source]

return widget’s window x/y position (overridden for absolute coordinates relative/scrollable layouts).

Parameters

wid – widget to determine the position of.

Return type

Tuple[float, float]

Returns

tuple of x and y screen coordinate.