euporie.core.widgets.display

Define custom controls which re-render on resize.

Functions

add_cmd(**kwargs)	Add a command to the centralized command system.
ceil(x, /)	Return the ceiling of x as an Integral.
convert(data, from_, to[, cols, rows, fg, ...])	Convert between formats.
data_pixel_size(data, format_[, fg, bg])	Get the dimensions of an image.
find_route(from_, to)	Find the shortest conversion path between two formats.
fragment_list_width(fragments)	Return the character width of this text fragment list.
get_app()	Get the current active (running) Application.
get_position_func_overlay(target_window)	Generate function to positioning floats over existing windows.
load_registered_bindings(*names[, config])	Assign key-bindings to commands based on a dictionary.
pixels_to_cell_size([px, py])	Get the cell width and aspect ration of a pixel dimension.
register_bindings(bindings)	Update the key-binding registry.
scrollable(window)	Return a filter which indicates if a window is scrollable.
select_graphic_control(format_)	Determine which graphic control to use.
split_lines(fragments)	Take a single list of (style_str, text) tuples and yield one such list for each line.
tmuxify(cmd)	Wrap an escape sequence for tmux passthrough.
to_filter(bool_or_filter)	Accept both booleans and Filters as input and turn it into a Filter.
to_formatted_text(value[, style, auto_convert])	Convert the given value (which can be formatted text) into a list of text fragments.
to_str(value)	Turn callable or string into string.
wrap(ft, width[, style, placeholder, left, ...])	Wrap formatted text at a given width.

Classes

ABCMeta(name, bases, namespace, /, **kwargs)	Metaclass for defining Abstract Base Classes (ABCs).
BoundedWritePosition(xpos, ypos, width, ...)	A write position which also hold bounding box information.
Char([char, style])	Represent a single character in a Screen.
Condition(func)	Turn any callable into a Filter.
ConditionalContainer(content, filter)	Wrapper around any other container that can change the visibility.
DiInt([top, right, bottom, left])	A tuple of four integers with directions.
Display(data, format_[, path, fg_color, ...])	Rich output displays.
DisplayControl(data, format_[, path, ...])	A data formatter, which displays cell output data.
DisplayWindow([content, width, height, ...])	A window sub-class which can scroll left and right.
Event(sender[, handler])	Simple event to which event handlers can be attached. For instance::.
Float(content[, top, right, bottom, left, ...])	Float for use in a FloatContainer.
FormattedTextDisplayControl(data, format_[, ...])	A data formatter, which displays cell output data.
GraphicControl(data, format_[, path, ...])	A base-class for display controls which render terminal graphics.
GraphicWindow(content, position[, filter])	A window responsible for displaying terminal graphics content.
ItermGraphicControl(data, format_[, path, ...])	A graphic control which displays images using iTerm's graphics protocol.
KittyGraphicControl(data, format_[, path, ...])	A graphic control which displays images using Kitty's graphics protocol.
MarginContainer(margin, target)	A container which renders a stand-alone margin.
MouseEvent(position, event_type, button, ...)	Mouse event, sent to UIControl.mouse_handler.
MouseEventType(value[, names, module, ...])
MouseHandlers()	Two dimensional raster of callbacks for mouse events.
Point(x, y)
ScrollbarMargin([display_arrows, ...])	Margin displaying a scrollbar.
SimpleCache([maxsize])	Very simple cache that discards the oldest item when the cache size is exceeded.
SixelGraphicControl(data, format_[, path, ...])	A graphic control which displays images as sixels.
UIContent(get_line, StyleAndTextTuples] = >, ...)	Content generated by a user control.
UIControl()	Base class for all user interface controls.
VSplit(children[, window_too_small, align, ...])	Several layouts, one stacked left/right of the other. ::.
Window([content, width, height, z_index, ...])	Container that holds a control.
WritePosition(xpos, ypos, width, height)
partial	partial(func, *args, **keywords) - new function with partial application of the given arguments and keywords.

Exceptions

NotVisible

Exception to signal that a graphic is not currently visible.

class euporie.core.widgets.display.Display(data: Any, format_: str, path: Path | None = None, fg_color: str | None = None, bg_color: str | None = None, height: AnyDimension = None, width: AnyDimension = None, px: int | None = None, py: int | None = None, focusable: FilterOrBool = False, focus_on_click: FilterOrBool = False, wrap_lines: FilterOrBool = False, always_hide_cursor: FilterOrBool = True, scrollbar: FilterOrBool = True, scrollbar_autohide: FilterOrBool = True, dont_extend_height: FilterOrBool = True, style: str | Callable[[], str] = '')

Bases: object

Rich output displays.

