Skip to content

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.

x: int = 0 class-attribute

Offset in the x-axis (horizontal)

y: int = 0 class-attribute

Offset in the y-axis (vertical)

blend(destination, factor)

Blend (interpolate) to a new point.

Parameters:

Name Type Description Default
destination Point

Point where factor would be 1.0.

 required
factor float

A value between 0 and 1.0.

 required

Returns:

Name Type Description
Point Offset

A new point on a line between self and destination.

clamped() property

Ensure x and y are above zero.

Returns:

Name Type Description
Offset Offset

New offset.

get_distance_to(other)

Get the distance to another offset.

Parameters:

Name Type Description Default
other Offset

An offset.

 required

Returns:

Name Type Description
float float

Distance to other offset.

is_origin() property

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

Returns:

Name Type Description
bool bool

True if the offset is the origin.

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 ──────▶

height: int = 0 class-attribute

The height of the region.

width: int = 0 class-attribute

The width of the region.

x: int = 0 class-attribute

Offset in the x-axis (horizontal).

y: int = 0 class-attribute

Offset in the y-axis (vertical).

area() property

Get the area within the region.

Returns:

Name Type Description
int int

Area covered by this region.

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:

Name Type Description
Region Region

New Region with adjusted offset.

bottom() property

Maximum Y value (non inclusive).

Returns:

Name Type Description
int int

y coordinate.

bottom_left() property

Bottom left offset of the region.

Returns:

Name Type Description
Offset Offset

Bottom left offset.

bottom_right() property

Bottom right of the region.

Returns:

Name Type Description
Offset Offset

Bottom right.

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:

Name Type Description
Region 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:

Name Type Description
Region Region

No region, not bigger than size.

column_range() property

A range object for X coordinates.

column_span() property

Get the start and end columns (x coord).

The end value is exclusive.

Returns:

Type Description
tuple[int, int]

tuple[int, int]: Pair of x coordinates (column numbers).

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:

Name Type Description
bool 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:

Name Type Description
bool 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:

Name Type Description
bool bool

True if the other region fits perfectly within this region.

corners() property

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

Returns:

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

tuple[int, int, int, int]: A tuple of (<left>, <top>, <right>, <bottom>).

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:

Name Type Description
Region 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:

Name Type Description
Region 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:

Name Type Description
Region Region

A new region.

from_offset(offset, size) classmethod

Create a region from offset and size.

Parameters:

Name Type Description Default
offset Point

Offset (top left point).

 required
size tuple[int, int]

Dimensions of region.

 required

Returns:

Name Type Description
Region 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:

Name Type Description
Region 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:

Name Type Description
Offset Offset

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

grow(margin)

Grow a region by adding spacing.

Parameters:

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

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

 required

Returns:

Name Type Description
Region 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:

Name Type Description
Region Region

A new region that covers when the two regions overlap.

line_range() property

A range object for Y coordinates.

line_span() property

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

The end value is exclusive.

Returns:

Type Description
tuple[int, int]

tuple[int, int]: Pair of y coordinates (line numbers).

offset() property

Get the start point of the region.

Returns:

Name Type Description
Offset Offset

Top left offset.

overlaps(other) cached

Check if another region overlaps this region.

Parameters:

Name Type Description Default
other Region

A Region.

 required

Returns:

Name Type Description
bool bool

True if other region shares any cells with this region.

reset_offset() property

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

Returns:

Name Type Description
Region Region

reset region.

right() property

Maximum X value (non inclusive).

Returns:

Name Type Description
int int

x coordinate.

shrink(margin)

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:

Name Type Description
Region Region

The new, smaller region.

size() property

Get the size of the region.

Returns:

Name Type Description
Size Size

Size of the 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]

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]

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]

tuple[Region, Region]: Two regions, which add up to the original (self).

top_right() property

Top right offset of the region.

Returns:

Name Type Description
Offset Offset

Top right.

translate(offset)

Move the offset of the Region.

Parameters:

Name Type Description Default
offset tuple[int, int]

Offset to add to region.

 required

Returns:

Name Type Description
Region 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:

Name Type Description
Region Region

An optimally sized region to cover both regions.

Size

Bases: NamedTuple

The dimensions of a rectangular region.

height: int = 0 class-attribute

The height in cells.

width: int = 0 class-attribute

The width in cells.

area() property

Get the area of the size.

Returns:

Name Type Description
int int

Area 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:

Name Type Description
bool 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:

Name Type Description
bool bool

True if the point is within the region.

line_range() property

Get a range covering lines.

Returns:

Name Type Description
range range

A builtin range object.

region() property

Get a region of the same size.

Returns:

Name Type Description
Region Region

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

Spacing

Bases: NamedTuple

The spacing around a renderable.

bottom: int = 0 class-attribute

Space from the bottom of a region.

left: int = 0 class-attribute

Space from the left of a region.

right: int = 0 class-attribute

Space from the left of a region.

top: int = 0 class-attribute

Space from the top of a region.

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:

Name Type Description
Spacing Spacing

Spacing(amount, amount, amount, amount)

bottom_right() property

Bottom right space.

Returns:

Type Description
tuple[int, int]

tuple[int, int]: (<right>, <bottom>)

css() property

Gets a string containing the spacing in CSS format.

Returns:

Name Type Description
str str

Spacing in CSS format.

grow_maximum(other)

Grow spacing with a maximum.

Parameters:

Name Type Description Default
other Spacing

Spacing object.

 required

Returns:

Name Type Description
Spacing Spacing

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

height() property

Total space in height.

Returns:

Name Type Description
int int

Height.

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:

Name Type Description
Spacing Spacing

Spacing(0, amount, 0, amount)

top_left() property

Top left space.

Returns:

Type Description
tuple[int, int]

tuple[int, int]: (<left>, <top>)

totals() property

Get total horizontal and vertical space.

Returns:

Type Description
tuple[int, int]

tuple[int, int]: (<horizontal>, <vertical>)

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:

Name Type Description
Spacing 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:

Name Type Description
Spacing Spacing

Spacing(amount, 0, amount, 0)

width() property

Total space in width.

Returns:

Name Type Description
int int

Width.

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:

Name Type Description
T T

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