textual.geometry

Functions and classes to manage terminal geometry (anything involving coordinates or dimensions).

NULL_OFFSET module-attribute

NULL_OFFSET: Final = Offset(0, 0)

An [Offset][textual.geometry.Offset] constant for (0, 0).

NULL_REGION module-attribute

NULL_REGION: Final = Region(0, 0, 0, 0)

A [Region][textual.geometry.Region] constant for a null region (at the origin, with both width and height set to zero).

NULL_SIZE module-attribute

NULL_SIZE: Final = Size(0, 0)

A [Size][textual.geometry.Size] constant for a null size (with zero area).

NULL_SPACING module-attribute

NULL_SPACING: Final = Spacing(0, 0, 0, 0)

A [Spacing][textual.geometry.Spacing] constant for no space.

SpacingDimensions module-attribute

SpacingDimensions: TypeAlias = Union[
    int,
    Tuple[int],
    Tuple[int, int],
    Tuple[int, int, int, int],
]

The valid ways in which you can specify spacing.

Shape

Shape(regions)

An arbitrary shape defined by a sequence of regions.

This class currently exists to filter widgets within a shape defined when the user is slecting text.

area property

area: int

Cells covered by the shape.

bounds property

bounds: Region

A region that encloses the shape.

regions property

regions: tuple[Region, ...]

The regions in the shape.

contains_point

contains_point(offset)

Check if the given offset is within the shape.

Parameters:

Name	Type	Description	Default
offset	Offset	An offset.	required

Returns:

Type	Description
bool	True if the given offset is anywhere within the shape, otherwise False.

overlaps

overlaps(region)

Does a region overlap this shape?

Parameters:

Name	Type	Description	Default
region	Region	A Region to check.	required

Returns:

Type	Description
bool	True if any part of the shape overlaps the region, False if there is no overlap.

selection_bounds classmethod

selection_bounds(container, start, end)

Get a shape that would be constructed by a user selecting text between two points.

The shape would look something like this:

    XXXXXXXXXX <- top
XXXXXXXXXXXXXX
XXXXXXXXXXXXXX <- middle
XXXXXXXXXXXXXX
XXXXXXXXX      <- bottom

Parameters:

Name	Type	Description	Default
container	Region	The container region for the selection.	required
start	Offset	The start offset.	required
end	Offset	The end offset.	required

Returns:

Type	Description
Shape	A new shape covering the selection bounds.

clamp

clamp(value, minimum, maximum)

Restrict a value to a given range.

If value is less than the minimum, return the minimum. If value is greater than the maximum, return the maximum. Otherwise, return value.

The minimum and maximum arguments values may be given in reverse order.

Parameters:

Name	Type	Description	Default
value	T	A value.	required
minimum	T	Minimum value.	required
maximum	T	Maximum value.	required

Returns:

Type	Description
T	New value that is not less than the minimum or greater than the maximum.