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 the main app class, extending the abstract/generic class MainAppBase 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 MainAppBase which adds a context-sensitive help system, application status, app state variables, app state constants, application flow and generic 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`and :mod:`ae.gui 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 gets loaded).

• on_app_built (kivy.app.App.build, after the root widget gets to 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)

Functions

keyboard_command_key(win_inst, key_code)

get keyboard command key from code, encapsulating in this function to make WindowX11 compatible to WindowSDL2.

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

keyboard_command_key(win_inst, key_code)

get keyboard command key from code, encapsulating in this function to make WindowX11 compatible to WindowSDL2.

Parameters:

• win_inst (Any) – used Window instance (on linux either of WindowX11 or WindowSDL/2).

• key_code (int) – key code to get the command key string for.

Return type:

str

Returns:

command key string or empty string on X11 or if no command key was found.

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(win_inst, key_code, _scan_code, key_text, modifiers)

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

Parameters:

• win_inst (Any) – configured/used Window instance.

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

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

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

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

Return type:

bool

Returns:

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

key_release_from_kivy(win_inst, key_code, _scan_code)

key release/up event.

Return type:

bool

Returns:

return the value of the 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:

always True.

on_resume()

app resume event automatically loading the app states.

emits the on_app_resume event.

Return type:

bool

Returns:

always True.

on_start()

kivy app start event.

called after the 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: MainAppBase

Kivy application

documents_root_path: str = '.'

the root file path for app documents; for import/export

help_dropdown: Widget | None = None

instance of an opened help menu

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 the framework app instance (optionally extended by the app project).

Return type:

tuple[Optional[Callable], Optional[Callable]]

Returns:

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

_init_path_placeholders()

add Kivy-specific paths

app_env_dict()

collect run-time app environment data and settings.

Return type:

dict[str, Any]

Returns:

dict with app environment data/settings.

backup_config_resources()

backup kivy-specific config files and logs to {ado}<now_str>.

Return type:

str

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.

call_method_repeatedly(interval, callback, *args, **kwargs)

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

Parameters:

• interval (float) – interval in seconds between two calls of 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:

repeatedly call event object instance, providing a cancel method to allow the cancellation of the repeated call within the interval 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 as a popup (in front, as foremost widget). if the passed widget has a method named activate_modal (like, for example, the method 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).

help_layout_activation()

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_clipboard_file_delete_confirmed(file_path, _kwargs)

delete the file at the specified file path (after the user copied ‘DELETE_FILE’ into Clipboard).

Parameters:

• file_path (str) – file name to delete (with an optional path relative to the CWD).

• _kwargs (dict[str, Any]) – unused flow event kwargs.

Return type:

bool

Returns:

a boolean True value if the file could be deleted, else False.

on_clipboard_file_overwrite_confirmed(file_path, _event_kwargs)

save Clipboard content to specified, and maybe existing, file path relative to the cwd of the running app.

Parameters:

• file_path (str) – file name (with an optional path relative to the CWD).

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

Return type:

bool

Returns:

boolean True if clipboard content is not empty and could be saved to file, else False.

called from on_clipboard_file_save directly or indirectly via show_confirmation(). used to store ini or env files into the current working directory (on Android the inaccessible files/app folder within the app installation folder; prefix file path with ../app-name/ or ../ for files that have to be kept on app update).

on_clipboard_file_save(file_path, _event_kwargs)

debug event handler to check save of Clipboard content to the specified file path.

Parameters:

• file_path (str) – file name (with an optional path relative to the app cwd).

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

Return type:

bool

Returns:

the boolean True if the file path in the specified flow key is not empty, else False.

called from InputShowPopup opened from the user prefs debug menu item, declared in UserPreferencesPopup.

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 a flow key).

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

Return type:

bool

Returns:

the boolean value 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_key, _event_kwargs)

enable debug mode after clicking 3 times within 6 seconds.

Return type:

bool

Returns:

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

play_beep()

make a short beep sound.

play_sound(sound_name)

play an 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 a vibration 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:

the created and displayed/opened popup class instance.

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

quickly roughly pre-calculate the 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_by_id(widget_id, root_widget=None)

search the z-axis top/foremost widget within/underneath the specified root widget by its id.

Parameters:

• widget_id (str) – widget id string to bottom-up-search for.

• root_widget (Optional[Widget]) – widget/container to start search underneath from, else from the widget tree root/win.

Return type:

Optional[Widget]

Returns:

either the found widget or None if not found.

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.