xnano.core.content

Shared visibility and stacking state for composed content.

Attributes:

• style (Style | None) –

  Optional shared style.

• z (int) –

  Sibling-local paint order.

• visible (bool) –

  Whether this content paints.

style: Style | None = None

z: int = 0

visible: bool = True

Bases: ContentBase

One styled text run.

Attributes:

• text (str) –

  Text displayed by the run.

• foreground (ColorLike | None) –

  Foreground color.

• background (ColorLike | None) –

  Background color.

• modifiers (tuple[CharacterModifier, ...]) –

  Character modifiers.

text: str

foreground: ColorLike | None = None

background: ColorLike | None = None

modifiers: tuple[CharacterModifier, ...] = ()

style: Style | None = None

z: int = 0

visible: bool = True

__post_init__(color: Any) -> None

83
84
85

def __post_init__(self, color: Any) -> None:
    """Apply the deprecated constructor alias."""
    resolve_init_alias(self, color, old="color", new="foreground")

plain(
    text: str,
    *,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
    color: ColorLike | None = None
) -> "Run"

 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

@classmethod
def plain(
    cls,
    text: str,
    *,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
    color: ColorLike | None = None,
) -> "Run":
    """Create a plain styled run.

    Args:
        text: Text displayed by the run.
        foreground: Foreground color.
        background: Background color.
        modifiers: Character modifiers.
        style: Optional shared style.
        z: Sibling-local paint order.
        visible: Whether the run paints.
        color: Deprecated alias for ``foreground``.

    Returns:
        A run containing ``text``.
    """
    foreground = resolve_color_alias(foreground, color, stacklevel=3)
    return cls(
        text=text,
        foreground=foreground,
        background=background,
        modifiers=tuple(modifiers or ()),
        style=style,
        z=z,
        visible=visible,
    )

Bases: ContentBase

Wrapped plain text or lines of styled runs.

Attributes:

• text (str) –

  Plain text content.

• lines (tuple[tuple[Run, ...], ...]) –

  Styled text lines.

• foreground (ColorLike | None) –

  Default foreground color.

• background (ColorLike | None) –

  Default background color.

• modifiers (tuple[CharacterModifier, ...]) –

  Default character modifiers.

• horizontal_align (Alignment | None) –

  Horizontal alignment.

• vertical_align (VerticalAlignment | None) –

  Vertical alignment within the painted area.

• wrap (bool) –

  Whether long lines wrap.

text: str = ''

lines: tuple[tuple[Run, ...], ...] = ()

foreground: ColorLike | None = None

background: ColorLike | None = None

modifiers: tuple[CharacterModifier, ...] = ()

horizontal_align: Alignment | None = None

vertical_align: VerticalAlignment | None = None

wrap: bool = True

style: Style | None = None

z: int = 0

visible: bool = True

__post_init__(color: Any, align: Any) -> None

168
169
170
171

def __post_init__(self, color: Any, align: Any) -> None:
    """Apply deprecated constructor aliases."""
    resolve_init_alias(self, color, old="color", new="foreground")
    resolve_init_alias(self, align, old="align", new="horizontal_align")

from_plain(
    text: str,
    *,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    horizontal_align: Alignment | None = None,
    vertical_align: VerticalAlignment | None = None,
    wrap: bool = True,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
    color: ColorLike | None = None
) -> "TextBlock"

173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205

@classmethod
def from_plain(
    cls,
    text: str,
    *,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    horizontal_align: Alignment | None = None,
    vertical_align: VerticalAlignment | None = None,
    wrap: bool = True,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
    color: ColorLike | None = None,
) -> "TextBlock":
    """Create a block from plain text and explicit style values.

    ``color`` is a deprecated alias for ``foreground``.
    """
    foreground = resolve_color_alias(foreground, color, stacklevel=3)
    return cls(
        text=text,
        foreground=foreground,
        background=background,
        modifiers=tuple(modifiers or ()),
        horizontal_align=horizontal_align,
        vertical_align=vertical_align,
        wrap=wrap,
        style=style,
        z=z,
        visible=visible,
    )

from_lines(
    lines: Sequence[Sequence[Run] | Run | str],
    *,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    horizontal_align: Alignment | None = None,
    vertical_align: VerticalAlignment | None = None,
    wrap: bool = True,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
    color: ColorLike | None = None
) -> "TextBlock"

207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247

