xnano.components

def remove(self) -> None:
    """Take the hook off every placement. Removing twice does nothing."""
    if self._is_removed:
        return
    self._is_removed = True
    if self in self._owner._hooks:
        self._owner._hooks.remove(self)
    handles, self._handles = self._handles, []
    for _, handle in handles:
        handle.remove()

def __xnano_render__(self, context: Context[DepsT, StateT]) -> Renderable:
    """Draw the component with the parameters it was given."""
    return cast('Renderable', self._call(context))

def hook(
    self,
    function: Callable[..., object] | None = None,
    /,
    *,
    on: HookKind | None = None,
    when: When[object, object] | None = None,
    every: float | None = None,
    after: float | None = None,
    keys: KeyName | Sequence[KeyName] | None = None,
    requires_deps: bool = False,
) -> ComponentHook | Callable[[Callable[..., object]], ComponentHook]:
    """
    Call a function when something happens to a placement of this component.

    The function receives the hook's [`Context`][xnano.context.Context] and a
    [`ComponentContext`][xnano.components.ComponentContext]. The arguments are those of
    ``hook`` on a placement, and a mouse, scroll or drag hook hears only the pointer
    inside the placement. Keys are not consumed: while nothing has focus, every key hook
    hears a key. On a component function the hook is installed on every
    placement of that function, those that exist now and those created later; on a
    component made by calling it, only on its placements. A playable component has no
    placement: its hook is installed on the canvas when the component is played.

    Args:
        function: The function to call, or ``None`` to use this as a decorator.
        on: What to listen to; see [`HookKind`][xnano.types.HookKind].
        when: A condition that must hold; see [`When`][xnano.types.When].
        every: Repeat every this many seconds (``'tick'``) or beats (``'beat'``).
        after: Run once after this many seconds or beats.
        keys: The key or keys an ``on='key'`` hook reacts to.
        requires_deps: Whether the hook needs the dependencies given to
            ``new(deps=...)``. Checked each time the hook is installed.

    Returns:
        A [`ComponentHook`][xnano.components.ComponentHook], whose ``remove`` takes the
        hook off every placement; or, without a function, the decorator.

    Raises:
        ValueError: The combination of arguments does not make sense; see
            [`hook`][xnano.canvas.Canvas.hook].
        TerminalError: ``requires_deps`` is true and the canvas was created without
            ``deps``.

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

        @xnano.renderable
        def label(context: xnano.Context, text: str = 'x') -> str:
            return text

        with xnano.new(width=10, height=1) as canvas:
            pressed = []

            @label.hook(on='key', keys='a')
            def heard(
                context: xnano.Context,
                component_context: xnano.components.ComponentContext,
            ) -> None:
                pressed.append(component_context.arguments['text'])

            canvas.write(label(text='hi'))
            canvas.push(Event.key_press('a'))
            canvas.deliver_events()
            assert pressed == ['hi']
        ```
    """
    from xnano._hooks import _check_hook_arguments, _check_hook_function
    from xnano._when import compile_when

    _check_hook_arguments(
        cast('_Hooked[object, object]', _PlacementLike()), on, every, after, keys
    )
    compile_when(when)
    settings = _HookSettings(on, when, every, after, keys, requires_deps)

    def attach(callback: Callable[..., object]) -> ComponentHook:
        component_hook = ComponentHook(
            self, _check_hook_function(callback, arguments=2), settings
        )
        self._hooks.append(component_hook)
        try:
            self._install_everywhere(component_hook)
        except BaseException:
            component_hook.remove()
            raise
        return component_hook

    if function is None:
        return attach
    return attach(function)

def __xnano_play__(self, context: Context[DepsT, StateT]) -> Playable:
    """Return what to play, with the parameters the component was given."""
    return cast('Playable', self._call(context))

