Toast Notification System - Complete Guide

Back to Documentation Hub

Toast Notification System - Complete Guide

Component: bravura.components.toasts.Toast and bravura.components.toasts.ToastCenter

Status: ✅ Production Ready

License Tiers: All tiers (Standard, Professional, Enterprise)

Last Updated: October 17, 2025

---

Overview

The Bravura SDK provides a sophisticated toast notification system with two distinct visual styles and full theme integration. Toast notifications are transient, non-blocking messages that appear temporarily to provide feedback, alerts, or status updates to users.

Key Features

---

Table of Contents

  1. Visual Styles
  2. Notification Types
  3. Theme Integration
  4. Basic Usage
  5. Advanced Configuration
  6. Best Practices
  7. API Reference
  8. Troubleshooting

---

Visual Styles

Standard Style (All Tiers)

The default toast style featuring clean, modern design with theme-aware colors.

Visual Characteristics:

Best For:

Example Appearance:


┌────────────────────────────────────────┐
│  ℹ️  This is an informational toast   │
│     notification message               │  ×
└────────────────────────────────────────┘

Premium Style (Professional/Enterprise)

A glass panel style with frosted effects and elevated depth for premium applications.

Visual Characteristics:

Best For:

Example Appearance:


╔════════════════════════════════════════╗
║  ✅  Operation completed successfully! ║
║     All files processed                ║  ×
╚════════════════════════════════════════╝
   (with frosted glass effect)

License Requirement:

---

Notification Types

Info Notifications

Purpose: General information, neutral updates, status messages

Theme Colors Used:

Icon: ℹ️

Example Use Cases:


toast_center.show("Settings have been saved", kind="info")

Success Notifications

Purpose: Successful operations, completed tasks, positive confirmations

Theme Colors Used:

Icon: ✅

Example Use Cases:


toast_center.show("Upload complete!", kind="success",
                  sub_message="All files processed")

Warning Notifications

Purpose: Cautionary messages, non-critical issues, important notices

Theme Colors Used:

Icon: ⚠️

Example Use Cases:


toast_center.show("Warning: Please review your settings",
                  kind="warning")

Error Notifications

Purpose: Errors, failures, critical issues requiring attention

Theme Colors Used:

Icon: ❌

Example Use Cases:


toast_center.show("Error: Failed to save changes",
                  kind="error",
                  sub_message="Please try again")

---

Theme Integration

How Theme Colors Work

Toast notifications dynamically adapt to the active theme by pulling colors from the theme token system:


# Toast styling uses these theme tokens:
{
    "background_secondary": "#2a2a2a",  # Toast background
    "text_main": "#ffffff",             # Primary text
    "text_secondary": "#cccccc",        # Secondary text
    "border_color": "#444444",          # Border and outlines
    "accent_color_1": "#26D0CE",        # Info notifications
    "success_color": "#10B981",         # Success notifications
    "warning_color": "#F59E0B",         # Warning notifications
    "error_color": "#EF4444"            # Error notifications
}

Theme Examples

Each of the 10 Bravura themes provides unique color palettes:

Standard Themes (All Tiers):

  1. Light - Clean white/gray with teal accents
  2. Dark - Professional dark gray with teal accents
  3. Black - Deep black with purple accents
  4. White - Pure white with red accents
  5. Blue - Sky blue backgrounds with seafoam accents
  6. Pink - Soft pink backgrounds with pink accents
  7. Ocean - Deep blue-green with cyan accents

Premium Themes (Professional/Enterprise):

  1. Wigley Studios - Premium teal/gold brand colors
  2. Platinum - Warm platinum gold with sophisticated accents
  3. Custom Branding - Rich indigo with modern status colors

Dynamic Theme Switching

When users switch themes, toast notifications automatically update:


# Apply new theme
theme_manager.apply_theme("ocean")

# New toasts automatically use Ocean theme colors
toast_center.show("Theme changed!", kind="success")
# Result: Toast with deep blue background and cyan success icon

Important: Existing visible toasts retain their original theme colors. Only new toasts created after the theme change will use the new colors.

---

Basic Usage

Quick Start


