Skip to content

CharacterVisual

Module: terminaltexteffects.engine.animation

A class for storing symbol, color, and terminal graphical modes for the character.

Parameters:

Name Type Description Default
symbol str

The unformatted symbol.

 required
bold bool

Bold mode.

 False
dim bool

Dim mode.

 False
italic bool

Italic mode.

 False
underline bool

Underline mode.

 False
blink bool

Blink mode.

 False
reverse bool

Reverse mode.

 False
hidden bool

Hidden mode.

 False
strike bool

Strike mode.

 False
colors ColorPair | None

The symbol's colors.

 None
_fg_color_code str | int | None

The symbol's foreground color code.

 None
_bg_color_code str | int | None

The symbol's background color code.

 None

Attributes:

Name Type Description
formatted_symbol str

The current symbol with all ANSI sequences applied.

Methods:

Name Description
format_symbol

Formats the symbol for printing by applying ANSI sequences for supported active modes and color.
Source code in terminaltexteffects/engine/animation.py 
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
@dataclass
class CharacterVisual:
    """A class for storing symbol, color, and terminal graphical modes for the character.

    Args:
        symbol (str): The unformatted symbol.
        bold (bool): Bold mode.
        dim (bool): Dim mode.
        italic (bool): Italic mode.
        underline (bool): Underline mode.
        blink (bool): Blink mode.
        reverse (bool): Reverse mode.
        hidden (bool): Hidden mode.
        strike (bool): Strike mode.
        colors (graphics.ColorPair | None): The symbol's colors.
        _fg_color_code (str | int | None): The symbol's foreground color code.
        _bg_color_code (str | int | None): The symbol's background color code.

    Attributes:
        formatted_symbol (str): The current symbol with all ANSI sequences applied.

    Methods:
        format_symbol: Formats the symbol for printing by applying ANSI sequences for supported active modes and color.

    """

    symbol: str
    bold: bool = False
    dim: bool = False
    italic: bool = False
    underline: bool = False
    blink: bool = False
    reverse: bool = False
    hidden: bool = False
    strike: bool = False
    colors: graphics.ColorPair | None = None  # the Color object provided during initialization
    # the _*_color_code attributes are used to store the actual 8-bit int or 24-bit hex str after applying terminal
    # config args these are used by colorterm to produce the ansi sequences
    _fg_color_code: str | int | None = None
    _bg_color_code: str | int | None = None

    def __post_init__(self) -> None:
        """Create the formatted symbol by applying ANSI sequences for any active modes and color."""
        self.formatted_symbol = self.format_symbol()

    def format_symbol(self) -> str:
        """Format the symbol for printing by applying ANSI sequences for supported active modes and color.

        The `dim` attribute is stored on the visual but is not currently emitted as an ANSI sequence.
        """
        formatting_string = ""
        if self.bold:
            formatting_string += ansitools.apply_bold()
        # Future: review the dim ANSI sequence and decide whether CharacterVisual should emit it.
        if self.italic:
            formatting_string += ansitools.apply_italic()
        if self.underline:
            formatting_string += ansitools.apply_underline()
        if self.blink:
            formatting_string += ansitools.apply_blink()
        if self.reverse:
            formatting_string += ansitools.apply_reverse()
        if self.hidden:
            formatting_string += ansitools.apply_hidden()
        if self.strike:
            formatting_string += ansitools.apply_strikethrough()
        if self._fg_color_code is not None:
            formatting_string += colorterm.fg(self._fg_color_code)
        if self._bg_color_code is not None:
            formatting_string += colorterm.bg(self._bg_color_code)

        return f"{formatting_string}{self.symbol}{ansitools.reset_all() if formatting_string else ''}"

__post_init__()

Create the formatted symbol by applying ANSI sequences for any active modes and color.

Source code in terminaltexteffects/engine/animation.py 
70
71
72
def __post_init__(self) -> None:
    """Create the formatted symbol by applying ANSI sequences for any active modes and color."""
    self.formatted_symbol = self.format_symbol()

format_symbol()

Format the symbol for printing by applying ANSI sequences for supported active modes and color.

The dim attribute is stored on the visual but is not currently emitted as an ANSI sequence.

Source code in terminaltexteffects/engine/animation.py 
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def format_symbol(self) -> str:
    """Format the symbol for printing by applying ANSI sequences for supported active modes and color.

    The `dim` attribute is stored on the visual but is not currently emitted as an ANSI sequence.
    """
    formatting_string = ""
    if self.bold:
        formatting_string += ansitools.apply_bold()
    # Future: review the dim ANSI sequence and decide whether CharacterVisual should emit it.
    if self.italic:
        formatting_string += ansitools.apply_italic()
    if self.underline:
        formatting_string += ansitools.apply_underline()
    if self.blink:
        formatting_string += ansitools.apply_blink()
    if self.reverse:
        formatting_string += ansitools.apply_reverse()
    if self.hidden:
        formatting_string += ansitools.apply_hidden()
    if self.strike:
        formatting_string += ansitools.apply_strikethrough()
    if self._fg_color_code is not None:
        formatting_string += colorterm.fg(self._fg_color_code)
    if self._bg_color_code is not None:
        formatting_string += colorterm.bg(self._bg_color_code)

    return f"{formatting_string}{self.symbol}{ansitools.reset_all() if formatting_string else ''}"