def hook(
    self,
    function: Callable[..., object] | None = None,
    /,
    *,
    on: HookKind | None = None,
    when: When[object, object] | None = None,
    every: float | None = None,
    after: float | None = None,
    keys: KeyName | Sequence[KeyName] | None = None,
    requires_deps: bool = False,
) -> ComponentHook | Callable[[Callable[..., object]], ComponentHook]:
    """
    Call a function when something happens to a placement of this component.

    The function receives the hook's [`Context`][xnano.context.Context] and a
    [`ComponentContext`][xnano.components.ComponentContext]. The arguments are those of
    ``hook`` on a placement, and a mouse, scroll or drag hook hears only the pointer
    inside the placement. Keys are not consumed: while nothing has focus, every key hook
    hears a key. On a component function the hook is installed on every
    placement of that function, those that exist now and those created later; on a
    component made by calling it, only on its placements. A playable component has no
    placement: its hook is installed on the canvas when the component is played.

    Args:
        function: The function to call, or ``None`` to use this as a decorator.
        on: What to listen to; see [`HookKind`][xnano.types.HookKind].
        when: A condition that must hold; see [`When`][xnano.types.When].
        every: Repeat every this many seconds (``'tick'``) or beats (``'beat'``).
        after: Run once after this many seconds or beats.
        keys: The key or keys an ``on='key'`` hook reacts to.
        requires_deps: Whether the hook needs the dependencies given to
            ``new(deps=...)``. Checked each time the hook is installed.

    Returns:
        A [`ComponentHook`][xnano.components.ComponentHook], whose ``remove`` takes the
        hook off every placement; or, without a function, the decorator.

    Raises:
        ValueError: The combination of arguments does not make sense; see
            [`hook`][xnano.canvas.Canvas.hook].
        TerminalError: ``requires_deps`` is true and the canvas was created without
            ``deps``.

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

        @xnano.renderable
        def label(context: xnano.Context, text: str = 'x') -> str:
            return text

        with xnano.new(width=10, height=1) as canvas:
            pressed = []

            @label.hook(on='key', keys='a')
            def heard(
                context: xnano.Context,
                component_context: xnano.components.ComponentContext,
            ) -> None:
                pressed.append(component_context.arguments['text'])

            canvas.write(label(text='hi'))
            canvas.push(Event.key_press('a'))
            canvas.deliver_events()
            assert pressed == ['hi']
        ```
    """
    from xnano._hooks import _check_hook_arguments, _check_hook_function
    from xnano._when import compile_when

    _check_hook_arguments(
        cast('_Hooked[object, object]', _PlacementLike()), on, every, after, keys
    )
    compile_when(when)
    settings = _HookSettings(on, when, every, after, keys, requires_deps)

    def attach(callback: Callable[..., object]) -> ComponentHook:
        component_hook = ComponentHook(
            self, _check_hook_function(callback, arguments=2), settings
        )
        self._hooks.append(component_hook)
        try:
            self._install_everywhere(component_hook)
        except BaseException:
            component_hook.remove()
            raise
        return component_hook

    if function is None:
        return attach
    return attach(function)

def __call__(
    self, *arguments: ParametersT.args, **keywords: ParametersT.kwargs
) -> RenderableComponent[DepsT, StateT]:
    """Give the component its own parameters; the context is passed for you."""
    return cast(
        'RenderableComponent[DepsT, StateT]', self._bind(*arguments, **keywords)
    )

def __xnano_render__(self, context: Context[DepsT, StateT]) -> Renderable:
    """Draw the component with its default parameters."""
    return cast('Renderable', self._call_with_defaults(context))

def hook(
    self,
    function: Callable[..., object] | None = None,
    /,
    *,
    on: HookKind | None = None,
    when: When[object, object] | None = None,
    every: float | None = None,
    after: float | None = None,
    keys: KeyName | Sequence[KeyName] | None = None,
    requires_deps: bool = False,
) -> ComponentHook | Callable[[Callable[..., object]], ComponentHook]:
    """
    Call a function when something happens to a placement of this component.

    The function receives the hook's [`Context`][xnano.context.Context] and a
    [`ComponentContext`][xnano.components.ComponentContext]. The arguments are those of
    ``hook`` on a placement, and a mouse, scroll or drag hook hears only the pointer
    inside the placement. Keys are not consumed: while nothing has focus, every key hook
    hears a key. On a component function the hook is installed on every
    placement of that function, those that exist now and those created later; on a
    component made by calling it, only on its placements. A playable component has no
    placement: its hook is installed on the canvas when the component is played.

    Args:
        function: The function to call, or ``None`` to use this as a decorator.
        on: What to listen to; see [`HookKind`][xnano.types.HookKind].
        when: A condition that must hold; see [`When`][xnano.types.When].
        every: Repeat every this many seconds (``'tick'``) or beats (``'beat'``).
        after: Run once after this many seconds or beats.
        keys: The key or keys an ``on='key'`` hook reacts to.
        requires_deps: Whether the hook needs the dependencies given to
            ``new(deps=...)``. Checked each time the hook is installed.

    Returns:
        A [`ComponentHook`][xnano.components.ComponentHook], whose ``remove`` takes the
        hook off every placement; or, without a function, the decorator.

    Raises:
        ValueError: The combination of arguments does not make sense; see
            [`hook`][xnano.canvas.Canvas.hook].
        TerminalError: ``requires_deps`` is true and the canvas was created without
            ``deps``.

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

        @xnano.renderable
        def label(context: xnano.Context, text: str = 'x') -> str:
            return text

        with xnano.new(width=10, height=1) as canvas:
            pressed = []

            @label.hook(on='key', keys='a')
            def heard(
                context: xnano.Context,
                component_context: xnano.components.ComponentContext,
            ) -> None:
                pressed.append(component_context.arguments['text'])

            canvas.write(label(text='hi'))
            canvas.push(Event.key_press('a'))
            canvas.deliver_events()
            assert pressed == ['hi']
        ```
    """
    from xnano._hooks import _check_hook_arguments, _check_hook_function
    from xnano._when import compile_when

    _check_hook_arguments(
        cast('_Hooked[object, object]', _PlacementLike()), on, every, after, keys
    )
    compile_when(when)
    settings = _HookSettings(on, when, every, after, keys, requires_deps)

    def attach(callback: Callable[..., object]) -> ComponentHook:
        component_hook = ComponentHook(
            self, _check_hook_function(callback, arguments=2), settings
        )
        self._hooks.append(component_hook)
        try:
            self._install_everywhere(component_hook)
        except BaseException:
            component_hook.remove()
            raise
        return component_hook

    if function is None:
        return attach
    return attach(function)