A container for displaying rich output data.

property data: Any

Return the display’s current data.

property format_: str

Return the display’s current data format.

make_sizing_func(data: Any, format_: str, fg: str | None, bg: str | None) → Callable[[], tuple[int, float]]

Create a function to recalculate the data’s dimensions in terminal cells.

property path: Path | None

Return the display’s current data path.

property px: int | None

Return the displayed data’s pixel widget.

property py: int | None

Return the displayed data’s pixel height.

style() → str

Use the background color of the data as the default style.

update_sizing() → None

Create a sizing function when the data’s pixel size changes.

class euporie.core.widgets.display.DisplayControl(data: Any, format_: str, path: Path | None = None, fg_color: str | None = None, bg_color: str | None = None, sizing_func: Callable[[], tuple[int, float]] | None = None, focusable: FilterOrBool = False, focus_on_click: FilterOrBool = False, wrap_lines: FilterOrBool = False)

Bases: prompt_toolkit.layout.controls.UIControl

A data formatter, which displays cell output data.

It will attempt to display the data in the best way possible, and reacts to resize events - i.e. images are downscaled to fit, markdown is re-flowed, etc.

property aspect: float

Lazily load the aspect ratio of the output.

close() → None

Remove the displayed object entirely.

property content_width: int

Return the maximum line length of the content.

create_content(width: int, height: int) → prompt_toolkit.layout.controls.UIContent

Generate rendered output at a given size.

Parameters

• width – The desired output width

• height – The desired output height

Returns

UIContent for the given output size.

property cursor_position: prompt_toolkit.data_structures.Point

Get the cursor position.

property data: Any

Return the control’s display data.

get_invalidate_events() → Iterable[Event[object]]

Return the Window invalidate events.

get_key_bindings() → KeyBindingsBase | None

Return the control’s key bindings.

get_rendered_lines(width: int, height: int, wrap_lines: bool = False) → list[StyleAndTextTuples]

Render the output data.

hide() → None

Hide the output from show.

is_focusable() → bool

Determine if the current control is focusable.

property max_cols: int

Load the maximum width of the output in terminal columns.

mouse_handler(mouse_event: MouseEvent) → NotImplementedOrNone

Mouse handler for this control.

move_cursor_down() → None

Move the cursor down one line.

move_cursor_left() → None

Move the cursor down one line.

move_cursor_right() → None

Move the cursor up one line.

move_cursor_up() → None

Move the cursor up one line.

preferred_height(width: int, max_available_height: int, wrap_lines: bool, get_line_prefix: GetLinePrefixCallable | None) → int

Return the number of lines in the rendered content.

preferred_width(max_available_width: int) → int | None

Return the width of the rendered content.

reset() → None

Clear the display control’s caches (required if the control’s data changes).

size() → None

Load the maximum cell width and aspect ratio of the output.

class euporie.core.widgets.display.DisplayWindow(content: UIControl | None = None, width: AnyDimension = None, height: AnyDimension = None, z_index: int | None = None, dont_extend_width: FilterOrBool = False, dont_extend_height: FilterOrBool = False, ignore_content_width: FilterOrBool = False, ignore_content_height: FilterOrBool = False, left_margins: Sequence[Margin] | None = None, right_margins: Sequence[Margin] | None = None, scroll_offsets: ScrollOffsets | None = None, allow_scroll_beyond_bottom: FilterOrBool = False, wrap_lines: FilterOrBool = False, get_vertical_scroll: Callable[[Window], int] | None = None, get_horizontal_scroll: Callable[[Window], int] | None = None, always_hide_cursor: FilterOrBool = False, cursorline: FilterOrBool = False, cursorcolumn: FilterOrBool = False, colorcolumns: None | list[ColorColumn] | Callable[[], list[ColorColumn]] = None, align: WindowAlign | Callable[[], WindowAlign] = WindowAlign.LEFT, style: str | Callable[[], str] = '', char: None | str | Callable[[], str] = None, get_line_prefix: GetLinePrefixCallable | None = None)

Bases: prompt_toolkit.layout.containers.Window

A window sub-class which can scroll left and right.

content: DisplayControl

get_children() → list[prompt_toolkit.layout.containers.Container]

Return the list of child Container objects.

get_key_bindings() → prompt_toolkit.key_binding.key_bindings.KeyBindingsBase | None

Returns a KeyBindings object. These bindings become active when any user control in this container has the focus, except if any containers between this container and the focused user control is modal.

is_modal() → bool

When this container is modal, key bindings from parent containers are not taken into account if a user control in this container is focused.

preferred_height(width: int, max_available_height: int) → prompt_toolkit.layout.dimension.Dimension

