Skip to content

Geometry

geometry

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

Offset

Bases: NamedTuple

A cell offset defined by x and y coordinates. Offsets are typically relative to the top left of the terminal or other container.

Textual prefers the names x and y, but you could consider x to be the column and y to be the row.

clamped: Offset property

Ensure x and y are above zero.

Returns:

Type Description
Offset

New offset.

is_origin: bool property

Check if the point is at the origin (0, 0).

Returns:

Type Description
bool

True if the offset is the origin.

x: int class-attribute

Offset in the x-axis (horizontal)

y: int class-attribute

Offset in the y-axis (vertical)

blend(destination, factor)

Blend (interpolate) to a new point.

Parameters:

Name Type Description Default
destination Offset

Point where factor would be 1.0.

required
factor float

A value between 0 and 1.0.

required

Returns:

Type Description
Offset

A new point on a line between self and destination.

get_distance_to(other)

Get the distance to another offset.

Parameters:

Name Type Description Default
other Offset

An offset.

required

Returns:

Type Description
float

Distance to other offset.

Region

Bases: NamedTuple

Defines a rectangular region.

A Region consists of a coordinate (x and y) and dimensions (width and height).

  (x, y)
    ┌────────────────────┐ ▲
    │                    │ │
    │                    │ │
    │                    │ height
    │                    │ │
    │                    │ │
    └────────────────────┘ ▼
    ◀─────── width ──────▶

area: int property

Get the area within the region.

Returns:

Type Description
int

Area covered by this region.

bottom: int property

Maximum Y value (non inclusive).

Returns:

Type Description
int

y coordinate.

bottom_left: Offset property

Bottom left offset of the region.

Returns:

Type Description
Offset

Bottom left offset.

bottom_right: Offset property

Bottom right of the region.

Returns:

Type Description
Offset

Bottom right.

column_range: range property

A range object for X coordinates.

column_span: tuple[int, int] property

Get the start and end columns (x coord).

The end value is exclusive.

Returns:

Type Description
tuple[int, int]

Pair of x coordinates (column numbers).

corners: tuple[int, int, int, int] property

Get the top left and bottom right coordinates as a tuple of integers.

Returns:

Type Description
tuple[int, int, int, int]

A tuple of (<left>, <top>, <right>, <bottom>).

height: int class-attribute

The height of the region.

line_range: range property

A range object for Y coordinates.

line_span: tuple[int, int] property

Get the start and end line number (y coord).

The end value is exclusive.

Returns:

Type Description
tuple[int, int]

Pair of y coordinates (line numbers).

offset: Offset property

Get the start point of the region.

Returns:

Type Description
Offset

Top left offset.

reset_offset: Region property

An region of the same size at (0, 0).

Returns:

Type Description
Region

Reset region.

right: int property

Maximum X value (non inclusive).

Returns:

Type Description
int

x coordinate.

size: Size property

Get the size of the region.

Returns:

Type Description
Size

Size of the region.

top_right: Offset property

Top right offset of the region.

Returns:

Type Description
Offset

Top right.

width: int class-attribute

The width of the region.

x: int class-attribute

Offset in the x-axis (horizontal).

y: int class-attribute

Offset in the y-axis (vertical).

at_offset(offset)

Get a new Region with the same size at a given offset.

Parameters:

Name Type Description Default
offset tuple[int, int]

An offset.

required

Returns:

Type Description
Region

New Region with adjusted offset.

clip(width, height)

Clip this region to fit within width, height.

Parameters:

Name Type Description Default
width int

Width of bounds.

required
height int

Height of bounds.

required

Returns:

Type Description
Region

Clipped region.

clip_size(size)

Clip the size to fit within minimum values.

Parameters:

Name Type Description Default
size tuple[int, int]

Maximum width and height.

required

Returns:

Type Description
Region

No region, not bigger than size.

contains(x, y)

Check if a point is in the region.

Parameters:

Name Type Description Default
x int

X coordinate.

required
y int

Y coordinate.

required

Returns:

Type Description
bool

True if the point is within the region.

contains_point(point)

Check if a point is in the region.

Parameters:

Name Type Description Default
point tuple[int, int]

