PathPicker UI element

This is an UI element that allows the app’s user to navigate the local filesystem and pick files or directories.

Picking a file:

from zpui_lib.ui import PathPicker
...
# If initial_path is a directory, PathPicker will start in that directory
# If initial_path is a file, PathPicker will start in its base directory and move to that file
path = PathPicker(initial_path, i, o, name="My app's PathPicker for picking a file").activate()
if path: # User might exit PathPicker at any time and it will return None
    purge_file_from_existence(path) # Do something with that file

Picking a directory, i.e. to read files from or to store files in:

from zpui_lib.ui import PathPicker
...
path = PathPicker(initial_path, i, o, dirs_only=True, name="My app's PathPicker for picking a directory").activate()
if path:
    purge_dir_from_existence(path)

Instantiating the PathPicker:

class zpui_lib.ui.PathPicker(path, i, o, callback=None, name=None, file=None, display_hidden=False, dirs_only=False, append_current_dir=True, current_dot=False, prev_dot=True, scrolling=True, **kwargs)[source]

__init__(path, i, o, callback=None, name=None, file=None, display_hidden=False, dirs_only=False, append_current_dir=True, current_dot=False, prev_dot=True, scrolling=True, **kwargs)[source]

Initialises the PathPicker object.

Args:

path: a path to start from. If path to a file is passed, will start from that file (unless overridden with file keyword argument).

i, o: input&output device objects.

Kwargs:

callback: if set, PathPicker will call the callback with path as first argument upon selecting path, instead of exiting the activate()

file: if set, PathPicker will locate the file in the path passed and move its pointer to that file (provided it is found).

dirs_only: if True, PathPicker will only show directories

append_current_dir: if False, PathPicker won’t add “Dir: %/current/dir%” first entry when dirs_only is enabled

current_dot: if True, PathPicker will show ‘.’ path

prev_dot: if True, PathPicker will show ‘..’ path

display_hidden: if True, PathPicker will display hidden files

activate(): A method which is called when the UI element needs to start operating. Is blocking, sets up input&output devices, refreshes the UI element, then calls the idle_loop method while the UI element is active. self.in_foreground is True, while callbacks are executed from the input device thread.

deactivate(): Deactivates the UI element, exiting it.

More info:

class zpui_lib.ui.PathPicker(path, i, o, callback=None, name=None, file=None, display_hidden=False, dirs_only=False, append_current_dir=True, current_dot=False, prev_dot=True, scrolling=True, **kwargs)[source]

Bases: Menu

view_mixin: alias of MenuRenderingMixin

activate(): A method which is called when the UI element needs to start operating. Is blocking, sets up input&output devices, refreshes the UI element, then calls the idle_loop method while the UI element is active. self.in_foreground is True, while callbacks are executed from the input device thread.

activate_input(): Sets up the input device if one was passed to the UI element - calling i.stop_listen, self.configure_input and i.listen. If an input element wasn’t passed, checks if one is expected.

after_activate(): Hook for child UI elements, is called each time before activate() returns - before get_return_value is called. Is the perfect place to, say, remove input streaming callbacks.

before_activate()[source]: Hook for child UI elements, meant to be called. For a start, resets the pointer to the start_pointer.

before_foreground(): Hook for child UI elements. Is called each time to_foreground is called.

configure_input(): Configures the input device - you can set your keymap, streaming callbacks or both - abstracting away stop_listen and listen. Can be overridden by child elements.

deactivate(): Deactivates the UI element, exiting it.

determine_location(): Figures out the place in ZPUI where the UI element is summoned from. Pretty cool!

exec_contents_hook(): Executes contents_hook and, if successful, sets new contents. If contents_hook failed to execute (or returned None), will see if on_contents_hook_fail attribute is callable and, if it is, calls it. Otherwise, deactivates the Menu. Returns True if successful. If failed at any step, returns False. If contents_hook is not set, returns None.

generate_keymap(): Makes the keymap dictionary for the input device.

generate_name_if_not_supplied(): Generating a random yet descriptive UI element name if one was not supplied. The name hasa to be random enough so that overlays can be applied properly. The name generated will include the directory where the app is called from.

get_default_view(): Decides on the view to use for a BaseListUIElement when config file has no information on it.

