Kriss.Wpf.Toasts 1.0.0

Kriss.Wpf.Toasts

dotnet add package Kriss.Wpf.Toasts

Kriss.Wpf.Toasts is a modern, light-as-air Toast Notification library for WPF applications (.NET 10 / WPF).

Built around the effortless MsgToast.Show() static API for single-line notifications. From instant status presets and async AskAsync dialogs — to rich custom cards with real-time progress bars, smart multi-window targeting, and invisible anti-spam deduplication. Powered by zero third-party dependencies, total background thread-safety, and natural MVVM harmony.

📸 Preview

📑 Table of Contents

• 📦 Installation & XAML Setup
• 🚀 Quick Start (Minimal Setup)
• 🎨 Rich Customization & Composition
• 🎯 Multi-Window & Control Targeting (ToastTarget)
• ⚙️ Global Management (ToastManager) & Localization
• 🚀 Advanced Features & MVVM Integration
• 📁 Repository Structure
• 📄 License

📦 Installation & XAML Setup

Install via .NET CLI:

dotnet add package Kriss.Wpf.Toasts

Or via Package Manager Console:

Install-Package Kriss.Wpf.Toasts

⚡ XAML Namespace Setup (Optional)

Zero XAML Required: Calling MsgToast.Show() from C# works 100% out of the box with zero XAML boilerplate.
If you wish to mark specific target windows or controls directly in XAML, add the namespace below:

xmlns:toasts="clr-namespace:Kriss.Wpf.Toasts;assembly=Kriss.Wpf.Toasts"


<Window toasts:ToastHost.WindowName="MainWindow">
    <Border toasts:ToastHost.LocalHostName="LogHost"/>
</Window>

🚀 Quick Start (Minimal Setup)

1. Instant Single-Line Notification (MsgToast.Show)

using Kriss.Wpf.Toasts;

// Display a simple toast card in one line of code
MsgToast.Show("Operation completed successfully!");

2. Semantic Status Presets (Success, Error, Warning, Info)

// Express status notifications with built-in vector icons and side accent stripes
MsgToast.ShowSuccess("Settings saved successfully!", "Success");
MsgToast.ShowError("Database connection failed.", "Error");
MsgToast.ShowWarning("API rate limit exceeded.", "Warning");
MsgToast.ShowInfo("New software update v1.0.0 available.", "Info");

3. Interactive Async Dialogs (MsgToast.AskAsync)

// Await interactive dialog responses directly in async/await code
MessageBoxResult result = await MsgToast.AskAsync("Save modified files before closing?", MessageBoxButton.YesNo);

if (result == MessageBoxResult.Yes)
{
    // Await custom button labels dialog
    bool confirmed = await MsgToast.AskAsync("Delete selected items?", confirmText: "Yes, Delete", cancelText: "Keep Items");
}

4. Progress Bar Toast (ToastProgressContent)

// Display a progress bar for background operations
var progress = new ToastProgressContent(maximum: 100) { Value = 45 };
MsgToast.Show("Downloading package assets...", progress);

🎨 Rich Customization & Composition

Tailor every aspect of a toast card — from geometry and typography to rich multi-element composition.

A. Appearance & Options (ToastOptions & ToastAppearance)

// Configure positioning, custom accent brushes, typography, and lifetimes
var options = new ToastOptions
{
    Title = "Custom Configuration",
    IsLeft = true,                               // Position at Bottom-Left
    AccentBrush = Brushes.DeepSkyBlue,           // Custom side accent stripe
    Lifetime = TimeSpan.FromSeconds(8),          // Display lifetime duration
    Appearance = new ToastAppearance
    {
        TitleFontSize = 15.0,                    // Title font size
        BodyFontSize = 13.0,                     // Body font size
        CornerRadius = new CornerRadius(10)      // Card corner radius
    }
};

MsgToast.Show(options, "Notification card with custom appearance and lifetime.");

B. Rich Content Composition & Real-Time Updates

