ae.lisz_app_data

lisz demo app data handling

this module provides common constants, functions and methods for the showcase/demo application Lisz, which is demonstrating the usage of the GUI framework packages provided by the ae namespace.

usage demonstration of ae namespace portions

the usage of the following ae namespace portions gets demonstrated by this application:

• ae.base: basic constants and helper functions

• ae.files: file collection, grouping and caching

• ae.deep: deep data structure search and replace

• ae.i18n: internationalization / localization helpers

• ae.paths: generic file path helpers

• ae.dynamicod: evaluation and execution helper functions

• ae.updater: application environment updater

• ae.core: application core constants, helper functions and base classes

• ae.literal: literal type detection and evaluation

• ae.console: console application environment

• ae.parse_date: parse date strings more flexible and less strict

• ae.gui: abstract base class for python applications with a graphical user interface with context help, app tours, app flow and app state changes

Hint

the Kivy variant of this demo app uses additionally the following ae namespace portions: ae.kivy_auto_width, ae.kivy_dyn_chi, ae.kivy_relief_canvas, ae.kivy and ae.kivy_user_prefs.

features of the lisz demo app

• internationalization of texts, user messages, help texts, button/label texts (ae.i18n)

• easy mapping of files in complex folder structures (ae.files, ae.paths)

• providing help layouts (ae.gui.tours, ae.kivy.widgets)

• colors changeable by user (ae.kivy_user_prefs, ae.enaml_app)

• font and button sizes are changeable by user (ae.gui.utils)

• dark and light theme switchable by user

• sound output support with sound volume configurable by user

• recursive item data tree manipulation: add, edit and delete item

• each item can be selected/check marked

• filtering of selected/checked and unselected/unchecked items

• an item represents either a sub-node (sub-list) or a leaf of the data tree

• item order changeable via drag & drop

• item can be moved to the parent or a sub-node

• easy navigation within the item tree (up/down navigation in tree and quick jump)

lisz application data model

the lisz demo app is managing a recursive item tree - a list of lists - that can be used e.g., as a to-do/shopping list.

to keep this demo app simple, the data managed by the lisz application is a minimalistic tree structure that gets stored as a application status, without the need of any database. the root node and with that the whole recursive data structure gets stored in the app state variable root_node.

the root of the tree structure is a list of the type LiszNode containing list items of type LiszItem. a LiszItem element represents a dict of the type Dict[str, Any].

each LiszItem element of the tree structure is either a leaf or a node. and each node is a sub-list with a recursive structure identical to the root node and of the type LiszNode.

the following graph is showing an example data tree:

digraph { node [shape=record, width=3] rec1 [label="{<rec1>Root Node | { <A>Item A | <C>Item C | <D>... } }"] "root_node app state variable" -> rec1 [arrowhead=crow style=tapered penwidth=3] rec1:A -> "Leaf Item A" [minlen=3] rec2 [label="{<rec2>Node Item C (sub-node) | { <CA>Item CA | <CB>Item CB | <CN>... } }"] rec1:C -> rec2 rec2:CA -> "Leaf Item CA" [minlen=2] rec3 [label="{<rec3>Node Item CB (sub-sub-node) | { <CBA>Item CBA | <CDn>... } }"] rec2:CB -> rec3 rec3:CBA -> "Leaf Item CBA" }

in the above example tree structure is containing the root node items A (which is a leaf) and C (which is a sub-node).

the node C consists of the items CA and CB where CA is a leaf and CB is a node.

the first item of the node CB is another sub-node with the leaf item CBA.

GUI framework demo implementations

integration of the following GUI frameworks on top of the abstract base class (implemented in the ae.gui portion of the ae namespace):

• Kivy based on the Kivy framework: kivy lisz demo app

• Enaml based on the enaml framework: enaml lisz demo app

• Beeware Toga based on the beeware framework: beeware toga lisz demo app

• Dabo based on the dabo framework: dabo lisz demo app

• pyglet

• pygobject

• AppJar

