euporie.core.graphics

Define controls for display of terminal graphics.

Functions

abstractmethod(funcobj)	A decorator indicating abstract methods.
ceil(x, /)	Return the ceiling of x as an Integral.
find_route(from_, to)	Find and cache conversion routes.
get_app()	Get the current active (running) Application.
get_cwidth(string)	Return width of a string.
passthrough(cmd)	Wrap an escape sequence for terminal passthrough.
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.
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.

Classes

ABCMeta(name, bases, namespace, /, **kwargs)	Metaclass for defining Abstract Base Classes (ABCs).
BoundedWritePosition(xpos, ypos, width, height)	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.
Datum(data, *args, **kwargs)	Class for storing and converting display data.
DiInt([top, right, bottom, left])	A tuple of four integers with directions.
FastDictCache(get_value[, size])	Fast, lightweight cache which keeps at most size items.
Float(content[, top, right, bottom, left, ...])	Float for use in a FloatContainer.
GraphicControl(datum[, scale, bbox])	A base-class for display controls which render terminal graphics.
GraphicProcessor(control)	Class which loads and positions graphics references in a UIContent.
GraphicWindow(content, get_position[, filter])	A window responsible for displaying terminal graphics content.
ItermGraphicControl(datum[, scale, bbox])	A graphic control which displays images using iTerm's graphics protocol.
KittyGraphicControl(datum[, scale, bbox])	A graphic control which displays images using Kitty's graphics protocol.
MouseHandlers()	Two dimensional raster of callbacks for mouse events.
Point(x, y)
SimpleCache([maxsize])	Very simple cache that discards the oldest item when the cache size is exceeded.
SixelGraphicControl(datum[, scale, bbox])	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.
Window([content, width, height, z_index, ...])	Container that holds a control.
WritePosition(xpos, ypos, width, height)

Exceptions

NotVisible

Exception to signal that a graphic is not currently visible.

class euporie.core.graphics.GraphicControl(datum: Datum, scale: float = 0, bbox: euporie.core.data_structures.DiInt | None = None)

Bases: UIControl

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

close() → None

Remove the displayed object entirely.

abstract convert_data(wp: WritePosition) → str

Convert datum to required format.

create_content(width: int, height: int) → 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.

get_invalidate_events() → Iterable[Event[object]]

Return a list of Event objects. This can be a generator. (The application collects all these events, in order to bind redraw handlers to these events.)

get_key_bindings() → KeyBindingsBase | None

The key bindings that are specific for this user control.

Return a KeyBindings object if some key bindings are specified, or None otherwise.

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

Render the output data.

hide() → None

Hide the graphic from show.

is_focusable() → bool

Tell whether this user control is focusable.

mouse_handler(mouse_event: MouseEvent) → NotImplementedOrNone

Handle mouse events.

When NotImplemented is returned, it means that the given event is not handled by the UIControl itself. The Window or key bindings can decide to handle this event as scrolling or changing focus.

Parameters:

mouse_event – MouseEvent instance.

move_cursor_down() → None

Request to move the cursor down. This happens when scrolling down and the cursor is completely at the top.

move_cursor_up() → None

Request to move the cursor up.

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

class euporie.core.graphics.GraphicProcessor(control: UIControl)

Bases: object

Class which loads and positions graphics references in a UIContent.

get_graphic_float(key: str) → prompt_toolkit.layout.containers.Float | None

Create a graphical float for an image.

load(content: UIContent) → None

Check for graphics in lines of text.

class euporie.core.graphics.GraphicWindow(content: GraphicControl, get_position: Callable[[Screen], BoundedWritePosition], filter: FilterOrBool = True, *args: Any, **kwargs: Any)

Bases: 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) → Dimension

Calculate the preferred height for this window.

preferred_width(max_available_width: int) → 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.graphics.ItermGraphicControl(datum: Datum, scale: float = 0, bbox: euporie.core.data_structures.DiInt | None = None)

Bases: GraphicControl

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

close() → None

Remove the displayed object entirely.

convert_data(wp: WritePosition) → str

Convert the graphic’s data to base64 data.

create_content(width: int, height: int) → 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.

get_invalidate_events() → Iterable[Event[object]]

Return a list of Event objects. This can be a generator. (The application collects all these events, in order to bind redraw handlers to these events.)

get_key_bindings() → KeyBindingsBase | None

The key bindings that are specific for this user control.

Return a KeyBindings object if some key bindings are specified, or None otherwise.

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.

is_focusable() → bool

Tell whether this user control is focusable.

mouse_handler(mouse_event: MouseEvent) → NotImplementedOrNone

Handle mouse events.

When NotImplemented is returned, it means that the given event is not handled by the UIControl itself. The Window or key bindings can decide to handle this event as scrolling or changing focus.

Parameters:

mouse_event – MouseEvent instance.

move_cursor_down() → None

Request to move the cursor down. This happens when scrolling down and the cursor is completely at the top.

move_cursor_up() → None

Request to move the cursor up.

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

class euporie.core.graphics.KittyGraphicControl(datum: Datum, scale: float = 0, bbox: euporie.core.data_structures.DiInt | None = None)

Bases: GraphicControl

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

close() → None

Remove the displayed object entirely.

convert_data(wp: WritePosition) → str

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

create_content(width: int, height: int) → 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.

delete() → None

Delete the graphic from the terminal.

get_invalidate_events() → Iterable[Event[object]]

Return a list of Event objects. This can be a generator. (The application collects all these events, in order to bind redraw handlers to these events.)

get_key_bindings() → KeyBindingsBase | None

The key bindings that are specific for this user control.

Return a KeyBindings object if some key bindings are specified, or None otherwise.

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

Tell whether this user control is focusable.

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

Send the graphic to the terminal without displaying it.

mouse_handler(mouse_event: MouseEvent) → NotImplementedOrNone

Handle mouse events.

When NotImplemented is returned, it means that the given event is not handled by the UIControl itself. The Window or key bindings can decide to handle this event as scrolling or changing focus.

Parameters:

mouse_event – MouseEvent instance.

move_cursor_down() → None

Request to move the cursor down. This happens when scrolling down and the cursor is completely at the top.

move_cursor_up() → None

Request to move the cursor up.

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.

exception euporie.core.graphics.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.graphics.SixelGraphicControl(datum: Datum, scale: float = 0, bbox: euporie.core.data_structures.DiInt | None = None)

Bases: GraphicControl

A graphic control which displays images as sixels.

close() → None

Remove the displayed object entirely.

convert_data(wp: WritePosition) → str

Convert datum to required format.

create_content(width: int, height: int) → 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.

get_invalidate_events() → Iterable[Event[object]]

Return a list of Event objects. This can be a generator. (The application collects all these events, in order to bind redraw handlers to these events.)

get_key_bindings() → KeyBindingsBase | None

The key bindings that are specific for this user control.

Return a KeyBindings object if some key bindings are specified, or None otherwise.

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.

is_focusable() → bool

Tell whether this user control is focusable.

mouse_handler(mouse_event: MouseEvent) → NotImplementedOrNone

Handle mouse events.

When NotImplemented is returned, it means that the given event is not handled by the UIControl itself. The Window or key bindings can decide to handle this event as scrolling or changing focus.

Parameters:

mouse_event – MouseEvent instance.

move_cursor_down() → None

Request to move the cursor down. This happens when scrolling down and the cursor is completely at the top.

move_cursor_up() → None

Request to move the cursor up.

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

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

Determine which graphic control to use.