ae.gui.app

abstract Framework-independent base class for python applications with a graphical user interface

Module Attributes

ACTIONS_EXTENDING_FLOW_PATH	flow actions that are extending the flow path.
ACTIONS_REDUCING_FLOW_PATH	flow actions that are shrinking/reducing the flow paths.
ACTIONS_CHANGING_FLOW_WITHOUT_CONFIRMATION	flow actions that are processed without the need to be confirmed.
CLOSE_POPUP_FLOW_ID	flow id to close opened dropdown/popup
IGNORED_HELP_FLOWS	tuple of flow ids never search/show help text for
IGNORED_HELP_STATES	tuple of app state names never searched help for
HIDDEN_GLOBALS	tuple of global/module variable names that are hidden in global_variables()

Classes

MainAppBase(**console_app_kwargs)

abstract base class to implement a GUIApp-conform app class

ACTIONS_EXTENDING_FLOW_PATH = ['add', 'confirm', 'edit', 'enter', 'open', 'show', 'suggest']

flow actions that are extending the flow path.

ACTIONS_REDUCING_FLOW_PATH = ['close', 'leave']

flow actions that are shrinking/reducing the flow paths.

ACTIONS_CHANGING_FLOW_WITHOUT_CONFIRMATION = ['', 'enter', 'focus', 'leave', 'suggest']

flow actions that are processed without the need to be confirmed.

CLOSE_POPUP_FLOW_ID = 'close_flow_popup'

flow id to close opened dropdown/popup

IGNORED_HELP_FLOWS = ('close_flow_popup',)

tuple of flow ids never search/show help text for

IGNORED_HELP_STATES = ('flow_id', 'flow_path', 'win_rectangle')

tuple of app state names never searched help for

HIDDEN_GLOBALS = ('ABC', 'abstractmethod', '_add_base_globals', 'Any', '__builtins__', '__cached__', 'Callable', '_d_', '__doc__', '__file__', '__loader__', 'module_globals', '__name__', 'Optional', '__package__', '__path__', '__spec__', 'Type', '__version__')

tuple of global/module variable names that are hidden in global_variables()

class MainAppBase(**console_app_kwargs)

Bases: ConsoleApp, ABC

abstract base class to implement a GUIApp-conform app class

app_state_version: int = 0

version number of the app state variables in <config>.ini

cancel_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.99, 0.09, 0.09, 0.69]

rgba color for create/add/register actions

confirm_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.09, 0.99, 0.09, 0.69]

rgba color for create/add/register actions

create_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.39, 0.99, 0.69, 0.69]

rgba color for create/add/register actions

delete_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.99, 0.69, 0.69, 0.69]

rgba color for delete/remove actions

error_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.99, 0.09, 0.39, 0.69]

rgba color for error actions

flow_id: str = ''

id of the current app flow (entered by the app user)

flow_id_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.99, 0.99, 0.69, 0.69]

rgba color for flow id / drag&drop node placeholder

flow_path_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.99, 0.99, 0.39, 0.48]

rgba color for flow_path/drag&drop item placeholder

font_size: float = 21.0

font size used toolbar and flow screens

help_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.09, 0.69, 0.99, 0.69]

rgba color to mark widgets with context-sensitive help

info_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.99, 0.99, 0.09, 0.69]

rgba color for info actions

lang_code: str = ''

user language code (e.g., ‘es’ or ‘es_ES’ for Spanish)

light_theme: bool = False

True=light theme/background, False=dark theme

read_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.09, 0.99, 0.69, 0.69]

rgba color for read actions

selected_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.69, 0.99, 0.39, 0.18]

rgba color for selected list items

sound_volume: float = 0.12

sound volume of current app (0.0=mute, 1.0=max)

theme_names: list[str] = []

list of theme names

unselected_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.39, 0.39, 0.39, 0.18]

rgba color for unselected list items

update_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.99, 0.09, 0.99, 0.69]

rgba color for edit/modify/update actions

vibration_volume: float = 0.3

vibration volume of current app (0.0=mute, 1.0=max)

warn_ink: tuple[float, float, float] | list[float] | tuple[float, float, float, float] = [0.99, 0.99, 0.09, 0.69]

rgba color for hint/warn actions

win_rectangle: tuple = (0, 0, 1920, 1080)

window coordinates (x, y, width, height)

framework_app: Any = None