// 1. Composite Card: Image + Text + Buttons with Custom Lambda Actions
var icon = new ToastImageContent("pack://application:,,,/Images/pepper.png") { Dock = Dock.Left };

var buttons = new ToastButtonsContent();
buttons.Add("Retry", () => RetryOperation());
buttons.Add("Close", () => CloseOperation());

MsgToast.Show(options, icon, "Failed to connect to remote server.", buttons);

// 2. Real-Time Progress Updates via IToastHandle
var progress = new ToastProgressContent(maximum: 100);
var downloadOptions = new ToastOptions { Title = "Downloading Archive", Lifetime = TimeSpan.MaxValue };

using var handle = MsgToast.Show(downloadOptions, "Downloading assets...", progress);

for (int i = 0; i <= 100; i += 25)
{
    await Task.Delay(400);
    progress.Value = i;
    handle?.Update("Downloading assets...", progress); // Real-time update
}

🎯 Multi-Window & Control Targeting (ToastTarget)

Route toasts to active windows, specific open windows (ToastHost.WindowName), or directly over specific UI controls (ToastHost.LocalHostName).

1. XAML Target Markup

<Window x:Class="MyApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:toasts="clr-namespace:Kriss.Wpf.Toasts;assembly=Kriss.Wpf.Toasts"
        toasts:ToastHost.WindowName="MainWindow">
    
    
    <Border toasts:ToastHost.LocalHostName="LogHost" Margin="10" Background="#1E1E1E">
        <TextBox x:Name="TxtLog" Text="System Log Output..."/>
    </Border>
</Window>

2. Target Routing Examples

// 1. Default: Target active window
MsgToast.Show("Toast in active window");

// 2. Target specific open window by ToastHost.WindowName
MsgToast.Show(new ToastTarget(WindowName: "SecondaryWindow"), "Routed Notification", "Sent to SecondaryWindow.");

// 3. Target specific control panel by ToastHost.LocalHostName
MsgToast.Show(new ToastTarget(HostName: "LogHost"), "Log Updated", "Displayed directly over the Log TextBox panel.");

💡 Pro-Tip: Cross-Window Notification Routing from Child Windows

Trigger toasts from child windows (SecondaryWindow or settings dialogs) directly onto the Main Application Window without passing window references or writing complex event aggregators:

// Executed inside child window ViewModel (SecondaryViewModel):

// Option A: Direct routing to MainWindow by WindowName
MsgToast.Show(new ToastTarget(WindowName: "MainWindow"), "Settings Saved", "Changes applied to MainWindow.");

// Option B: Auto-search target host across ALL open application windows
MsgToast.Show(new ToastTarget(HostName: "LogHost"), "Child Log Entry", "Log entry sent from child window.");

🔍 Target Resolution & Layout Mechanics

• Window Resolution (ToastTargetResolver): When Window and WindowName are null, the library resolves to win.IsActive, falling back to Application.Current.MainWindow. For background or non-active windows, explicitly specifying WindowName: "SecondaryWindow" is recommended.
• Control Resolution (x:Name vs LocalHostName): Elements are resolved first by native WPF x:Name, then by toasts:ToastHost.LocalHostName. Using LocalHostName is recommended as it provides self-documenting XAML code.
• Layout & Stacking: Cards stack vertically from bottom to top. By default, cards align to the Bottom-Right corner. Setting options.IsLeft = true aligns them to the Bottom-Left corner.

⚙️ Global Management (ToastManager) & Localization

Centralized global settings, bulk management operations, and international localization.

1. Global Default Settings

// Set global default lifetime, hover pause, and stack limits
ToastManager.DefaultLifetime = TimeSpan.FromSeconds(5);
ToastManager.DefaultPauseOnHover = true;
ToastManager.MaxDisplayedToasts = 5;

2. Bulk Management Operations

// Gracefully dismiss all active toasts across all windows
ToastManager.DismissAll(immediate: false);

// Pause or resume lifetime timers for all active toasts
ToastManager.PauseAll();
ToastManager.ResumeAll();

