Skip to content

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: 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(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.