xnano.placement

def local(self, point: _core.Point) -> _core.Point:
    """
    Convert a cell of the screen into a cell of this placement.

    Args:
        point: A cell in screen coordinates, such as ``context.mouse.position``.

    Examples:
        ```python
        import xnano
        from xnano_core import Point

        with xnano.new(width=20, height=4) as canvas:
            placement = canvas.write('hi', x=10, y=1)
            assert placement.local(Point(11, 1)) == Point(1, 0)
        ```
    """
    point = check_point(point)
    bounds = self._buffer._absolute_bounds
    return _core.Point(point.x - bounds.x, point.y - bounds.y)

def move(self, x: int = 0, y: int = 0) -> Placement[DepsT, StateT]:
    """
    Move the placement by a number of cells along each axis.

    The move is held inside a range on the axis
    (``x=(0, 39)``), so a slider's thumb stops at the ends of its track. A position that
    is a formula keeps its formula and shifts it. Piping ``xnano.operations.Move`` onto
    the placement is also held inside its ranges.

    Args:
        x: Columns to move right; a negative number moves left.
        y: Rows to move down; a negative number moves up.

    Returns:
        The placement, so calls can chain.

    Raises:
        TypeError: An amount is not a whole number.

    Examples:
        ```python
        import xnano

        with xnano.new(width=20, height=3) as canvas:
            thumb = canvas.write('#', x=(0, 10), y=1)
            thumb.move(x=4, y=-1)
            assert (thumb.x, thumb.y) == (4, 0)
            thumb.right(99)
            assert thumb.x == 10
        ```
    """
    horizontal = check_cells(x, 'x')
    vertical = check_cells(y, 'y')
    self._require_attached()
    steps: tuple[tuple[AxisName, int], ...] = (('x', horizontal), ('y', vertical))
    for axis, step in steps:
        if step == 0:
            continue
        with self._canvas._lock:
            binding = self._bindings.get(axis)
        if binding is None:
            self._set_axis(axis, getattr(self._buffer, axis) + step)
            continue
        # A formula moves only as far as its range or edges let it, so moves past an
        # edge do not pile up and have to be undone before the opposite move shows.
        current = getattr(self._buffer, axis)
        try:
            target = self._clamp(axis, current + step, self._resolve_offline)
        except _core.RuntimeRequiredError:
            target = current + step
        self._set_axis(axis, binding[0] + _round_half_away(target - current))
    return self

def up(self, count: int = 1) -> Placement[DepsT, StateT]:
    """
    Move the placement up by ``count`` rows; see [`move`][xnano.placement.Placement.move].

    Args:
        count: How many rows to move.

    Raises:
        TypeError: ``count`` is not a whole number.
        ValueError: ``count`` is negative.
    """
    return self.move(y=-check_count(count, verb='up', opposite='down'))

def down(self, count: int = 1) -> Placement[DepsT, StateT]:
    """
    Move the placement down by ``count`` rows; see [`move`][xnano.placement.Placement.move].

    Args:
        count: How many rows to move.

    Raises:
        TypeError: ``count`` is not a whole number.
        ValueError: ``count`` is negative.
    """
    return self.move(y=check_count(count, verb='down', opposite='up'))

def left(self, count: int = 1) -> Placement[DepsT, StateT]:
    """
    Move the placement left by ``count`` columns; see [`move`][xnano.placement.Placement.move].

    Args:
        count: How many columns to move.

    Raises:
        TypeError: ``count`` is not a whole number.
        ValueError: ``count`` is negative.
    """
    return self.move(x=-check_count(count, verb='left', opposite='right'))

def right(self, count: int = 1) -> Placement[DepsT, StateT]:
    """
    Move the placement right by ``count`` columns; see [`move`][xnano.placement.Placement.move].

    Args:
        count: How many columns to move.

    Raises:
        TypeError: ``count`` is not a whole number.
        ValueError: ``count`` is negative.
    """
    return self.move(x=check_count(count, verb='right', opposite='left'))

def render(self, *, format: Literal['text', 'ansi'] = 'text') -> str:
    """
    Draw the placement, with its border, padding and nested placements, to a string.

    Args:
        format: ``'text'`` for the characters only, ``'ansi'`` with colors and styles.

    Examples:
        ```python
        import xnano

        with xnano.new(width=10, height=3) as canvas:
            card = canvas.write('hi', border='rounded')
            assert card.render().splitlines() == ['╭──╮', '│hi│', '╰──╯']
        ```
    """
    self._flush_look()
    return self._buffer.render(format=format)

