Graphics begin_fill interface

This page explains the Graphics class begin_fill method interface.

What interface is this?

begin_fill interface would set the fill color and fill alpha settings. This setting would be maintained until it is called again or called the clear method.

Basic usage

Draw vector graphics interfaces (e.g., draw_rect) would use these fill settings when creating, so the begin_fill method needs to be called before calling each drawing interface.

import apysc as ap

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

# Set blue fill color and draw the first rectangle.
sprite.graphics.begin_fill(color=ap.Color("#0af"))
sprite.graphics.draw_rect(x=50, y=50, width=50, height=50)

# Draw the second rectangle (fill color setting will be maintained).
sprite.graphics.draw_rect(x=150, y=50, width=50, height=50)

# Set the other fill color and draw the third rectangle.
sprite.graphics.begin_fill(color=ap.Color("#f0a"))
sprite.graphics.draw_rect(x=250, y=50, width=50, height=50)

ap.save_overall_html(dest_dir_path="graphics_begin_fill_basic_usage/")

Fill color setting

The color argument sets the fill color, and the begin_fill interface requires this argument.

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()

# Set a cyan fill color and draw the rectangle.
sprite.graphics.begin_fill(color=ap.Color("#0af"))
sprite.graphics.draw_rect(x=50, y=50, width=50, height=50)

ap.save_overall_html(dest_dir_path="graphics_begin_fill_fill_color/")

If you want to clear fill color, specify the COLORLESS constant to this argument.

For example, since the following code clears fill color settings, a rectangle graphic becomes invisible.

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"))

# Clear fill color by specifying the `COLORLESS`` constant.
sprite.graphics.begin_fill(color=ap.COLORLESS)

# Since fill color is not set, the rectangle is invisible.
sprite.graphics.draw_rect(x=50, y=50, width=50, height=50)

ap.save_overall_html(dest_dir_path="graphics_begin_fill_color_setting_clear/")

Color code is acceptable like the following list:

  • Six characters, e.g., #00aaff.

  • Three characters, e.g., #0af (this becomes #00aaff).

  • A single character, e.g., #5 (this becomes #000005).

  • A skipped # symbol string, e.g., 0af (this becomes #00aaff).

  • The COLORLESS constant (this setting clears the fill color setting).

import apysc as ap

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

# Six characters fill color setting (a cyan color).
sprite.graphics.begin_fill(color=ap.Color("#00aaff"))
sprite.graphics.draw_rect(x=50, y=50, width=50, height=50)

# Three characters fill color setting (a magenta color).
sprite.graphics.begin_fill(color=ap.Color("#f0a"))
sprite.graphics.draw_rect(x=150, y=50, width=50, height=50)

# Single characters fill color setting (a black color).
sprite.graphics.begin_fill(color=ap.Color("#0"))
sprite.graphics.draw_rect(x=250, y=50, width=50, height=50)

# Fill color that a skipped `#` symbol is also acceptable.
sprite.graphics.begin_fill(color=ap.Color("999"))
sprite.graphics.draw_rect(x=350, y=50, width=50, height=50)

ap.save_overall_html(dest_dir_path="graphics_begin_fill_acceptable_color_settings/")

Fill color alpha (opacity) setting

Fill color alpha (opacity) can be set by the alpha argument. It can accept 0.0 (transparent) to 1.0 (opaque).

import apysc as ap

ap.Stage(
    background_color=ap.Color("#333"),
    stage_width=200,
    stage_height=200,
    stage_elem_id="stage",
)
sprite: ap.Sprite = ap.Sprite()

sprite.graphics.begin_fill(color=ap.Color("#00aaff"), alpha=0.2)
sprite.graphics.draw_rect(x=50, y=75, width=50, height=50)
sprite.graphics.draw_rect(x=75, y=50, width=50, height=50)
sprite.graphics.draw_rect(x=75, y=75, width=50, height=50)
sprite.graphics.draw_rect(x=75, y=100, width=50, height=50)
sprite.graphics.draw_rect(x=100, y=75, width=50, height=50)

ap.save_overall_html(dest_dir_path="graphics_begin_fill_alpha_setting/")

begin_fill 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] begin_fill(self, *, color: apysc._color.color.Color, alpha: Union[float, apysc._type.number.Number] = 1.0) -> None

[Interface summary]

Set single color value for fill.

[Parameters]

  • color: Color

    • A color setting.

  • alpha: float or Number, default 1.0

    • Color opacity (0.0 to 1.0).

[Examples]

>>> import apysc as ap
>>> _ = ap.Stage(
...     stage_width=150,
...     stage_height=150,
...     background_color=ap.Color("#333"),
...     stage_elem_id="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
... )
>>> rectangle.fill_color
Color("#00aaff")

>>> rectangle.fill_alpha
Number(0.5)

fill_color 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 fill color.

[Returns]

  • fill_color: Color

    • Current fill-color. If not be set, this interface returns a COLORLESS constant.

[Examples]

>>> import apysc as ap
>>> _ = ap.Stage(
...     stage_width=150,
...     stage_height=150,
...     background_color=ap.Color("#333"),
...     stage_elem_id="stage",
... )
>>> sprite: ap.Sprite = ap.Sprite()
>>> sprite.graphics.begin_fill(
...     color=ap.Color("#0af"),
...     alpha=0.5,
... )
>>> sprite.graphics.fill_color
Color("#00aaff")

fill_alpha 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 current fill color opacity.

[Returns]

  • fill_alpha: Number

    • Current fill color opacity (0.0 to 1.0). If not be set, 1.0 will be returned.

[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
... )
>>> rectangle.fill_alpha
Number(0.5)