textual.geometry

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

NULL_OFFSET `module-attribute` ¶

NULL_OFFSET = Offset(0, 0)

An offset constant for (0, 0).

NULL_REGION `module-attribute` ¶

NULL_REGION = Region(0, 0, 0, 0)

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

NULL_SIZE `module-attribute` ¶

NULL_SIZE = Size(0, 0)

A Size constant for a null size (with zero area).

NULL_SPACING `module-attribute` ¶

NULL_SPACING = Spacing(0, 0, 0, 0)

A Spacing constant for no space.

SpacingDimensions `module-attribute` ¶

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

The valid ways in which you can specify spacing.

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.

Offsets support addition, subtraction, multiplication, and negation.

Example

>>> from textual.geometry import Offset
>>> offset = Offset(3, 2)
>>> offset
Offset(x=3, y=2)
>>> offset += Offset(10, 0)
>>> offset
Offset(x=13, y=2)
>>> -offset
Offset(x=-13, y=-2)

clamped `property` ¶

clamped

This offset with x and y restricted to values above zero.

is_origin `property` ¶

is_origin

Is the offset at (0, 0)?

x `class-attribute` `instance-attribute` ¶

x = 0

Offset in the x-axis (horizontal)

y `class-attribute` `instance-attribute` ¶

y = 0

Offset in the y-axis (vertical)

blend ¶

blend(destination, factor)

Calculate a new offset on a line between this offset and a destination offset.

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.

clamp ¶

clamp(width, height)

Clamp the offset to fit within a rectangle of width x height.

Parameters:

Name	Type	Description	Default
`width` ¶	`int`	Width to clamp.	required
`height` ¶	`int`	Height to clamp.	required

Returns:

Type	Description
`Offset`	A new offset.

get_distance_to ¶

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

Example

>>> from textual.geometry import Region
>>> region = Region(4, 5, 20, 10)
>>> region
Region(x=4, y=5, width=20, height=10)
>>> region.area
200
>>> region.size
Size(width=20, height=10)
>>> region.offset
Offset(x=4, y=5)
>>> region.contains(1, 2)
False
>>> region.contains(10, 8)
True

area `property` ¶

area

The area under the region.

bottom `property` ¶

bottom

Maximum Y value (non inclusive).

bottom_left `property` ¶

bottom_left

Bottom left offset of the region.

Returns:

Type	Description
`Offset`	An offset.

bottom_right `property` ¶

bottom_right

Bottom right offset of the region.

Returns:

Type	Description
`Offset`	An offset.

center `property` ¶

center

The center of the region.

Note, that this does not return an Offset, because the center may not be an integer coordinate.

Returns:

Type	Description
`tuple[float, float]`	Tuple of floats.

column_range `property` ¶

column_range

A range object for X coordinates.

column_span `property` ¶

column_span

A pair of integers for the start and end columns (x coordinates) in this region.

The end value is exclusive.

corners `property` ¶

corners

The top left and bottom right coordinates as a tuple of four integers.

height `class-attribute` `instance-attribute` ¶

height = 0

The height of the region.

line_range `property` ¶

line_range

A range object for Y coordinates.

line_span `property` ¶

line_span

A pair of integers for the start and end lines (y coordinates) in this region.

The end value is exclusive.

offset `property` ¶

offset

The top left corner of the region.

Returns:

Type	Description
`Offset`	An offset.

reset_offset `property` ¶

reset_offset

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

Returns:

Type	Description
`Region`	A region at the origin.

right `property` ¶

right

Maximum X value (non inclusive).

size `property` ¶

size

Get the size of the region.

top_right `property` ¶

top_right

Top right offset of the region.

Returns:

Type	Description
`Offset`	An offset.

width `class-attribute` `instance-attribute` ¶

width = 0

The width of the region.

x `class-attribute` `instance-attribute` ¶

x = 0

Offset in the x-axis (horizontal).

y `class-attribute` `instance-attribute` ¶

y = 0

Offset in the y-axis (vertical).

at_offset ¶

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 ¶

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 ¶

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 ¶

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 ¶

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 `cached` ¶

contains_region(other)

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 ¶

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 ¶

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 `classmethod` ¶

from_corners(x1, y1, x2, y2)

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 `classmethod` ¶

from_offset(offset, size)

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 `classmethod` ¶

from_union(regions)

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 `classmethod` ¶

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

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.	`False`

Returns:

Type	Description
`Offset`	An offset required to add to region to move it inside window_region.

grow `cached` ¶

grow(margin)

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.

inflect ¶

inflect(x_axis=+1, y_axis=+1, margin=None)

Inflect a region around one or both axis.

The x_axis and y_axis parameters define which direction to move the region. A positive value will move the region right or down, a negative value will move the region left or up. A value of 0 will leave that axis unmodified.

╔══════════╗    │
║          ║
║   Self   ║    │
║          ║
╚══════════╝    │

