textual.strip

This module contains the Strip class and related objects.

A Strip contains the result of rendering a widget. See Line API for how to use Strips.

Strip

Strip(segments, cell_length=None)

Represents a 'strip' (horizontal line) of a Textual Widget.

A Strip is like an immutable list of Segments. The immutability allows for effective caching.

Parameters:

Name	Type	Description	Default
segments	Iterable[Segment]	An iterable of segments.	required
cell_length	int | None	The cell length if known, or None to calculate on demand.	None

cell_length property

cell_length: int

Get the number of cells required to render this object.

link_ids property

link_ids: set[str]

A set of the link ids in this Strip.

text property

text: str

Segment text.

adjust_cell_length

adjust_cell_length(cell_length, style=None)

Adjust the cell length, possibly truncating or extending.

Parameters:

Name	Type	Description	Default
cell_length	int	New desired cell length.	required
style	Style | None	Style when extending, or None.	None

Returns:

Type	Description
Strip	A new strip with the supplied cell length.

align classmethod

align(strips, style, width, height, horizontal, vertical)

Align a list of strips on both axis.

Parameters:

Name	Type	Description	Default
strips	list[Strip]	A list of strips, such as from a render.	required
style	Style	The Rich style of additional space.	required
width	int	Width of container.	required
height	int | None	Height of container.	required
horizontal	AlignHorizontal	Horizontal alignment method.	required
vertical	AlignVertical	Vertical alignment method.	required

Returns:

Type	Description
Iterable[Strip]	An iterable of strips, with additional padding.

apply_filter

apply_filter(filter, background)

Apply a filter to all segments in the strip.

Parameters:

Name	Type	Description	Default
filter	LineFilter	A line filter object.	required

Returns:

Type	Description
Strip	A new Strip.

apply_meta

apply_meta(meta)

Apply meta to all segments.

Parameters:

Name	Type	Description	Default
meta	dict[str, Any]	A dict of meta information.	required

Returns:

Type	Description
Strip	A new strip.

apply_offsets

apply_offsets(x, y)

Apply offsets used in text selection.

Parameters:

Name	Type	Description	Default
x	int	Offset on X axis (column).	required
y	int	Offset on Y axis (row).	required

Returns:

Type	Description
Strip	New strip.

apply_style

apply_style(style)

Apply a style to the Strip.

Parameters:

Name	Type	Description	Default
style	Style	A Rich style.	required

Returns:

Type	Description
Strip	A new strip.

blank classmethod

blank(cell_length, style=None)

Create a blank strip.

Parameters:

Name	Type	Description	Default
cell_length	int	Desired cell length.	required
style	StyleType | None	Style of blank.	None

Returns:

Type	Description
Strip	New strip.

crop

crop(start, end=None)

Crop a strip between two cell positions.

Parameters:

Name	Type	Description	Default
start	int	The start cell position (inclusive).	required
end	int | None	The end cell position (exclusive).	None

Returns:

Type	Description
Strip	A new Strip.

crop_extend

crop_extend(start, end, style)

Crop between two points, extending the length if required.

Parameters:

Name	Type	Description	Default
start	int	Start offset of crop.	required
end	int	End offset of crop.	required
style	Style | None	Style of additional padding.	required

Returns:

Type	Description
Strip	New cropped Strip.

crop_pad

crop_pad(cell_length, left, right, style)

Crop the strip to cell_length, and add optional padding.

Parameters:

Name	Type	Description	Default
cell_length	int	Cell length of strip prior to padding.	required
left	int	Additional padding on the left.	required
right	int	Additional padding on the right.	required
style	Style	Style of any padding.	required

Returns:

Type	Description
Strip	Cropped and padded strip.

discard_meta

discard_meta()

Remove all meta from segments.

Returns:

Type	Description
Strip	New strip.

divide

divide(cuts)

Divide the strip into multiple smaller strips by cutting at given (cell) indices.

Parameters:

Name	Type	Description	Default
cuts	Iterable[int]	An iterable of cell positions as ints.	required

Returns:

Type	Description
Sequence[Strip]	A new list of strips.

extend_cell_length

extend_cell_length(cell_length, style=None)

Extend the cell length if it is less than the given value.

Parameters:

Name	Type	Description	Default
cell_length	int	Required minimum cell length.	required
style	Style | None	Style for padding if the cell length is extended.	None

Returns:

Type	Description
Strip	A new Strip.

from_lines classmethod

from_lines(lines, cell_length=None)

Convert lines (lists of segments) to a list of Strips.

Parameters:

Name	Type	Description	Default
lines	list[list[Segment]]	List of lines, where a line is a list of segments.	required
cell_length	int | None	Cell length of lines (must be same) or None if not known.	None

Returns:

Type	Description
list[Strip]	List of strips.

index_to_cell_position

index_to_cell_position(index)

Given a character index, return the cell position of that character. This is the sum of the cell lengths of all the characters before the character at index.

Parameters:

Name	Type	Description	Default
index	int	The index to convert.	required

Returns:

Type	Description
int	The cell position of the character at index.

join classmethod

join(strips)

Join a number of strips into one.

Parameters:

Name	Type	Description	Default
strips	Iterable[Strip | None]	An iterable of Strips.	required

Returns:

Type	Description
Strip	A new combined strip.

simplify

simplify()

Simplify the segments (join segments with same style)

Returns:

Type	Description
Strip	New strip.

style_links

style_links(link_id, link_style)

Apply a style to Segments with the given link_id.

Parameters:

Name	Type	Description	Default
link_id	str	A link id.	required
link_style	Style	Style to apply.	required

Returns:

Type	Description
Strip	New strip (or same Strip if no changes).

StripRenderable

StripRenderable(strips, width=None)

A renderable which renders a list of strips into lines.

get_line_length

get_line_length(segments)

Get the line length (total length of all segments).

Parameters:

Name	Type	Description	Default
segments	Iterable[Segment]	Iterable of segments.	required

Returns:

Type	Description
int	Length of line in cells.