the main app base mixin class LiszDataMixin provided by this module is used to manage the common data structures, functions and methods for the various demo applications variants based on ae.gui and the related GUI framework implementation portions (like e.g. ae.kivy.apps and ae.enaml_app) of the ae namespace.

gui framework implementation variants

kivy

the kivy lisz app is based on the Kivy framework, a pypi package documented here.

Fig. 1 kivy lisz app root list	Fig. 2 fruits sub-list	Fig. 3 using a light theme
Fig. 4 lisz user preferences	Fig. 5 kivy lisz color editor	Fig. 6 bigger font size

kivy wish list

• kv language looper pseudo widget (like enaml is providing) to easily generate sets of similar widgets.

enaml

the enaml lisz demo app is based on the enaml framework, a pypi package documented here at ReadTheDocs.

Fig. 7 enaml/qt lisz app

Fig. 8 light-themed in landscape

automatic update of widget attributes

dependencies have to be executed/read_from, so e.g., the icon attribute will not be updated if app.app_state_light_theme gets changed:

icon << main_app.cached_icon('font_size') or app.app_state_light_theme

on the contrary, the icon will be updated by the following two statements:

icon << main_app.cached_icon('font_size') if app.app_state_light_theme else main_app.cached_icon('font_size')
icon << app.app_state_light_theme == None or main_app.cached_icon('font_size')

the KeyEvent implementation is based on this SO answer posted by the enamlx author frmdstryr/Jairus Martin: https://stackoverflow.com/questions/20380940/how-to-get-key-events-when-using-enaml. alternative and more complete implementation can be found in the enamlx package (https://github.com/frmdstryr/enamlx).

enaml wish list

• type and syntax checking, code highlighting and debugging of enaml files within PyCharm.

• fix freezing of linux/Ubuntu system in debugging of opening/opened PopupViews in PyCharm.

Module Attributes

FLOW_PATH_ROOT_ID	pseudo item id needed for flow path jumper and for drop onto the leave item button
FLOW_PATH_TEXT_SEP	flow path separator for flow_path_text()
FOCUS_FLOW_PREFIX	flow key prefix shown for any focused item
INVALID_ITEM_ID_PREFIX_CHARS	invalid initial chars in item id (to detect id | literal in a flow key)
NODE_FILE_PREFIX	file name prefix for node imports/exports
NODE_FILE_EXT	file extension for node imports/exports
IMPORT_NODE_MAX_FILE_LEN	maximum file length of an importable node file
IMPORT_NODE_MAX_ITEMS	maximum number of items to import or paste from clipboard
LiszItem	node item data (nid) type
LiszNode	node/list type
UserAccessRightsChangesType	oaio user access rights changes type.

Functions

check_item_id(item_id)	check if the passed item id string is valid.
correct_item_id(item_id)	strip and replace extra/invalid characters from the passed item id string.
flow_path_items_from_text(text)	parse and interpret text block for (optional) flow path text and node data (in pprint.pformat/repr format).
item_import_button_text(item, source)	return the translated button text/caption for to quickly import an item/node from a clipboard/file/oaio source.
item_sel_filter(item)	callable to filter selected LiszItems.
item_unsel_filter(item)	callable to filter unselected LiszItems.
node_sel_factor(node)	determine the selection factor of the specified node from the selected children/leaf items.
selectable_and_total_sub_items(node[, ...])	determine the number of selectable and total leaf items, of the node argument and their sub-nodes.

Classes

EditorOaioMixin()	item editor mixin bundling the user access to an oaio item.
LiszDataMixin()	lisz data model - independent from used GUI framework.

FLOW_PATH_ROOT_ID = '^^^^'

pseudo item id needed for flow path jumper and for drop onto the leave item button

FLOW_PATH_TEXT_SEP = ' > '

flow path separator for flow_path_text()

FOCUS_FLOW_PREFIX = '='

flow key prefix shown for any focused item

INVALID_ITEM_ID_PREFIX_CHARS = '[{'