A tuple of x and y coordinates.

required

Returns:

Type Description
bool

True if the point is within the region.

contains_region(other) cached

Check if a region is entirely contained within this region.

Parameters:

Name Type Description Default
other Region

A region.

required

Returns:

Type Description
bool

True if the other region fits perfectly within this region.

crop_size(size)

Get a region with the same offset, with a size no larger than size.

Parameters:

Name Type Description Default
size tuple[int, int]

Maximum width and height (WIDTH, HEIGHT).

required

Returns:

Type Description
Region

New region that could fit within size.

expand(size)

Increase the size of the region by adding a border.

Parameters:

Name Type Description Default
size tuple[int, int]

Additional width and height.

required

Returns:

Type Description
Region

A new region.

from_corners(x1, y1, x2, y2) classmethod

Construct a Region form the top left and bottom right corners.

Parameters:

Name Type Description Default
x1 int

Top left x.

required
y1 int

Top left y.

required
x2 int

Bottom right x.

required
y2 int

Bottom right y.

required

Returns:

Type Description
Region

A new region.

from_offset(offset, size) classmethod

Create a region from offset and size.

Parameters:

Name Type Description Default
offset tuple[int, int]

Offset (top left point).

required
size tuple[int, int]

Dimensions of region.

required

Returns:

Type Description
Region

A region instance.

from_union(regions) classmethod

Create a Region from the union of other regions.

Parameters:

Name Type Description Default
regions Collection[Region]

One or more regions.

required

Returns:

Type Description
Region

A Region that encloses all other regions.

get_scroll_to_visible(window_region, region, *, top=False) classmethod

Calculate the smallest offset required to translate a window so that it contains another region.

This method is used to calculate the required offset to scroll something in to view.

Parameters:

Name Type Description Default
window_region Region

The window region.

required
region Region

The region to move inside the window.

required
top bool

Get offset to top of window. Defaults to False

False

Returns:

Type Description
Offset

An offset required to add to region to move it inside window_region.

grow(margin) cached

Grow a region by adding spacing.

Parameters:

Name Type Description Default
margin tuple[int, int, int, int]

Grow space by (<top>, <right>, <bottom>, <left>).

required

Returns:

Type Description
Region

New region.

intersection(region) cached

Get the overlapping portion of the two regions.

Parameters:

Name Type Description Default
region Region

A region that overlaps this region.

required

Returns:

Type Description
Region

A new region that covers when the two regions overlap.

overlaps(other) cached

Check if another region overlaps this region.

Parameters:

Name Type Description Default
other Region

A Region.

required

Returns:

Type Description
bool

True if other region shares any cells with this region.

shrink(margin) cached

Shrink a region by subtracting spacing.

Parameters:

Name Type Description Default
margin tuple[int, int, int, int]

Shrink space by (<top>, <right>, <bottom>, <left>).

required

Returns:

Type Description
Region

The new, smaller region.

split(cut_x, cut_y) cached

Split a region in to 4 from given x and y offsets (cuts).

           cut_x ↓
        ┌────────┐ ┌───┐
        │        │ │   │
        │    0   │ │ 1 │
        │        │ │   │
cut_y → └────────┘ └───┘
        ┌────────┐ ┌───┐
        │    2   │ │ 3 │
        └────────┘ └───┘

Parameters:

Name Type Description Default
cut_x int

Offset from self.x where the cut should be made. If negative, the cut is taken from the right edge.

required
cut_y int

Offset from self.y where the cut should be made. If negative, the cut is taken from the lower edge.

required

Returns:

Type Description
tuple[Region, Region, Region, Region]

Four new regions which add up to the original (self).

split_horizontal(cut) cached

Split a region in to two, from a given x offset.

            ┌─────────┐
            │    0    │
            │         │
    cut →   └─────────┘
            ┌─────────┐
            │    1    │
            └─────────┘

Parameters:

Name Type Description Default
cut int

An offset from self.x where the cut should be made. May be negative, for the offset to start from the right edge.

required

Returns:

Type Description
tuple[Region, Region]

Two regions, which add up to the original (self).

split_vertical(cut) cached

