xnano.widgets

def __setitem__(self, key: Coordinate, value: Cell | str) -> None:
    """
    Replace one cell with a ``Cell`` or a single grapheme.

    Examples:
        ```python
        buffer = Buffer(width=3, height=1)
        buffer[2, 0] = 'z'
        buffer[0, 0] = Cell('a', foreground='green')
        assert buffer.text == 'a z'
        ```
    """

def write(
    self,
    text: TextContent,
    *,
    x: int = 0,
    y: int = 0,
    style: Style | None = None,
    mode: WriteMode = 'replace',
) -> None:
    """
    Write text starting at a cell.

    Text is clipped by display columns, whole graphemes are kept together and the
    continuation cells of wide characters are repaired.

    Args:
        text: A string or styled text.
        x: The starting column.
        y: The starting row.
        style: A style applied to the written cells.
        mode: ``'replace'`` overwrites the cell; ``'preserve_background'`` keeps
            the background already there.

    Examples:
        ```python
        buffer = Buffer(width=6, height=2)
        buffer.write('hi', x=1, y=0, style=Style(foreground='red'))
        assert buffer[1, 0].foreground == Color('red')
        assert buffer.text.split('\\n')[0] == ' hi'
        ```
    """

def fill(self, cell: Cell | str = ' ') -> None:
    """
    Set every cell of the surface.

    Examples:
        ```python
        buffer = Buffer(width=3, height=1)
        buffer.fill('#')
        assert buffer.text == '###'
        ```
    """

def set_background_colors(
    self,
    colors: Sequence[ColorValue | None],
    *,
    width: int,
    x: int = 0,
    y: int = 0,
) -> None:
    """
    Set the background color of a block of cells in one pass.

    Symbols and foreground colors are kept, and the whole block counts as one change (the
    revision grows by one).

    Args:
        colors: A flat, row-major sequence of colors (names, ``(r, g, b)`` tuples or
            [`Color`][xnano_core._xnano_core.Color] values). ``None`` leaves a cell alone.
        width: The number of colors in one row of ``colors``.
        x: The column of the block's top-left cell in this surface.
        y: The row of the block's top-left cell in this surface.

    Raises:
        ValueError: ``width`` is below 1, ``len(colors)`` is not a multiple of ``width``, or
            the block does not fit inside the surface, or an entry is not a color.
        TypeError: ``colors`` is a single string instead of a sequence of colors, or an
            entry has no color meaning.

    Examples:
        ```python
        buffer = Buffer(width=3, height=2)
        buffer.write('abc')
        buffer.set_background_colors(['red', None, (0, 0, 255), 'green'], width=2, x=1)
        assert buffer[1, 0].background == Color('red')
        assert buffer[2, 0].background == Color.reset
        assert buffer[1, 1].background == Color('#0000ff')
        assert buffer[2, 1].background == Color('green')
        assert buffer[1, 0].symbol == 'b'
        ```
    """

def set_foreground_colors(
    self,
    colors: Sequence[ColorValue | None],
    *,
    width: int,
    x: int = 0,
    y: int = 0,
) -> None:
    """
    Set the foreground color of a block of cells in one pass.

    Symbols and background colors are kept, and the whole block counts as one change (the
    revision grows by one).

    Args:
        colors: A flat, row-major sequence of colors (names, ``(r, g, b)`` tuples or
            [`Color`][xnano_core._xnano_core.Color] values). ``None`` leaves a cell alone.
        width: The number of colors in one row of ``colors``.
        x: The column of the block's top-left cell in this surface.
        y: The row of the block's top-left cell in this surface.

    Raises:
        ValueError: ``width`` is below 1, ``len(colors)`` is not a multiple of ``width``, or
            the block does not fit inside the surface, or an entry is not a color.
        TypeError: ``colors`` is a single string instead of a sequence of colors, or an
            entry has no color meaning.

    Examples:
        ```python
        buffer = Buffer(width=3, height=2)
        buffer.write('abc')
        buffer.set_foreground_colors(['red', None, (0, 0, 255), 'green'], width=2, x=1)
        assert buffer[1, 0].foreground == Color('red')
        assert buffer[2, 0].foreground == Color.reset
        assert buffer[1, 1].foreground == Color('#0000ff')
        assert buffer[2, 1].foreground == Color('green')
        assert buffer[1, 0].symbol == 'b'
        ```
    """

