mouseover and mouseout interfaces

This page explains the mouseover and mouseout interfaces.

What interfaces are these?

The mouseover interface binds the event handler. Moreover, this interface calls the handler when a mouse cursor is over on a DisplayObject instance. Conversely, the mouseout interface also binds and calls the handler when a cursor is out from the DisplayObject one.

See also

The following page describes the basic mouse event interfaces.

Basic usage of the mouseover and mouseout interfaces

Each DisplayObject instance has the mouseover and mouseout interfaces, and you can bind handlers by these.

The following example binds the mouse over and handler and mouse out one to the rectangle. The rectangle color changes when your cursor is over the rectangle. Also, it reverts to the original one when your cursor is outed from the rectangle.

import apysc as ap


def on_mouseover(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
    """
    The handler that the rectangle calls when mouseover.

    Parameters
    ----------
    e : MouseEvent
        Event instance.
    options : dict
        Optional arguments dictionary.
    """
    rectangle: ap.Rectangle = e.this

    # Change the rectangle fill color to magenta.
    rectangle.fill_color = ap.Color("#f0a")


def on_mouseout(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
    """
    The handler that the rectangle calls when mouseout.

    Parameters
    ----------
    e : MouseEvent
        Event instance.
    options : dict
        Optional arguments dictionary.
    """
    rectangle: ap.Rectangle = e.this

    # Revert the rectangle fill color.
    rectangle.fill_color = ap.Color("#0af")


ap.Stage(
    background_color=ap.Color("#333"),
    stage_width=150,
    stage_height=150,
    stage_elem_id="stage",
)

sprite: ap.Sprite = ap.Sprite()

sprite.graphics.begin_fill(color=ap.Color("#0af"))
rectangle: ap.Rectangle = sprite.graphics.draw_rect(x=50, y=50, width=50, height=50)

# Bind the mouse over and mouse out event handlers to the rectangle.
rectangle.mouseover(on_mouseover)
rectangle.mouseout(on_mouseout)

ap.save_overall_html(dest_dir_path="mouseover_and_mouseout_basic_usage/")

Unbind interfaces

The unbind_mouseover and unbind_mouseout interfaces unbind each registered handler from the DisplayObject.

The following example unbind handlers in the on_mouseover and on_mouseout functions so that the interface calls these handlers only once.

import apysc as ap


def on_mouseover(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
    """
    The handler that the rectangle calls when mouseover.

    Parameters
    ----------
    e : MouseEvent
        Event instance.
    options : dict
        Optional arguments dictionary.
    """
    rectangle: ap.Rectangle = e.this
    rectangle.fill_color = ap.Color("#f0a")

    # Unbind the mouseover handler.
    rectangle.unbind_mouseover(handler=on_mouseover)


def on_mouseout(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
    """
    The handler that the rectangle calls when mouseout.

    Parameters
    ----------
    e : MouseEvent
        Event instance.
    options : dict
        Optional arguments dictionary.
    """
    rectangle: ap.Rectangle = e.this
    rectangle.fill_color = ap.Color("#0af")

    rectangle.unbind_mouseout(handler=on_mouseout)


ap.Stage(
    background_color=ap.Color("#333"),
    stage_width=150,
    stage_height=150,
    stage_elem_id="stage",
)

sprite: ap.Sprite = ap.Sprite()

sprite.graphics.begin_fill(color=ap.Color("#0af"))
rectangle: ap.Rectangle = sprite.graphics.draw_rect(x=50, y=50, width=50, height=50)

rectangle.mouseover(on_mouseover)
rectangle.mouseout(on_mouseout)

ap.save_overall_html(dest_dir_path="mouseover_and_mouseout_unbind_interfaces/")

There are also existing the unbind_mouseover_all and unbind_mouseout_all interfaces. These interfaces unbind all the handlers from the target DisplayObject instance.

mouseover API

Note: the document build script generates and updates this API document section automatically. Maybe this section is duplicated compared with previous sections.

[Interface signature] mouseover(self, handler: Callable[[apysc._event.mouse_event.MouseEvent, ~_Options], NoneType], *, options: Union[~_Options, NoneType] = None) -> str

[Interface summary]

Add mouse over event listener setting.

[Parameters]

  • handler: _Handler

    • Callable that would be called when mouse over on this instance.

  • options: dict or None, default None

    • Optional arguments dictionary to be passed to a handler.

[Returns]

  • name: str

    • Handler’s name.

[Examples]

>>> import apysc as ap
>>> def on_mouseover(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
...     rectangle: ap.Rectangle = e.this
...     rectangle.fill_color = ap.Color("#f0a")
>>> stage: ap.Stage = ap.Stage()
>>> sprite: ap.Sprite = ap.Sprite()
>>> sprite.graphics.begin_fill(color=ap.Color("#0af"))
>>> rectangle: ap.Rectangle = sprite.graphics.draw_rect(
...     x=50, y=50, width=50, height=50
... )
>>> _ = rectangle.mouseout(on_mouseover)

[References]

unbind_mouseover API

Note: the document build script generates and updates this API document section automatically. Maybe this section is duplicated compared with previous sections.

[Interface signature] unbind_mouseover(self, handler: Callable[[apysc._event.mouse_event.MouseEvent, ~_Options], NoneType]) -> None

[Interface summary]

Unbind a specified handler’s mouseover event.

[Parameters]

  • handler: _Handler

    • Unbinding target Callable.

[Examples]

>>> import apysc as ap
>>> def on_mouseover(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
...     rectangle: ap.Rectangle = e.this
...     rectangle.fill_color = ap.Color("#f0a")
...     rectangle.unbind_mouseover(on_mouseover)
>>> stage: ap.Stage = ap.Stage()
>>> sprite: ap.Sprite = ap.Sprite()
>>> sprite.graphics.begin_fill(color=ap.Color("#0af"))
>>> rectangle: ap.Rectangle = sprite.graphics.draw_rect(
...     x=50, y=50, width=50, height=50
... )
>>> _ = rectangle.mouseout(on_mouseover)

unbind_mouseover_all API

Note: the document build script generates and updates this API document section automatically. Maybe this section is duplicated compared with previous sections.

[Interface signature] unbind_mouseover_all(self) -> None

[Interface summary]

Unbind all mouseover events.

[Examples]

>>> import apysc as ap
>>> def on_mouseover(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
...     rectangle: ap.Rectangle = e.this
...     rectangle.fill_color = ap.Color("#f0a")
...     rectangle.unbind_mouseover_all()
>>> stage: ap.Stage = ap.Stage()
>>> sprite: ap.Sprite = ap.Sprite()
>>> sprite.graphics.begin_fill(color=ap.Color("#0af"))
>>> rectangle: ap.Rectangle = sprite.graphics.draw_rect(
...     x=50, y=50, width=50, height=50
... )
>>> _ = rectangle.mouseout(on_mouseover)

mouseout API

Note: the document build script generates and updates this API document section automatically. Maybe this section is duplicated compared with previous sections.

[Interface signature] mouseout(self, handler: Callable[[apysc._event.mouse_event.MouseEvent, ~_Options], NoneType], *, options: Union[~_Options, NoneType] = None) -> str

[Interface summary]

Add mouse out event listener setting.

[Parameters]

  • handler: _Handler

    • Callable that would be called when mouse out on this instance.

  • options: dict or None, default None

    • Optional arguments dictionary to be passed to a handler.

[Returns]

  • name: str

    • Handler’s name.

[Examples]

>>> import apysc as ap
>>> def on_mouseout(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
...     rectangle: ap.Rectangle = e.this
...     rectangle.fill_color = ap.Color("#f0a")
>>> stage: ap.Stage = ap.Stage()
>>> sprite: ap.Sprite = ap.Sprite()
>>> sprite.graphics.begin_fill(color=ap.Color("#0af"))
>>> rectangle: ap.Rectangle = sprite.graphics.draw_rect(
...     x=50, y=50, width=50, height=50
... )
>>> _ = rectangle.mouseout(on_mouseout)

[References]

unbind_mouseout API

Note: the document build script generates and updates this API document section automatically. Maybe this section is duplicated compared with previous sections.

[Interface signature] unbind_mouseout(self, handler: Callable[[apysc._event.mouse_event.MouseEvent, ~_Options], NoneType]) -> None

[Interface summary]

Unbind a specified handler’s mouse-out event.

[Parameters]

  • handler: _Handler

    • Unbinding target Callable.

[Examples]

>>> import apysc as ap
>>> def on_mouseout(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
...     rectangle: ap.Rectangle = e.this
...     rectangle.fill_color = ap.Color("#f0a")
...     rectangle.unbind_mouseout(on_mouseout)
>>> stage: ap.Stage = ap.Stage()
>>> sprite: ap.Sprite = ap.Sprite()
>>> sprite.graphics.begin_fill(color=ap.Color("#0af"))
>>> rectangle: ap.Rectangle = sprite.graphics.draw_rect(
...     x=50, y=50, width=50, height=50
... )
>>> _ = rectangle.mouseout(on_mouseout)

unbind_mouseout_all API

Note: the document build script generates and updates this API document section automatically. Maybe this section is duplicated compared with previous sections.

[Interface signature] unbind_mouseout_all(self) -> None

[Interface summary]

Unbind all mouse out events.

[Examples]

>>> import apysc as ap
>>> def on_mouseout(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
...     rectangle: ap.Rectangle = e.this
...     rectangle.fill_color = ap.Color("#f0a")
...     rectangle.unbind_mouseout_all()
>>> stage: ap.Stage = ap.Stage()
>>> sprite: ap.Sprite = ap.Sprite()
>>> sprite.graphics.begin_fill(color=ap.Color("#0af"))
>>> rectangle: ap.Rectangle = sprite.graphics.draw_rect(
...     x=50, y=50, width=50, height=50
... )
>>> _ = rectangle.mouseout(on_mouseout)