import tkinter as tk
from bravura.themes.theme_manager import ProfessionalThemeManager
from bravura.components.toasts import create_toast_center

class MyApp:
    def __init__(self):
        self.root = tk.Tk()
        self.root.title("My Application")

        # Initialize theme manager
        self.theme_manager = ProfessionalThemeManager(self)
        self.theme_manager.apply_theme("dark")

        # Create toast center
        theme_colors = self.theme_manager.get_current_theme_colors()
        self.toast_center = create_toast_center(
            self.root,
            theme_colors
        )

        # Show a notification
        self.toast_center.show(
            "Welcome to my application!",
            kind="info"
        )

if __name__ == "__main__":
    app = MyApp()
    app.root.mainloop()

Simple Notifications


# Info notification
toast_center.show("Processing started", kind="info")

# Success notification
toast_center.show("Task completed", kind="success")

# Warning notification
toast_center.show("Please review settings", kind="warning")

# Error notification
toast_center.show("Failed to connect", kind="error")

Notifications with Details


# Main message with additional details
toast_center.show(
    main_message="Operation completed successfully",
    sub_message="All 42 files processed",
    kind="success"
)

# Multi-line details
toast_center.show(
    main_message="Configuration updated",
    sub_message="Theme: Dark\nLanguage: English\nAutostart: Enabled",
    kind="info"
)

---

Advanced Configuration

Creating a Toast Center


from bravura.components.toasts import ToastCenter

# Manual creation with full control
toast_center = ToastCenter(
    parent=root_window,
    tokens=theme_manager.get_current_theme_colors(),
    default_style="standard",  # or "premium"
    default_duration=3000,     # 3 seconds
    max_toasts=5,              # Maximum visible toasts
    spacing=10                 # Pixels between toasts
)

Custom Duration


# Quick message (1 second)
toast_center.show("Saved!", kind="success", duration=1000)

# Standard duration (3 seconds) - default
toast_center.show("Processing...", kind="info", duration=3000)

# Long message (5 seconds)
toast_center.show(
    "Important: Please read the release notes",
    kind="warning",
    duration=5000
)

# Persistent toast (requires manual dismissal)
toast_center.show("Critical error", kind="error", duration=None)

Style Override


# Force standard style (even for Pro/Enterprise users)
toast_center.show(
    "Standard notification",
    kind="info",
    style="standard"
)

# Request premium style (falls back if not licensed)
toast_center.show(
    "Premium notification",
    kind="success",
    style="premium"
)

Position Control


# Default: Top-right corner
toast_center.position = "top-right"

# Other positions
toast_center.position = "top-left"
toast_center.position = "bottom-right"
toast_center.position = "bottom-left"
toast_center.position = "top-center"
toast_center.position = "bottom-center"

Manual Dismissal


# Users can click the X button on any toast
# Or click anywhere on the toast to dismiss it

# Programmatic dismissal of all toasts
toast_center.dismiss_all()

# Get currently visible toasts
active_toasts = toast_center.get_active_toasts()
print(f"{len(active_toasts)} toasts currently visible")

---

Best Practices

When to Use Toast Notifications

✅ Good Use Cases:

❌ Avoid For:

Message Length Guidelines

Main Message:

Sub Message:

Examples:

✅ Good:


toast_center.show(
    "File uploaded successfully",
    sub_message="photo_2025.jpg (2.4 MB)",
    kind="success"
)

❌ Too Verbose:


toast_center.show(
    "The file that you selected has been successfully uploaded to the server and is now available for viewing",
    kind="success"
)

Choosing the Right Style

Use Standard Style When:

Use Premium Style When:

Frequency and Timing

Frequency:

Duration:

Example:


# Good: Group related actions
toast_center.show(
    "3 items deleted",
    sub_message="Photo1.jpg, Photo2.jpg, Photo3.jpg",
    kind="success"
)

# Bad: Showing 3 separate toasts in rapid succession

Accessibility Considerations

Visual:

Interaction:

Implementation Tips:


