xnano.operations

def evaluate(self, context: EvaluationContext) -> ValueType_co:
    """
    Compute the expression's value.

    Examples:
        ```python
        from xnano_core._xnano_core import _reference

        width = _reference('Width', 'numeric_property')
        context = EvaluationContext(buffer=Buffer(width=5, height=1))
        assert (width * 2).evaluate(context) == 10
        ```
    """

def then(self, other: Operation) -> Operation:
    """
    An operation that applies this operation, then ``other``.

    Examples:
        ```python
        buffer = Buffer(width=6, height=1)
        buffer.update(Write('ab').then(Write('c', x=2)))
        assert buffer.text.startswith('abc')
        ```
    """

def when(self, condition: Predicate) -> Operation:
    """
    An operation that applies only while ``condition`` is true.

    Examples:
        ```python
        from xnano_core._xnano_core import _reference

        width = _reference('Width', 'numeric_property')
        buffer = Buffer(width=6, height=1)
        buffer.update(Write('wide').when(width > 4))
        assert buffer.text.startswith('wide')
        ```
    """

@staticmethod
def kinds() -> list[str]:
    """
    The name of every kind of customization.

    Examples:
        ```python
        assert 'style' in Customization.kinds()
        ```
    """

@staticmethod
def defaults(kind: str) -> dict[str, object]:
    """
    The parameter names of a kind with their defaults, in order.

    Raises:
        ValueError: ``kind`` is not a customization kind.

    Examples:
        ```python
        assert Customization.defaults('margin') == {'horizontal': 0, 'vertical': 0}
        ```
    """

def build(self) -> object:
    """
    The core object this customization stands for: a ``Style``, ``Border``, ``Effect``,
    ``Block``, ``Margin``, audio effect and so on, with all of its own methods.

    Examples:
        ```python
        assert isinstance(Customization('style', bold=True).build(), Style)
        ```
    """

def to_operation(self) -> Operation:
    """
    The core operation that applies this customization.

    Raises:
        TypeError: The kind is not applied as an operation, such as ``'block'``.
    """

def to_audio_effect(self) -> object:
    """
    The audio effect behind an ``'audio.*'`` customization.

    Raises:
        TypeError: The kind is not an audio effect.
    """

def apply_to_surface(self, surface: Surface) -> None:
    """Apply this customization to a buffer, widget or region."""

def apply_to(
    self,
    target: Canvas[object, object] | Placement[object, object] | _core.Surface,
) -> None:
    """
    Apply this customization to a canvas, placement or surface.

    It stays attached to the target: after this, assigning one of its fields applies it
    again, so a customization from ``fx`` is a live handle on what it changed. A running
    effect is stopped and started again with the new values.

    Args:
        target: The target to apply the customization to.
    """
    from xnano.canvas import Canvas
    from xnano.placement import Placement

    self._attach(target)
    if isinstance(target, (Placement, Canvas)):
        target._buffer.update(self)
        if self.customization_kind.startswith('effect.'):
            target._canvas._record_effect(self, target)
    elif isinstance(target, _core.Surface):
        target.update(self)

def cancel(self) -> None:
    """
    Stop this effect on the target it was applied to.

    Does nothing for an effect that was never applied or has already finished, and for a
    customization that is not an effect.

    Examples:
        ```python
        import xnano
        from xnano.operations import fx

        with xnano.new('hi', width=4, height=1) as canvas:
            fade = fx('effect.fade_to', foreground='red', duration_milliseconds=5000)
            fade.apply_to(canvas)
            fade.cancel()
            fade.cancel()
        ```
    """
    target = self.__dict__.get('_target')
    key = getattr(self, 'key', None)
    if target is None or not isinstance(key, str):
        return
    if not self.customization_kind.startswith('effect.'):
        return
    surface = target._buffer if hasattr(target, '_buffer') else target
    surface.update(_core.CancelEffect(key))

def evaluate(self, context: EvaluationContext) -> ValueType_co:
    """
    Compute the expression's value.

    Examples:
        ```python
        from xnano_core._xnano_core import _reference

        width = _reference('Width', 'numeric_property')
        context = EvaluationContext(buffer=Buffer(width=5, height=1))
        assert (width * 2).evaluate(context) == 10
        ```
    """

def then(self, other: Operation) -> Operation:
    """
    An operation that applies this operation, then ``other``.

    Examples:
        ```python
        buffer = Buffer(width=6, height=1)
        buffer.update(Write('ab').then(Write('c', x=2)))
        assert buffer.text.startswith('abc')
        ```
    """

def when(self, condition: Predicate) -> Operation:
    """
    An operation that applies only while ``condition`` is true.

    Examples:
        ```python
        from xnano_core._xnano_core import _reference

        width = _reference('Width', 'numeric_property')
        buffer = Buffer(width=6, height=1)
        buffer.update(Write('wide').when(width > 4))
        assert buffer.text.startswith('wide')
        ```
    """

def __or__(self, other: Operation) -> Operation:
    """
    Combine this operation with ``other`` so both run in sequence.

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

def evaluate(self, context: EvaluationContext) -> ValueType_co:
    """
    Compute the expression's value.

    Examples:
        ```python
        from xnano_core._xnano_core import _reference

        width = _reference('Width', 'numeric_property')
        context = EvaluationContext(buffer=Buffer(width=5, height=1))
        assert (width * 2).evaluate(context) == 10
        ```
    """

def then(self, other: Operation) -> Operation:
    """
    An operation that applies this operation, then ``other``.

    Examples:
        ```python
        buffer = Buffer(width=6, height=1)
        buffer.update(Write('ab').then(Write('c', x=2)))
        assert buffer.text.startswith('abc')
        ```
    """

def when(self, condition: Predicate) -> Operation:
    """
    An operation that applies only while ``condition`` is true.

    Examples:
        ```python
        from xnano_core._xnano_core import _reference

        width = _reference('Width', 'numeric_property')
        buffer = Buffer(width=6, height=1)
        buffer.update(Write('wide').when(width > 4))
        assert buffer.text.startswith('wide')
        ```
    """

def __or__(self, other: Operation) -> Operation:
    """
    Combine this operation with ``other`` so both run in sequence.

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

def evaluate(self, context: EvaluationContext) -> ValueType_co:
    """
    Compute the expression's value.

    Examples:
        ```python
        from xnano_core._xnano_core import _reference

        width = _reference('Width', 'numeric_property')
        context = EvaluationContext(buffer=Buffer(width=5, height=1))
        assert (width * 2).evaluate(context) == 10
        ```
    """

def then(self, other: Operation) -> Operation:
    """
    An operation that applies this operation, then ``other``.

    Examples:
        ```python
        buffer = Buffer(width=6, height=1)
        buffer.update(Write('ab').then(Write('c', x=2)))
        assert buffer.text.startswith('abc')
        ```
    """

def when(self, condition: Predicate) -> Operation:
    """
    An operation that applies only while ``condition`` is true.

    Examples:
        ```python
        from xnano_core._xnano_core import _reference

        width = _reference('Width', 'numeric_property')
        buffer = Buffer(width=6, height=1)
        buffer.update(Write('wide').when(width > 4))
        assert buffer.text.startswith('wide')
        ```
    """

def __or__(self, other: Operation) -> Operation:
    """
    Combine this operation with ``other`` so both run in sequence.

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

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
        ```
    """