@classmethod
def from_lines(
    cls,
    lines: Sequence[Sequence[Run] | Run | str],
    *,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    horizontal_align: Alignment | None = None,
    vertical_align: VerticalAlignment | None = None,
    wrap: bool = True,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
    color: ColorLike | None = None,
) -> "TextBlock":
    """Create a block from styled line sequences.

    ``color`` is a deprecated alias for ``foreground``.
    """
    foreground = resolve_color_alias(foreground, color, stacklevel=3)
    normalized: list[tuple[Run, ...]] = []
    for line in lines:
        if isinstance(line, str):
            normalized.append((Run(text=line),))
        elif isinstance(line, Run):
            normalized.append((line,))
        else:
            normalized.append(tuple(line))
    return cls(
        lines=tuple(normalized),
        foreground=foreground,
        background=background,
        modifiers=tuple(modifiers or ()),
        horizontal_align=horizontal_align,
        vertical_align=vertical_align,
        wrap=wrap,
        style=style,
        z=z,
        visible=visible,
    )

Bases: ContentBase

Lay out child content in one direction.

Attributes:

• children (tuple[ContentBase, ...]) –

  Child content.

• direction (Direction) –

  Layout direction.

• gap (int) –

  Cells between children.

children: tuple[ContentBase, ...] = ()

direction: Direction = 'vertical'

gap: int = 0

style: Style | None = None

z: int = 0

visible: bool = True

Bases: ContentBase

Decorate child content with a frame and padding.

Attributes:

• child (ContentBase) –

  Content inside the panel.

• title (str | None) –

  Optional frame title.

• title_position (FrameTitlePosition | None) –

  Frame title alignment.

• border (Border | None) –

  Border style.

• border_color (ColorLike | None) –

  Border foreground color.

• border_sides (tuple[Side, ...] | None) –

  Visible border sides.

• background (ColorLike | None) –

  Panel background color.

• padding (PaddingLike | None) –

  Space between border and child.

child: ContentBase

title: str | None = None

title_position: FrameTitlePosition | None = None

border: Border | None = None

border_color: ColorLike | None = None

border_sides: tuple[Side, ...] | None = None

background: ColorLike | None = None

padding: PaddingLike | None = None

style: Style | None = None

z: int = 0

visible: bool = True

Bases: ContentBase

Render a filled progress gauge.

Attributes:

• progress (float) –

  Completion ratio from zero to one.

• label (str | None) –

  Text displayed inside the gauge.

• foreground (ColorLike) –

  Filled-region color.

• background (ColorLike | None) –

  Gauge background color.

progress: float = 0.0

label: str | None = None

foreground: ColorLike = 'green'

background: ColorLike | None = None

style: Style | None = None

z: int = 0

visible: bool = True

Bases: ContentBase

Render progress as a single horizontal line.

Attributes:

• progress (float) –

  Completion ratio from zero to one.

• label (str | None) –

  Text displayed with the line.

• foreground (ColorLike | None) –

  Default foreground color.

• filled_color (ColorLike | None) –

  Completed-region color.

• unfilled_color (ColorLike | None) –

  Remaining-region color.

• background (ColorLike | None) –

  Line background color.

progress: float = 0.0

label: str | None = None

foreground: ColorLike | None = None

filled_color: ColorLike | None = None

unfilled_color: ColorLike | None = None

background: ColorLike | None = None

style: Style | None = None

z: int = 0

visible: bool = True

One value in a bar chart.

Attributes:

• value (int) –

  Numeric bar value.

• label (str) –

  Label beneath the bar.

• text_value (str | None) –

  Displayed value override.

• color (ColorLike | None) –

  Bar color.

• value_color (ColorLike | None) –

  Value-label color.

value: int

label: str = ''

text_value: str | None = None

color: ColorLike | None = None

value_color: ColorLike | None = None

A labeled group of chart bars.

Attributes:

• bars (tuple[Bar, ...]) –

  Bars in this group.

• label (str | None) –

  Group label.

bars: tuple[Bar, ...] = ()

label: str | None = None

Bases: ContentBase

Render grouped bars.

Attributes:

• groups (tuple[BarGroup, ...]) –

  Bar groups.

• bar_width (int) –

  Width of each bar in cells.

• bar_gap (int) –

  Cells between bars.

• group_gap (int) –

  Cells between groups.

• max_value (int | None) –

  Explicit value ceiling.

• direction (Direction) –

  Bar growth direction.

• color (ColorLike | None) –

  Default bar color.

• value_color (ColorLike | None) –

  Default value-label color.

• label_color (ColorLike | None) –

  Bar-label color.

groups: tuple[BarGroup, ...] = ()

bar_width: int = 1

bar_gap: int = 1

group_gap: int = 0

max_value: int | None = None

direction: Direction = 'vertical'

color: ColorLike | None = None

value_color: ColorLike | None = None

