Geometry
Functions and classes to manage terminal geometry (anything involving coordinates or dimensions).
NULL_REGION
module-attribute
¶
A Region constant for a null region (at the origin, with both width and height set to zero).
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.
Offset
class
¶
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
blend
method
¶
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. |
Region
class
¶
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
bottom_left
property
¶
bottom_right
property
¶
center
property
¶
column_span
property
¶
A pair of integers for the start and end columns (x coordinates) in this region.
The end value is exclusive.
corners
property
¶
The top left and bottom right coordinates as a tuple of four integers.
line_span
property
¶
A pair of integers for the start and end lines (y coordinates) in this region.
The end value is exclusive.
offset
property
¶
reset_offset
property
¶
top_right
property
¶
at_offset
method
¶
clip
method
¶
clip_size
method
¶
contains
method
¶
contains_point
method
¶
contains_region
cached
¶
crop_size
method
¶
expand
method
¶
from_corners
classmethod
¶
from_offset
classmethod
¶
from_union
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
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. |
False
|
Returns
Type | Description |
---|---|
Offset
|
An offset required to add to region to move it inside window_region. |
grow
cached
¶
inflect
method
¶
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
¶
overlaps
cached
¶
shrink
cached
¶
split
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
cached
¶
Split a region in to two, from a given y offset.
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 a region in to two, from a given x offset.
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_inside
method
¶
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. |
Size
class
¶
Bases: NamedTuple
The dimensions (width and height) of a rectangular region.
Example
contains
method
¶
Spacing
class
¶
Bases: NamedTuple
The spacing around a renderable, 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
bottom_right
property
¶
A pair of integers for the right, and bottom space.
css
property
¶
A string containing the spacing in CSS format.
For example: "1" or "2 4" or "4 2 8 2".
totals
property
¶
A pair of integers for the total horizontal and vertical space.
all
classmethod
¶
grow_maximum
method
¶
horizontal
classmethod
¶
unpack
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 |
Returns
Type | Description |
---|---|
Spacing
|
New Spacing object. |
vertical
classmethod
¶
clamp
function
¶
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. |