invalid initial chars in item id (to detect id | literal in a flow key)

NODE_FILE_PREFIX = 'node_'

file name prefix for node imports/exports

NODE_FILE_EXT = '.txt'

file extension for node imports/exports

IMPORT_NODE_MAX_FILE_LEN = 8192

maximum file length of an importable node file

IMPORT_NODE_MAX_ITEMS = 12

maximum number of items to import or paste from clipboard

LiszItem

node item data (nid) type

alias of dict[str, Any]

LiszNode

node/list type

alias of list[dict[str, Any]]

UserAccessRightsChangesType

oaio user access rights changes type.

alias of list[tuple[str, str, str]]

check_item_id(item_id)

check if the passed item id string is valid.

Parameters:

item_id (str) – item id to check.

Return type:

str

Returns:

“” if all chars in the specified item_id argument are valid, else one of the translated message strings.

correct_item_id(item_id)

strip and replace extra/invalid characters from the passed item id string.

Parameters:

item_id (str) – item id string to correct.

Return type:

str

Returns:

corrected item id (can result in an empty string).

flow_path_items_from_text(text)

parse and interpret text block for (optional) flow path text and node data (in pprint.pformat/repr format).

Parameters:

text (str) –

text block to be parsed. the text block can optionally be prefixed with an extra line (separated by a new line ‘\n’ character) containing the destination flow path in text format (using FLOW_PATH_TEXT_SEP to separate the flow path items).

the (rest of the) text block represents the node/item data in one of the following formats:

• single text line (interpreted as a single leaf item).

• multiple text lines (interpreted as multiple leaf items).

• dict repr string, starting with a curly bracket character.

• list repr string, starting with a square bracket character.

Return type:

tuple[str, str, list[dict[str, Any]]]

Returns:

tuple of error message (empty string if no error occurred), flow path (empty string if root or not given) and node list.

item_import_button_text(item, source)

return the translated button text/caption for to quickly import an item/node from a clipboard/file/oaio source.

Parameters:

• item (dict[str, Any]) – item, items or node to import or dict with an error message in the ‘_err_’ key.

• source (str) – source text (untranslated)

Return type:

str

Returns:

button text/caption string.

item_sel_filter(item)

callable to filter selected LiszItems.

Parameters:

item (dict[str, Any]) – item data structure to check.

Return type:

bool

Returns:

boolean True if the item is a selected leaf or if the item is a node with only selected sub-leaves, else False.

item_unsel_filter(item)

callable to filter unselected LiszItems.

Parameters:

item (dict[str, Any]) – item data structure to check.

Return type:

bool

Returns:

the value True if the item is an unselected leaf or if the item is a node with only unselected leaves, else False.

node_sel_factor(node)

determine the selection factor of the specified node from the selected children/leaf items.

Parameters:

node (list[dict[str, Any]]) – item node to determine the selection factor of its children.

Return type:

float

Returns:

selection factor between 0.0 and 1.0.

selectable_and_total_sub_items(node, selected=0, total=0)

determine the number of selectable and total leaf items, of the node argument and their sub-nodes.

Parameters:

• node (list[dict[str, Any]]) – starting node.

• selected (int) – initial number of selected items.

• total (int) – initial total number of leaves.

Return type:

tuple[int, int]

Returns:

tuple of selectable and total leaf items. dividing [0] by [1] results in a value between 0.0 and 1.0 reflecting the relation between selected and unselected leaves.

class EditorOaioMixin

Bases: object

item editor mixin bundling the user access to an oaio item.

oaio_id: str

edited oaio id of the item or empty string if not registered

_set_oaio_id: str

initial value of the oaio id when editor get initialized

_userz_acc: list[dict[str, str]]

edited user access rights

_set_userz_acc: list[dict[str, str]]

initial access rights value when the editor gets initialized

main_app: LiszDataMixin

reference to the main app instance, set by the item editor

item_data: dict[str, Any]

reference to the item data to edit, set by the item editor

init_oaio_vars()