def refresh(self) -> None:
    """
    Draw a placement made from a component again, at the next frame.

    A component is evaluated once, and again only when it read something that changes. When
    something it does not track changes, such as a field of a class-based component or a
    value in ``context.deps``, call this to evaluate it again. A placement that was not made
    from a component has nothing to evaluate, so this does nothing.

    Examples:
        ```python
        import xnano

        @xnano.renderable
        def counter(context: xnano.Context) -> str:
            return str(context.deps['count'])

        dependencies = {'count': 0}
        with xnano.new(width=4, height=1, deps=dependencies) as canvas:
            placement = canvas.write(counter)
            dependencies['count'] = 7
            placement.refresh()
            canvas.step()
            assert canvas.render().strip() == '7'
        ```
    """
    driver = self._driver
    if driver is not None:
        driver.refresh()

@refuse_unknown_keywords
def write(
    self,
    content: Content | Canvas[WrittenDepsT, WrittenStateT] | None = None,
    /,
    *,
    x: Axis | None = None,
    y: Axis | None = None,
    width: Axis | None = None,
    height: Axis | None = None,
    layer: int = 0,
    lock: bool = False,
    edges: EdgeBehavior | None = None,
    effects: Sequence[RenderableEffectSpecification] = (),
    style: _core.Style | None = None,
    foreground: ColorValue | None = None,
    background: ColorValue | None = None,
    bold: bool = False,
    dim: bool = False,
    italic: bool = False,
    underline: bool = False,
    blink: bool = False,
    reverse: bool = False,
    hidden: bool = False,
    crossed_out: bool = False,
    title: str | None = None,
    border: _core.BorderKind | bool | None = None,
    border_style: _core.Style | None = None,
    padding: Spacing | None = None,
    margin: Spacing | None = None,
) -> Placement[DepsT, StateT]:
    """
    Add a child placement inside this placement.

    A child placement's ``x``, ``y``, ``width`` and ``height`` are measured relative to
    this placement's buffer, so ``track.write('█', x=(0, track.width - 1), y=0)`` moves
    inside ``track``. To change this placement with an operation, a style or an effect, use
    [`update`][xnano.placement.Placement.update].

    Args:
        content: Child content to place inside this buffer.
        x: Column of the child's left edge, relative to this placement.
        y: Row of the child's top edge, relative to this placement.
        width: Width of the child in cells.
        height: Height of the child in cells.
        layer: Layer ordering among siblings.
        lock: Lock dynamic axes to their initial values.
        edges: What the content does at the edges of its area: ``'clip'``, ``'stop'`` or
            ``'wrap'``; see [`Placement.edges`][xnano.placement.Placement.edges]. Left
            out, it follows what it is written on.
        effects: Effects to start on the child, as dictionaries with a ``kind`` key.
        style: Ready-made [`Style`][xnano.styles.Style] for text.
        foreground: Text foreground color.
        background: Text background color.
        bold: Whether text is bold.
        dim: Whether text is dimmed.
        italic: Whether text is italic.
        underline: Whether text is underlined.
        blink: Whether text blinks.
        reverse: Whether foreground and background are swapped.
        hidden: Whether text is hidden.
        crossed_out: Whether text is struck through.
        title: Title for a box around text.
        border: The kind of border for a box around the content, a
            [`BorderKind`][xnano.types.BorderKind] such as ``'plain'``, ``'rounded'``,
            ``'double'`` or ``'thick'``; ``True`` for ``'plain'`` and ``False`` for none.
        border_style: Style for the box's border.
        padding: Space between the border and the text; see
            [`Canvas.write`][xnano.canvas.Canvas.write].
        margin: Space outside the box, in the same forms.
    """
    self._require_attached()
    if edges is not None:
        edges = check_edges(edges)
    look = self._appearance
    if look is not None and self._decorated is None and self._has_frame(look):
        self._has_nested = True
        self._look_changed()
        self._flush_look()
    placement = self._canvas._place_on(
        self._content,
        content,
        parent_owner=cast('Placement[object, object]', self),
        x=x,
        y=y,
        width=width,
        height=height,
        layer=layer,
        lock=lock,
        style=style,
        foreground=foreground,
        background=background,
        bold=bold,
        dim=dim,
        italic=italic,
        underline=underline,
        blink=blink,
        reverse=reverse,
        hidden=hidden,
        crossed_out=crossed_out,
        title=title,
        border=border,
        border_style=border_style,
        padding=padding,
        margin=margin,
    )
    if effects:
        apply_effects(cast('Placement[object, object]', placement), effects)
    placement._take_edges(edges, content)
    return placement

