xnano.effects
xnano.effects
Animate grid fields with fades, movement, painting, delays, and composition.
Classes:
-
AbstractEffect–Abstract base for user-composed visual effects.
-
FadeEffect–Fade foreground color to a target color.
-
FadeFromEffect–Fade foreground color from a source color.
-
FadeToEffect–Fade foreground and background to target colors.
-
FadeFromBothEffect–Fade foreground and background from source colors.
-
DissolveEffect–Random pixel dissolve transition.
-
CoalesceEffect–Typewriter-style cell assembly.
-
DirectionalEffect–Shared parameters for slide and sweep effects.
-
SweepInEffect–Directional sweep revealing content.
-
SweepOutEffect–Directional sweep hiding content.
-
SlideInEffect–Directional slide revealing content.
-
SlideOutEffect–Directional slide hiding content.
-
PaintEffect–Paint foreground and background to target colors.
-
PaintForegroundEffect–Paint foreground to a target color.
-
PaintBackgroundEffect–Paint background to a target color.
-
SleepEffect–No-op delay used when composing effect sequences.
-
SequenceEffect–Run child effects one after another.
-
ParallelEffect–Run child effects simultaneously.
-
RepeatEffect–Repeat a child effect.
-
DelayEffect–Delay before starting a child effect.
-
EffectHandle–A running effect, per target field.
Functions:
-
resolve_effect–Resolve an effect description into an
AbstractEffect. -
Effect–Create a user-facing effect description.
Attributes:
-
EffectMotion(TypeAlias) –Directional motion for slide and sweep effects.
-
EffectInterpolation(TypeAlias) –Interpolation curve applied over an effect's duration.
-
EffectColorSpace(TypeAlias) –Color interpolation space for color-driven effects.
-
EffectCellFilter(TypeAlias) –Terminal cells selected by an effect.
-
KnownEffectKind(TypeAlias) –Built-in effect kinds that can be composed through
Effector
module-attribute
¶
Directional motion for slide and sweep effects.
Values
"up_to_down": Motion travels from the top edge downward.
"down_to_up": Motion travels from the bottom edge upward.
"left_to_right": Motion travels from the left edge rightward.
"right_to_left": Motion travels from the right edge leftward.
module-attribute
¶
EffectInterpolation: TypeAlias = Literal[
"linear",
"smooth_step",
"sine_in",
"sine_out",
"sine_in_out",
"quad_in",
"quad_out",
"quad_in_out",
"cubic_in",
"cubic_out",
"cubic_in_out",
"expo_in",
"expo_out",
"expo_in_out",
"bounce_in",
"bounce_out",
"bounce_in_out",
"elastic_in",
"elastic_out",
"elastic_in_out",
"back_in",
"back_out",
"back_in_out",
"spring",
]
Interpolation curve applied over an effect's duration.
Values
"linear": Constant-rate progression.
"smooth_step": Eased start and end with a smooth midpoint.
"sine_in" / "sine_out" / "sine_in_out": Sinusoidal easing.
"quad_in" / "quad_out" / "quad_in_out": Quadratic easing.
"cubic_in" / "cubic_out" / "cubic_in_out": Cubic easing.
"expo_in" / "expo_out" / "expo_in_out": Exponential easing.
"bounce_in" / "bounce_out" / "bounce_in_out": Bounce easing.
"elastic_in" / "elastic_out" / "elastic_in_out": Elastic easing.
"back_in" / "back_out" / "back_in_out": Overshoot easing.
"spring": Spring-like easing.
module-attribute
¶
Color interpolation space for color-driven effects.
Values
"rgb": Interpolate in RGB space.
"hsl": Interpolate in HSL space.
"hsv": Interpolate in HSV space.
module-attribute
¶
EffectCellFilter: TypeAlias = Literal[
"all",
"text",
"non_empty",
"background",
"background_only",
]
Terminal cells selected by an effect.
Values
"all": Every cell in the target field area.
"text": Cells containing text-like characters.
"non_empty": Cells whose symbol is not a space.
"background": Cells carrying a non-reset background color.
"background_only": Blank cells carrying a non-reset background;
styled text cells are excluded.
module-attribute
¶
KnownEffectKind: TypeAlias = Literal[
"fade",
"fade_from",
"fade_to",
"fade_from_both",
"dissolve",
"coalesce",
"sweep_in",
"sweep_out",
"slide_in",
"slide_out",
"paint",
"paint_fg",
"paint_bg",
"sleep",
"sequence",
"parallel",
"repeat",
"delay",
]
Built-in effect kinds that can be composed through Effect or
a controller's play_effect.
Values
"fade": Fade foreground color to a target.
"fade_from": Fade foreground color from a source.
"fade_to": Fade foreground and background to targets.
"fade_from_both": Fade foreground and background from sources.
"dissolve": Random pixel dissolve transition.
"coalesce": Typewriter-style cell assembly.
"sweep_in": Directional sweep revealing content.
"sweep_out": Directional sweep hiding content.
"slide_in": Directional slide revealing content.
"slide_out": Directional slide hiding content.
"paint": Paint foreground and background to targets.
"paint_fg": Paint foreground to a target color.
"paint_bg": Paint background to a target color.
"sleep": No-op delay for sequencing.
"sequence": Run child effects one after another.
"parallel": Run child effects simultaneously.
"repeat": Repeat a child effect.
"delay": Delay before starting a child effect.
dataclass
¶
AbstractEffect(
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: ABC
Abstract base for user-composed visual effects.
Subclasses describe effect intent with xnano types and literals.
A controller lowers them to whatever native effect representation it
understands. Terminal and web surfaces both lower these descriptions
through the runtime.
Attributes:
-
duration_ms(int) –Duration in milliseconds.
-
interpolation(EffectInterpolation | None) –Optional interpolation curve.
-
cell_filter(EffectCellFilter | None) –Optional terminal-cell selection.
-
key(str | None) –Optional identity used to replace an active effect.
Examples:
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
FadeEffect(
color: ColorLike = "white",
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Fade foreground color to a target color.
Attributes:
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
FadeFromEffect(
color: ColorLike = "white",
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Fade foreground color from a source color.
Attributes:
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
FadeToEffect(
color: ColorLike = "white",
background: ColorLike = "black",
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Fade foreground and background to target colors.
Attributes:
-
color(ColorLike) –Target foreground color.
-
background(ColorLike) –Target background color.
class-attribute
instance-attribute
¶
background: ColorLike = 'black'
Target background color.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
FadeFromBothEffect(
color: ColorLike = "white",
background: ColorLike = "black",
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Fade foreground and background from source colors.
Attributes:
-
color(ColorLike) –Source foreground color.
-
background(ColorLike) –Source background color.
class-attribute
instance-attribute
¶
background: ColorLike = 'black'
Source background color.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
DissolveEffect(
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Random pixel dissolve transition.
Attributes:
-
duration_ms(int) –Duration in milliseconds.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
CoalesceEffect(
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Typewriter-style cell assembly.
Attributes:
-
duration_ms(int) –Duration in milliseconds.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
DirectionalEffect(
direction: EffectMotion = "left_to_right",
gradient_length: int = 14,
randomness: int = 2,
color: ColorLike = "white",
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Shared parameters for slide and sweep effects.
Attributes:
-
direction(EffectMotion) –Direction of travel.
-
gradient_length(int) –Length of the motion gradient in cells.
-
randomness(int) –Randomness along the gradient.
-
color(ColorLike) –Accent color of the gradient.
class-attribute
instance-attribute
¶
direction: EffectMotion = 'left_to_right'
Direction the effect travels across the target area.
class-attribute
instance-attribute
¶
gradient_length: int = 14
Length of the motion gradient in cells.
class-attribute
instance-attribute
¶
randomness: int = 2
Randomness applied along the gradient.
class-attribute
instance-attribute
¶
color: ColorLike = 'white'
Accent color used by the motion gradient.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
SweepInEffect(
direction: EffectMotion = "left_to_right",
gradient_length: int = 14,
randomness: int = 2,
color: ColorLike = "white",
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: DirectionalEffect
Directional sweep revealing content.
Attributes:
-
direction(EffectMotion) –Direction of travel.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
class-attribute
instance-attribute
¶
direction: EffectMotion = 'left_to_right'
Direction the effect travels across the target area.
class-attribute
instance-attribute
¶
gradient_length: int = 14
Length of the motion gradient in cells.
dataclass
¶
SweepOutEffect(
direction: EffectMotion = "left_to_right",
gradient_length: int = 14,
randomness: int = 2,
color: ColorLike = "white",
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: DirectionalEffect
Directional sweep hiding content.
Attributes:
-
direction(EffectMotion) –Direction of travel.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
class-attribute
instance-attribute
¶
direction: EffectMotion = 'left_to_right'
Direction the effect travels across the target area.
class-attribute
instance-attribute
¶
gradient_length: int = 14
Length of the motion gradient in cells.
dataclass
¶
SlideInEffect(
direction: EffectMotion = "left_to_right",
gradient_length: int = 14,
randomness: int = 2,
color: ColorLike = "white",
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: DirectionalEffect
Directional slide revealing content.
Attributes:
-
direction(EffectMotion) –Direction of travel.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
class-attribute
instance-attribute
¶
direction: EffectMotion = 'left_to_right'
Direction the effect travels across the target area.
class-attribute
instance-attribute
¶
gradient_length: int = 14
Length of the motion gradient in cells.
dataclass
¶
SlideOutEffect(
direction: EffectMotion = "left_to_right",
gradient_length: int = 14,
randomness: int = 2,
color: ColorLike = "white",
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: DirectionalEffect
Directional slide hiding content.
Attributes:
-
direction(EffectMotion) –Direction of travel.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
class-attribute
instance-attribute
¶
direction: EffectMotion = 'left_to_right'
Direction the effect travels across the target area.
class-attribute
instance-attribute
¶
gradient_length: int = 14
Length of the motion gradient in cells.
dataclass
¶
PaintEffect(
color: ColorLike = "white",
background: ColorLike = "black",
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Paint foreground and background to target colors.
Attributes:
-
color(ColorLike) –Target foreground color.
-
background(ColorLike) –Target background color.
class-attribute
instance-attribute
¶
background: ColorLike = 'black'
Target background color.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
PaintForegroundEffect(
color: ColorLike = "white",
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Paint foreground to a target color.
Attributes:
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
PaintBackgroundEffect(
background: ColorLike = "black",
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Paint background to a target color.
Attributes:
-
background(ColorLike) –Target background color.
class-attribute
instance-attribute
¶
background: ColorLike = 'black'
Target background color.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
SleepEffect(
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
No-op delay used when composing effect sequences.
Attributes:
-
duration_ms(int) –Delay in milliseconds.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
SequenceEffect(
effects: tuple[AbstractEffect, ...] = (),
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Run child effects one after another.
Attributes:
-
effects(tuple[AbstractEffect, ...]) –Child effects to run in order.
class-attribute
instance-attribute
¶
effects: tuple[AbstractEffect, ...] = ()
Child effects to run in order.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
ParallelEffect(
effects: tuple[AbstractEffect, ...] = (),
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Run child effects simultaneously.
Attributes:
-
effects(tuple[AbstractEffect, ...]) –Child effects to run in parallel.
class-attribute
instance-attribute
¶
effects: tuple[AbstractEffect, ...] = ()
Child effects to run in parallel.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
RepeatEffect(
child: AbstractEffect | None = None,
times: int | None = None,
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Repeat a child effect.
Attributes:
-
child(AbstractEffect | None) –Effect to repeat.
-
times(int | None) –Number of repetitions, or forever when unset.
class-attribute
instance-attribute
¶
times: int | None = None
Number of times to repeat the child effect.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
DelayEffect(
child: AbstractEffect | None = None,
*,
duration_ms: int = 300,
interpolation: EffectInterpolation | None = None,
cell_filter: EffectCellFilter | None = None,
key: str | None = None
)
Bases: AbstractEffect
Delay before starting a child effect.
Attributes:
-
child(AbstractEffect | None) –Effect to start after the delay.
-
duration_ms(int) –Delay in milliseconds.
class-attribute
instance-attribute
¶
child: AbstractEffect | None = None
Effect to start after the delay.
class-attribute
instance-attribute
¶
duration_ms: int = dataclasses.field(
default=300, kw_only=True
)
Duration of the effect in milliseconds.
class-attribute
instance-attribute
¶
interpolation: EffectInterpolation | None = (
dataclasses.field(default=None, kw_only=True)
)
Optional interpolation curve for the effect.
class-attribute
instance-attribute
¶
cell_filter: EffectCellFilter | None = dataclasses.field(
default=None, kw_only=True
)
Optional terminal-cell selection applied by the controller.
class-attribute
instance-attribute
¶
key: str | None = dataclasses.field(
default=None, kw_only=True
)
Optional identity for this effect instance.
Used by a controller to derive a stable, de-duplicating id per target
field (e.g. f"{key}:{field_name}") so replaying the same effect
kind on the same field replaces the running instance instead of
stacking a new one. Left unset, the controller falls back to the
field name alone.
dataclass
¶
EffectHandle(
keys: tuple[str, ...] = (),
runtime: Any = None,
effect: "AbstractEffect | None" = None,
fields: tuple[str, ...] = (),
loop_in_context: bool = False,
)
A running effect, per target field.
Truthy when at least one target field had a rendered area, so
if self.grid_effect(...) keeps working. Also a context manager:
the effect is cancelled on exit, which is how an effect is scoped to a
block rather than to a duration.
Methods:
-
cancel–Stop the effect on every target field. Idempotent.
Attributes:
-
keys(tuple[str, ...]) –Session keys this handle cancels, one per target field.
-
runtime(Any) –Runtime that registered the effect.
-
effect('AbstractEffect | None') –Resolved effect, replayed on
__enter__when looping. -
fields(tuple[str, ...]) –Target field names, for replay.
-
loop_in_context(bool) –Whether entering a
withblock should loop the effect. -
active(bool) –Whether the effect is still animating.
class-attribute
instance-attribute
¶
Session keys this handle cancels, one per target field.
class-attribute
instance-attribute
¶
runtime: Any = None
Runtime that registered the effect.
class-attribute
instance-attribute
¶
Resolved effect, replayed on __enter__ when looping.
class-attribute
instance-attribute
¶
Target field names, for replay.
class-attribute
instance-attribute
¶
loop_in_context: bool = False
Whether entering a with block should loop the effect.
property
¶
active: bool
Whether the effect is still animating.
False once cancelled. Otherwise reflects the session's own
animation state, which is shared across effects — see
Runtime.is_animating.
Stop the effect on every target field. Idempotent.
resolve_effect(
effect: AbstractEffect | KnownEffectKind,
*,
duration_ms: int = 300,
color: ColorLike | None = None,
background: ColorLike | None = None,
direction: EffectMotion | None = None,
gradient_length: int | None = None,
randomness: int | None = None,
interpolation: EffectInterpolation | None = None,
effects: Sequence[AbstractEffect] | None = None,
child: AbstractEffect | None = None,
times: int | None = None,
key: str | None = None
) -> AbstractEffect
Resolve an effect description into an AbstractEffect.
Parameters:
-
effect(AbstractEffect | KnownEffectKind) –A built effect instance or a known effect kind string.
-
duration_ms(int, default:300) –Duration of the effect in milliseconds.
-
color(ColorLike | None, default:None) –Foreground or accent color for color-driven effects.
-
background(ColorLike | None, default:None) –Background color for two-color effects.
-
direction(EffectMotion | None, default:None) –Motion direction for slide and sweep effects.
-
gradient_length(int | None, default:None) –Gradient length for slide and sweep effects.
-
randomness(int | None, default:None) –Randomness for slide and sweep effects.
-
interpolation(EffectInterpolation | None, default:None) –Interpolation curve for the effect.
-
effects(Sequence[AbstractEffect] | None, default:None) –Child effects for sequence and parallel composition.
-
child(AbstractEffect | None, default:None) –Child effect for repeat and delay composition.
-
times(int | None, default:None) –Repeat count for repeat effects.
-
key(str | None, default:None) –Identity used by a controller to de-duplicate this effect per target field. Ignored when
effectis already anAbstractEffectinstance — setkeyon the instance itself in that case.
Returns:
-
AbstractEffect–A resolved
AbstractEffectinstance.
Source code in xnano/effects.py
Effect(
effect: KnownEffectKind,
*,
duration_ms: int = 300,
color: ColorLike | None = None,
background: ColorLike | None = None,
direction: EffectMotion | None = None,
gradient_length: int | None = None,
randomness: int | None = None,
interpolation: EffectInterpolation | None = None,
effects: Sequence[AbstractEffect] | None = None,
child: AbstractEffect | None = None,
times: int | None = None,
key: str | None = None
) -> AbstractEffect
Effect(
effect: AbstractEffect,
*,
duration_ms: int = 300,
color: ColorLike | None = None,
background: ColorLike | None = None,
direction: EffectMotion | None = None,
gradient_length: int | None = None,
randomness: int | None = None,
interpolation: EffectInterpolation | None = None,
effects: Sequence[AbstractEffect] | None = None,
child: AbstractEffect | None = None,
times: int | None = None,
key: str | None = None
) -> AbstractEffect
Effect(
effect: KnownEffectKind | AbstractEffect,
*,
duration_ms: int = 300,
color: ColorLike | None = None,
background: ColorLike | None = None,
direction: EffectMotion | None = None,
gradient_length: int | None = None,
randomness: int | None = None,
interpolation: EffectInterpolation | None = None,
effects: Sequence[AbstractEffect] | None = None,
child: AbstractEffect | None = None,
times: int | None = None,
key: str | None = None
) -> AbstractEffect
Create a user-facing effect description.
Parameters:
-
effect(KnownEffectKind | AbstractEffect) –A known effect kind or an existing effect instance.
-
duration_ms(int, default:300) –Duration of the effect in milliseconds.
-
color(ColorLike | None, default:None) –Foreground or accent color for color-driven effects.
-
background(ColorLike | None, default:None) –Background color for two-color effects.
-
direction(EffectMotion | None, default:None) –Motion direction for slide and sweep effects.
-
gradient_length(int | None, default:None) –Gradient length for slide and sweep effects.
-
randomness(int | None, default:None) –Randomness for slide and sweep effects.
-
interpolation(EffectInterpolation | None, default:None) –Interpolation curve for the effect.
-
effects(Sequence[AbstractEffect] | None, default:None) –Child effects for sequence and parallel composition.
-
child(AbstractEffect | None, default:None) –Child effect for repeat and delay composition.
-
times(int | None, default:None) –Repeat count for repeat effects.
-
key(str | None, default:None) –Identity used by a controller to de-duplicate this effect per target field, e.g. distinguishing two independently triggered
"fade"effects on the same grid.
Returns:
-
AbstractEffect–A resolved
AbstractEffectinstance.