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: ~typing.Callable[[str, ~typing.Optional[~zelfred.ui.UI]], ~typing.List[~zelfred.item.T_ITEM]], hello_message: ~typing.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: ~typing.Optional[~blessed.terminal.Terminal] = None, render_class: ~typing.Type[~zelfred.render.T_UI_RENDER] = <class 'zelfred.render.UIRender'>)

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.

Additional private attributes:

Parameters:

• _handler_queue – user may nest session in another session, this LIFO queue stores the handler functions of the parent sessions, so that when we exit the inner session and go back to the previous session.

• _line_editor_input_queue – similar to _handler_queue, but stores the parent sessions’ user input queries.

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.

Zelfred default key bindings:

• ⬆: tap Ctrl + E or UP to move item selection cursor up (previous item).

• ⏫: tap Ctrl + R to scroll item selection cursor up.

• ⬇️: tap Ctrl + D or DOWN to move item selection cursor down (next item).

• ⏬: tap Ctrl + F to scroll item selection cursor down.

• ⬅️: tap LEFT to move query input cursor to the left.

• ➡️: tap RIGHT to move query input cursor to the right.

• ⏪: tap Alt + LEFT to move query input cursor to the previous word.

• ⏩: tap Alt + Right to move query input cursor to the next word.

• ⏮️: tap HOME to move query input cursor to the beginning of the line.

• ⏭️: tap END to move query input cursor to the end of the line.

• ◀️: tap Ctrl + K to delete the previous word.

• ▶️: tap Ctrl + L to delete the next word.

• ↩️: tap Ctrl + X to clear the query input.

• ◀️: tap BACKSPACE to delete query input backward.

• ▶️: tap DELETE to delete query input forward.

• 🔴: tap Ctrl + C to quit the app.

• ⤴️: tap F1 to quit the current sub session and go back to the previous session and recover previous user input.

User defined (customizable) item action:

• 🚀: tap Enter to perform custom user action.

• 🚀: tap Ctrl + A to perform custom item action.

• 🚀: tap Ctrl + W to perform custom item action.

• 🚀: tap Ctrl + U to perform custom item action.

• 🚀: tap Ctrl + P to perform custom item action.

User defined UI keybinding:

• 🚀: tap CTRL + T to perform custom UI action, default is “do nothing.

• 🚀: tap CTRL + G to perform custom UI action, default is “do nothing.

• 🚀: tap CTRL + B to perform custom UI action, default is “do nothing.

• 🚀: tap CTRL + N to perform custom UI action, default is “do nothing.

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. See JumpOutSessionError:`() part in run_session() to see how it works.

Parameters:

• handler – see UI

• initial_query – the initial user input query in the sub session. it is the start-up text in the user input line editor.

initialize_loop()

Process the first loop of a session. This loop starts with a hello message, and then run the handler, then render the UI.

main_loop(_ith: int = 0)

This is the main loop of the UI. It starts with waiting for user input, and the run the handler, then render the UI.

jump_out_session_loop()

This loop is executed after a JumpOutSessionError is raised.

It pops up the current session from the queue and use the handler of previous session to run handler, and then render the UI.

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_session(_do_init: bool = True)

Run a “session” in the UI. A “session” has a main loop, and it’s handler to process user input query.

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

except exc.JumpOutSessionError:

This error will be raised when user press F1 If the current session is a sub session, then it rolls backs the handler and line editor input to the previous state. If the current session is the main session, then it will do nothing.

except exc.KeyboardInterrupt:

This error will be raised when user press Ctrl-C. It will move the cursor to the end and prepare to exit the UI.

run()

Run the UI.