get_displayed_contents(): This function is to be used for views, in case an UI element wants to display entries differently than they’re stored (for example, this is used in NumberedMenu).

get_return_value()[source]: Can be overridden by child UI elements. Return value will be returned when UI element’s activate() exits.

get_views_dict(): Is called if you explicitly set up your UI element to accept views. Expected to return a list of all available views.

idle_loop(): Contains code which will be executed in UI element’s idle loop. By default, is just a 0.1 second sleep and a scroll() call.

key_deactivate(): A method to deactivate the menu specifically on key press. Is mostly useful for making key callbacks easily patchable.

move_down(): Moves the pointer one entry down, if possible. Is typically used as a callback from input event processing thread.

move_to_end(): Goes to the last entry if not already there.

move_to_start(counter=None): Goes to the first entry if not already there.

move_up(): Moves the pointer one entry up, if possible. Is typically used as a callback from input event processing thread.

on_pointer_update(): Lets you do things every time the pointer has been updated. Undefined by default. You’d benefit from making sure you keep calling it every time you update the pointer!

page_down(counter=None): Scrolls up a full screen of entries, if possible. If not possible, moves as far as it can.

page_up(counter=None): Scrolls down a full screen of UI entries, if possible. If not possible, moves as far as it can.

print_contents(): A debug method. Useful for hooking up to an input event so that you can see the representation of current UI element’s contents.

print_keymap(): A debug method. Useful for hooking up to an input event so that you can see what’s the keymap of a currently active UI element.

print_name(): A debug method. Useful for hooking up to an input event so that you can see which UI element is currently active.

process_callback(func): Decorates a function so that during its execution the UI element stops being in foreground. Is typically used as a wrapper for a callback from input event processing thread. After callback’s execution is finished, sets the keymap again and refreshes the UI element.

process_contents()

Processes contents for custom callbacks. Currently, only ‘exit’ calbacks are supported.

If self.append_exit is set, it goes through the menu and removes every callback which either is self.deactivate or is just a string ‘exit’. Then, it appends a single “Exit” entry at the end of menu contents. It makes dynamically appending entries to menu easier and makes sure there’s only one “Exit” callback, at the bottom of the menu.

process_keymap(keymap): Processes the keymap, wrapping all callbacks using the process_callback method. If a string is supplied instead of a callable, it looks it up from methods - if a method is not found, raises ValueError. Also, sets KEY_LEFT to deactivate unless self.override_left is set to False (override with caution).

process_right_press(): Calls the second callback on the right button press.

refresh(): A placeholder to be used for BaseUIElement.

select_entry()[source]: |Is typically used as a callback from input event processing thread. |After callback’s execution is finished, sets the keymap again and refreshes the screen. |If menu has no elements, exits the menu. |If MenuExitException is returned from the callback, exits menu, too.

set_contents(contents): Sets the UI element contents and triggers pointer recalculation in the view.

set_default_keymap(): Sets the default keymap, getting it straight from the generate_keymap.

set_keymap(keymap): Receives and processes UI element’s keymap (filtered using process_keymap before setting).

set_views_dict(): Sets the views dict and adds view mixins to views if mixins are available and adding one is appropriate.

to_background(): Signals activate to finish executing.

to_foreground(): Is called when UI element’s activate() method is used, sets flags and performs all the actions so that UI element can display its contents and receive keypresses. Also, refreshes the screen.

trigger_contents_hook(): External method to trigger Menu contents update if the contents_hook is set. If contents_hook is not set, raises an AttributeError.

update_keymap()[source]: Updates the keymap.

validate_contents(contents): A hook to validate contents before they’re set. If validation is unsuccessful, raise exceptions (it’s better if exception message contains the faulty entry). Does not check if the contents are falsey.

in_background = False: flag which indicates whether menu is currently active, either being displayed or just waiting in background (for example, when you go into a sub-menu, the parent menu will still be considered active).

in_foreground = False: flag which indicates whether menu is currently displayed.

property is_active: A condition to be checked by activate to see when the UI element is active. Can be overridden by child elements if necessary. By default returns self.in_background, so if you only have a single UI element without external callback processing, it might make sense to check in_foreground instead.

pointer = 0: number of currently selected menu entry, starting from 0.