app class instance of the used GUI framework

framework_win: Any = None

window instance of the used GUI framework

framework_root: Any = None

app root layout widget

space_width: float = 8.1

width of a space char in pixels; depends on font size

image_files: FilesRegister | None = None

image/icon files

sound_files: FilesRegister | None = None

sound/audio files

theme_specific_cfg_vars: set[str] = {}

config-variables that changes when the theme gets changed

displayed_help_id: str = ''

message id of currently explained/focused target widget in help mode

help_activator: Any = None

help mode de-/activator button widget

help_layout: Any | None = None

help text container widget in active help mode else None

tour_layout: Any | None = None

tour layout/overlay widget in active tour mode else None

tour_overlay_class: Type | None = None

UI-framework-specific tour overlay class, set by main app subclass

_next_help_id: str = ''

last app-state/flow change to show help text on help mode activation

_closing_popup_open_flow_id: str = ''

flow id of just closed popup

__init__(**console_app_kwargs)

create an instance of app class.

Parameters:

console_app_kwargs – kwargs to be passed to the __init__ method of ConsoleApp.

_exit_code

init by stop_app() and passed onto OS by run_app()

_last_focus_flow_id

id of the last valid focused window/widget/item/context

flow_path: list[str] = []

list of flow ids, reflecting recent user actions

_start_event_loop: Callable | None

callable to start event loop of the GUI framework

_stop_event_loop: Callable | None

callable to start event loop of the GUI framework

_init_default_theme_cfg_vars()

called from self._init_default_user_cfg_vars() to extend user config vars after/in self.__init__()

_init_default_user_cfg_vars()

init user default config variables.

override this method to add module-/app-specific config vars that can be set individually per user.

abstractmethod 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 object instance, providing a cancel method to allow the cancellation of the delayed call within the delay time.

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

abstractmethod ensure_top_most_z_index(widget)

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

Parameters:

widget (Any) – the popup/dropdown/container widget to be moved to the top.

abstractmethod help_activation_toggle()

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

abstractmethod init_app(framework_app_class=None)

initialize framework app instance and root window/layout, return GUI event loop start/stop methods.

Parameters:

framework_app_class (Any) – class to create an app instance (optionally extended by the app project).

Return type:

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

Returns:

tuple of two callable, the 1st to start and the 2nd to stop/exit the GUI event loop.

app_state_keys()

determine current config variable names/keys of the app state section APP_STATE_SECTION_NAME.

Return type:

tuple[str, ...]

Returns:

tuple of all app state item keys (config variable names).

backup_config_resources()

backup config files and image/sound/translations resources to {ado}<now_str>.

config files are collected from {ado}, {usr} or {cwd} (the first found file name only - see/sync-with ae.console.ConsoleApp.add_cfg_files()).

resources are copied from {ado} or {cwd} (only the first found resources root path).

Return type:

str

change_app_state(app_state_name, state_value, send_event=True, old_name='')

change app state and show help text in active help mode.

Parameters:

• app_state_name (str) – app state name to change.

• state_value (Any) – the new value of the app status to change.

• send_event (bool) – pass False to prevent send/call of the main_app.on_<app_state_name> event.

• old_name (str) – pass to add state to the main config file: old state name to rename/migrate or UNSET to only add a new app state variable with the name specified in app_state_name.

change_flow(new_flow_id, **event_kwargs)

try to change/switch the current flow id to the value passed in new_flow_id.

Parameters:

• new_flow_id (str) – new flow id (maybe overwritten by flow change confirmation event handlers by assigning a flow id to event_kwargs[‘flow_id’]).

• event_kwargs –

  optional args to pass additional data or info onto and from the flow change confirmation event handler.

  the following keys are currently supported/implemented by this module/portion (additional keys can be added by the modules/apps using this method):

  • changed_event_name: optional main app event method name to be called if the flow got confirmed and changed.

  • count: optional number used to render a pluralized help text for this flow change (this number gets also passed to the help text formatter by/in change_flow()).

  • edit_widget: optional widget instance for edit/input.

  • flow_id: process flow_path as specified by the new_flow_id argument, but then overwrite this flow id with this event arg value to set flow_id.

  • popup_kwargs: optional dict passed to the Popup __init__ method, like e.g., dict(opener=opener_widget_of_popup, data=…).

  • popups_to_close: optional, either the number of top/most-recent popups to close, or a tuple of popup instances to be closed. the closing is done by this method after the flow change got confirmed.

  • ’reset_last_focus_flow_id’: pass True to reset the last focus flow id, pass False or None to ignore the last focus id (and not use to set flow id) or pass a flow id string value to change the last focus flow id to the passed value.

  • tap_widget: optional tapped button widget instance (initiating this flow change).

  some of these keys get specified directly on the call of this method, e.g., via tap_kwargs or tap_kwargs, where others get added by the flow change confirmation handlers/callbacks.