def update(
    self, *operations: _core.Operation | _core.Style
) -> Placement[DepsT, StateT]:
    """
    Change this placement's content with operations, styles or effects.

    Args:
        operations: What to apply, in order: an operation, a contextual operation, a style,
            or an effect such as ``Effect.dissolve(duration_milliseconds=500)``.

    Examples:
        ```python
        import xnano
        from xnano.effects import Effect

        with xnano.new(width=20, height=3) as canvas:
            title = canvas.write('Welcome')
            title.update(Effect.dissolve(duration_milliseconds=500))
        ```
    """
    self._require_attached()
    for item in operations:
        if isinstance(item, ContextualOperation):
            cast('ContextualOperation[DepsT, StateT]', item).apply_to(self)
        elif isinstance(item, Customization):
            item.apply_to(cast('Placement[object, object]', self))
        elif isinstance(item, _core.Style):
            self._buffer.update(_core.ApplyStyle(item))
        else:
            self._buffer.update(item)
            if isinstance(item, (_core.Move, _core.Place)):
                for axis in ('x', 'y'):
                    if axis in self._limits:
                        self._enforce(axis)
    return self

def __or__(
    self, operation: _core.Operation | _core.Style
) -> Placement[DepsT, StateT]:
    """Apply ``operation`` to this placement and return ``self``."""
    return self.update(operation)

def __ior__(
    self, operation: _core.Operation | _core.Style
) -> Placement[DepsT, StateT]:
    """Apply ``operation`` to this placement in place and return ``self``."""
    return self.update(operation)

def remove(self) -> None:
    """Take the buffer off the canvas. Removing twice is harmless."""
    if self._removed:
        return
    self._removed = True
    # A look that was waiting to be drawn is dropped with the placement.
    self._look_is_dirty = False
    canvas = self._canvas
    if not canvas._is_closed:
        canvas._look_was_drawn(self)
    with canvas._lock:
        nested = [
            other
            for other in canvas._placements
            if other._parent_owner is self
            or getattr(other._parent_owner, '_parent_placement', None) is self
        ]
    for other in nested:
        other.remove()
    follow = canvas._cursor_follow
    if (
        follow is not None
        and not canvas._is_closed
        and any(follow[0] is buffer for buffer in (self._buffer, self._content))
    ):
        # A cursor that followed this placement has nowhere to be once it is gone.
        canvas._cursor_view.position = None
    driver = self._driver
    if driver is not None:
        self._driver = None
        driver.close()
    self._cancel_hooks()
    self._renderable_effects.clear()
    namespace = self._state_namespace
    if namespace is not None:
        self._state_namespace = None
        namespace._remove()
    with self._canvas._lock:
        self._bindings.clear()
        self._limits.clear()
    try:
        self._parent_buffer.detach(self._buffer)
    except ValueError:
        pass
    self._canvas._release(self)
    with canvas._lock:
        children = [
            child
            for child in canvas._children
            if child._parent_placement is self and not child._is_closed
        ]
    for child in children:
        # A canvas written into this placement is closed with it.
        child.close()

def __setattr__(self, name: str, value: object) -> None:
    """Set an attribute, or raise ``AttributeError`` for an unknown public name."""
    if (
        name[:1] != '_'
        and self.__dict__.get('_is_sealed')
        and not hasattr(type(self), name)
        and name not in self.__dict__
    ):
        kind = type(self).__name__
        settable = sorted(
            key
            for key in dir(type(self))
            if key[:1] != '_' and _is_settable(type(self), key)
        )
        close = difflib.get_close_matches(name, settable, n=1)
        hint = f' Did you mean {close[0]!r}?' if close else ''
        raise AttributeError(
            f'{kind} has no attribute called {name!r}, so assigning to it would change '
            f'nothing.{hint} The attributes you can assign are: {", ".join(settable)}.'
        )
    object.__setattr__(self, name, value)