─ ─ ─ ─ ─ ─ ─ ─ ┼ ─ ─ ─ ─ ─ ─ ─ ─

                │    ┌──────────┐
                     │          │
                │    │  Result  │
                     │          │
                │    └──────────┘

Parameters:

Name	Type	Description	Default
`x_axis` ¶	`int`	+1 to inflect in the positive direction, -1 to inflect in the negative direction.	`+1`
`y_axis` ¶	`int`	+1 to inflect in the positive direction, -1 to inflect in the negative direction.	`+1`
`margin` ¶	`Spacing \| None`	Additional margin.	`None`

Returns:

Type	Description
`Region`	A new region.

intersection `cached` ¶

intersection(region)

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 `cached` ¶

overlaps(other)

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 `cached` ¶

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:

Type	Description
`Region`	The new, smaller region.

split `cached` ¶

split(cut_x, cut_y)

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 `cached` ¶

split_horizontal(cut)

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

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

Parameters:

Name	Type	Description	Default
`cut` ¶	`int`	An offset from self.y where the cut should be made. May be negative, for the offset to start from the lower edge.	required

Returns:

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

split_vertical `cached` ¶

split_vertical(cut)

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 `cached` ¶

translate(offset)

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)

translate_inside ¶

translate_inside(container, x_axis=True, y_axis=True)

Translate this region, so it fits within a container.

This will ensure that there is as little overlap as possible. The top left of the returned region is guaranteed to be within the container.

┌──────────────────┐         ┌──────────────────┐
│    container     │         │    container     │
│                  │         │    ┌─────────────┤
│                  │   ──▶   │    │    return   │
│       ┌──────────┴──┐      │    │             │
│       │    self     │      │    │             │
└───────┤             │      └────┴─────────────┘
        │             │
        └─────────────┘

Parameters:

Name	Type	Description	Default
`container` ¶	`Region`	A container region.	required
`x_axis` ¶	`bool`	Allow translation of X axis.	`True`
`y_axis` ¶	`bool`	Allow translation of Y axis.	`True`

Returns:

Type	Description
`Region`	A new region with same dimensions that fits with inside container.

union `cached` ¶

union(region)

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 (width and height) of a rectangular region.

Example

>>> from textual.geometry import Size
>>> size = Size(2, 3)
>>> size
Size(width=2, height=3)
>>> size.area
6
>>> size + Size(10, 20)
Size(width=12, height=23)

area `property` ¶

area

The area occupied by a region of this size.

height `class-attribute` `instance-attribute` ¶

height = 0

The height in cells.

line_range `property` ¶

line_range

A range object that covers values between 0 and height.

region `property` ¶

region

A region of the same size, at the origin.

width `class-attribute` `instance-attribute` ¶

width = 0

The width in cells.

clamp_offset ¶

clamp_offset(offset)

Clamp an offset to fit within the width x height.

Parameters:

Name	Type	Description	Default
`offset` ¶	`Offset`	An offset.	required

Returns:

Type	Description
`Offset`	A new offset that will fit inside the dimensions defined in the Size.

contains ¶

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 ¶

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.

with_height ¶

with_height(height)

Get a new Size with just the height changed.

Parameters:

Name	Type	Description	Default
`width` ¶		New height.	required

Returns:

Type	Description
`Size`	New Size instance.

with_width ¶

with_width(width)

Get a new Size with just the width changed.

Parameters:

Name	Type	Description	Default
`width` ¶	`int`	New width.	required

Returns:

Type	Description
`Size`	New Size instance.

Spacing ¶

Bases: NamedTuple

Stores spacing around a widget, such as padding and border.

Spacing is defined by four integers for the space at the top, right, bottom, and left of a region.

┌ ─ ─ ─ ─ ─ ─ ─▲─ ─ ─ ─ ─ ─ ─ ─ ┐
               │ top
│        ┏━━━━━▼━━━━━━┓         │
 ◀──────▶┃            ┃◀───────▶
│  left  ┃            ┃ right   │
         ┃            ┃
│        ┗━━━━━▲━━━━━━┛         │
               │ bottom
└ ─ ─ ─ ─ ─ ─ ─▼─ ─ ─ ─ ─ ─ ─ ─ ┘

Example

>>> from textual.geometry import Region, Spacing
>>> region = Region(2, 3, 20, 10)
>>> spacing = Spacing(1, 2, 3, 4)
>>> region.grow(spacing)
Region(x=-2, y=2, width=26, height=14)
>>> region.shrink(spacing)
Region(x=6, y=4, width=14, height=6)
>>> spacing.css
'1 2 3 4'

bottom `class-attribute` `instance-attribute` ¶

bottom = 0

Space from the bottom of a region.

bottom_right `property` ¶

bottom_right

A pair of integers for the right, and bottom space.

css `property` ¶

css

A string containing the spacing in CSS format.

For example: "1" or "2 4" or "4 2 8 2".

