diff --git a/src/textual/color.py b/src/textual/color.py index e4bf7e404..ca1307500 100644 --- a/src/textual/color.py +++ b/src/textual/color.py @@ -1,10 +1,11 @@ """ -This module contains a powerful Color class which Textual uses to expose colors. +This module contains a powerful [Color][textual.color.Color] class which Textual uses to manipulate colors. ## Named colors The following named colors are used by the [parse][textual.color.Color.parse] method. + ```{.rich columns="80" title="colors"} from textual._color_constants import COLOR_NAME_TO_RGB from textual.color import Color @@ -41,8 +42,6 @@ import rich.repr from rich.color import Color as RichColor from rich.color import ColorType from rich.color_triplet import ColorTriplet -from rich.style import Style -from rich.text import Text from typing_extensions import Final from textual.css.scalar import percentage_string_to_float @@ -143,6 +142,22 @@ class Color(NamedTuple): Colors are stored as three values representing the degree of red, green, and blue in a color, and a fourth "alpha" value which defines where the color lies on a gradient of opaque to transparent. + Example: + ```python + >>> from textual.color import Color + >>> color = Color.parse("red") + >>> color + Color(255, 0, 0) + >>> color.darken(0.5) + Color(98, 0, 0) + >>> color + Color.parse("green") + Color(0, 128, 0) + >>> color_with_alpha = Color(100, 50, 25, 0.5) + >>> color_with_alpha + Color(100, 50, 25, a=0.5) + >>> color + color_with_alpha + Color(177, 25, 12) + ``` """ @@ -185,7 +200,12 @@ class Color(NamedTuple): @property def inverse(self) -> Color: - """The inverse of this color.""" + """The inverse of this color. + + Returns: + Inverse color. + + """ r, g, b, a = self return Color(255 - r, 255 - g, 255 - b, a) @@ -242,6 +262,9 @@ class Color(NamedTuple): HSL color is an alternative way of representing a color, which can be used in certain color calculations. + Returns: + Color encoded in HSL format. + """ r, g, b = self.normalized h, l, s = rgb_to_hls(r, g, b) @@ -295,7 +318,12 @@ class Color(NamedTuple): @property def monochrome(self) -> Color: - """A monochrome version of this color.""" + """A monochrome version of this color. + + Returns: + The monochrome (black and white) version of this color. + + """ r, g, b, a = self gray = round(r * 0.2126 + g * 0.7152 + b * 0.0722) return Color(gray, gray, gray, a) diff --git a/src/textual/geometry.py b/src/textual/geometry.py index 7a52eb7b7..4ebb0e17f 100644 --- a/src/textual/geometry.py +++ b/src/textual/geometry.py @@ -61,6 +61,21 @@ class Offset(NamedTuple): 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: + ```python + >>> 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) + ``` + """ x: int = 0 @@ -139,7 +154,21 @@ class Offset(NamedTuple): class Size(NamedTuple): - """The dimensions of a rectangular region.""" + """The dimensions (width and height) of a rectangular region. + + Example: + ```python + >>> 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) + ``` + + """ width: int = 0 """The width in cells.""" @@ -237,6 +266,24 @@ class Region(NamedTuple): ◀─────── width ──────▶ ``` + Example: + ```python + >>> 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 + ``` + """ x: int = 0 @@ -831,7 +878,24 @@ class Region(NamedTuple): class Spacing(NamedTuple): - """The spacing around a renderable.""" + """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, + + Example: + ```python + >>> 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' + ``` + + """ top: int = 0 """Space from the top of a region."""