Return type:

bool

Returns:

boolean True if flow got confirmed by a declared custom flow change confirmation event handler (either event method or Popup class) of the app, and if the flow changed accordingly.

returning False if the help mode is active and the calling widget is not selected.

some flow actions are handled internally independent of the return value of a custom event handler, like e.g. ‘enter’ or ‘leave’ will always extend or reduce the flow path and the action ‘focus’ will give the indexed widget the input focus (these exceptions are configurable via ACTIONS_CHANGING_FLOW_WITHOUT_CONFIRMATION).

change_observable(name, value, is_app_state=False)

change observable attribute/member/property in framework_app instance (and shadow copy in the main app).

Parameters:

• name (str) – name of the observable attribute/member or key of an observable dict property.

• value (Any) – new value of the observable.

• is_app_state (bool) – pass True for an app state observable.

static class_by_name(class_name)

search class name in framework modules as well as in app main.py to return the related class/type object.

Parameters:

class_name (str) – name of the class.

Return type:

Optional[Type]

Returns:

class object with the specified class name or UNSET if not found.

property color_attr_names: set[str]

determine the app state attribute/config-var names of all UI colors, including app-specific colors.

Returns:

set of app state attribute names of all colors, declared/configured by ae-framework+app.

static dpi_factor()

dpi scaling factor - override if the used GUI framework supports dpi scaling.

Return type:

float

close_popups(classes=(), count=-1, force=False)

close specified/all opened popups (starting with the foremost popup).

Parameters:

• classes (tuple) – optional class filter - if not passed, then only the first foremost widgets underneath the app win with an open method will be closed. pass tuple to restrict found popup widgets to certain classes. like e.g., pass (Popup, DropDown, FlowPopup) to get all popups of an app (in Kivy use Factory.WidgetClass if the widget is declared only in kv lang).

• count (int) – maximum number of popups to close (if it is negative or not specified, then all currently opened popups will be closed).

• force (bool) – pass True force the remove of popup without calling its close/dismiss method.

find_image(image_name, height=32.0, light_theme=True)

find the best fitting image in the registered img folders.

Parameters:

• image_name (str) – name of the image (file name without extension).

• height (float) – preferred height of the image/icon.

• light_theme (bool) – preferred theme (dark/light) of the image.

Return type:

Optional[RegisteredFile]

Returns:

image file object (RegisteredFile/CachedFile) if found else None.

find_sound(sound_name)

find sound by name.

Parameters:

sound_name (str) – name of the sound to search for.

Return type:

Optional[RegisteredFile]

Returns:

cached sound file object (RegisteredFile/CachedFile) if sound name was found else None.

find_widget(match, root_widget=None)

bottom-up-search the widget tree returning the first matching widget in reversed z-order (foremost first).

Parameters:

• match (Callable[[Any], bool]) – callable called with the widget as an argument, returning True if the widget matches.

• root_widget (Optional[Any]) – optional root widget to start searching from. if None, then the root of the widget tree is used.

Return type:

Optional[Any]

Returns:

the first found widget in reversed z-order (top-most widget first).

flow_path_action(flow_path=None, path_index=-1)

determine the action of the last (newest) entry in the flow_path.

Parameters:

• flow_path (Optional[list[str]]) – optional flow path to get the flow action from (default=self.flow_path).

• path_index (int) – optional index in the flow_path (default=-1).

Return type:

str

Returns:

flow action string or an empty string if the flow path is empty or the index does not exist.

global_variables(**patches)

determine generic/most-needed global variables to evaluate expressions/macros.

Parameters:

patches – dict of variable names and values to add/replace on top of generic globals.

Return type:

dict[str, Any]

Returns:

dict of global variables patched with patches.

help_app_state_display(help_vars, changed=False)

actualize the help layout if active, before and after the change of the app state.

