Marquee

pywry.toolbar.Marquee

Bases: ToolbarItem

A scrolling text/content ticker component using CSS animations.

Displays content that scrolls horizontally or vertically across the container. Useful for news tickers, announcements, or any content that should scroll continuously.

Uses CSS animations instead of the deprecated <marquee> HTML element for better browser compatibility, performance, and accessibility.

Emits {value: ..., componentId: ...} when clicked (if clickable=True).

ATTRIBUTE	DESCRIPTION
text	The text content to scroll. Can include simple inline HTML. TYPE: str
speed	Animation duration in seconds for one complete scroll cycle. Lower values = faster scrolling (default: 15.0, range: 1.0 - 300.0). TYPE: float
direction	Scroll direction: "left" (default), "right", "up", or "down". TYPE: str
behavior	Animation behavior: "scroll" (default, continuous loop), "alternate" (bounces), "slide" (scrolls once), or "static" (no scrolling). TYPE: str
pause_on_hover	Pause animation when mouse hovers over marquee (default: True). TYPE: bool
gap	Gap in pixels between repeated content for seamless looping (default: 50, range: 0 - 500). TYPE: int
clickable	Whether clicking the marquee emits an event (default: False). TYPE: bool
separator	Optional separator string between repeated content, e.g., " • " (default: ""). TYPE: str
items	List of content items to cycle through for static behavior (default: None). TYPE: list of str or None
children	Nested toolbar items to scroll (alternative to text for complex content). TYPE: list or None

Examples:

Simple news ticker:

>>> Marquee(
...     text="Breaking News: Stock prices are up 5% today!",
...     event="ticker:click",
...     speed=20,
...     pause_on_hover=True,
... )

Bouncing alert:

>>> Marquee(
...     text="⚠️ System maintenance scheduled",
...     behavior="alternate",
...     speed=8,
...     style="background: var(--pywry-accent); padding: 4px 8px;",
... )

Vertical scrolling credits:

>>> Marquee(
...     text="Thank you for using PyWry!",
...     direction="up",
...     speed=10,
... )

Functions

validate_content

validate_content() -> Marquee

Ensure either text or children is provided.

build_html

build_html(parent_id: str | None = None) -> str

Build marquee HTML with CSS animation.

PARAMETER	DESCRIPTION
parent_id	Parent component ID for context chain inheritance. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
str	HTML string for the marquee component.

collect_scripts

collect_scripts() -> list[str]

Collect scripts from nested children (for consistency with Div).

RETURNS	DESCRIPTION
list[str]	List of script content strings from children.

update_payload

update_payload(text: str | None = None, html_content: str | None = None, speed: float | None = None, paused: bool | None = None, separator: str | None = None) -> tuple[str, dict[str, Any]]

Generate event name and payload for dynamic marquee updates.

Use this with widget.emit() to update marquee content dynamically.

PARAMETER	DESCRIPTION
text	New plain text content (will be escaped). TYPE: str | None DEFAULT: None
html_content	New HTML content (use instead of text for rich content). TYPE: str | None DEFAULT: None
speed	New animation speed in seconds. TYPE: float | None DEFAULT: None
paused	True to pause, False to resume animation. TYPE: bool | None DEFAULT: None
separator	New separator between repeated content. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
tuple[str, dict[str, Any]]	Event name and payload dict for widget.emit().

Example

ticker = Marquee(text="Loading...", component_id="news-ticker")
# ... later ...
event, data = ticker.update_payload(text="Breaking news!")
widget.emit(event, data)

# Or with speed change:
event, data = ticker.update_payload(text="Urgent!", speed=8)
widget.emit(event, data)

auto_generate_component_id

auto_generate_component_id() -> ToolbarItem

Auto-generate component_id based on type if not provided.

validate_event_name classmethod

validate_event_name(v: str) -> str

Validate event follows namespace:event-name pattern.