label_color: ColorLike | None = None

style: Style | None = None

z: int = 0

visible: bool = True

One named data series in a plot.

Attributes:

• data (tuple[tuple[float, float], ...]) –

  Plot coordinates.

• name (str | None) –

  Legend label.

• color (ColorLike | None) –

  Series color.

• marker (CanvasMarkerLike | None) –

  Point marker.

• graph_type (GraphTypeLike) –

  Line, bar, or scatter representation.

data: tuple[tuple[float, float], ...] = ()

name: str | None = None

color: ColorLike | None = None

marker: CanvasMarkerLike | None = None

graph_type: GraphTypeLike = 'line'

Labels and bounds for one plot axis.

Attributes:

• title (str | None) –

  Axis title.

• bounds (tuple[float, float] | None) –

  Minimum and maximum values.

• labels (tuple[str, ...] | None) –

  Tick labels.

• color (ColorLike | None) –

  Axis color.

title: str | None = None

bounds: tuple[float, float] | None = None

labels: tuple[str, ...] | None = None

color: ColorLike | None = None

Bases: ContentBase

Render one or more numeric data series.

Attributes:

• datasets (tuple[PlotDataset, ...]) –

  Data series.

• x_axis (PlotAxis | None) –

  Horizontal axis.

• y_axis (PlotAxis | None) –

  Vertical axis.

• color (ColorLike | None) –

  Default plot color.

• legend (bool) –

  Whether to show the legend.

• legend_position (LegendPositionLike | None) –

  Legend placement.

datasets: tuple[PlotDataset, ...] = ()

x_axis: PlotAxis | None = None

y_axis: PlotAxis | None = None

color: ColorLike | None = None

legend: bool = True

legend_position: LegendPositionLike | None = 'top_right'

style: Style | None = None

z: int = 0

visible: bool = True

One individually styled sparkline sample.

Attributes:

• value (int) –

  Sample value.

• color (ColorLike | None) –

  Sample color.

value: int

color: ColorLike | None = None

Bases: ContentBase

Render a compact sequence of vertical samples.

Attributes:

• data (tuple[int, ...]) –

  Sample values.

• bars (tuple[SparklineBar, ...] | None) –

  Individually styled samples.

• max_value (int | None) –

  Explicit sample ceiling.

• foreground (ColorLike | None) –

  Default sample color.

• background (ColorLike | None) –

  Sparkline background.

• absent_value_color (ColorLike | None) –

  Color for missing or zero samples.

• absent_value_symbol (str | None) –

  Symbol for missing or zero samples.

data: tuple[int, ...] = ()

bars: tuple[SparklineBar, ...] | None = None

max_value: int | None = None

foreground: ColorLike | None = None

background: ColorLike | None = None

absent_value_color: ColorLike | None = None

absent_value_symbol: str | None = None

style: Style | None = None

z: int = 0

visible: bool = True

Styled content in one table column.

Attributes:

• content (str | Run | TextBlock) –

  Cell content.

• foreground (ColorLike | None) –

  Foreground color.

• background (ColorLike | None) –

  Background color.

• modifiers (tuple[CharacterModifier, ...]) –

  Character modifiers.

content: str | Run | TextBlock = ''

foreground: ColorLike | None = None

background: ColorLike | None = None

modifiers: tuple[CharacterModifier, ...] = ()

One styled table row.

Attributes:

• cells (tuple[TableCell | str, ...]) –

  Cells in column order.

• foreground (ColorLike | None) –

  Default row foreground.

• background (ColorLike | None) –

  Default row background.

• height (int) –

  Row height in cells.

cells: tuple[TableCell | str, ...] = ()

foreground: ColorLike | None = None

background: ColorLike | None = None

height: int = 1

Bases: ContentBase

Render tabular rows with optional selection.

Attributes:

• rows (tuple[TableRow, ...]) –

  Body rows.

• header (TableRow | None) –

  Optional header row.

• footer (TableRow | None) –

  Optional footer row.

• column_widths (tuple[int | float, ...] | None) –

  Fixed cell widths or fractional widths.

• column_spacing (int) –

  Cells between columns.

• selected_row (int | None) –

  Selected body row.

• selected_column (int | None) –

  Selected column.

• highlight_color (ColorLike | None) –

  Selection foreground.

• highlight_background (ColorLike | None) –

  Selection background.

• highlight_symbol (str | None) –

  Symbol prefixed to the selected row.

rows: tuple[TableRow, ...] = ()

header: TableRow | None = None

footer: TableRow | None = None

column_widths: tuple[int | float, ...] | None = None

column_spacing: int = 1