def pixels(self, *, encoding: PixelEncoding = 'half_blocks') -> PixelView:
    """
    Return a pixel view that draws into this surface.

    Args:
        encoding: ``'half_blocks'`` for one column and two rows per cell or
            ``'braille'`` for two columns and four rows per cell.

    Examples:
        ```python
        buffer = Buffer(width=3, height=2)
        assert (buffer.pixels().width, buffer.pixels().height) == (3, 4)
        assert (buffer.pixels(encoding='braille').width) == 6
        ```
    """

def update(self, *operations: Operation) -> None:
    """
    Apply operations in argument order.

    Raises:
        UnsupportedOperationError: The surface's registry cannot apply an operation.
        RuntimeRequiredError: An operation needs a mounted buffer on a runtime.

    Examples:
        ```python
        buffer = Buffer(width=8, height=3)
        buffer.update(Border('rounded'), Write('hi', x=1, y=1))
        assert buffer[0, 0].symbol == '╭'
        assert buffer[1, 1].symbol == 'h'
        ```
    """

def inspect(self, expression: Expression[ValueType]) -> ValueType:
    """
    Evaluate an expression against this surface and return its value.

    Examples:
        ```python
        width = _reference('Width', 'numeric_property')
        height = _reference('Height', 'numeric_property')
        buffer = Buffer(width=8, height=3)
        assert buffer.inspect(width) == 8
        assert buffer.inspect(width * height) == 24
        ```
    """

def supports(self, operation: type[Operation]) -> bool:
    """
    Return whether the buffer's registry can apply an operation type.

    Examples:
        ```python
        assert Buffer(width=1, height=1).supports(Fill)
        ```
    """

def add_hook(
    self,
    callback: HookCallback,
    *,
    condition: Predicate | None = None,
    events: Sequence[HookEventKind] = ('tick',),
    priority: int = 0,
    once: bool = False,
) -> Hook:
    """
    Run a callback when the runtime reports matching events for this surface.

    Args:
        callback: Called with a context for the event.
        condition: An expression that must be true for the callback to run.
        events: The event kinds to listen to.
        priority: Hooks with higher priority run first.
        once: Whether to remove the hook after its first run.

    Returns:
        The registered hook, which can be cancelled.

    Examples:
        ```python
        keys = []
        with Runtime.offscreen(width=10, height=2) as runtime:
            buffer = Buffer()
            runtime.mount(buffer, geometry='inherit')
            buffer.add_hook(lambda context: keys.append(context.event.key.key), events=['key'])
            runtime.dispatch(Event.key_press('a'))
            runtime.step()
        assert keys == ['a']
        ```
    """

def invalidate(self, area: Rectangle | None = None) -> None:
    """
    Ask the runtime to redraw an area, or the whole surface.

    Examples:
        ```python
        buffer = Buffer(width=4, height=2)
        buffer.invalidate(Rectangle(0, 0, 2, 1))
        ```
    """

def to_cell_grid(self) -> bytes:
    """
    Pack the surface into the cell grid byte format.

    Examples:
        ```python
        packed = Buffer.with_text('abc').to_cell_grid()
        assert cell_grid_to_text(packed) == ['abc']
        ```
    """

def __or__(self, operation: Operation | Style) -> Self:
    """
    Apply ``operation`` to this surface and return the surface.

    Examples:
        ```python
        buffer = Buffer(width=6, height=1) | Write('abc')
        assert buffer.text.startswith('abc')
        ```
    """