Parameters:

• help_vars (dict[str, Any]) –

  help context args/kwargs of the change_flow() method.

  items passed to the help text formatter:

  • count: optional number used to render a pluralized help text for this app state change.

• changed (bool) – pass False before change of the app state, or True if the app state has already changed.

Return type:

bool

Returns:

boolean True if help mode and layout are active and the found target widget is locked, else False.

help_display(help_id, help_vars, key_suffix='', must_have=False)

display help text to the user in activated help mode.

Parameters:

• help_id (str) – help id to show help text for.

• help_vars (dict[str, Any]) – variables used in the conversion of the f-string expression to a string. optional items passed to the help text formatter: * count: optional number used to render a pluralized help text. * self: target widget to show help text for.

• key_suffix (str) – suffix to the key used if the translation is a dict.

• must_have (bool) – pass True to display error help text and console output if no help text exists.

Return type:

bool

Returns:

boolean True if help text got found and displayed.

help_flow_display(help_vars, changed=False)

actualize the help layout if active, exclusively called by change_flow().

Parameters:

• help_vars (dict[str, Any]) – help context args/kwargs of the change_flow() method.

• changed (bool) – pass/specify False before the change to the new flow, else pass True if the flow got changed already.

Return type:

bool

Returns:

boolean True if the help layout is active and the found target widget is locked, else False.

help_is_inactive(help_id)

check if help mode is inactive and reserve/notedown current help id for next help mode activation.

Parameters:

help_id (str) – help id to be reserved for next help activation with empty help id.

Return type:

bool

Returns:

boolean True if help mode is inactive, else False.

help_target_and_id(help_vars)

find a help widget/target and help id on help mode activation.

Parameters:

help_vars (dict[str, Any]) – optional help vars.

Return type:

tuple[Any, str]

Returns:

tuple of the help target widget and the help id.

help_widget(help_id, help_vars)

ensure/find the help target widget via attribute name/value and extend help_vars.

Parameters:

• help_id (str) – widget.help_id attribute value to detect widget and call stack locals.

• help_vars (dict[str, Any]) – help env variables to be extended with event activation stack frame locals and a ‘self’ key with the help target widget.

Return type:

Any

Returns:

the found target widget or self.help_activator if not found.

img_file(image_name, font_size=None, light_theme=None)

shortcutting find_image() method w/o bound property to get the image file path.

Parameters:

• image_name (str) – image name (file name stem).

• font_size (Optional[float]) – optional font size in pixels.

• light_theme (Optional[bool]) – optional theme (True=light, False=dark).

Return type:

str

Returns:

file path of an image file or empty string if a matching image file could not be found.

key_press_from_framework(modifiers, key)

dispatch key press event, coming normalized from the UI framework.

Parameters:

• modifiers (str) – modifier keys.

• key (str) – key character.

Return type:

bool

Returns:

boolean True if the key got consumed/used else False.

load_app_states()

prepare app.run_app by loading app states from config files and check for added/updated state vars

load_images()

load images from app folder img.

load_sounds()

load audio sounds from the app folder snd.

load_translations(lang_code)

load translation texts for the passed language code.

Parameters:

lang_code (str) – the new language code to be set (passed as flow key). empty on first app run/start.

mix_background_ink()

remix background ink if one of the basic back colors changes.

on_app_build()

default/fallback flow change confirmation event handler.

on_app_exit()

default/fallback flow change confirmation event handler.

on_app_init()

default/fallback flow change confirmation event handler.

on_app_quit()

default/fallback flow change confirmation event handler.

on_app_run()

default/fallback flow change confirmation event handler.

on_app_started()

app initialization event - the last one on app startup.

on_app_state_version_upgrade(from_version)

upgrade app state config vars from the specified app state version to the next one.

Parameters:

from_version (int) – app state version to upgrade from.

on_app_tour_toggle(_flow_key, _event_kwargs)

event handler for to start/stop an app onboarding tour.

Parameters:

• _flow_key (str) – (unused)

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

Return type:

bool

Returns:

always True.

on_debug_level_change(level_name, _event_kwargs)

debug level app state change flow change confirmation event handler.

Parameters:

• level_name (str) – the new debug level name to be set (passed as the flow key).

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

Return type:

bool

Returns:

boolean True to confirm the debug level change.

on_flow_change(flow_id, event_kwargs)