def __call__(
    self, *arguments: ParametersT.args, **keywords: ParametersT.kwargs
) -> PlayableComponent[DepsT, StateT]:
    """Give the component its own parameters; the context is passed for you."""
    return cast(
        'PlayableComponent[DepsT, StateT]', self._bind(*arguments, **keywords)
    )

def __xnano_play__(self, context: Context[DepsT, StateT]) -> Playable:
    """Return what to play with the default parameters."""
    return cast('Playable', self._call_with_defaults(context))

def hook(
    self,
    function: Callable[..., object] | None = None,
    /,
    *,
    on: HookKind | None = None,
    when: When[object, object] | None = None,
    every: float | None = None,
    after: float | None = None,
    keys: KeyName | Sequence[KeyName] | None = None,
    requires_deps: bool = False,
) -> ComponentHook | Callable[[Callable[..., object]], ComponentHook]:
    """
    Call a function when something happens to a placement of this component.

    The function receives the hook's [`Context`][xnano.context.Context] and a
    [`ComponentContext`][xnano.components.ComponentContext]. The arguments are those of
    ``hook`` on a placement, and a mouse, scroll or drag hook hears only the pointer
    inside the placement. Keys are not consumed: while nothing has focus, every key hook
    hears a key. On a component function the hook is installed on every
    placement of that function, those that exist now and those created later; on a
    component made by calling it, only on its placements. A playable component has no
    placement: its hook is installed on the canvas when the component is played.

    Args:
        function: The function to call, or ``None`` to use this as a decorator.
        on: What to listen to; see [`HookKind`][xnano.types.HookKind].
        when: A condition that must hold; see [`When`][xnano.types.When].
        every: Repeat every this many seconds (``'tick'``) or beats (``'beat'``).
        after: Run once after this many seconds or beats.
        keys: The key or keys an ``on='key'`` hook reacts to.
        requires_deps: Whether the hook needs the dependencies given to
            ``new(deps=...)``. Checked each time the hook is installed.

    Returns:
        A [`ComponentHook`][xnano.components.ComponentHook], whose ``remove`` takes the
        hook off every placement; or, without a function, the decorator.

    Raises:
        ValueError: The combination of arguments does not make sense; see
            [`hook`][xnano.canvas.Canvas.hook].
        TerminalError: ``requires_deps`` is true and the canvas was created without
            ``deps``.

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

        @xnano.renderable
        def label(context: xnano.Context, text: str = 'x') -> str:
            return text

        with xnano.new(width=10, height=1) as canvas:
            pressed = []

            @label.hook(on='key', keys='a')
            def heard(
                context: xnano.Context,
                component_context: xnano.components.ComponentContext,
            ) -> None:
                pressed.append(component_context.arguments['text'])

            canvas.write(label(text='hi'))
            canvas.push(Event.key_press('a'))
            canvas.deliver_events()
            assert pressed == ['hi']
        ```
    """
    from xnano._hooks import _check_hook_arguments, _check_hook_function
    from xnano._when import compile_when

    _check_hook_arguments(
        cast('_Hooked[object, object]', _PlacementLike()), on, every, after, keys
    )
    compile_when(when)
    settings = _HookSettings(on, when, every, after, keys, requires_deps)

    def attach(callback: Callable[..., object]) -> ComponentHook:
        component_hook = ComponentHook(
            self, _check_hook_function(callback, arguments=2), settings
        )
        self._hooks.append(component_hook)
        try:
            self._install_everywhere(component_hook)
        except BaseException:
            component_hook.remove()
            raise
        return component_hook

    if function is None:
        return attach
    return attach(function)