Calculate the preferred height for this window.

preferred_width(max_available_width: int) → prompt_toolkit.layout.dimension.Dimension

Calculate the preferred width for this window.

reset() → None

Reset the state of this container and all the children. (E.g. reset scroll offsets, etc…)

vertical_scroll: int

write_to_screen(screen: prompt_toolkit.layout.screen.Screen, mouse_handlers: prompt_toolkit.layout.mouse_handlers.MouseHandlers, write_position: prompt_toolkit.layout.screen.WritePosition, parent_style: str, erase_bg: bool, z_index: int | None) → None

Write window to screen. This renders the user control, the margins and copies everything over to the absolute position at the given screen.

class euporie.core.widgets.display.FormattedTextDisplayControl(data: Any, format_: str, path: Path | None = None, fg_color: str | None = None, bg_color: str | None = None, sizing_func: Callable[[], tuple[int, float]] | None = None, focusable: FilterOrBool = False, focus_on_click: FilterOrBool = False, wrap_lines: FilterOrBool = False)

Bases: euporie.core.widgets.display.DisplayControl

A data formatter, which displays cell output data.

It will attempt to display the data in the best way possible, and reacts to resize events - i.e. images are downscaled to fit, markdown is re-flowed, etc.

property aspect: float

Lazily load the aspect ratio of the output.

close() → None

Remove the displayed object entirely.

property content_width: int

Return the maximum line length of the content.

create_content(width: int, height: int) → prompt_toolkit.layout.controls.UIContent

Generate rendered output at a given size.

Parameters

• width – The desired output width

• height – The desired output height

Returns

UIContent for the given output size.

property cursor_position: prompt_toolkit.data_structures.Point

Get the cursor position.

property data: Any

Return the control’s display data.

get_invalidate_events() → Iterable[Event[object]]

Return the Window invalidate events.

get_key_bindings() → KeyBindingsBase | None

Return the control’s key bindings.

get_rendered_lines(width: int, height: int, wrap_lines: bool = False) → list[StyleAndTextTuples]

Get rendered lines from the cache, or generate them.

hide() → None

Hide the output from show.

is_focusable() → bool

Determine if the current control is focusable.

property max_cols: int

Load the maximum width of the output in terminal columns.

mouse_handler(mouse_event: MouseEvent) → NotImplementedOrNone

Mouse handler for this control.

move_cursor_down() → None

Move the cursor down one line.

move_cursor_left() → None

Move the cursor down one line.

move_cursor_right() → None

Move the cursor up one line.

move_cursor_up() → None

Move the cursor up one line.

preferred_height(width: int, max_available_height: int, wrap_lines: bool, get_line_prefix: GetLinePrefixCallable | None) → int

Return the number of lines in the rendered content.

preferred_width(max_available_width: int) → int | None

Return the width of the rendered content.

reset() → None

Clear the display control’s caches (required if the control’s data changes).

size() → None

Load the maximum cell width and aspect ratio of the output.

class euporie.core.widgets.display.GraphicControl(data: Any, format_: str, path: Path | None = None, fg_color: str | None = None, bg_color: str | None = None, sizing_func: Callable[[], tuple[int, float]] | None = None, focusable: FilterOrBool = False, focus_on_click: FilterOrBool = False, scale: float = 0, bbox: DiInt | None = None)

Bases: euporie.core.widgets.display.DisplayControl

A base-class for display controls which render terminal graphics.

property aspect: float

Lazily load the aspect ratio of the output.

close() → None

Remove the displayed object entirely.

property content_width: int

Return the maximum line length of the content.

create_content(width: int, height: int) → prompt_toolkit.layout.controls.UIContent

Generate rendered output at a given size.

Parameters

• width – The desired output width

• height – The desired output height

Returns

UIContent for the given output size.

property cursor_position: prompt_toolkit.data_structures.Point

Get the cursor position.

property data: Any

Return the control’s display data.

get_invalidate_events() → Iterable[Event[object]]

Return the Window invalidate events.

get_key_bindings() → KeyBindingsBase | None

Return the control’s key bindings.

get_rendered_lines(width: int, height: int, wrap_lines: bool = False) → list[StyleAndTextTuples]

Render the output data.

hide() → None

Hide the output from show.

is_focusable() → bool

Determine if the current control is focusable.

property max_cols: int

Load the maximum width of the output in terminal columns.

mouse_handler(mouse_event: MouseEvent) → NotImplementedOrNone

Mouse handler for this control.

move_cursor_down() → None

Move the cursor down one line.

move_cursor_left() → None

Move the cursor down one line.

move_cursor_right() → None

