EffectCharacter

Module: terminaltexteffects.engine.base_character

A class representing a single character from the input data.

EffectCharacters are managed by the Terminal and are used to apply animations and effects to individual characters. Add an EffectCharacter to the Terminal using the add_character method of the Terminal class.

Methods:

Name	Description
tick	Progress the character's animation and motion by one step.

Attributes:

Name	Type	Description
character_id	int	The unique ID of the character, generated by the Terminal.
input_symbol	str	The symbol for the character in the input data.
input_coord	Coord	The coordinate of the character in the input data.
is_visible	bool	Whether the character is currently visible and should be printed to the terminal.
animation	Animation	The animation object that controls the character's appearance.
motion	Motion	The motion object that controls the character's movement.
event_handler	EventHandler	The event handler object that handles events related to the character.
layer	int	The layer of the character. The layer determines the order in which characters are printed.
is_fill_character	bool	Whether the character is a fill character. Fill characters are used to fill the empty cells of the Canvas.

Source code in terminaltexteffects/engine/base_character.py

class EffectCharacter:
    """A class representing a single character from the input data.

    EffectCharacters are managed by the Terminal and are used to apply animations and effects to individual characters.
    Add an EffectCharacter to the Terminal using the add_character method of the Terminal class.

    Methods:
        tick: Progress the character's animation and motion by one step.

    Attributes:
        character_id (int): The unique ID of the character, generated by the Terminal.
        input_symbol (str): The symbol for the character in the input data.
        input_coord (Coord): The coordinate of the character in the input data.
        is_visible (bool): Whether the character is currently visible and should be printed to the terminal.
        animation (graphics.Animation): The animation object that controls the character's appearance.
        motion (motion.Motion): The motion object that controls the character's movement.
        event_handler (EventHandler): The event handler object that handles events related to the character.
        layer (int): The layer of the character. The layer determines the order in which characters are printed.
        is_fill_character (bool): Whether the character is a fill character. Fill characters are used to fill
            the empty cells of the Canvas.

    """

    def __init__(self, character_id: int, symbol: str, input_column: int, input_row: int) -> None:
        """Initialize the character instance with the character ID, symbol, and input coordinates.

        Args:
            character_id (int): The unique ID of the character, generated by the Terminal.
            symbol (str): The symbol for the character in the input data.
            input_column (int): The column of the character in the input data.
            input_row (int): The row of the character in the input data.

        """
        self._character_id: int = character_id
        self._input_symbol: str = symbol
        self._input_coord: Coord = Coord(input_column, input_row)
        self._input_ansi_sequences: dict[str, str | None] = {"fg_color": None, "bg_color": None}
        self._is_visible: bool = False
        self.animation: animation.Animation = animation.Animation(self)
        self.motion: motion.Motion = motion.Motion(self)
        self.event_handler: EventHandler = EventHandler(self)
        self.layer: int = 0
        self.is_fill_character = False
        self.links: set[EffectCharacter] = set()
        self.neighbors: dict[str, EffectCharacter | None] = {}

    @property
    def input_symbol(self) -> str:
        """The symbol for the character in the input data."""
        return self._input_symbol

    @property
    def input_coord(self) -> Coord:
        """The coordinate of the character in the input data."""
        return self._input_coord

    @property
    def is_visible(self) -> bool:
        """Whether the character is currently visible and should be printed to the terminal."""
        return self._is_visible

    @property
    def character_id(self) -> int:
        """The unique ID of the character, generated by the Terminal."""
        return self._character_id

    @property
    def is_active(self) -> bool:
        """Returns whether the character is currently active.

        A character is active if its animation or motion is not complete.

        Returns:
            bool: True if the character is active, False if not.

        """
        return bool(not self.animation.active_scene_is_complete() or not self.motion.movement_is_complete())

    def tick(self) -> None:
        """Progress the character's animation and motion by one step."""
        self.motion.move()
        self.animation.step_animation()

    def _link(self, char: EffectCharacter, *, bidirectional: bool = True) -> None:
        """Link this character with another character.

        Used for spanning tree algorithms.

        Args:
            char (EffectCharacter): Character being linked to this character.
            bidirectional (bool, optional): Apply the link on both characters. Defaults to True.

        """
        if bidirectional:
            char._link(self, bidirectional=False)
        self.links.add(char)

    def __hash__(self) -> int:
        """Return the hash value of the character."""
        return hash(self.character_id)

    def __eq__(self, other: object) -> bool:
        """Check if two EffectCharacter instances are equal based on their character_id."""
        if not isinstance(other, EffectCharacter):
            return NotImplemented
        return self.character_id == other.character_id

    def __repr__(self) -> str:
        """Return a string representation of the EffectCharacter instance."""
        return (
            f"EffectCharacter(character_id={self.character_id}, symbol='{self.input_symbol}', "
            f"input_column={self.input_coord.column}, input_row={self.input_coord.row})"
        )

