click interface¶
This page explains the click interface.
What interface is this?¶
The click interface binds the click event to any DisplayObject instance (e.g., Sprite, Rectangle, and so on). These interfaces call the registered handler function if you mouse down on that instance and mouse up.
Conversely, the unbind_click interface unbinds the click event from the DisplayObject instance.
See also¶
The following page describes basic mouse event interfaces.
Basic usage of the click interface¶
Each DisplayObject instance has the click method, and you can bind handlers by that.
The following example binds the click event handler to the rectangle.
import apysc as ap
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"))
def on_click(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
"""
The handler that the rectangle calls when clicked.
Parameters
----------
e : MouseEvent
Event instance.
options : dict
Optional arguments.
"""
rectangle: ap.Rectangle = e.this
rectangle.fill_color = ap.Color("#f0a")
rectangle: ap.Rectangle = sprite.graphics.draw_rect(x=50, y=50, width=50, height=50)
rectangle.click(handler=on_click)
ap.save_overall_html(dest_dir_path="click_basic_usage_of_the_click_interface/")
If you click the following rectangle, the rectangle color becomes the magenta color.
Basic usage of the unbind_click interface¶
The unbind_click interface can remove the binded click event from a DisplayObject instance.
The following example removes the click event by the unbind_click method, and nothing happens if you click the rectangle.
import apysc as ap
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"))
def on_click(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
"""
The handler that the rectangle calls when clicked.
Parameters
----------
e : MouseEvent
Event instance.
options : dict
Optional arguments.
"""
rectangle: ap.Rectangle = e.this
rectangle.fill_color = ap.Color("#f0a")
rectangle: ap.Rectangle = sprite.graphics.draw_rect(x=50, y=50, width=50, height=50)
rectangle.click(handler=on_click)
rectangle.unbind_click(handler=on_click)
ap.save_overall_html(dest_dir_path="click_basic_usage_of_the_unbind_click_interface/")
Unbind all the click event handlers¶
unbind_click_all interface can unbind all the click event handlers from the DisplayObject instance.
The following example removes all the click events by the unbind_click_all method (if you click the rectangle, nothing happens).
import apysc as ap
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"))
def on_click(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
"""
The handler that the rectangle calls when clicked.
Parameters
----------
e : MouseEvent
Event instance.
options : dict
Optional arguments.
"""
rectangle: ap.Rectangle = e.this
rectangle.fill_color = ap.Color("#f0a")
rectangle: ap.Rectangle = sprite.graphics.draw_rect(x=50, y=50, width=50, height=50)
rectangle.click(handler=on_click)
rectangle.unbind_click_all()
ap.save_overall_html(dest_dir_path="click_unbind_all_the_click_event_handlers/")
click 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] click(self, handler: Callable[[apysc._event.mouse_event.MouseEvent, ~_Options], NoneType], *, options: Union[~_Options, NoneType] = None) -> str
[Interface summary]
Add a click event listener setting.
[Parameters]
handler: _HandlerA callable would be called when clicking this instance.
options: dict or None, default NoneOptional arguments dictionary to be passed to a handler.
[Returns]
name: strHandler’s name.
[Examples]
>>> import apysc as ap
>>> def on_click(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
... rectangle: ap.Rectangle = e.this
... rectangle.x += 10
>>> 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.click(on_click)
[References]
unbind_click 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_click(self, handler: Callable[[apysc._event.mouse_event.MouseEvent, ~_Options], NoneType]) -> None
[Interface summary]
Unbind specified handler’s click event.
[Parameters]
handler: _HandlerUnbinding target Callable.
[Examples]
>>> import apysc as ap
>>> def on_click(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
... rectangle: ap.Rectangle = e.this
... rectangle.fill_color = ap.Color("#f0a")
... rectangle.unbind_click(on_click)
>>> 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.click(on_click)
unbind_click_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_click_all(self) -> None
[Interface summary]
Unbind all click events.
[Examples]
>>> import apysc as ap
>>> def on_click(e: ap.MouseEvent[ap.Rectangle], options: dict) -> None:
... rectangle: ap.Rectangle = e.this
... rectangle.fill_color = ap.Color("#f0a")
... rectangle.unbind_click_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.click(on_click)
