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
¶
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)
¶
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
¶
bottom_left: Offset
property
¶
bottom_right: Offset
property
¶
column_range: range
property
¶
A range object for X coordinates.
column_span: tuple[int, int]
property
¶
corners: tuple[int, int, int, int]
property
¶
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
¶
offset: Offset
property
¶
reset_offset: Region
property
¶
size: Size
property
¶
top_right: Offset
property
¶
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)
¶
clip(width, height)
¶
clip_size(size)
¶
contains(x, y)
¶
contains_point(point)
¶
contains_region(other)
cached
¶
crop_size(size)
¶
expand(size)
¶
from_corners(x1, y1, x2, y2)
classmethod
¶
from_offset(offset, size)
classmethod
¶
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
¶
intersection(region)
cached
¶
overlaps(other)
cached
¶
shrink(margin)
cached
¶
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.
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.
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
¶
Size
¶
Bases: NamedTuple
The dimensions of a rectangular 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
¶
css: str
property
¶
Gets a string containing the spacing in CSS format.
Returns:
Type | Description |
---|---|
str
|
Spacing in CSS format. |
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
¶
totals: tuple[int, int]
property
¶
all(amount)
classmethod
¶
grow_maximum(other)
¶
horizontal(amount)
classmethod
¶
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 |
Returns:
Type | Description |
---|---|
Spacing
|
New Spacing object. |
vertical(amount)
classmethod
¶
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. |