@classmethod
def with_text(cls, text: TextContent, *, style: Style | None = None) -> Buffer:
    """
    Create a buffer sized to fit some text.

    Examples:
        ```python
        buffer = Buffer.with_text('abc')
        assert (buffer.width, buffer.height) == (3, 1)
        ```
    """

@classmethod
def with_size(cls, width: int, height: int) -> Buffer:
    """
    Create a blank buffer of a given size.

    Examples:
        ```python
        assert Buffer.with_size(5, 2).width == 5
        ```
    """

@classmethod
def with_cells(cls, cells: Sequence[Cell], *, width: int, height: int) -> Buffer:
    """
    Create a buffer from cells in row-major order.

    Examples:
        ```python
        buffer = Buffer.with_cells([Cell('a'), Cell('b')], width=2, height=1)
        assert buffer.text == 'ab'
        ```
    """

@classmethod
def from_cell_grid(cls, packed: bytes) -> Buffer:
    """
    Create a buffer from the cell grid byte format.

    Raises:
        CellGridError: The bytes are not a valid cell grid.

    Examples:
        ```python
        packed = Buffer.with_text('hi').to_cell_grid()
        assert Buffer.from_cell_grid(packed).text == 'hi'
        ```
    """

@classmethod
def from_cell_animation(cls, packed: bytes, *, start_milliseconds: int = 0) -> Buffer:
    """
    Create a buffer showing one frame of a packed cell animation.

    Args:
        packed: The cell animation bytes.
        start_milliseconds: The point in the animation to show.

    Raises:
        CellGridError: The bytes are not a valid cell animation.

    Examples:
        ```python
        frames = [Buffer.with_text('a').to_cell_grid(), Buffer.with_text('b').to_cell_grid()]
        packed = pack_cell_animation(frames, frame_durations_milliseconds=[50, 50])
        assert Buffer.from_cell_animation(packed, start_milliseconds=60).text == 'b'
        ```
    """

def region(self, bounds: Rectangle) -> Region:
    """
    Return a region covering a rectangle of the buffer.

    Examples:
        ```python
        buffer = Buffer(width=4, height=2)
        assert buffer.region(Rectangle(1, 0, 2, 2)).bounds == Rectangle(1, 0, 2, 2)
        ```
    """

def resize(self, width: int, height: int) -> None:
    """
    Change the size, keeping the cells that still fit.

    Examples:
        ```python
        buffer = Buffer.with_text('abcd')
        buffer.resize(2, 1)
        assert buffer.text == 'ab'
        ```
    """

def paste(
    self,
    source: Buffer | Region,
    *,
    x: int = 0,
    y: int = 0,
    mode: PasteMode = 'replace',
) -> None:
    """
    Copy the cells of another buffer or region into this one.

    Args:
        source: The cells to copy.
        x: The destination column of the source's left edge.
        y: The destination row of the source's top edge.
        mode: ``'replace'`` copies every cell, ``'preserve_background'`` keeps
            the destination background and ``'transparent'`` skips cells that
            are marked transparent.

    Examples:
        ```python
        sprite = Buffer.with_text('ab')
        canvas = Buffer(width=5, height=1)
        canvas.paste(sprite, x=2)
        assert canvas.text == '  ab'
        ```
    """

def attach(
    self,
    child: Buffer,
    *,
    geometry: GeometryMode = 'explicit',
    mode: PasteMode = 'replace',
) -> None:
    """
    Attach a child buffer as a retained layer of this one.

    The child keeps its own cells and is composited when this buffer is drawn,
    ordered by ``layer`` and then by attachment order. A child with
    ``geometry='inherit'`` always fills the parent's content rectangle. The
    ``'transparent'`` mode skips cells explicitly marked transparent, not spaces.

    Raises:
        ValueError: The child already has a parent.

    Examples:
        ```python
        parent = Buffer(width=8, height=3)
        child = Buffer('hi', x=2, y=1)
        parent.attach(child)
        assert parent.children == (child,)
        assert parent.render(format='text').split('\\n')[1] == '  hi'
        ```
    """