called from GUI-specific ItemEditor.__init__() of the main app to initialize the oaio related variables.

property oaio_is_registered: bool

determine if the current oaio is or will be registered when the editor gets closed.

property user_can_unregister: bool

determine if the authenticated user can unregister the current oaio (specified via self.oaio_id).

property user_is_creator: bool

determine if the current app user is or will be the creator of the actual oaio.

property userz_access_changes: list[tuple[str, str, str]]

determine changes of userz access rights.

Returns:

list of tuples with the username, the old and the new access right, in the order they have to be changed/sent-to-server; e.g., to unregister an oaio the subscribers before the creator (in reversed by the access right). returns an empty list on any error or if the client or the oaio server is not online.

Raises:

AssertionError – if internal data structures got corrupted (user-count or -index discrepancies between self._userz_acc and self._set_userz_acc).

property userz_access_rights: list[dict[str, str]]

determine the userz and their access rights for the item specified via self.item_id/.oaio_id.

Returns:

list of dicts with ‘username’ and ‘access_right’ keys or an empty list if the client/server is offline or if an error occurred.

invalidate_cached_user_access_rights()

call to force reload of oaio user access rights.

userz_access_index(username='')

determine the index of a user within the userz access list.

Parameters:

username (str) – username to search for, defaults to the current user if not specified.

Return type:

int

Returns:

index of the current/specified user in the userz access rights list or -1 if the user does not exist in the userz access list.

class LiszDataMixin

Bases: object

lisz data model - independent from used GUI framework.

root_node: list[dict[str, Any]] = []

root node of lisz data structure

current_node_items: list[dict[str, Any]]

currently displayed/selected node

filtered_indexes: list[int]

indexes of the filtered/displayed items in the current node

oaio_client: OaioClient | None = None

optional oaio server client (if OAIO_HOST_NAME is set)

oaio_refs: dict[str, list[dict[str, Any]]] = {}

shared oaios: key=oaio id, val=item refs in root_node tree

filter_selected: bool = False

True to hide/filter-out selected node items

filter_unselected: bool = False

True to hide/filter-out unselected node items

debug_level: int

current debug_level

flow_id: str

current flow id

flow_path: list[str]

current flow path

help_layout: Any | None

help text container widget in active help mode else None

tour_layout: Any | None

tour layout/overlay widget in active tour mode else None

user_id: str

user_id from ae.console

_refreshing_data: bool = False

DEBUG True while running refresh_all() method

call_method: Callable

call_method_delayed: Callable

call_method_repeatedly: Callable

change_app_state: Callable

change_flow: Callable

flow_path_action: Callable

get_variable: Callable

play_sound: Callable

popups_opened: Callable

vpo: Callable

refresh_node_widgets: Callable

_refresh_oaio_refs()

_refresh_oaio_values()

_sync_with_oaio_server(*_args)

add_item(nid, node_to_add_to=None, new_item_index=0)

add an item (leaf or node) to the currently displayed node.

Parameters:

• nid (dict[str, Any]) – LiszItem to add (has to have a non-empty item id).

• node_to_add_to (Optional[list[dict[str, Any]]]) – node where the passed item will be added to (def=current node).

• new_item_index (int) – index where the new item will be inserted (default=0, ignored if it already exists).

Return type:

str

Returns:

error message if any error happened, else empty string.

add_items(items, node_to_add_to=None)

add item to the currently displayed node.

Parameters:

• items (list[dict[str, Any]]) – LiszNode list to add (each item has to have a non-empty item id).

• node_to_add_to (Optional[list[dict[str, Any]]]) – node where the passed item will be added to (def=current node).

Return type:

str

Returns:

error message if any error happened (multiple error messages are separated by \n), else empty string.

change_item_sel(item, value)

changes the selected state of a given item to the provided value and sync it if it is a registered oaio.

Parameters:

• item (dict[str, Any]) – lisz node item whose selected state will be updated.

• value (bool) – the newly selected state to be applied to the item.