checking if exists a Popup class for the new flow and if yes, then open it.

Parameters:

• flow_id (str) – new flow id.

• event_kwargs (dict[str, Any]) – optional event kwargs; the optional item with the key popup_kwargs will be passed onto the __init__ method of the found Popup class.

Return type:

bool

Returns:

boolean True if Popup class was found and displayed.

this method is mainly used as the last fallback clicked flow change confirmation event handler of a FlowButton.

on_flow_id_ink()

redirect flow id back ink app state color change event handler to actualize mixed_back_ink.

on_flow_path_ink()

redirect flow path back ink app state color change event handler to actualize mixed_back_ink.

on_flow_popup_close(_flow_key, _event_kwargs)

default popup close handler of FlowPopup widget, updates of flow_path and resets help widget/text.

Parameters:

• _flow_key (str) – unused flow key.

• _event_kwargs (dict[str, Any]) – unused popup args.

Return type:

bool

Returns:

always returning True.

on_font_size()

app state change event handler to synchronize the MainAppBase.space_width attribute.

on_key_press(modifiers, key_code)

check key press event to be handled and processed as command/action.

Parameters:

• modifiers (str) – modifier keys.

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

Return type:

bool

Returns:

boolean True if the key press event got handled, else False.

on_lang_code_change(lang_code, _event_kwargs)

language app state change flow change confirmation event handler.

Parameters:

• lang_code (str) – the new language code to be set (passed as flow key). empty on first app run/start.

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

Return type:

bool

Returns:

boolean True to confirm the language change.

on_light_theme_change(_flow_key, event_kwargs)

app theme app state change flow change confirmation event handler.

Parameters:

• _flow_key (str) – flow key.

• event_kwargs (dict[str, Any]) – event kwargs with the key ‘light_theme’ containing True|False for light|dark theme.

Return type:

bool

Returns:

boolean True to confirm the change of the flow id.

on_selected_ink()

redirect the selected item back ink app state color change event handler to actualize mixed_back_ink.

on_theme_change(theme_id, _event_kwargs)

change app theme event handler.

Parameters:

• theme_id (str) – flow key with the id/name of the theme to switch to.

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

Return type:

bool

Returns:

on_theme_delete(theme_id, _event_kwargs)

change app theme event handler.

Parameters:

• theme_id (str) – flow key with the id/name of the theme to delete.

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

Return type:

bool

Returns:

on_theme_save(theme_id, _event_kwargs)

event handler to save app theme if not exist, or overwrite it after confirmation.

Parameters:

• theme_id (str) – flow key with the name/id of the theme to add/update.

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

Return type:

bool

Returns:

a True value if the flow got accepted/redirected and changed, else False.

on_theme_update(theme_id, _event_kwargs)

event handler to update/overwrite an existing app theme.

Parameters:

• theme_id (str) – flow key with the name/id of the theme to update.

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

Return type:

bool

Returns:

boolean True if the flow got accepted and changed, else False.

on_unselected_ink()

redirect unselected item back ink app state color change event handler to actualize mixed_back_ink.

on_user_register(user_id, event_kwargs)

called on close of UserNameEditorPopup to check user input and create/register the current os user.

Parameters:

• user_id (str) – new/old user id, passed as new_user_id kwarg to the method ConsoleApp.register_user().

• event_kwargs (dict[str, Any]) – event kwargs, plus optionally the following kwargs which will be extracted from the event kwargs and passed onto the ae.console.ConsoleApp.register_user() method: * reset_cfg_vars * set_as_default

Return type:

bool

Returns:

True if user got registered else False.

open_popup(popup_class, **popup_kwargs)

open Popup/DropDown, calling the open/show method of the instance created from the passed popup class.

Parameters:

• popup_class (Type) – class of the Popup/DropDown widget/window.

• popup_kwargs – args to instantiate and show/open the popup.

Return type:

Any

Returns:

the created and displayed/opened popup class instance.

Hint

overwrite this method if the used GUI framework is providing a different method to open a popup window or if a widget in the Popup/DropDown needs to get the input focus.

play_beep()

make a short beep sound, should be overwritten by the used GUI framework.

play_sound(sound_name)

play an audio/sound file, should be overwritten by the GUI framework.

Parameters:

sound_name (str) – name of the sound to play.

play_vibrate(pattern=(0.0, 0.09, 0.21, 0.3, 0.09, 0.09, 0.21, 0.09))