Move the cursor up one line.

move_cursor_up() → None

Move the cursor up one line.

preferred_height(width: int, max_available_height: int, wrap_lines: bool, get_line_prefix: GetLinePrefixCallable | None) → int

Return the number of lines in the rendered content.

preferred_width(max_available_width: int) → int | None

Return the width of the rendered content.

reset() → None

Clear the display control’s caches (required if the control’s data changes).

size() → None

Load the maximum cell width and aspect ratio of the output.

class euporie.core.widgets.display.GraphicWindow(content: GraphicControl, position: Callable[[Screen], tuple[WritePosition, DiInt]], filter: FilterOrBool = True, *args: Any, **kwargs: Any)

Bases: prompt_toolkit.layout.containers.Window

A window responsible for displaying terminal graphics content.

The content is displayed floating on top of a target window.

The graphic will be displayed if: - a completion menu is not being shown - a dialog is not being shown - a menu is not being shown - the output it attached to is fully in view

content: GraphicControl

get_children() → list[prompt_toolkit.layout.containers.Container]

Return the list of child Container objects.

get_key_bindings() → prompt_toolkit.key_binding.key_bindings.KeyBindingsBase | None

Returns a KeyBindings object. These bindings become active when any user control in this container has the focus, except if any containers between this container and the focused user control is modal.

is_modal() → bool

When this container is modal, key bindings from parent containers are not taken into account if a user control in this container is focused.

preferred_height(width: int, max_available_height: int) → prompt_toolkit.layout.dimension.Dimension

Calculate the preferred height for this window.

preferred_width(max_available_width: int) → prompt_toolkit.layout.dimension.Dimension

Calculate the preferred width for this window.

reset() → None

Reset the state of this container and all the children. (E.g. reset scroll offsets, etc…)

write_to_screen(screen: Screen, mouse_handlers: MouseHandlers, write_position: WritePosition, parent_style: str, erase_bg: bool, z_index: int | None) → None

Draw the graphic window’s contents to the screen if required.

class euporie.core.widgets.display.ItermGraphicControl(data: Any, format_: str, path: Path | None = None, fg_color: str | None = None, bg_color: str | None = None, sizing_func: Callable[[], tuple[int, float]] | None = None, focusable: FilterOrBool = False, focus_on_click: FilterOrBool = False, scale: float = 0, bbox: DiInt | None = None)

Bases: euporie.core.widgets.display.GraphicControl

A graphic control which displays images using iTerm’s graphics protocol.

property aspect: float

Lazily load the aspect ratio of the output.

close() → None

Remove the displayed object entirely.

property content_width: int

Return the maximum line length of the content.

convert_data(rows: int, cols: int) → str

Convert the graphic’s data to base64 data.

create_content(width: int, height: int) → prompt_toolkit.layout.controls.UIContent

Generate rendered output at a given size.

Parameters

• width – The desired output width

• height – The desired output height

Returns

UIContent for the given output size.

property cursor_position: prompt_toolkit.data_structures.Point

Get the cursor position.

property data: Any

Return the control’s display data.

get_invalidate_events() → Iterable[Event[object]]

Return the Window invalidate events.

get_key_bindings() → KeyBindingsBase | None

Return the control’s key bindings.

get_rendered_lines(width: int, height: int, wrap_lines: bool = False) → list[StyleAndTextTuples]

Get rendered lines from the cache, or generate them.

hide() → None

Hide the output from show.

is_focusable() → bool

Determine if the current control is focusable.

property max_cols: int

Load the maximum width of the output in terminal columns.

mouse_handler(mouse_event: MouseEvent) → NotImplementedOrNone

Mouse handler for this control.

move_cursor_down() → None

Move the cursor down one line.

move_cursor_left() → None

Move the cursor down one line.

move_cursor_right() → None

Move the cursor up one line.

move_cursor_up() → None

Move the cursor up one line.

preferred_height(width: int, max_available_height: int, wrap_lines: bool, get_line_prefix: GetLinePrefixCallable | None) → int

Return the number of lines in the rendered content.

preferred_width(max_available_width: int) → int | None

Return the width of the rendered content.

reset() → None

Clear the display control’s caches (required if the control’s data changes).

size() → None

Load the maximum cell width and aspect ratio of the output.

class euporie.core.widgets.display.KittyGraphicControl(data: Any, format_: str, path: Path | None = None, fg_color: str | None = None, bg_color: str | None = None, sizing_func: Callable[[], tuple[int, float]] | None = None, focusable: FilterOrBool = False, focus_on_click: FilterOrBool = False, scale: float = 0, bbox: DiInt | None = None)

Bases: euporie.core.widgets.display.GraphicControl