change_sub_node_sel(node, set_sel_to)

change the selection of the passed node’s sub-leaves to the specified value.

Parameters:

• node (list[dict[str, Any]]) – node of which to change the selection of the subitem leaves.

• set_sel_to (bool) – pass True to only toggle the unselected subitem leaves, False to only the selected ones.

current_item_or_node_literal()

return the currently focused/displayed item or node as repr string.

Return type:

str

Returns:

pformat repr string of the currently focused item id/node or of the displayed node.

delete_items(*item_ids, parent_node=None, node_only=False)

delete either complete items or sub node of the items (identified by the passed item ids).

Parameters:

• item_ids (str) – tuple of item ids to identify the items/sub-nodes to be deleted.

• parent_node (Optional[list[dict[str, Any]]]) – node from where the item has to be removed from (default=current node).

• node_only (bool) – pass True if only delete the sub-node of the identified item, False to delete the item.

Return type:

list[dict[str, Any]]

edit_validate(old_item_index, new_id=None, want_node=None, parent_node=None, new_item_index=0, editor=None, oaio_id=None)

validate and save the user changes after adding/importing a new item or editing an existing item.

Parameters:

• old_item_index (int) – index in the current node of the edited item or -1 if a new item (to be added).

• new_id (Optional[str]) – new/edited id string. passing an empty string for an existing item will delete it.

• want_node (Optional[bool]) – pass True if the new/edited item wants to have a sub-node, False if not.

• parent_node (Optional[list[dict[str, Any]]]) – node where the edited/added item has to be updated/inserted (default=current list).

• new_item_index (int) – index where the new item has to be inserted (default=0, ignored in edit item mode).

• editor (Any) – ItemEditor popup instance (if called from it) with its old/new user access rights.

• oaio_id (Optional[str]) – new oaio id for import called from on_node_import()/import_items(); default: None.

Return type:

str

Returns:

empty string on successful edit validation or on cancellation of a new item (with empty id string). returns an error string, or ‘request_delete_confirmation_for_item’ if the user has to confirm the deletion after the user wiped the item id string, or ‘request_delete_confirmation_for_node’ if the user has to confirm the removal of the sub-node.

export_node(flow_path, file_path='.', node=None)

export node specified by the passed flow_path argument.

Parameters:

• flow_path (list[str]) – flow path of the node to export.

• file_path (str) – folder to store the node data into (def=current working directory).

• node (Optional[list[dict[str, Any]]]) – explicit/filtered node items (if not passed, then all items will be exported).

Return type:

str

Returns:

empty string if the node got exported without errors, else the error/exception message.

find_item_index(item_id, searched_node=None)

determine the list index of the passed item id in the searched node or in the current node.

Parameters:

• item_id (str) – item id to find.

• searched_node (Optional[list[dict[str, Any]]]) – searched node. if not passed, then the current node will be searched instead.

Return type:

int

Returns:

item list index in the searched node or -1 if item id was not found.

flow_key_text(flow_id, landscape)

determine the shortest possible text fragment of the passed flow key that is unique in the current node.

used to display unique part of the key of the focused item/node.

Parameters:

• flow_id (str) – flow id to get the flow key to check from (pass the observed value to update GUI automatically, either self.app_state_flow_id or self.app_states[‘flow_id’]).

• landscape (bool) – boolean True if the window has the landscape shape (resulting in a larger abbreviation). pass the observed attribute, mostly situated in the framework_win (e.g., self.framework_win.landscape).

Return type:

str

Returns:

display text containing a flow key.

flow_path_from_text(text, skip_check=False)

restore the full complete flow path from the shortened flow keys generated by flow_path_text().

Parameters:

• text (str) – flow path text - like returned by flow_path_text().

• skip_check (bool) – pass True to skip the check if the flow path exists in the current self.root_node.

Return type:

list[str]

Returns:

flow path list.

flow_path_node(flow_path=None, create=False)

determine the node specified by the passed flow path, optionally create missing nodes of the flow path.

