Glass Panel Component - Usage Guide

Component: bravura.components.glass_panels.GlassPanel

Status: ✅ Production Ready

License Tiers: Professional, Enterprise

Last Updated: October 17, 2025

---

Overview

The Glass Panel component creates premium depth cards with frosted glass effects, layered shadows, and smooth hover animations. It provides visual hierarchy and professional polish aligned with the Wigley Studios design system.

Key Features

✅ Multiple Elevation Levels - card, elevated, modal, floating
✅ Smooth Hover Animations - 120-180ms ease transitions
✅ 3-Layer Shadow System - near/mid/far for realistic depth
✅ Canvas-Based Rendering - faux-glass with subtle transparency
✅ Theme-Aware Styling - uses premium token sets
✅ Stable API - compatible with existing usage patterns

---

Basic Usage

Simple Example


import tkinter as tk
from bravura.themes.theme_manager import ProfessionalThemeManager
from bravura.components.glass_panels import GlassPanel

class MyApp:
    def __init__(self):
        self.root = tk.Tk()
        self.root.title("My App with Glass Panels")
        self.root.geometry("800x600")

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

        # Create glass panel with theme colors
        glass_panel = GlassPanel(
            parent=self.root,
            tokens=self.theme_manager.get_current_theme_colors(),
            elevation="card"
        )
        glass_panel.pack(fill="both", expand=True, padx=20, pady=20)

        # Add content to the panel
        content_area = glass_panel.get_content_area()

        # Add widgets to content area
        tk.Label(content_area, text="Glass Panel Content",
                font=("Segoe UI", 14)).pack(pady=20)

        tk.Button(content_area, text="Sample Button").pack(pady=10)

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

---

Elevation Levels

Available Elevations

Elevation	Use Case	Visual Effect	Shadow Intensity
`"card"`	Standard content cards	Subtle elevation	Light shadows
`"elevated"`	Important sections	Moderate elevation	Medium shadows
`"modal"`	Dialogs, overlays	High elevation	Strong shadows
`"floating"`	Tooltips, popups	Maximum elevation	Very strong shadows

Choosing the Right Elevation


# For subtle UI elements (recommended for typical usage)
card_panel = GlassPanel(parent, elevation="card")

# For important sections
elevated_panel = GlassPanel(parent, elevation="elevated")

# For modal dialogs
modal_panel = GlassPanel(parent, elevation="modal")

# For floating elements
floating_panel = GlassPanel(parent, elevation="floating")

---

Advanced Configuration

Custom Styling


# Custom glass panel with specific settings
glass_panel = GlassPanel(
    parent=parent_widget,
    tokens=theme_tokens,
    elevation="card",
    hover_elevation=True,  # Enable hover effects
    animated=False,        # Disable entrance animations
    padding=16,            # Custom padding
    corner_radius=8        # Custom corner radius
)

Theme Integration


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

# Create panel with theme colors
glass_panel = GlassPanel(
    parent=parent,
    tokens=theme_tokens,
    elevation="card"
)

---

Best Practices

When to Use Glass Panels

✅ Good Use Cases:

Dashboard cards and statistics
Modal dialogs and overlays
Floating tooltips and popups
Important content sections
Premium feature highlights
Premium toast notifications (Professional/Enterprise tiers)

❌ Avoid For:

Standard form layouts
Dense data tables
Simple content containers
High-frequency UI elements

Performance Considerations

Glass panels use Canvas rendering for visual effects
Limit the number of glass panels in complex layouts
Use elevation="card" for most UI elements
Reserve higher elevations for important content

Accessibility

Glass panels maintain proper contrast ratios
Hover effects are subtle and non-distracting
Focus indicators work correctly with glass panels
Screen readers can access content normally

---

Common Patterns

Dashboard Layout


# Main dashboard with glass panels
main_frame = tk.Frame(root)

# Statistics cards
stats_frame = tk.Frame(main_frame)
for i in range(4):
    card = GlassPanel(
        stats_frame,
        tokens=theme_tokens,
        elevation="card"
    )
    card.grid(row=0, column=i, padx=10, pady=10, sticky="ew")

    # Add content to card
    content = card.get_content_area()
    tk.Label(content, text=f"Card {i+1}").pack(pady=10)

# Main content area
content_panel = GlassPanel(
    main_frame,
    tokens=theme_tokens,
    elevation="elevated"
)
content_panel.pack(fill="both", expand=True, padx=20, pady=20)

Modal Dialog


def show_modal():
    modal = tk.Toplevel(root)
    modal.title("Modal Dialog")
    modal.geometry("400x300")

    # Create glass panel for modal content
    glass_panel = GlassPanel(
        modal,
        tokens=theme_tokens,
        elevation="modal"
    )
    glass_panel.pack(fill="both", expand=True, padx=20, pady=20)

    # Add content
    content = glass_panel.get_content_area()
    tk.Label(content, text="Modal Content").pack(pady=20)

Premium Toast Notifications


from bravura.components import create_toast_center

# Create toast center with premium style (Pro/Enterprise only)
toast_center = create_toast_center(
    root,
    theme_tokens,
    default_style="premium"  # Uses GlassPanel internally
)

# Show premium glass panel toast
toast_center.show(
    "Premium notification",
    sub_message="With frosted glass effect",
    kind="success",
    style="premium"
)

---

Troubleshooting

Common Issues

Glass panel appears too strong/intense:

Use elevation="card" instead of higher elevations
Consider using standard ttk.LabelFrame for subtle UI elements
Reduce the number of glass panels in your layout

Performance issues with many glass panels:

Limit glass panels to important UI elements
Use standard frames for dense content areas
Consider using animated=False to disable entrance animations

Theme colors not applying:

Ensure theme manager is initialized before creating glass panels
Pass tokens=theme_manager.get_current_theme_colors()
Check that the theme manager is properly configured

Error Messages

"bad window path name" errors:

These occur when glass panels are destroyed improperly
Ensure proper cleanup in your application's close handlers
Use glass_panel.destroy() instead of glass_panel.pack_forget()

---

API Reference

GlassPanel Constructor


GlassPanel(
    parent: tk.Widget,
    tokens: Optional[Dict[str, Any]] = None,
    theme_tokens: Optional[Dict[str, Any]] = None,  # Alias for tokens
    elevation: str = "card",
    hover_elevation: bool = True,
    animated: bool = False,
    **kwargs: Any
) -> GlassPanel

Key Methods


# Get content area for adding widgets
content_area = glass_panel.get_content_area()

# Change elevation dynamically
glass_panel.set_elevation("elevated")

# Add content using factory function
widget = glass_panel.add_content(lambda: tk.Button(None, text="Button"))

# Proper cleanup
glass_panel.destroy()

---

Migration Guide

From Standard Frames


# Old approach
frame = ttk.LabelFrame(parent, text="Content", padding=10)
tk.Label(frame, text="Content").pack()

# New approach with glass panel
glass_panel = GlassPanel(parent, tokens=theme_tokens, elevation="card")
content = glass_panel.get_content_area()
tk.Label(content, text="Content").pack()

From Custom Canvas Widgets


# Old approach
canvas = tk.Canvas(parent, bg="#1a1a1a", highlightthickness=0)
# Manual drawing code...

# New approach
glass_panel = GlassPanel(parent, tokens=theme_tokens, elevation="card")
content = glass_panel.get_content_area()
# Add widgets to content area

---

License Information

Professional Tier: Basic glass panel functionality

Enterprise Tier: All features including custom elevations and animations

For licensing questions, contact sales@wigleystudios.com

---