xnano.art

def follow(self, art: Art | None) -> None:
    """
    Keep an art in the middle of the screen, or pass ``None`` to stop following.

    Args:
        art: The art to follow.
    """
    self.target = art

def add(
    self,
    art: Art,
    /,
    *,
    x: float = 0,
    y: float = 0,
    layer: int = 0,
    anchor: Anchor = (0, 0),
    is_solid: bool = False,
) -> Art:
    """
    Put another art in this one, at a position in pixels.

    Args:
        art: The art to add. It may be added to one art only.
        x: The pixel column of the child's anchor inside this art.
        y: The pixel row of the child's anchor inside this art.
        layer: Children with a higher layer are drawn over lower ones; children on the
            same layer are drawn in the order they were added.
        anchor: The ``(x, y)`` pixel of the child that sits at ``(x, y)``.
        is_solid: Whether the child's opaque pixels block the movement of other children.

    Returns:
        The child, to move, change or remove.

    Raises:
        ValueError: The art already belongs to an art, or is this art or one that holds
            it.

    Examples:
        ```python
        import xnano

        world = xnano.draw(None, width=8, height=8)
        hero = world.add(xnano.draw(['R', 'R'], {'R': 'red'}), x=3, y=2, anchor=(0, 1))
        assert (hero.x, hero.y) == (3, 2)
        ```
    """
    if not isinstance(art, Art):
        raise TypeError(
            f'add() takes an Art made with xnano.draw(...), but got '
            f'{type(art).__name__}. Wrap a picture with xnano.draw(image) first.'
        )
    ancestor: Art | None = self
    while ancestor is not None:
        if ancestor is art:
            raise ValueError(
                'An art cannot be added to itself or to an art it holds. Add it to '
                'another world.'
            )
        ancestor = ancestor._parent
    if art._parent is not None:
        raise ValueError(
            'This art already belongs to another art. Call art.remove() first, or draw '
            'a second one.'
        )
    art._parent = self
    art._x = float(x)
    art._y = float(y)
    art._layer = layer
    art._anchor = anchor
    art._blocks_movement = is_solid
    self._children.append(art)
    self._changed()
    return art

def replace(
    self,
    source: str | Sequence[str] | Image | TerminalImage | bytes | bytearray | None,
    palette: Mapping[str, ColorValue] | str | None = None,
    *,
    width: int | None = None,
    height: int | None = None,
) -> None:
    """
    Swap the pixels for others, keeping the position, layer and parent.

    The solid ground is kept when the new pixels have the same size and cleared when the
    size changes.

    This is how a walk cycle or a zoom is made: draw every frame once, and replace the
    pixels of the art that is on screen. The sources are the ones
    [`draw`][xnano.draw] takes, except a symbol name.

    Args:
        source: Text rows, an image, RGBA bytes or ``None``.
        palette: What each character of text rows means.
        width: The width in pixels of RGBA bytes or of a blank world.
        height: The height in pixels.

    Examples:
        ```python
        import xnano

        frame_one = ['AB']
        hero = xnano.draw(frame_one, {'A': 'red', 'B': 'blue'})
        hero.replace(['BA'], {'A': 'red', 'B': 'blue'})
        assert hero.width == 2
        ```
    """
    rgba, pixel_width, pixel_height = _pixels_of(source, palette, width, height)
    previous_width, previous_height = self._width, self._height
    self._rgba = None if rgba is None else bytes(rgba)
    self._width = pixel_width
    self._height = pixel_height
    if (pixel_width, pixel_height) != (previous_width, previous_height):
        self._solid_map = None
    self._changed()

def remove(self) -> None:
    """Take the art out of the art that holds it. Removing a loose art does nothing."""
    parent = self._parent
    if parent is None:
        return
    self._parent = None
    if self in parent._children:
        parent._children.remove(self)
    if parent.camera.target is self:
        parent.camera.target = None
    parent._changed()

def move(self, x: float = 0, y: float = 0) -> tuple[float, float]:
    """
    Move the art by a number of pixels, sliding along solid ground instead of stopping.

    The two axes are tried one after the other, a pixel at a time, so walking diagonally
    into a wall keeps moving along it and a thin wall cannot be stepped over. The anchor
    pixel is what collides. An art without a parent art, or whose parent has no solid
    ground, moves freely. Positive ``x`` moves right and positive ``y`` moves down.

    Pixels are half a cell: ``art.move(y=-1)`` moves one pixel up, where
    ``placement.move(y=-1)`` moves the whole art one cell up.

    Args:
        x: How far to move along ``x``, in pixels.
        y: How far to move along ``y``, in pixels.

    Returns:
        The distance moved along each axis, ``(0.0, 0.0)`` when blocked.

    Examples:
        ```python
        import xnano

        world = xnano.draw(None, width=8, height=8)
        solid = bytearray(64)
        for row in range(8):
            solid[row * 8 + 5] = 1
        world.solid_map = solid
        hero = world.add(xnano.draw(['R'], {'R': 'red'}), x=4, y=2)
        assert hero.move(2, 1) == (0.0, 1.0)
        assert (hero.x, hero.y) == (4, 3)
        ```
    """
    _check_pixels(x, name='x', verb='move')
    _check_pixels(y, name='y', verb='move')
    before_x, before_y = self._x, self._y
    self.x = self._advance(self._x, self._y, x, is_horizontal=True)
    self.y = self._advance(self._x, self._y, y, is_horizontal=False)
    return (self._x - before_x, self._y - before_y)