Parameters:

• flow_path (Optional[list[str]]) – flow path list.

• create (bool) – pass True to create missing nodes. only on False this method will return an empty list on invalid/broken flow_path.

Return type:

list[dict[str, Any]]

Returns:

node list at flow_path (if found -or- created is True and no-creation-errors) or empty list (if flow_path not found and created is False or on creation error).

flow_path_quick_jump_nodes()

determine the current flow paths of all nodes excluding the current, to quick-jump from the current node.

Return type:

list[str]

Returns:

flow path texts list of all nodes apart from the current one.

flow_path_text(flow_path, min_len=3, display_root=False, separator=' > ')

generate shortened display text from the passed flow path.

Parameters:

• flow_path (list[str]) – flow path list.

• min_len (int) – minimum length of node ids (flow id keys). pass zero value to not shorten ids.

• display_root (bool) – pass True to return FLOW_PATH_ROOT_ID on an empty/root path.

• separator (str) – path item separator (default=FLOW_PATH_TEXT_SEP).

Return type:

str

Returns:

shortened display text string of the passed flow path (which can be converted back to a flow path list with the method flow_path_from_text()).

focus_neighbour_item(delta)

move flow id to the previous/next displayed/filtered node item.

Parameters:

delta (int) – moving a step (if greater 0 then forward, else backward).

global_variables(**patches)

overridden to add app-specific globals.

Return type:

dict[str, Any]

importable_files_nodes(folder_path)

check all files found in the specified folder_path and load and return them as a LiszNode structure.

Parameters:

folder_path (str) – path to the folder where the importable files are situated.

Return type:

list[dict[str, Any]]

Returns:

list of item/sub-node dicts for each found and importable file. if the file content is inappropriate or if an error occurred, then the item dict has an item key ‘_err_’ with the respective error-message in its value.

importable_oaios_node()

check subscribed oaio and load and return them as a LiszNode structure.

Return type:

list[dict[str, Any]]

Returns:

list of item dicts for each subscribed oaio or empty list if the user has no subscription or if the internet or the oaio server is not available.

importable_text_node(text)

check text block content and if contains a valid importable item, then return it as a LiszNode structure.

Text:

text block content to check and convert to a node list (e.g., from clipboard).

Return type:

list[dict[str, Any]]

Returns:

importable items parsed from the specified text directly as items and as node or list of a dict with the key ‘_err_’ and the respective error-message as the value if text block content is empty/invalid.

static import_file_item(file_path)

load a node file and determine the importable item(s).

Parameters:

file_path (str) – path of the node file to import.

Return type:

dict[str, Any]

Returns:

the item with the id created from the file name and a node with subitems. if the file content is inappropriate or if an import error occurred, then the returned dict has only the key ‘_err_’ with the error-message as its value.

import_items(node, parent=None, item_index=0)

import passed node items into the passed parent/destination node at the given index.

Parameters:

• node (list[dict[str, Any]]) – node with items to import/add.

• parent (Optional[list[dict[str, Any]]]) – destination node to add the node items to (def=current node list).

• item_index (int) – list index in the destination node where the items have to be inserted (default=0).

Return type:

str

Returns:

empty string if all items of the node got imported correctly, else error message string.

import_node(node_id, node, parent=None, item_index=0)

import passed node as new node into the passed parent node at the given index.

Parameters:

• node_id (str) – id of the new node to import/add.

• node (list[dict[str, Any]]) – node with items to import/add.

• parent (Optional[list[dict[str, Any]]]) – destination node to add the new node to (def=current node list).

• item_index (int) – list index in the parent node where the items have to be inserted (default=0).

Return type:

str

Returns:

empty string if the node got added/imported correctly, else error message string.

item_by_id(item_id, searched_node=None)

search item in either the passed or the current node.

Parameters:

• item_id (str) – item id to find.

• searched_node (Optional[list[dict[str, Any]]]) – searched node. if not passed, then the current node will be searched instead.

Return type:

