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.