ui

Alfred Workflow UI simulator.

class zelfred.ui.DebugItem(title: str, subtitle: Union[str, NoneType] = None, uid: str = <factory>, arg: Union[str, NoneType] = None, autocomplete: Union[str, NoneType] = None, variables: Dict[str, Any] = <factory>)

enter_handler(ui: UI)

This is the abstract method that will perform user defined action when user hits Enter on this item. Develop should inherit this class and override this method to perform user defined action.

Parameters:

ui – the UI object.

class zelfred.ui.UI(handler: Callable[[str, Optional[UI]], List[T_ITEM]], hello_message: Optional[str] = 'Welcome to interactive UI!', capture_error: bool = True, process_input_immediately: bool = False, process_input_after_query_delay: bool = False, query_delay: float = 0.3, show_items_limit: int = 20, scroll_speed: int = 5, terminal: Optional[Terminal] = None)

Zelfred terminal UI implementation.

Parameters:

• handler – the handler is the core of a Zelfred App. It’s a user-defined function that takes the entered query and the UI object as inputs and returns a list of items to render.

• handler – a callable function that takes a query string as input and returns a list of items.

• hello_message – sometimes the handler execution for the first time run takes long. This message will be shown to user to indicate that the handler is still running, and the UI will show the returned items once the handler is done.

• capture_error – whether you want to capture the error and show it in the UI, or you want to raise the error immediately.

• process_input_immediately – the handler will be called immediately after user input. This is the default behavior.

• process_input_after_query_delay – the handler will be called after a delay of query_delay seconds after the first user input. For example, let’s say the query delay is 0.3 second. At begin, the user input is empty, then user entered “a”. If then the user entered “bcd” within 0.3 second, the handler will not be called to give you the latest items. The handler will be called until the user entered a new key, let’s say “e”, from 0.4 second after he entered “a”.

• query_delay – read above.

• show_items_limit – max number of items to show in the dropdown menu.

• scroll_speed – scroll speed in the dropdown menu.

replace_handler(handler: Callable[[str, Optional[UI]], List[T_ITEM]])

Replace the current handler with a new handler, and store the current handler and the current user input query, so that we can recover them when we need.

clear_query()

A wrapper of the _clear_query() method, ensures that the need_clear_query flag is set to True at the end regardless of whether an exception is raised.

clear_items()

A wrapper of the _clear_items() method, ensures that the need_clear_query flag is set to True at the end regardless of whether an exception is raised.

print_query()

A wrapper of the core logic for printing query, ensures that the need_print_query flag is set to True at the end regardless of whether an exception is raised.

print_items()

A wrapper of the core logic for printint items, ensures that the need_print_items and need_run_handler flag is set to True at the end regardless of whether an exception is raised.

process_key_pressed_input(pressed: str)

Process user keyboard input.

• UP: move up

• DOWN: move down

• LEFT: move left

• RIGHT: move right

• HOME: move to start of the line

• END: move to end of the line

• CTRL + E: move up

• CTRL + D: move down

• CTRL + R: scroll up

• CTRL + F: scroll down

• CTRL + H: move left

• CTRL + L: move right

• CTRL + G: move word left

• CTRL + K: move word right

• CTRL + X: clear input

Actions:

• Enter:

• CTRL + A:

• CTRL + W:

• CTRL + P:

process_input()

A wrapper of the core logic for processing input, ensures that the need_process_input flag is set to True at the end regardless of whether an exception is raised.

move_to_end()

Move the cursor to the next line of the end of the dropdown menu.

repaint()

Repaint the UI right after the items is ready. This is useful when you want to show a message before running the real handler.

run_sub_session(handler: Callable[[str, Optional[UI]], List[T_ITEM]], initial_query: str = '')

Run a sub session with a new handler. User can tap “F1” to go back to the previous session.

Parameters:

• handler – see UI

• initial_query – the initial user input query in the sub session.

debug_loop(e: Exception)

Display error message in the UI and wait for new user input. New user input may fix the problem or trigger another error.

run(_do_init: bool = True)

Run the UI.

Read UI Event Loop (or this link) for more information.