dict[str, Any]

Returns:

found item or if not found a new dict with the single key=value ‘id’=item_id.

load_app_states()

overriding ae.gui.app.MainAppBase.load_app_states() to populate or actualize self.oaio_refs

move_item(dragged_node, dragged_id, dropped_path=None, dropped_id='')

move item id from passed dragged_node to the node and index specified by dropped_path and dropped_id.

Parameters:

• dragged_node (list[dict[str, Any]]) – node where the item got dragged/moved from.

• dragged_id (str) – id of the dragged/moved item.

• dropped_path (Optional[list[str]]) – optional destination/drop node path, if not passed, then use dragged_node.

• dropped_id (str) – optional destination item where the dragged item will be moved before it. if not specified or an empty string got passed, then the item will be placed at the end of the destination node.

Return type:

bool

node_info(node, what=(), recursive=True)

determine statistics info for the node specified by node.

Parameters:

• node (list[dict[str, Any]]) – node to get info for.

• what (tuple[str, ...]) –

  pass a tuple of statistic info fields to include only these in the returned dict (passing an empty tuple or nothing will include all the following fields):

  • ’count’: number of items (nodes and leaves) in this node (including sub-nodes).

  • ’leaf_count’: number of sub-leaves.

  • ’node_count’: number of sub-nodes.

  • ’selected_leaf_count’: number of selected sub-leaves.

  • ’unselected_leaf_count’: number of unselected sub-leaves.

  • ’names’: list of all sub-item/-node names/ids.

  • ’leaf_names’: list of all sub-leaf names.

  • ’selected_leaf_names’: list of all selected sub-leaf names.

  • ’unselected_leaf_names’: list of all unselected sub-leaf names.

• recursive (bool) – pass False if only the passed node has to be investigated.

Return type:

dict[str, Union[int, str, list[str]]]

Returns:

dict with the node info specified by the what argument.

on_app_build()

gui app pre-build callback/event to initialize the oaio client.

on_app_state_root_node_save(root_node)

shrink root_node app state variable before it get saved to the config file.

Return type:

list[dict[str, Any]]

on_filter_toggle(toggle_attr, _event_kwargs)

toggle filter on click of either the selected or the unselected filter button.

note that the inverted filter may be toggled to prevent both filters being active.

Parameters:

• toggle_attr (str) – specifying the filter button to toggle, either ‘filter_selected’ or ‘filter_unselected’.

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

Return type:

bool

Returns:

always True to process flow id change.

on_item_enter(_key, event_kwargs)

entering sub node from the current node.

Parameters:

• _key (str) – flow key (item id).

• event_kwargs (dict) – event kwargs.

Return type:

bool

Returns:

always True to process/change flow id.

on_item_leave(_key, event_kwargs)

leaving sub node, setting current node to parent node.

Parameters:

• _key (str) – flow key (item id).

• event_kwargs (dict) – event kwargs.

Return type:

bool

Returns:

always True to process/change flow id.

on_item_sel_change(item_id, event_kwargs)

toggle, set or reset in the current node the selection of a leaf item or of the sub-leaves of a node item.

Parameters:

• item_id (str) – item id of the leaf/node to toggle selection for.

• event_kwargs (dict) – event kwargs, containing a set_sel_to key with a boolean value, where True will select and False deselect the item (or the subitems if the item is a non-empty node).

Return type:

bool

Returns:

always True to process/change flow id.

this flow change event can be used alternatively to on_item_sel_toggle() for more sophisticated lisz app implementations, like e.g., the kivy lisz demo app .

on_item_sel_confirming(item_id, event_kwargs)

confirming sub-list item de-/selection from ItemSelConfirmPopup

Return type:

bool

on_item_sel_toggle(item_id, event_kwargs)

toggle selection of leaf item.

Parameters:

• item_id (str) – item id of the leaf to toggle selection for.

• event_kwargs (dict) – event kwargs.

Return type:

bool

Returns:

always True to process/change flow id.

on_key_press(modifiers, key_code)

