Welcome to professional Python GUI development! This comprehensive guide covers installation, setup, and your first Bravura application - from zero to professional GUI in under 15 minutes.
Before you begin, ensure you have:
To check your Python version:
python --version
# Should show Python 3.7.0 or higher
To verify tkinter is available:
import tkinter as tk
print("tkinter is ready!")
---
cd "Bravura"
python quick_test.py
✅ Success! You should see a professional GUI window with animations.
For integrating into existing projects:
# Install Bravura SDK from wheel file (in your customer package)
pip install ./bravura-1.0.0-py3-none-any.whl
# Activate your license
python -m bravura --activate --license-key YOUR_LICENSE_KEY --email your@email.com
# Or activate interactively
python -m bravura --activate
Note: Bravura is not available on PyPI. You must install from the .whl file included in your customer package download.
Enhance your Bravura experience:
# GPU acceleration and detection
pip install GPUtil
# Audio feedback and enhanced animations
pip install pygame
# Advanced system monitoring
pip install psutil
# High-DPI display support
pip install Pillow
---
Bravura provides a comprehensive set of components organized by functionality and tier. Here's what you need to know:
# Top-level imports (most common)
from bravura import Toolkit, ToolkitApp, ThemeManager
# Component imports (detailed control)
from bravura.components import StatusBar, MenuSystem, AmbientBackground
# Helper functions (recommended for quick setup)
from bravura.components import create_status_bar, create_ambient_background
All components check your license tier at runtime. Attempting to use Professional/Enterprise components without the proper license will raise a TierViolationError.
Quick Reference: See QUICK_START.md for the complete import list organized by tier.
---
Create a file called my_first_app.py:
from bravura import get_audio_analyzer_framework
# Get the framework class and create instance
AppClass = get_audio_analyzer_framework()
app = AppClass()
# Run your application
app.run()
Run it:
python my_first_app.py
Congratulations! You now have a professional GUI application with:
For a more polished experience with customization:
from bravura import get_audio_analyzer_framework
# Get the framework class and create instance
AppClass = get_audio_analyzer_framework()
app = AppClass()
# Customize the title
app.root.title("My Professional Application")
# Add a startup message
app._log_message("🚀 Welcome to my application!")
app._log_message("✨ Professional toolkit loaded successfully")
# Run the application
app.run()
---
# main.py - Your complete application
from bravura import get_audio_analyzer_framework
AppClass = get_audio_analyzer_framework()
app = AppClass()
app.root.title("My Professional App")
app.run()
# Add to your existing project structure
your_project/
├── main.py # Your existing code
├── gui_main.py # Bravura framework
├── components/ # Bravura components
└── your_modules/ # Your application logic
# Create isolated environment
python -m venv gui_env
gui_env\Scripts\activate # Windows
source gui_env/bin/activate # macOS/Linux
# Install dependencies
pip install pygame GPUtil psutil
# Extract Bravura files to project
# ... run your application ...
The toolkit uses gui_config.json for persistent settings:
{
"theme": {
"default_theme": "wigley_site"
},
"window": {
"stay_on_top": false,
"remember_position": true,
"width": 1200,
"height": 800
},
"performance": {
"gpu_acceleration": true,
"animation_speed": 1.0,
"progress_rainbow": true
},
"logging": {
"level": "INFO",
"max_lines": 1000
}
}
Key Settings:
default_theme: Startup theme ("wigley_site", "dark", "platinum", etc.)gpu_acceleration: Enable hardware accelerationanimation_speed: UI animation timing (0.5-2.0)stay_on_top: Window always visibleprogress_rainbow: Animated progress barsCustomization Options:
gui_config.json directly---
These fundamental components form the foundation of any Bravura application:
from bravura import Toolkit, ToolkitApp
# Quick framework (complete GUI in one line)
app = Toolkit(app_name="My App", theme="dark", use_gpu=True)
app.run()
# Custom application (inherit from ToolkitApp for advanced control)
class MyProcessor(ToolkitApp):
def on_start(self, inputs):
# Your processing logic here
self.update_progress(50, "Processing...")
return {"status": "completed", "result": "success"}
processor = MyProcessor()
processor.run({"data": "example"})
When to use:
Toolkit: Quick prototypes, demo applications, simple GUIsToolkitApp: Production applications, complex workflows, background processingLearn more: API_REFERENCE.md - Core Framework
---
Professional status bar with timer, ETA, and multi-section display:
from bravura.components import create_status_bar
# Create status bar
status = create_status_bar(root)
status.pack(fill=tk.X, side=tk.BOTTOM)
# Use status bar
status.start_timer()
status.set_status("Processing files...")
status.set_progress_message("File 15 of 100")
status.update_eta("00:05:30") # 5 minutes 30 seconds remaining
# When complete
status.reset_timer()
status.set_status("Ready")
Key Features:
Learn more: API_REFERENCE.md - StatusBar
---
Advanced menu system with keyboard shortcuts and dynamic manipulation:
from bravura.components import create_menu_system
# Create menu system
menu = create_menu_system(root)
# Add File menu
menu.add_menu("File", [
{"label": "New", "command": new_file, "accelerator": "Ctrl+N"},
{"label": "Open", "command": open_file, "accelerator": "Ctrl+O"},
"separator",
{"label": "Recent Files", "submenu": [
{"label": "file1.txt", "command": lambda: open_recent("file1.txt")},
{"label": "file2.txt", "command": lambda: open_recent("file2.txt")}
]},
"separator",
{"label": "Exit", "command": root.quit}
])
# Add Edit menu with checkbuttons
menu.add_menu("View", [
{
"label": "Toolbar",
"type": "checkbutton",
"variable": toolbar_var,
"command": toggle_toolbar
}
])
# Dynamic updates
menu.set_item_state("File", "Save", "disabled") # Disable Save
menu.add_item("File", {"label": "Save As...", "command": save_as})
Key Features:
Learn more: API_REFERENCE.md - MenuSystem
---
Three progress bar styles for different use cases:
from bravura.components import (
BasicProgressBar,
GradientProgressBar,
GlowingProgressBar # Professional+ only
)
# BasicProgressBar - Clean, professional style
progress1 = BasicProgressBar(parent, style="standard", width=400)
progress1.pack()
progress1.set_value(75)
# Three styles available:
# - "standard": Teal accent (#20C6B7)
# - "success": Green accent (#28A745)
# - "warning": Orange accent (#F2842E)
# GradientProgressBar - Beautiful purple→pink gradient
progress2 = GradientProgressBar(parent, width=400)
progress2.pack()
progress2.set_value(50)
# GlowingProgressBar - Animated rainbow (Professional+ tier)
from bravura.glowing_progress_bar import GlowingProgressManager
manager = GlowingProgressManager(root)
progress3 = GlowingProgressBar(parent, manager, bar_type="rainbow")
progress3.pack()
progress3.set_progress(60)
progress3.start_glow_animation()
When to use each:
BasicProgressBar: Standard operations, file processing, downloadsGradientProgressBar: Visual appeal, splash screens, onboardingGlowingProgressBar: Premium applications, long-running tasks, visual impactLearn more: API_REFERENCE.md - Progress Bars
---
Professional terminal with real-time logging and color-coded messages:
from bravura.components import create_analysis_terminal
# Create terminal
terminal = create_analysis_terminal(parent, width=800, height=200)
terminal.pack(fill="both", expand=True)
# Log messages with severity levels
terminal.log("Starting process...", level="info")
terminal.log("Warning: Low disk space", level="warning")
terminal.log("Processing complete", level="success")
terminal.log("Error: Connection failed", level="error")
# Clear terminal
terminal.clear()
# Auto-scroll to bottom
terminal.scroll_to_end()
Key Features:
Learn more: Component is self-documenting via inline help
---
Bravura includes premium button components in all tiers:
from bravura.components import PremiumButton
# Create premium button
save_btn = PremiumButton(
parent,
text="💾 Save Project",
command=save_project,
style="primary", # primary, secondary, success, danger, warning
loading=False,
width=None,
height=36, # Pixel height
bg_color="#8B5CF6", # Custom purple background
fg_color="#FFFFFF", # White text
hover_color="#A78BFA" # Light purple hover
)
save_btn.pack(side=tk.RIGHT, padx=10)
# Show loading state
save_btn.set_loading(True)
# ... perform save ...
save_btn.set_loading(False)
Key Features:
Best for: Primary page actions, hero CTAs, important operations
---
from bravura.components import CompactPremiumButton
# Toolbar buttons
for action in ["Bold", "Italic", "Underline"]:
btn = CompactPremiumButton(
toolbar,
text=action,
command=lambda a=action: format_text(a),
width=8, # Character-based width
style="primary"
)
btn.pack(side=tk.LEFT, padx=2)
# Form buttons with uniform width
ok_btn = CompactPremiumButton(form, text="OK", command=ok, width=10)
cancel_btn = CompactPremiumButton(form, text="Cancel", command=cancel, width=10)
Key Features:
Best for: Toolbars, form controls, table actions, any dense UI
---
from bravura.components import ButtonFactory
# Automatically selects the right button type
hero_btn = ButtonFactory.create(parent, text="Save", context="hero")
toolbar_btn = ButtonFactory.create(parent, text="Bold", context="toolbar")
form_btn = ButtonFactory.create(parent, text="OK", context="form")
# Convenience methods
hero = ButtonFactory.create_hero(parent, text="Launch", command=launch)
toolbar = ButtonFactory.create_toolbar(parent, text="Cut", command=cut, width=8)
form = ButtonFactory.create_form(parent, text="Apply", command=apply, width=10)
Context types:
hero: Creates PremiumButtontoolbar: Creates CompactPremiumButtonform: Creates CompactPremiumButtonaction: Creates CompactPremiumButtonsecondary: Creates themed ttk.ButtonLearn more: BUTTON_USAGE_GUIDE.md
---
Create the signature Wigley Studios ambient glow effects:
from bravura.components import AmbientBackground
# Create ambient background with theme integration
ambient = AmbientBackground(
root,
width=1200,
height=800,
theme_tokens=theme_manager.get_current_theme_colors(),
enable_animation=True,
animation_speed="medium", # "slow", "medium", "fast"
particle_count=30, # 10-60 particles
glow_effects=True
)
# Your UI goes here - it will appear above the ambient background
main_frame = ttk.Frame(root)
main_frame.pack(fill="both", expand=True, padx=20, pady=20) # Padding shows ambient!
Performance:
Theme Integration:
# Update colors when theme changes (instant, no recreation)
ambient.set_theme_tokens(theme_manager.get_current_theme_colors())
Learn more: AMBIENT_BACKGROUND_USAGE.md
---
Create beautiful glass panels with backdrop blur effects:
from bravura.components import create_glass_panel
# Create glass panel
panel = create_glass_panel(
parent,
width=400,
height=300,
title="Settings",
theme_tokens=theme_manager.get_current_theme_colors()
)
panel.pack(padx=20, pady=20)
# Add content to panel.content_frame
label = ttk.Label(panel.content_frame, text="Panel content goes here")
label.pack(pady=20)
# Modal glass panel
modal = create_modal_panel(
parent,
width=500,
height=400,
title="Confirmation"
)
Key Features:
Learn more: GLASS_PANEL_USAGE.md
---
Universal tooltip system with smart positioning:
from bravura.components import add_tooltip, ToolTip
# Simple tooltips (recommended)
add_tooltip(button, "Click to save your project")
add_tooltip(entry, "Enter your username")
# Manual tooltip creation
tooltip = ToolTip(widget, text="Custom tooltip", delay=500)
# Rich tooltips with formatting
from bravura.components import RichToolTip
rich = RichToolTip(
widget,
title="Advanced Feature",
description="This feature allows you to...",
shortcut="Ctrl+Shift+A"
)
Features:
---
Show elegant toast notifications:
from bravura.components import show_success, show_error, show_warning, show_info
# Quick notifications
show_success(root, "File saved successfully!")
show_error(root, "Connection failed")
show_warning(root, "Disk space low")
show_info(root, "Update available")
# Advanced usage
from bravura.components import create_toast_center
toast = create_toast_center(root, theme_manager)
toast.show("Custom message", duration=3000, type_="info")
Styles:
Learn more: TOAST_STYLES.md
---
Spotify-style command palette (Ctrl+K):
from bravura.components import create_command_palette
# Create command palette
palette = create_command_palette(root, theme_manager)
# Register commands
palette.register_command(
command_id="new_file",
label="New File",
description="Create a new file",
shortcut="Ctrl+N",
callback=new_file
)
palette.register_command(
command_id="settings",
label="Open Settings",
category="Preferences",
callback=open_settings
)
# Users press Ctrl+K to open, type to search, Enter to execute
Features:
---
from bravura import ThemeManager
# Create theme manager
theme_manager = ThemeManager(app)
# Apply themes
theme_manager.apply_theme("dark") # Standard tier
theme_manager.apply_theme("wigley_site") # Professional+ tier
theme_manager.apply_theme("platinum") # Enterprise tier
# Get theme colors
colors = theme_manager.get_current_theme_colors()
teal = colors["accent_color_1"]
gold = colors["accent_color_2"]
# List available themes
themes = theme_manager.get_available_themes()
Available Themes:
default, dark, black, whitewigley_site, ocean_blue, forest_greenplatinum, customLearn more: THEMING_GUIDE.md | CUSTOM_BRANDING_THEME.md
---
from bravura import Worker
worker = Worker()
def background_task(emit, cancel):
for i in range(100):
if cancel.is_set():
emit("CANCELLED")
return
# Do work
emit("PROGRESS", percent=i, message=f"Processing {i}%")
time.sleep(0.1)
emit("DONE")
def on_message(msg_type, **kwargs):
if msg_type == "PROGRESS":
print(f"{kwargs['percent']}%: {kwargs['message']}")
elif msg_type == "DONE":
print("Complete!")
worker.run(background_task, on_message=on_message)
---
from bravura import GPUDetector, detect_gpus
# Quick detection
gpus = detect_gpus()
if gpus:
print(f"Found {len(gpus)} GPU(s)")
print(f"Primary: {gpus[0]['name']}")
# Advanced detection
detector = GPUDetector()
result = detector.detect_gpu()
if result["available"]:
for gpu in result["gpus"]:
print(f"GPU: {gpu['name']}")
print(f"Memory: {gpu['memory_total']} MB")
print(f"Utilization: {gpu['utilization']}%")
---
The toolkit includes several demo applications to showcase features:
python demo_commercial.py
What it shows:
Perfect for: First impressions, feature evaluation, showing to stakeholders
python demo_themes.py
What it shows:
Perfect for: Choosing themes, understanding design options
python demo_gpu_system.py
What it shows:
Perfect for: Understanding hardware integration
python demo_timer_eta.py
What it shows:
Perfect for: Understanding progress systems
---
# In your application code
app.theme_manager.apply_theme("dark") # Dark theme
app.theme_manager.apply_theme("ocean_blue") # Blue accent theme
app.theme_manager.apply_theme("forest_green") # Green accent theme
# Check if GPU is available
if app.detected_gpus:
app.use_gpu_var.set(True)
app._log_message(f"🔥 GPU acceleration enabled: {app.primary_gpu['name']}")
Click the "Start Analysis" button to see:
---
# Add custom log messages
app._log_message("🎯 My application started successfully!")
app._log_message("📊 Loading user data...")
app._log_message("✅ Initialization complete")
# Manual progress updates
app._update_progress_with_eta(25, "Loading data...")
app._update_progress_with_eta(50, "Processing...")
app._update_progress_with_eta(100, "Complete!")
# Update the status bar
app.status_var.set("Ready for action")
app.status_var.set("Processing data...")
app.status_var.set("Export complete")
---
| Problem | Solution |
|---|---|
| "No module named 'gui_main'" | Ensure you're in the correct directory with `gui_main.py` |
| Window appears too small | Check display scaling settings, or modify window size in code |
| Themes don't apply | Delete `gui_config.json` and restart to reset configuration |
| GPU not detected | Install `GPUtil` with `pip install GPUtil` |
| Progress bar not smooth | Ensure `pygame` is installed for enhanced animations |
---
Now that you have the basics working, explore more advanced features:
| Guide | What You'll Learn |
|---|---|
| QUICK_START.md | Complete import reference - all components at a glance |
| API_REFERENCE.md | Technical API documentation for all components |
| FEATURES_OVERVIEW.md | See all capabilities and features |
| INTEGRATION_GUIDE.md | Build production applications |
| THEMING_GUIDE.md | Master the theme system |
---
Deep dive into individual components:
| Component | Documentation |
|---|---|
| AmbientBackground | AMBIENT_BACKGROUND_USAGE.md |
| Buttons (Premium) | BUTTON_USAGE_GUIDE.md |
| Button Colors | BUTTON_COLOR_CUSTOMIZATION.md |
| GlassPanel | GLASS_PANEL_USAGE.md |
| LoadingDialog | UNIVERSAL_LOADING_DIALOG_COMPONENT_GUIDE.md |
| ToastCenter | TOAST_STYLES.md |
| Custom Branding | CUSTOM_BRANDING_THEME.md |
| Best Practices | BEST_PRACTICES.md |
| Common Mistakes | COMMON_MISTAKES.md |
---
Progression Path:
```python
from bravura import Toolkit
app = Toolkit(app_name="My App")
app.run()
```
```python
from bravura.components import StatusBar, MenuSystem
# Add status bar, menus, progress bars
```
```python
from bravura import ThemeManager
theme_manager = ThemeManager(app)
theme_manager.apply_theme("wigley_site")
```
```python
from bravura.components import AmbientBackground, GlassPanel
# Add visual polish
```
- Connect buttons to your functions
- Add progress tracking
- Implement file operations
- Build your unique features
---
- Try all demos in Bravura Demos and Templates/
- Study the source code
- Experiment with modifications
- Edit gui_config.json
- Try different themes
- Adjust animation speeds
- Toggle features on/off
- Start with templates in templates/ folder
- Customize for your needs
- Test on different platforms
---
See DOCS_INDEX.md for a complete list of all documentation with descriptions.
---
---
✅ Installation - Two methods: direct download or pip install from wheel file
✅ Imports - Top-level vs component imports, helper functions
✅ Tier System - Standard, Professional, Enterprise components
✅ Core Components - StatusBar, MenuSystem, Progress Bars, AnalysisTerminal
✅ Buttons - PremiumButton, CompactPremiumButton, ButtonFactory
✅ Visual Effects - AmbientBackground, GlassPanel (Professional+)
✅ Interactive UI - ToolTips, Toasts, CommandPalette (Professional+)
✅ Theme System - ThemeManager, built-in themes, custom branding
✅ Utilities - Worker, GPUDetector, ProgressTracker
---
🎉 Congratulations! You're ready to build professional Python GUI applications with Bravura!
Questions? Check the FAQ.md, browse DOCS_INDEX.md, or reach out to our support team at support@wigleystudios.com.
---
© 2025 Wigley Studios LLC. Professional Python GUI Framework.