Split a region in to two, from a given x offset.

         cut ↓
    ┌────────┐┌───┐
    │    0   ││ 1 │
    │        ││   │
    └────────┘└───┘

Parameters:

Name Type Description Default
cut int

An offset from self.x where the cut should be made. If cut is negative, it is taken from the right edge.

required

Returns:

Type Description
tuple[Region, Region]

Two regions, which add up to the original (self).

translate(offset) cached

Move the offset of the Region.

Parameters:

Name Type Description Default
offset tuple[int, int]

Offset to add to region.

required

Returns:

Type Description
Region

A new region shifted by (x, y)

union(region) cached

Get the smallest region that contains both regions.

Parameters:

Name Type Description Default
region Region

Another region.

required

Returns:

Type Description
Region

An optimally sized region to cover both regions.

Size

Bases: NamedTuple

The dimensions of a rectangular region.

area: int property

Get the area of the size.

Returns:

Type Description
int

Area in cells.

height: int class-attribute

The height in cells.

line_range: range property

Get a range covering lines.

Returns:

Type Description
range

A builtin range object.

region: Region property

Get a region of the same size.

Returns:

Type Description
Region

A region with the same size at (0, 0).

width: int class-attribute

The width in cells.

contains(x, y)

Check if a point is in area defined by the size.

Parameters:

Name Type Description Default
x int

X coordinate.

required
y int

Y coordinate.

required

Returns:

Type Description
bool

True if the point is within the region.

contains_point(point)

Check if a point is in the area defined by the size.

Parameters:

Name Type Description Default
point tuple[int, int]

A tuple of x and y coordinates.

required

Returns:

Type Description
bool

True if the point is within the region.

Spacing

Bases: NamedTuple

The spacing around a renderable.

bottom: int class-attribute

Space from the bottom of a region.

bottom_right: tuple[int, int] property

Bottom right space.

Returns:

Type Description
tuple[int, int]

(<right>, <bottom>)

css: str property

Gets a string containing the spacing in CSS format.

Returns:

Type Description
str

Spacing in CSS format.

height: int property

Total space in height.

Returns:

Type Description
int

Height.

left: int class-attribute

Space from the left of a region.

right: int class-attribute

Space from the left of a region.

top: int class-attribute

Space from the top of a region.

top_left: tuple[int, int] property

Top left space.

Returns:

Type Description
tuple[int, int]

(<left>, <top>)

totals: tuple[int, int] property

Get total horizontal and vertical space.

Returns:

Type Description
tuple[int, int]

(<horizontal>, <vertical>)

width: int property

Total space in width.

Returns:

Type Description
int

Width.

all(amount) classmethod

Construct a Spacing with a given amount of spacing on all edges.

Parameters:

Name Type Description Default
amount int

The magnitude of spacing to apply to all edges

required

Returns:

Type Description
Spacing

Spacing(amount, amount, amount, amount)

grow_maximum(other)

Grow spacing with a maximum.

Parameters:

Name Type Description Default
other Spacing

Spacing object.

required

Returns:

Type Description
Spacing

New spacing were the values are maximum of the two values.

horizontal(amount) classmethod

Construct a Spacing with a given amount of spacing on horizontal edges, and no vertical spacing.

Parameters:

Name Type Description Default
amount int

The magnitude of spacing to apply to horizontal edges

required

Returns:

Type Description
Spacing

Spacing(0, amount, 0, amount)

unpack(pad) classmethod

Unpack padding specified in CSS style.

Parameters:

Name Type Description Default
pad SpacingDimensions

An integer, or tuple of 1, 2, or 4 integers.

required

Raises:

Type Description
ValueError

If pad is an invalid value.

Returns:

Type Description
Spacing

New Spacing object.

vertical(amount) classmethod

Construct a Spacing with a given amount of spacing on vertical edges, and no horizontal spacing.

Parameters:

Name Type Description Default
amount int

The magnitude of spacing to apply to vertical edges

required

Returns:

Type Description
Spacing

Spacing(amount, 0, amount, 0)

clamp(value, minimum, maximum)

Adjust a value to it is not less than a minimum and not greater than a maximum value.

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.