ae.kivy.apps

ae.kivy.apps module

this module is providing two application classes, one of them extending the Kivy App class. the other app class is used as main app class, extending HelpAppBase with additional attributes and helper methods.

application classes

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

KivyMainApp is based on the following classes:

• the abstract base class HelpAppBase which adds context-sensitive help.

• the abstract base class MainAppBase which adds application status, app state variables, app state constants, application flow and application events.

• ConsoleApp is adding config files, config variables and config options.

• AppBase is adding application logging and application debugging.

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

kivy app config variables

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, ae.gui_app and ae.gui_help for more detailed information on all the inherited config variables, config options, config files and app state constants.

the additional config variables win_min_width and win_min_height, added by this portion, you can optionally 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_run().

more constants provided by this portion are declared in the widgets module.

kivy application events

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

• 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_start (kivy.app.App.on_start)

• on_app_started (one clock tick after on_app_start/kivy.app.App.on_start)

• on_app_pause (kivy.app.App.on_pause)

• on_app_resume (kivy.app.App.on_resume)

• on_app_stop (kivy.app.App.on_stop)

• on_app_stopped (one clock tick after on_app_stop)

Classes

FrameworkApp(main_app, **kwargs)	Kivy framework app class proxy redirecting events and callbacks to the main app class instance.
KivyMainApp(**console_app_kwargs)	Kivy application

class FrameworkApp(main_app, **kwargs)

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

init kivy app

main_app

set reference to KivyMainApp instance

build()

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)

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)

key release/up event.

Return type:

bool

Returns:

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

on_pause()

app pause event automatically saving the app states.

emits the on_app_pause event.

Return type:

bool

Returns:

True.

on_resume()

app resume event automatically loading the app states.

emits the on_app_resume event.

Return type:

bool

Returns:

True.

on_start()

kivy app start event.

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

emits the events: on_app_start and on_app_started.

on_stop()

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

resize handler updates: win_rectangle, landscape.

class KivyMainApp(**console_app_kwargs)

Bases: 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.i18n._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

Kivy main app tour overlay class

alias of TourOverlay

_debug_enable_clicks: int = 0

init_app(framework_app_class=<class 'ae.kivy.apps.FrameworkApp'>)

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

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)

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)

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)

resolve kv widgets

Return type:

Optional[Type]

static dpi_factor()

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

Return type:

float

ensure_top_most_z_index(widget)

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

Parameters:

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

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

global_variables(**patches)

overridden to add Kivy-specific globals.

Return type:

Dict[str, Any]

help_activation_toggle()

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

load_sounds()

override to preload audio sounds from app folder snd into sound file cache.

on_app_build()

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

on_app_built()

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

on_app_pause()

kivy on_pause() event handler.

on_app_resume()

kivy on_resume() event handler.

on_app_run()

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

on_app_start()

app start event handler - triggered by FrameworkApp.on_start().

on_app_started()

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

on_app_stopped()

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

on_flow_widget_focused()

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

on_kbd_input_mode_change(mode, _event_kwargs)

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

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

on_light_theme()

theme app-state-change-event-handler.

on_user_preferences_open(_flow_id, _event_kwargs)

enable debug mode after clicking 3 times within 6 seconds.

Parameters:

• _flow_id (str) – (unused).

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

Return type:

bool

Returns:

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

play_beep()

make a short beep sound.

play_sound(sound_name)

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

play vibrate pattern.

open_popup(popup_class, **popup_kwargs)

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 opener kwarg that will pass the popup opener widget to the popup.open() method; if opener gets not specified then the framework window will be used.

Return type:

Widget

Returns:

created and displayed/opened popup class instance.

text_size_guess(text, font_size=0.0, padding=(0.0, 0.0))

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

static widget_pos(wid)

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.