🌐 3. International Localization (IToastLocalizer)

Automatically resolves dialog button labels (AskAsync) between English (EN) and Russian (RU) based on CultureInfo.CurrentUICulture.

Custom labels can be configured for German (DE), Spanish (ES), or any language via SetCustomLabels:

// German Localization (DE)
ToastManager.Localizer = new DefaultToastLocalizer()
    .SetCustomLabels(yes: "Ja", no: "Nein", ok: "OK", cancel: "Abbrechen");

// Spanish Localization (ES)
ToastManager.Localizer = new DefaultToastLocalizer()
    .SetCustomLabels(yes: "Sí", no: "No", ok: "OK", cancel: "Cancelar");

Custom IToastLocalizer implementation example:

public class CustomFrenchLocalizer : IToastLocalizer
{
    public string GetLabel(MessageBoxResult result) => result switch
    {
        MessageBoxResult.Yes => "Oui",
        MessageBoxResult.No => "Non",
        MessageBoxResult.OK => "OK",
        MessageBoxResult.Cancel => "Annuler",
        _ => result.ToString()
    };
}

ToastManager.Localizer = new CustomFrenchLocalizer();

🚀 Advanced Features & MVVM Integration

1. Thread-Safety & Background Dispatcher Auto-Marshalling

Calling MsgToast.Show() or AskAsync() from Task.Run or background worker threads automatically checks Dispatcher.CheckAccess() and marshals execution onto the UI Dispatcher without throwing cross-thread InvalidOperationException:

// Safely call from background threads (Task.Run)
Task.Run(() =>
{
    // Background computations...
    
    // Automatically marshaled to UI Dispatcher!
    MsgToast.ShowSuccess("Background operation completed!");
});

2. Anti-Spam Deduplication (x2, x3...)

Anti-spam deduplication is a subtle UI gem: users don't explicitly think about it, but subconsciously appreciate that their screen isn't spammed with stacked duplicate cards.

When consecutive duplicate messages arrive, the library updates the existing card, incrementing a clean counter badge (x2, x3... x5) and resetting its lifetime countdown.

3. Zero Dependencies & Zero Configuration

• 0 KB Third-Party Footprint: 100% native .NET 10 / WPF code with zero third-party packages.
• Zero Configuration Setup: Theme resources load automatically. No manual ResourceDictionary registration in App.xaml or initialization methods required — call MsgToast.Show() directly from anywhere.

4. MVVM Compatibility

Designed for MVVM architecture. Trigger notifications and async dialogs directly from ViewModels using ICommand and AsyncRelayCommand:

public class MainViewModel : ViewModelBase
{
    public ICommand SaveCommand { get; }
    public ICommand ExportCommand { get; }

    public MainViewModel()
    {
        // 1. Standard toast notification command
        SaveCommand = new RelayCommand(() =>
        {
            MsgToast.ShowSuccess("Settings saved successfully!");
        });

        // 2. Async dialog command using AskAsync
        ExportCommand = new AsyncRelayCommand(async () =>
        {
            bool confirm = await MsgToast.AskAsync("Start report export?", "Export Now", "Cancel");
            if (confirm)
            {
                // Perform export...
            }
        });
    }
}

📁 Repository Structure

Kriss.Wpf.Toasts/
├── src/
│   └── Kriss.Wpf.Toasts/          # Main library source code (.NET 10 / WPF)
│       ├── Abstractions/           # Interfaces (IToastHandle, IToastLocalizer)
│       ├── Models/                 # Configuration & Content DTOs (ToastOptions, ToastContent, ToastTarget)
│       ├── Controls/               # UI Controls & Host Attachment (ToastCard, ToastOverlayHost, ToastHost)
│       └── Services/               # Public APIs & Resolution Services (MsgToast, ToastManager, ToastHostManager)
└── samples/
    └── Toast.Demo/                 # Comprehensive MVVM Demo Application

📄 License

This project is licensed under the MIT License.