def up(self, count: float = 1) -> float:
    """
    Move up by ``count`` pixels, sliding along solid ground, and say how far it got.

    Unlike [`Placement.up`][xnano.placement.Placement.up], which returns the placement
    so calls chain, this returns the distance moved, so a game can tell when the art was
    blocked.

    Args:
        count: How many pixels to move; pixels are half a cell.

    Returns:
        The distance moved in pixels, ``0.0`` when blocked.
    """
    _check_pixels(count, name='count', verb='up', opposite='down')
    return abs(self.move(y=-count)[1])

def down(self, count: float = 1) -> float:
    """
    Move down by ``count`` pixels, sliding along solid ground, and say how far it got.

    Unlike [`Placement.down`][xnano.placement.Placement.down], which returns the placement
    so calls chain, this returns the distance moved, so a game can tell when the art was
    blocked.

    Args:
        count: How many pixels to move; pixels are half a cell.

    Returns:
        The distance moved in pixels, ``0.0`` when blocked.
    """
    _check_pixels(count, name='count', verb='down', opposite='up')
    return abs(self.move(y=count)[1])

def left(self, count: float = 1) -> float:
    """
    Move left by ``count`` pixels, sliding along solid ground, and say how far it got.

    Unlike [`Placement.left`][xnano.placement.Placement.left], which returns the placement
    so calls chain, this returns the distance moved, so a game can tell when the art was
    blocked.

    Args:
        count: How many pixels to move; pixels are half a cell.

    Returns:
        The distance moved in pixels, ``0.0`` when blocked.
    """
    _check_pixels(count, name='count', verb='left', opposite='right')
    return abs(self.move(x=-count)[0])

def right(self, count: float = 1) -> float:
    """
    Move right by ``count`` pixels, sliding along solid ground, and say how far it got.

    Unlike [`Placement.right`][xnano.placement.Placement.right], which returns the placement
    so calls chain, this returns the distance moved, so a game can tell when the art was
    blocked.

    Args:
        count: How many pixels to move; pixels are half a cell.

    Returns:
        The distance moved in pixels, ``0.0`` when blocked.
    """
    _check_pixels(count, name='count', verb='right', opposite='left')
    return abs(self.move(x=count)[0])

def is_solid(self, x: float, y: float) -> bool:
    """
    Whether a pixel of this art's world cannot be walked on.

    Everything outside the world is solid. Inside it, a pixel is solid where
    [`solid_map`][xnano.art.Art.solid_map] holds a non-zero byte, or where an opaque pixel
    of a child added with ``is_solid=True`` is.

    Args:
        x: The world column.
        y: The world row.

    Examples:
        ```python
        import xnano

        world = xnano.draw(None, width=4, height=4)
        assert world.is_solid(-1, 0)
        assert not world.is_solid(2, 2)
        ```
    """
    return self._is_solid_for(x, y, mover=None)

def world_for_cell(self, x: int, y: int) -> tuple[int, int]:
    """
    The world pixel under a cell of the screen, such as the one the pointer is over.

    The cell must be one of the cells the art was last drawn in; a cell is two pixels
    tall, and the pixel returned is the lower one.

    Args:
        x: The cell's column in the placement of the art.
        y: The cell's row in the placement of the art.

    Examples:
        ```python
        import xnano

        world = xnano.draw(None, width=40, height=40)
        world.camera.x, world.camera.y = 16, 16
        with xnano.new(width=8, height=4) as canvas:
            canvas.write(world, width='100%', height='100%')
            canvas.step()
        assert world.world_for_cell(0, 0) == (16, 17)
        ```
    """
    left, top = self._origin()
    return left + x, top + _PIXELS_PER_CELL_ROW * y + 1

def render(
    self,
    *,
    width: int | None = None,
    height: int | None = None,
    format: Literal['text', 'ansi'] = 'text',
) -> str:
    """
    Draw the art to a string, without a canvas.

    Args:
        width: The width in cells. The art's own width by default.
        height: The height in cells. The art's own height in cells by default.
        format: ``'text'`` for the characters only, ``'ansi'`` with colors.

    Examples:
        ```python
        import xnano

        heart = xnano.draw(['R.R', 'RRR'], {'R': 'red'})
        assert heart.render() == ' ▄'
        ```
    """
    columns = self._width if width is None else width
    rows = (
        math.ceil(self._height / _PIXELS_PER_CELL_ROW) if height is None else height
    )
    return self._compose(columns, rows).render(format=format)

def __xnano_render__(self, context: Context) -> _core.Buffer:
    """Return the cells that show the art, as large as the area it is written in."""
    owner = context.buffer
    area = owner.region
    if hasattr(owner, 'refresh'):
        self._observers.add(cast('Placement[object, object]', owner))
    columns = area.width or self._width
    rows = area.height or math.ceil(self._height / _PIXELS_PER_CELL_ROW)
    return self._compose(columns, rows)