A graphic control which displays images using Kitty’s graphics protocol.

property aspect: float

Lazily load the aspect ratio of the output.

close() → None

Remove the displayed object entirely.

property content_width: int

Return the maximum line length of the content.

convert_data(rows: int, cols: int) → str

Convert the graphic’s data to base64 data for kitty graphics protocol.

create_content(width: int, height: int) → prompt_toolkit.layout.controls.UIContent

Generate rendered output at a given size.

Parameters

• width – The desired output width

• height – The desired output height

Returns

UIContent for the given output size.

property cursor_position: prompt_toolkit.data_structures.Point

Get the cursor position.

property data: Any

Return the control’s display data.

delete() → None

Delete the graphic from the terminal.

get_invalidate_events() → Iterable[Event[object]]

Return the Window invalidate events.

get_key_bindings() → KeyBindingsBase | None

Return the control’s key bindings.

get_rendered_lines(width: int, height: int, wrap_lines: bool = False) → list[StyleAndTextTuples]

Get rendered lines from the cache, or generate them.

hide() → None

Hide the graphic from show without deleting it.

is_focusable() → bool

Determine if the current control is focusable.

load(rows: int, cols: int) → None

Send the graphic to the terminal without displaying it.

property max_cols: int

Load the maximum width of the output in terminal columns.

mouse_handler(mouse_event: MouseEvent) → NotImplementedOrNone

Mouse handler for this control.

move_cursor_down() → None

Move the cursor down one line.

move_cursor_left() → None

Move the cursor down one line.

move_cursor_right() → None

Move the cursor up one line.

move_cursor_up() → None

Move the cursor up one line.

preferred_height(width: int, max_available_height: int, wrap_lines: bool, get_line_prefix: GetLinePrefixCallable | None) → int

Return the number of lines in the rendered content.

preferred_width(max_available_width: int) → int | None

Return the width of the rendered content.

reset() → None

Hide and delete the kitty graphic from the terminal.

size() → None

Load the maximum cell width and aspect ratio of the output.

exception euporie.core.widgets.display.NotVisible

Bases: Exception

Exception to signal that a graphic is not currently visible.

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class euporie.core.widgets.display.SixelGraphicControl(data: Any, format_: str, path: Path | None = None, fg_color: str | None = None, bg_color: str | None = None, sizing_func: Callable[[], tuple[int, float]] | None = None, focusable: FilterOrBool = False, focus_on_click: FilterOrBool = False, scale: float = 0, bbox: DiInt | None = None)

Bases: euporie.core.widgets.display.GraphicControl

A graphic control which displays images as sixels.

property aspect: float

Lazily load the aspect ratio of the output.

close() → None

Remove the displayed object entirely.

property content_width: int

Return the maximum line length of the content.

create_content(width: int, height: int) → prompt_toolkit.layout.controls.UIContent

Generate rendered output at a given size.

Parameters

• width – The desired output width

• height – The desired output height

Returns

UIContent for the given output size.

property cursor_position: prompt_toolkit.data_structures.Point

Get the cursor position.

property data: Any

Return the control’s display data.

get_invalidate_events() → Iterable[Event[object]]

Return the Window invalidate events.

get_key_bindings() → KeyBindingsBase | None

Return the control’s key bindings.

get_rendered_lines(width: int, height: int, wrap_lines: bool = False) → list[StyleAndTextTuples]

Get rendered lines from the cache, or generate them.

hide() → None

Hide the output from show.

is_focusable() → bool

Determine if the current control is focusable.

property max_cols: int

Load the maximum width of the output in terminal columns.

mouse_handler(mouse_event: MouseEvent) → NotImplementedOrNone

Mouse handler for this control.

move_cursor_down() → None

Move the cursor down one line.

move_cursor_left() → None

Move the cursor down one line.

move_cursor_right() → None

Move the cursor up one line.

move_cursor_up() → None

Move the cursor up one line.

preferred_height(width: int, max_available_height: int, wrap_lines: bool, get_line_prefix: GetLinePrefixCallable | None) → int

Return the number of lines in the rendered content.

preferred_width(max_available_width: int) → int | None

Return the width of the rendered content.

reset() → None

Clear the display control’s caches (required if the control’s data changes).

size() → None

Load the maximum cell width and aspect ratio of the output.

euporie.core.widgets.display.get_position_func_overlay(target_window: Window) → Callable[[Screen], tuple[WritePosition, DiInt]]

Generate function to positioning floats over existing windows.

euporie.core.widgets.display.select_graphic_control(format_: str) → type[euporie.core.widgets.display.GraphicControl] | None

Determine which graphic control to use.