# Pair toasts with other feedback methods
def save_data():
    # Save data
    success = perform_save()

    # Visual feedback (toast)
    toast_center.show("Data saved", kind="success")

    # Status bar update (persistent)
    status_bar.set_text("Last saved: " + get_timestamp())

    # Optional: Sound feedback for accessibility
    play_success_sound()

Performance Optimization

For Applications with Frequent Notifications:


# Limit maximum visible toasts
toast_center = ToastCenter(
    parent=root,
    tokens=theme_colors,
    max_toasts=3  # Only show 3 at a time
)

# Batch notifications when possible
def process_multiple_files(files):
    results = [process_file(f) for f in files]

    success_count = sum(1 for r in results if r.success)

    # Single notification instead of one per file
    toast_center.show(
        f"Processed {len(files)} files",
        sub_message=f"{success_count} successful",
        kind="success"
    )

Canvas Rendering:

---

API Reference

ToastCenter Class


class ToastCenter:
    """Manages toast notification display and lifecycle."""

    def __init__(
        self,
        parent: tk.Widget,
        tokens: dict,
        default_style: str = "standard",
        default_duration: int = 3000,
        max_toasts: int = 5,
        spacing: int = 10
    ):
        """
        Initialize toast notification center.

        Args:
            parent: Parent Tkinter widget
            tokens: Theme color tokens dictionary
            default_style: "standard" or "premium"
            default_duration: Default toast duration in milliseconds
            max_toasts: Maximum number of visible toasts
            spacing: Pixels between stacked toasts
        """

show() Method


def show(
    self,
    main_message: str,
    kind: str = "info",
    sub_message: str = "",
    duration: Optional[int] = None,
    style: Optional[str] = None
) -> Toast:
    """
    Show a toast notification.

    Args:
        main_message: Primary message text
        kind: Notification type - "info", "success", "warning", "error"
        sub_message: Optional secondary message text
        duration: Display duration in ms (None = manual dismiss only)
        style: Override default style - "standard" or "premium"

    Returns:
        Toast instance
    """

Helper Functions


def create_toast_center(
    parent: tk.Widget,
    theme_tokens: dict,
    default_style: str = "standard"
) -> ToastCenter:
    """
    Convenience function to create a toast center.

    Args:
        parent: Parent widget
        theme_tokens: Theme color dictionary
        default_style: "standard" or "premium"

    Returns:
        Configured ToastCenter instance
    """

Toast Class


class Toast:
    """Individual toast notification instance."""

    def dismiss(self):
        """Manually dismiss this toast."""

    def is_visible(self) -> bool:
        """Check if toast is currently visible."""

    def extend_duration(self, additional_ms: int):
        """Extend the display duration."""

---

Troubleshooting

Common Issues

Toasts Don't Appear:


# Problem: Parent widget not properly initialized
# Solution: Ensure parent is visible and has size

# Check parent widget
print(f"Parent width: {root.winfo_width()}")
print(f"Parent height: {root.winfo_height()}")

# Force geometry update
root.update_idletasks()

# Then create toast center
toast_center = create_toast_center(root, theme_colors)

Theme Colors Not Applied:


# Problem: Theme manager not initialized or tokens not passed
# Solution: Always pass fresh theme tokens

# Get current theme colors
theme_colors = theme_manager.get_current_theme_colors()

# Pass to toast center
toast_center = create_toast_center(root, theme_colors)

# After theme change, recreate toast center
def on_theme_change(new_theme):
    theme_manager.apply_theme(new_theme)

    # Recreate toast center with new colors
    self.toast_center = create_toast_center(
        self.root,
        theme_manager.get_current_theme_colors()
    )

Premium Style Shows Standard Instead:


# Problem: Standard tier license
# Solution: Upgrade to Professional or Enterprise

# Check console for warning message:
# "Warning: Premium toast style requires Professional/Enterprise license"

# Workaround: Use standard style with theme customization
toast_center = create_toast_center(
    root,
    theme_colors,
    default_style="standard"  # Explicit standard style
)

Toasts Overlap Other UI Elements:


# Problem: Z-order or positioning issues
# Solution: Adjust toast position or parent widget

# Use different position
toast_center.position = "bottom-right"  # Instead of top-right

