animation_width and animation_height interfaces¶

This page explains the animation_width and animation_height interfaces.

What interfaces are these?¶

The animation_width method interface creates an AnimationWidth instance. You can animate object width with it.

Similarly, the animation_height method interface creates an AnimationHeight instance. You can animate object height with it.

These interfaces exist on some DisplayObject instances, such as the Rectangle class.

Basic usage¶

The following example sets the width animation (from 50 to 100) with the animation_width method:

import apysc as ap

DURATION: int = 1000
EASING: ap.Easing = ap.Easing.EASE_OUT_QUINT


def on_animation_complete_1(e: ap.AnimationEvent[ap.Rectangle], options: dict) -> None:
    """
    The handler that the animation calls when its end.

    Parameters
    ----------
    e : ap.AnimationEvent
        Event instance.
    options : dict
        Optional arguments dictionary.
    """
    rectangle: ap.Rectangle = e.this.target
    animation_width: ap.AnimationWidth = rectangle.animation_width(
        width=50, duration=DURATION, easing=EASING
    )
    animation_width.animation_complete(on_animation_complete_2)
    animation_width.start()


def on_animation_complete_2(e: ap.AnimationEvent[ap.Rectangle], options: dict) -> None:
    """
    The handler that the animation calls when its end.

    Parameters
    ----------
    e : ap.AnimationEvent
        Event instance.
    options : dict
        Optional arguments dictionary.
    """
    rectangle: ap.Rectangle = e.this.target
    animation_width: ap.AnimationWidth = rectangle.animation_width(
        width=100, duration=DURATION, easing=EASING
    )
    animation_width.animation_complete(on_animation_complete_1)
    animation_width.start()


ap.Stage(
    stage_width=200,
    stage_height=150,
    background_color=ap.Color("#333"),
    stage_elem_id="stage",
)
sprite: ap.Sprite = ap.Sprite()
sprite.graphics.begin_fill(color=ap.Color("#00aaff"))
rectangle: ap.Rectangle = sprite.graphics.draw_rect(x=50, y=50, width=50, height=50)
animation_width: ap.AnimationWidth = rectangle.animation_width(
    width=100, duration=DURATION, easing=EASING
)
animation_width.animation_complete(on_animation_complete_1)
animation_width.start()

ap.save_overall_html(dest_dir_path="./animation_width_basic_usage/")

Similarly, the following example animates the height with the animation_height method:

import apysc as ap

DURATION: int = 1000
EASING: ap.Easing = ap.Easing.EASE_OUT_QUINT


def on_animation_complete_1(e: ap.AnimationEvent[ap.Rectangle], options: dict) -> None:
    """
    The handler that the animation calls when its end.

    Parameters
    ----------
    e : ap.AnimationEvent
        Event instance.
    options : dict
        Optional arguments dictionary.
    """
    rectangle: ap.Rectangle = e.this.target
    animation_height: ap.AnimationHeight = rectangle.animation_height(
        height=50, duration=DURATION, easing=EASING
    )
    animation_height.animation_complete(on_animation_complete_2)
    animation_height.start()


def on_animation_complete_2(e: ap.AnimationEvent[ap.Rectangle], options: dict) -> None:
    """
    The handler that the animation calls when its end.

    Parameters
    ----------
    e : ap.AnimationEvent
        Event instance.
    options : dict
        Optional arguments dictionary.
    """
    rectangle: ap.Rectangle = e.this.target
    animation_height: ap.AnimationHeight = rectangle.animation_height(
        height=100, duration=DURATION, easing=EASING
    )
    animation_height.animation_complete(on_animation_complete_1)
    animation_height.start()


ap.Stage(
    stage_width=150,
    stage_height=200,
    background_color=ap.Color("#333"),
    stage_elem_id="stage",
)
sprite: ap.Sprite = ap.Sprite()
sprite.graphics.begin_fill(color=ap.Color("#00aaff"))
rectangle: ap.Rectangle = sprite.graphics.draw_rect(x=50, y=50, width=50, height=50)
animation_height: ap.AnimationHeight = rectangle.animation_height(
    height=100, duration=DURATION, easing=EASING
)
animation_height.animation_complete(on_animation_complete_1)
animation_height.start()

ap.save_overall_html(dest_dir_path="./animation_height_basic_usage/")

Notes for the Ellipse instance¶

The ellipse instance’s animation_width and animation_height interfaces will return an AnimationWidthForEllipse and AnimationHeightForEllipse instance instead of an AnimationWidth instance, for the reason of the internal implementation, as follows:

import apysc as ap

ap.Stage(
    stage_width=150,
    stage_height=200,
    background_color=ap.Color("#333"),
    stage_elem_id="stage",
)
sprite: ap.Sprite = ap.Sprite()
sprite.graphics.begin_fill(color=ap.Color("#00aaff"))
ellipse: ap.Ellipse = sprite.graphics.draw_ellipse(x=100, y=100, width=100, height=100)
animation_width: ap.AnimationWidthForEllipse = ellipse.animation_width(
    width=200, duration=1000
)
animation_width.start()

animation_width 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] animation_width(self, *, width: Union[int, apysc._type.int.Int], duration: Union[int, apysc._type.int.Int] = 3000, delay: Union[int, apysc._type.int.Int] = 0, easing: apysc._animation.easing.Easing = <Easing.LINEAR: 'function(x) {return x;}'>) -> apysc._animation.animation_width.AnimationWidth

[Interface summary]

Set the width animation setting.

[Parameters]

width: Int or int
- The final width of the animation.
duration: Int or int, default 3000
- Milliseconds before an animation ends.
delay: Int or int, default 0
- Milliseconds before an animation starts.
easing: Easing, default Easing.LINEAR
- Easing setting.

[Returns]

animation_width: AnimationWidth
- Created animation setting instance.

[Notes]

To start this animation, you need to call the start method of the returned instance.

[Examples]

>>> import apysc as ap
>>> 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.animation_width(
...     width=100,
...     duration=1500,
...     easing=ap.Easing.EASE_OUT_QUINT,
... ).start()

[References]

animation_height API¶