character_id property

The unique ID of the character, generated by the Terminal.

input_coord property

The coordinate of the character in the input data.

input_symbol property

The symbol for the character in the input data.

is_active property

Returns whether the character is currently active.

A character is active if its animation or motion is not complete.

Returns:

Name	Type	Description
bool	bool	True if the character is active, False if not.

is_visible property

Whether the character is currently visible and should be printed to the terminal.

__eq__(other)

Check if two EffectCharacter instances are equal based on their character_id.

Source code in terminaltexteffects/engine/base_character.py

def __eq__(self, other: object) -> bool:
    """Check if two EffectCharacter instances are equal based on their character_id."""
    if not isinstance(other, EffectCharacter):
        return NotImplemented
    return self.character_id == other.character_id

__hash__()

Return the hash value of the character.

Source code in terminaltexteffects/engine/base_character.py

def __hash__(self) -> int:
    """Return the hash value of the character."""
    return hash(self.character_id)

__init__(character_id, symbol, input_column, input_row)

Initialize the character instance with the character ID, symbol, and input coordinates.

Parameters:

Name	Type	Description	Default
character_id	int	The unique ID of the character, generated by the Terminal.	required
symbol	str	The symbol for the character in the input data.	required
input_column	int	The column of the character in the input data.	required
input_row	int	The row of the character in the input data.	required

Source code in terminaltexteffects/engine/base_character.py

def __init__(self, character_id: int, symbol: str, input_column: int, input_row: int) -> None:
    """Initialize the character instance with the character ID, symbol, and input coordinates.

    Args:
        character_id (int): The unique ID of the character, generated by the Terminal.
        symbol (str): The symbol for the character in the input data.
        input_column (int): The column of the character in the input data.
        input_row (int): The row of the character in the input data.

    """
    self._character_id: int = character_id
    self._input_symbol: str = symbol
    self._input_coord: Coord = Coord(input_column, input_row)
    self._input_ansi_sequences: dict[str, str | None] = {"fg_color": None, "bg_color": None}
    self._is_visible: bool = False
    self.animation: animation.Animation = animation.Animation(self)
    self.motion: motion.Motion = motion.Motion(self)
    self.event_handler: EventHandler = EventHandler(self)
    self.layer: int = 0
    self.is_fill_character = False
    self.links: set[EffectCharacter] = set()
    self.neighbors: dict[str, EffectCharacter | None] = {}

__repr__()

Return a string representation of the EffectCharacter instance.

Source code in terminaltexteffects/engine/base_character.py

def __repr__(self) -> str:
    """Return a string representation of the EffectCharacter instance."""
    return (
        f"EffectCharacter(character_id={self.character_id}, symbol='{self.input_symbol}', "
        f"input_column={self.input_coord.column}, input_row={self.input_coord.row})"
    )

tick()

Progress the character's animation and motion by one step.

Source code in terminaltexteffects/engine/base_character.py

def tick(self) -> None:
    """Progress the character's animation and motion by one step."""
    self.motion.move()
    self.animation.step_animation()