Text Layout Classes

class urwid.TextLayout

Base class for a text layout algorithm that lays text out into lines for display.

layout(text: str | bytes, width: int, align: Literal['left', 'center', 'right'] | Align, wrap: Literal['any', 'space', 'clip', 'ellipsis'] | WrapMode) → _LayoutFormat

Return a layout structure for text.

Parameters:

• text – string in current encoding or unicode string

• width – number of screen columns available

• align – align mode for text

• wrap – wrap mode for text

Raises:

NotImplementedError – the subclass does not provide a layout implementation.

Layout structure is a list of line layouts, one per output line. Line layouts are lists than may contain the following tuples:

• (column width of text segment, start offset, end offset)

• (number of space characters to insert, offset or None)

• (column width of insert text, offset, “insert text”)

The offset in the last two tuples is used to determine the attribute used for the inserted spaces or text respectively. The attribute used will be the same as the attribute at that text offset. If the offset is None when inserting spaces then no attribute will be used.

supports_align_mode(align: Literal['left', 'center', 'right'] | Align) → bool

Return True if align is a supported align mode.

supports_wrap_mode(wrap: Literal['any', 'space', 'clip', 'ellipsis'] | WrapMode) → bool

Return True if wrap is a supported wrap mode.

class urwid.StandardTextLayout(*, tab_stops: Iterable[int] = (), tab_stop_every: int = 8)

Default TextLayout implementation, wrapping and aligning text by screen column.

Create a layout with word-processor style tab stops.

A tab character advances to the next tab stop, measured in rendered screen columns from the start of the displayed line: explicit tab_stops are used first, then stops repeat every tab_stop_every columns counted from column 0. With tab_stop_every 0 a tab past the last explicit stop takes no columns.

Parameters:

• tab_stops – screen columns of explicit tab stops.

• tab_stop_every – interval of the default tab stops, 0 for none.

Raises:

ValueError – tab_stop_every is negative, or one of tab_stops is not a positive column.

align_layout(text: str | bytes, width: int, segs: _LayoutFormat, wrap: Literal['any', 'space', 'clip', 'ellipsis'] | WrapMode, align: Literal['left', 'center', 'right'] | Align) → _LayoutFormat

Convert the layout segments to an aligned layout.

Raises:

ValueError – align is not a supported alignment.

calculate_text_segments(text: str | bytes, width: int, wrap: Literal['any', 'space', 'clip', 'ellipsis'] | WrapMode) → list[list[tuple[int, int, int | bytes] | tuple[int, int]]]

Calculate the segments of text to display given width screen columns to display them.

text - Unicode text or byte string to display width - number of available screen columns wrap - wrapping mode used

Returns a layout structure without an alignment applied. Each line holding a tab character is laid out with tab stops, see next_tab_stop():

wrap is clip or ellipsis? --yes--> per line: tabs? --yes--> place tabs, then cut with ellipsis
        |                                    +--no---> cut with ellipsis
        no
        |
per line: tabs? --yes--> wrap tab by tab
          +--no---> wrap at spaces or anywhere

Raises:

• CanNotDisplayText – a character does not fit into an empty display line.

• ValueError – wrap is not a supported wrapping mode.

layout(text: str | bytes, width: int, align: Literal['left', 'center', 'right'] | Align, wrap: Literal['any', 'space', 'clip', 'ellipsis'] | WrapMode) → _LayoutFormat

Return a layout structure for text.

next_tab_stop(column: int) → int

Return the screen column of the first tab stop after column.

When there is no stop after column, return column itself: the tab takes no columns.

>>> StandardTextLayout(tab_stops=(4, 10)).next_tab_stop(5)
10
>>> StandardTextLayout(tab_stops=(4, 10)).next_tab_stop(10)
16
>>> StandardTextLayout(tab_stops=(4, 10), tab_stop_every=0).next_tab_stop(10)
10

pack(maxcol: int, layout: _LayoutFormat) → int

Return a minimal maxcol value that would result in the same number of lines for layout.

layout must be a layout structure returned by self.layout().

Raises:

ValueError – layout is empty.

supports_align_mode(align: Literal['left', 'center', 'right'] | Align) → bool

Return True if align is ‘left’, ‘center’ or ‘right’.

supports_wrap_mode(wrap: Literal['any', 'space', 'clip', 'ellipsis'] | WrapMode) → bool

Return True if wrap is ‘any’, ‘space’, ‘clip’ or ‘ellipsis’.