Stage class¶

This page explains the Stage class.

What is the Stage?¶

The Stage is the apysc overall drawing area (like a viewport) and contains all elements.

You must create the Stage at the first of the apysc project (this runs cleaning up internal data and files).

Create stage¶

Creating a stage is simple, like this:

import apysc as ap

stage: ap.Stage = ap.Stage()

Stage background color setting¶

Stage class has a background_color option, which changes the stage’s background color.

import apysc as ap

stage: ap.Stage = ap.Stage(
    background_color=ap.Color("#333"),
    stage_elem_id="stage",
)

ap.save_overall_html(dest_dir_path="stage_background_color/")

This will create HTML with black background stage, as follows:

Stage size setting¶

Stage class has options to set stage width and stage height (arguments of stage_width and stage_height). These settings change stage sizes.

import apysc as ap

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

ap.save_overall_html(dest_dir_path="stage_size/")

The Previous script will create a horizontal stage, as follows:

Stage element id setting¶

Stage element id (HTML id) can be set by stage_elem_id argument. If you don’t specify this, the apysc sets any unique id (based on created timestamp, like stage_12345...).

import apysc as ap

stage: ap.Stage = ap.Stage(
    background_color=ap.Color("#333"),
    stage_elem_id="line_chart_1",
)

This option is useful when using the apysc project multiple times (for an easily identifiable ID) or version control.

get_stage function interface¶

The get_stage function returns the current stage instance.

This interface is sometimes useful to get a stage instance in the other function’s scope.

import apysc as ap


def _main() -> None:
    """
    Entry point of this project.
    """
    _: ap.Stage = ap.Stage(
        stage_width=150,
        stage_height=150,
        background_color=ap.Color("#333"),
        stage_elem_id="my_stage",
    )
    ...
    _other_function()


def _other_function() -> None:
    """
    The other function to do something.
    """
    stage: ap.Stage = ap.get_stage()
    assert stage.stage_elem_id == "my_stage"


_main()

Stage class constructor 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] __init__(self, *, stage_width: int = 300, stage_height: int = 185, background_color: apysc._color.color.Color = Color("#ffffff"), add_to: str = 'body', stage_elem_id: Union[str, NoneType] = None, variable_name_suffix: str = '') -> None

[Interface summary]

Create Stage (overall viewport) instance.

[Parameters]

stage_width: int, default 300
- Stage width.
stage_height: int, default 185
- Stage height
background_color: str, default Colors.WHITE_FFFFFF
- Hexadecimal background color string.
add_to: str, default ‘body’
- Specification of element to add stage. Unique tag (e.g., ‘body’) or ID selector (e.g., ‘#any-unique-elem’) is acceptable.
stage_elem_id: str or None, optional
- ID attribute set to stage HTML element (e.g., ‘line-graph’). If None is set, a random integer will be applied.
variable_name_suffix: str, default “”
- A JavaScript variable name suffix string. This setting is sometimes useful for JavaScript debugging.

[Examples]

>>> import apysc as ap
>>> stage: ap.Stage = ap.Stage(
...     stage_width=500,
...     stage_height=300,
...     background_color=ap.Color("#333"),
...     stage_elem_id="sales_chart",
... )

stage_elem_id property API¶

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

[Interface summary]

Get stage’s html element id.

[Returns]

stage_elem_id: str
- Stage’s html element id (not including class or id symbol). e.g., ‘line-graph’

[Examples]

>>> import apysc as ap
>>> stage: ap.Stage = ap.Stage(
...     stage_width=500,
...     stage_height=300,
...     background_color=ap.Color("#333"),
...     stage_elem_id="sales_chart",
... )
>>> stage.stage_elem_id
'sales_chart'

add_child 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] add_child(self, child: apysc._display.display_object.DisplayObject) -> None

[Interface summary]

Add display object child to this instance.

[Parameters]

child: DisplayObject
- Child instance to add.

[Examples]

>>> import apysc as ap
>>> stage: ap.Stage = ap.Stage()
>>> sprite_1: ap.Sprite = ap.Sprite()
>>> sprite_1.graphics.begin_fill(color=ap.Color("#0af"))
>>> rectangle: ap.Rectangle = sprite_1.graphics.draw_rect(
...     x=50, y=50, width=50, height=50
... )
>>> sprite_2: ap.Sprite = ap.Sprite()
>>> sprite_2.add_child(rectangle)