check key press event to be handled and processed as command/action in the current list.

Parameters:

• modifiers (str) – modifier keys string.

• key_code (str) – key code string.

Return type:

bool

Returns:

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

on_node_extract(flow_path_text, event_kwargs)

extract the leaves of the node specified by flow_path_text.

Parameters:

• flow_path_text (str) – flow path text or list literal (identifying the start node to extract from).

• event_kwargs (dict) –

  extra arguments specifying extract options (only extract_type is mandatory):

  extract_type specifies extract destination and an optional filter on un-/selected items. the first part defines the extract action (copy/cut/delete/export/share) and an optional second part (separated by an underscore) the filter. e.g., the following string values can be passed for a ‘copy’ extract action:

  • ’copy’ is copying all items of the specified node to the clipboard.

  • ’copy_sel’ is copying only the selected items of the node to the clipboard.

  • ’copy_unsel’ is copying only the unselected items to the clipboard.

  recursive specifies if False that the extraction affects only the leaves of the current node specified by flow_path_text and if True the extraction affects also the leaves of the sub-nodes (default=True).

  export_path specifies the destination folder of the export action (default=’.’/CWD).

Return type:

bool

Returns:

always True to process/change flow.

on_node_jump(flow_path_text, event_kwargs)

FlowButton clicked event handler restoring the flow path from the flow key.

Parameters:

• flow_path_text (str) – flow path text (identifying where to jump to).

• event_kwargs (dict[str, Any]) – event arguments (used to reset flow id).

Return type:

bool

Returns:

always True to process/change flow.

on_user_access_change(_flo_key, event_kwargs)

change oaio access right for item and user, called from the UserAccessRightPopup menu within the ItemEditor.

Parameters:

• _flo_key (str) – unused flow key.

• event_kwargs (dict[str, Any]) – the kwargs of the pressed button (with new access right) are: editor, user_id, new_right and optional others_right (bulk grant/revoke access rights).

Returns:

a True value if no error occurred (to allow flow change), else False.

Raises:

AssertionError – if the specified event_kwargs are invalid.

refresh_all()

changed flow event handler refreshing currently displayed items after changing the node/flow path.

refresh_current_node_items_from_flow_path()

refresh current node including the depending on the display node.

shrink_node_size(node, item_filter=None, recursive=True)

shrink node size by removing unneeded items and sel keys, e.g., to export/save space in the config file.

Parameters:

• node (list[dict[str, Any]]) – start or root node to shrink (in-place!).

• item_filter (Optional[Callable[[dict[str, Any]], bool]]) – pass callable to remove items from the passed node and its sub-nodes. the callable is getting each item as an argument and has to return True to remove it from its node.

• recursive (bool) – pass False if only the passed start node has to be shrunk.

sub_item_ids(node=None, item_ids=(), leaves_only=True, hide_sel_val=None, recursive=True, sub_ids=None)

return a list of item names/ids (if exists and recursive==True then including their sub-node items).

used to determine the affected item ids if the user wants to delete or de-/select the subitems of the item(s) specified by the passed arguments.

Parameters:

• node (Optional[list[dict[str, Any]]]) – searched node. if not passed, then use the current node as default.

• item_ids (tuple[str, ...]) – optional item id filter, if passed, then only return items with an id in this tuple. this filter will not be used for sub-node filtering (if recursive==True).

• leaves_only (bool) – pass False to also include/return node item ids.

• hide_sel_val (Optional[bool]) – pass False/True to exclude un-/selected leaf items from the returned list of ids. if None or not passed, then all found items will be included.

• recursive (bool) – pass False if only the passed start node has to be investigated/included.

• sub_ids (Optional[list[str]]) – already found subitem ids (used for the recursive calls of this method).

Return type:

list[str]

Returns:

ids list of the found items.

toggle_item_sel(node_idx)

toggle the item selection of the item identified by the list index in the current node.

Parameters:

node_idx (int) – list index of the item in the current node to change the selection for.