play a vibration pattern, to be overwritten by GUI-framework-specific implementation.

Parameters:

pattern (tuple) – optional tuple of pause and vibrate time sequence - use an error pattern if not passed.

popups_opened(classes=())

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

Parameters:

classes (tuple) – optional class filter - if not passed, then only the widgets underneath win/root with an open method will be added. pass tuple of popup widget classes to restrict the returned popup instances. like e.g., pass (Popup, DropDown, FlowPopup) to get all popups of an ae/Kivy app (in Kivy use Factory.WidgetClass if widget is declared only in kv lang).

Return type:

list

Returns:

list of the foremost opened/visible popup class instances (children of the app window), matching the classes or having an open method, ordered by their z-coordinate (the most front widget first).

register_user(**kwargs)

on user registration always disable app onboarding tours on app start

Parameters:

kwargs – see the ConsoleApp.register_user() method.

Return type:

bool

Returns:

see the ConsoleApp.register_user() method.

Hint

also called on the tour end, after the user has entered a valid username/id in UserNameEditorPopup and confirmed it via the FlowButton id_of_flow(‘register’, ‘user’).

retrieve_app_states()

determine the state of a running app from the main app instance and return it as dict.

Return type:

dict[str, Any]

Returns:

dict with all app states available in the config files.

run_app()

startup main and framework applications.

save_app_states()

save app state in the main config file.

Return type:

str

Returns:

empty string if app status could be saved into config files else error message.

setup_app_states(app_states, send_event=True)

put app state variables into the main app instance to prepare framework app.run_app.

Parameters:

• app_states (dict[str, Any]) – dict of the app states.

• send_event (bool) – pass False to prevent send/call of the main_app.on_<app_state_name> event.

show_confirmation(message, title='', confirm_flow_id='', confirm_kwargs=None, confirm_text='')

display a simple confirmation popup to the user, implemented by the used UI-framework.

Parameters:

• message (str) – message string to display.

• title (str) – title of confirmation box.

• confirm_flow_id (str) – tap_flow_id of the ‘confirm’ button.

• confirm_kwargs (Optional[dict[str, Any]]) – tap_kwargs event args of the ‘confirm’ button.

• confirm_text (str) – confirmation button text. if not passed, then the i18n translation of “confirm” is used.

Return type:

bool

Returns:

boolean True if the flow got accepted and changed, else False.

show_input(message, title='', input_default='', enter_confirms=True, confirm_flow_id='', confirm_kwargs=None, confirm_text='')

display a simple input box popup to the user, implemented by the used UI-framework.

Parameters:

• message (str) – prompt message to display.

• title (str) – title of input box. no title string will be displayed if not specified.

• input_default (str) – input default text. if not specified, then the input field will be empty.

• enter_confirms (bool) – pass False to disable the confirmation via pressing the enter key in the input field.

• confirm_flow_id (str) – tap_flow_id of the ‘confirm’ button. the string entered by the user will be amended as the flow key to it.

• confirm_kwargs (Optional[dict[str, Any]]) – tap_kwargs event args of the ‘confirm’ button.

• confirm_text (str) – confirmation button text. if not passed, then the i18n translation of “confirm” is used.

Return type:

bool

Returns:

boolean True value if the flow got accepted and changed, else False.

show_message(message, title='', is_error=True)

display (error) message popup to the user, implemented by the used UI-framework.

Parameters:

• message (str) – message string to display.

• title (str) – title of message box.

• is_error (bool) – pass False to not emit error tone/vibration.

Return type:

bool

Returns:

boolean True if the flow got accepted and changed, else False.

start_app_tour(tour_class=None)

start a new app tour, automatically cancelling a currently running app tour.

Parameters:

tour_class (Optional[Type[TourBase]]) – optional tour (pages) class, default: tour of current help id or OnboardingTour.

Return type:

bool

Returns:

boolean True if the UI-framework supports tours/has tour_overlay_class set and tour got started.

stop_app(exit_code=0)

quit this application.

Parameters:

exit_code (int) – optional exit code.

theme_load(theme_id)

load app theme-specific app state variables from the config file.

Parameters:

theme_id (str) – name (id string) of the theme to be loaded (overwrites main config theme variables).

theme_delete(theme_id)

delete the app theme from the main config file.

Parameters:

theme_id (str) – name (id string) of the theme to delete.

theme_save(theme_id)

save app theme-specific app state variables to the main config file.

Parameters:

theme_id (str) – name (id string) of the theme to be saved.

theme_update_names(theme_id, delete=False)

delete or update the app state list of available themes, on update sets the specified theme as the 1st item.

Parameters:

• theme_id (str) – name (id string) of the actual theme to delete/update.

• delete (bool) – pass True to remove the theme specified by theme_id from the app state list of theme names.

upgraded_config_app_state_version()

determine the app state version of an app upgrade.

Return type:

int

Returns:

value of app state variable APP_STATE_VERSION_VAR_NAME if the app got upgraded (and has a config file from a previous app installation), else 0.

widget_by_app_state_name(app_state_name)

determine the first (top-most on z-axis) widget having the passed app state name (app_state_name).

Parameters:

app_state_name (str) – app state name of the widget’s app_state_name attribute.

Return type:

Optional[Any]

Returns:

widget that has an ` app_state_name ` attribute with the passed app state name or None if not found.

widget_by_attribute(att_name, att_value, root_widget=None)

determine the first (top-most on z-axis) widget having the passed attribute name and value.

Parameters:

• att_name (str) – attribute name of the searched widget.

• att_value (str) – attribute value of the searched widget.

• root_widget (Optional[Any]) – optional root widget to start the search from, else search from the widget tree root.

Return type:

Optional[Any]

Returns:

widget that has the specified attribute with the specified value or None if not found.

widget_by_id(widget_id, root_widget=None)

determine the first (top-most on z-axis) widget identified by the passed widget_id.

Parameters:

• widget_id (str) – id of the widget to search for.

• root_widget (Optional[Any]) – optional root widget to start the search from, else search from the widget tree root.

Return type:

Optional[Any]

Returns:

widget_by_flow_id(flow_id)

determine the first (top-most on z-axis) widget having the passed flow_id.

Parameters:

flow_id (str) – flow id value of the searched widget’s tap_flow_id/focus_flow_id attribute.

Return type:

Optional[Any]

Returns:

widget that has a tap_flow_id/focus_flow_id attribute with the value of the passed flow id or None if not found.

widget_by_page_id(page_id)

determine the first (top-most on z-axis) widget having the passed tour page id.

Parameters:

page_id (str) – widgets tour page id from tap_flow_id/focus_flow_id/app_state_name attribute.

Return type:

Optional[Any]

Returns:

widget that has a tap_flow_id/focus_flow_id/app_state_name attribute with the value of the passed page id or None if not found.

widget_children(wid, only_visible=False)

determine the children of the widget or its container (if exists) in z-order (top-/foremost first).

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 the wid’s children widgets.

static widget_pos(wid)

return the absolute window x and y position of the passed widget.

Parameters:

wid (Any) – widget to determine the position of.

Return type:

tuple[float, float]

Returns:

tuple of x and y screen/window coordinate.

widget_tourable_children_page_ids(parent_widget)

determine all visible and tourable children widgets of the passed parent and its child container widgets.

Parameters:

parent_widget (Any) – parent widget to determine all children that are tourable.

Return type:

list

Returns:

tourable children page ids list of the passed parent widget.

widgets_enclosing_rectangle(widgets)

calculate the minimum bounding rectangle of all the passed widgets.

Parameters:

widgets (Union[list, tuple]) – list/tuple of widgets to determine the minimum bounding rectangle for.

Return type:

tuple[float, float, float, float]

Returns:

tuple of floats, with the x, y, width, height values of the bounding rectangle.

static widget_size(wid)

return the size (width and height) in pixels of the passed widget.

Parameters:

wid (Any) – widget to determine the size of.

Return type:

tuple[float, float]

Returns:

tuple of width and height in pixels.

static widget_visible(wid)

determine if the passed widget is visible (has width and height and (visibility or opacity) set).

Parameters:

wid (Any) – widget to determine visibility of.

Return type:

bool

Returns:

boolean True if the widget is visible (or visibility cannot be determined), False if hidden.

width_spaces(width)

return the number of spaces that result in the specified width by using the app font_size.

Return type:

str

win_pos_size_change(*win_pos_size)

screen resize handler called on window resize or when the app will exit/stop via closed event.

Parameters:

win_pos_size – window geometry/coordinates: x, y, width, height.