# Or create toast center on top-level widget
toast_center = create_toast_center(
    root,  # Main window, not nested frame
    theme_colors
)

Animation Stuttering:


# Problem: Main thread blocked by heavy operations
# Solution: Use background threads for heavy work

import threading

def heavy_operation():
    # Do work in background
    result = perform_calculation()

    # Show toast on main thread
    root.after(0, lambda: toast_center.show(
        "Calculation complete",
        kind="success"
    ))

threading.Thread(target=heavy_operation, daemon=True).start()

Error Messages

"bad window path name" Error:


def on_closing():
    try:
        toast_center.dismiss_all()
    except:
        pass
    root.destroy()

root.protocol("WM_DELETE_WINDOW", on_closing)

"invalid color name" Error:


# Validate theme colors
def validate_theme_colors(tokens):
    required = [
        "background_secondary", "text_main", "text_secondary",
        "accent_color_1", "success_color", "warning_color", "error_color"
    ]

    for key in required:
        if key not in tokens:
            print(f"Warning: Missing theme token: {key}")

---

Examples

Complete Application Example


import tkinter as tk
from tkinter import ttk
from bravura.themes.theme_manager import ProfessionalThemeManager
from bravura.components.toasts import create_toast_center
from bravura.components import PremiumButton

class NotificationDemoApp:
    def __init__(self):
        self.root = tk.Tk()
        self.root.title("Toast Notification Demo")
        self.root.geometry("600x400")

        # Initialize theme manager
        self.theme_manager = ProfessionalThemeManager(self)
        self.theme_manager.apply_theme("dark")

        # Create toast center
        self.toast_center = create_toast_center(
            self.root,
            self.theme_manager.get_current_theme_colors()
        )

        self.create_ui()

    def create_ui(self):
        # Title
        title = tk.Label(
            self.root,
            text="Toast Notification Examples",
            font=("Segoe UI", 16, "bold")
        )
        title.pack(pady=20)

        # Button frame
        button_frame = tk.Frame(self.root)
        button_frame.pack(pady=20)

        # Notification buttons
        buttons = [
            ("Show Info", "info", self.show_info),
            ("Show Success", "success", self.show_success),
            ("Show Warning", "warning", self.show_warning),
            ("Show Error", "error", self.show_error)
        ]

        for text, kind, command in buttons:
            btn = PremiumButton(
                button_frame,
                text=text,
                command=command,
                width=15
            )
            btn.pack(side="left", padx=5)

    def show_info(self):
        self.toast_center.show(
            "This is an informational message",
            kind="info"
        )

    def show_success(self):
        self.toast_center.show(
            "Operation completed successfully",
            sub_message="All files processed",
            kind="success"
        )

    def show_warning(self):
        self.toast_center.show(
            "Warning: Please review your settings",
            kind="warning"
        )

    def show_error(self):
        self.toast_center.show(
            "Error: Failed to save changes",
            sub_message="Please try again",
            kind="error"
        )

    def run(self):
        self.root.mainloop()

if __name__ == "__main__":
    app = NotificationDemoApp()
    app.run()

---

Migration Guide

From Custom Notification Systems


# Old approach: Custom Toplevel windows
def show_notification(message):
    popup = tk.Toplevel()
    popup.title("Notification")
    tk.Label(popup, text=message).pack()
    popup.after(3000, popup.destroy)

# New approach: Toast notifications
toast_center.show(message, kind="info")

From messagebox


# Old: Modal dialogs (blocking)
from tkinter import messagebox
messagebox.showinfo("Success", "Operation complete")

# New: Non-blocking toasts
toast_center.show("Operation complete", kind="success")

---

License Information

Standard Tier: Full access to standard toast style with all themes

Professional Tier: Access to both standard and premium toast styles

Enterprise Tier: Full access to all toast features and customization

For licensing questions, visit https://wigleystudios.com or contact sales@wigleystudios.com

---

See Also

---

Copyright (c) 2025 Wigley Studios LLC. All rights reserved.

Last updated: October 28, 2025

© 2025 Wigley Studios. All rights reserved. Ultimate Video Game Studio - Volume 1 is a trademark of Wigley Studios.