[References]

add_child and remove_child interfaces

remove_child 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] remove_child(self, child: apysc._display.display_object.DisplayObject) -> None

[Interface summary]

Remove display object child from this instance.

[Parameters]

child: DisplayObject
- Child instance to remove.

[Examples]

>>> import apysc as ap
>>> stage: ap.Stage = ap.Stage()
>>> sprite: ap.Sprite = ap.Sprite()
>>> sprite.graphics.begin_fill(color=ap.Color("#0af"), alpha=0.5)
>>> rectangle: ap.Rectangle = sprite.graphics.draw_rect(
...     x=50, y=50, width=50, height=50
... )
>>> sprite.graphics.remove_child(rectangle)
>>> print(rectangle.parent)
None

[References]

add_child and remove_child interfaces

contains 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] contains(self, child: apysc._display.display_object.DisplayObject) -> apysc._type.boolean.Boolean

[Interface summary]

Get a boolean whether this instance contains a specified child.

[Parameters]

child: DisplayObject
- Child instance to check.

[Returns]

result: Boolean
- If this instance contains a specified child, this method returns True.

[Examples]

>>> import apysc as ap
>>> stage: ap.Stage = ap.Stage()
>>> sprite: ap.Sprite = ap.Sprite()
>>> sprite.graphics.begin_fill(color=ap.Color("#0af"), alpha=0.5)
>>> rectangle: ap.Rectangle = sprite.graphics.draw_rect(
...     x=50, y=50, width=50, height=50
... )
>>> sprite.graphics.contains(rectangle)
Boolean(True)

>>> rectangle.remove_from_parent()
>>> sprite.graphics.contains(rectangle)
Boolean(False)

[References]

contains interface

num_children property API¶

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

[Interface summary]

Get a current children’s number.

[Returns]

num_children: int
- Current children number.

[Examples]

>>> import apysc as ap
>>> stage: ap.Stage = ap.Stage()
>>> sprite: ap.Sprite = ap.Sprite()
>>> sprite.graphics.begin_fill(color=ap.Color("#0af"), alpha=0.5)
>>> rectangle_1: ap.Rectangle = sprite.graphics.draw_rect(
...     x=50, y=50, width=50, height=50
... )
>>> rectangle_2: ap.Rectangle = sprite.graphics.draw_rect(
...     x=150, y=50, width=50, height=50
... )
>>> sprite.graphics.num_children
Int(2)

[References]

num_children interface

get_child_at 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] get_child_at(self, index: Union[int, apysc._type.int.Int]) -> apysc._display.display_object.DisplayObject

[Interface summary]

Get a child at a specified index.

[Parameters]

index: int or Int
- Child’s index (start from 0).

[Returns]

child: DisplayObject
- Target index child instance.

[Examples]

>>> import apysc as ap
>>> stage: ap.Stage = ap.Stage()
>>> sprite: ap.Sprite = ap.Sprite()
>>> sprite.graphics.begin_fill(color=ap.Color("#0af"), alpha=0.5)
>>> rectangle_1: ap.Rectangle = sprite.graphics.draw_rect(
...     x=50, y=50, width=50, height=50
... )
>>> rectangle_2: ap.Rectangle = sprite.graphics.draw_rect(
...     x=150, y=50, width=50, height=50
... )
>>> child_at_index_1: ap.DisplayObject = sprite.graphics.get_child_at(1)
>>> child_at_index_1 == rectangle_2
True

[References]

get_child_at interface

get_stage 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] get_stage() -> apysc._display.stage.Stage

[Interface summary]

Get an already instantiated stage instance.

[Returns]

stage: Stage
- Target stage instance.

[Raises]

StageNotCreatedError: If there is no instantiated stage yet.

Stage class¶

What is the Stage?¶

Create stage¶

Stage background color setting¶

Stage size setting¶

Stage element id setting¶

get_stage function interface¶

Stage class constructor API¶

stage_elem_id property API¶

add_child API¶

remove_child API¶

contains API¶

num_children property API¶

get_child_at API¶

get_stage API¶

Table of Contents

Previous topic

Next topic