height `property` ¶

height

Total space in the y axis.

left `class-attribute` `instance-attribute` ¶

left = 0

Space from the left of a region.

right `class-attribute` `instance-attribute` ¶

right = 0

Space from the right of a region.

top `class-attribute` `instance-attribute` ¶

top = 0

Space from the top of a region.

top_left `property` ¶

top_left

A pair of integers for the left, and top space.

totals `property` ¶

totals

A pair of integers for the total horizontal and vertical space.

width `property` ¶

width

Total space in the x axis.

all `classmethod` ¶

all(amount)

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 ¶

grow_maximum(other)

Grow spacing with a maximum.

Parameters:

Name	Type	Description	Default
`other` ¶	`Spacing`	Spacing object.	required

Returns:

Type	Description
`Spacing`	New spacing where the values are maximum of the two values.

horizontal `classmethod` ¶

horizontal(amount)

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 `classmethod` ¶

unpack(pad)

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 `classmethod` ¶

vertical(amount)

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 ¶

clamp(value, minimum, maximum)

Adjust a value so 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.

textual.geometry

NULL_OFFSET module-attribute ¶

NULL_REGION module-attribute ¶

NULL_SIZE module-attribute ¶

NULL_SPACING module-attribute ¶

SpacingDimensions module-attribute ¶

Offset ¶

clamped property ¶

is_origin property ¶

x class-attribute instance-attribute ¶

y class-attribute instance-attribute ¶

blend ¶

destination ¶

factor ¶

clamp ¶

width ¶

height ¶

get_distance_to ¶

other ¶

Region ¶

area property ¶

bottom property ¶

bottom_left property ¶

bottom_right property ¶

center property ¶

column_range property ¶

column_span property ¶

corners property ¶

height class-attribute instance-attribute ¶

line_range property ¶

line_span property ¶

offset property ¶

reset_offset property ¶

right property ¶

size property ¶

top_right property ¶

width class-attribute instance-attribute ¶

x class-attribute instance-attribute ¶

y class-attribute instance-attribute ¶

at_offset ¶

offset ¶

clip ¶

width ¶

height ¶

clip_size ¶

size ¶

contains ¶

x ¶

y ¶

contains_point ¶

point ¶

contains_region cached ¶

other ¶

crop_size ¶

size ¶

expand ¶

size ¶

from_corners classmethod ¶

x1 ¶

y1 ¶

x2 ¶

y2 ¶

from_offset classmethod ¶

offset ¶

size ¶

from_union classmethod ¶

regions ¶

get_scroll_to_visible classmethod ¶

window_region ¶

region ¶

top ¶

grow cached ¶

margin ¶

inflect ¶

x_axis ¶

y_axis ¶

margin ¶

intersection cached ¶

region ¶

overlaps cached ¶

NULL_OFFSET `module-attribute` ¶

NULL_REGION `module-attribute` ¶

NULL_SIZE `module-attribute` ¶

NULL_SPACING `module-attribute` ¶

SpacingDimensions `module-attribute` ¶

clamped `property` ¶

is_origin `property` ¶

x `class-attribute` `instance-attribute` ¶

y `class-attribute` `instance-attribute` ¶

`destination` ¶

`factor` ¶

`width` ¶

`height` ¶

`other` ¶

area `property` ¶

bottom `property` ¶

bottom_left `property` ¶

bottom_right `property` ¶

center `property` ¶

column_range `property` ¶

column_span `property` ¶

corners `property` ¶

height `class-attribute` `instance-attribute` ¶

line_range `property` ¶

line_span `property` ¶

offset `property` ¶

reset_offset `property` ¶

right `property` ¶

size `property` ¶

top_right `property` ¶

width `class-attribute` `instance-attribute` ¶

x `class-attribute` `instance-attribute` ¶

y `class-attribute` `instance-attribute` ¶

`offset` ¶

`width` ¶

`height` ¶

`size` ¶

`x` ¶

`y` ¶

`point` ¶

contains_region `cached` ¶

`other` ¶

`size` ¶

`size` ¶

from_corners `classmethod` ¶

`x1` ¶

`y1` ¶

`x2` ¶

`y2` ¶

from_offset `classmethod` ¶

`offset` ¶

`size` ¶

from_union `classmethod` ¶

`regions` ¶

get_scroll_to_visible `classmethod` ¶

`window_region` ¶

`region` ¶

`top` ¶

grow `cached` ¶

`margin` ¶

`x_axis` ¶

`y_axis` ¶

`margin` ¶

intersection `cached` ¶

`region` ¶

overlaps `cached` ¶

`other` ¶

shrink `cached` ¶

`margin` ¶

split `cached` ¶

`cut_x` ¶

`cut_y` ¶

split_horizontal `cached` ¶

`cut` ¶

split_vertical `cached` ¶

`cut` ¶

translate `cached` ¶

`offset` ¶

`container` ¶

`x_axis` ¶