SGU.Tools_MessageBoxTimed 3.7.1

.NET 6.0 .NET Framework 4.8

dotnet add package SGU.Tools_MessageBoxTimed --version 3.7.1

NuGet\Install-Package SGU.Tools_MessageBoxTimed -Version 3.7.1

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="SGU.Tools_MessageBoxTimed" Version="3.7.1" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="SGU.Tools_MessageBoxTimed" Version="3.7.1" />
                    

                            Directory.Packages.props

<PackageReference Include="SGU.Tools_MessageBoxTimed" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add SGU.Tools_MessageBoxTimed --version 3.7.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: SGU.Tools_MessageBoxTimed, 3.7.1"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package SGU.Tools_MessageBoxTimed@3.7.1

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=SGU.Tools_MessageBoxTimed&version=3.7.1
                    

                            Install as a Cake Addin

#tool nuget:?package=SGU.Tools_MessageBoxTimed&version=3.7.1
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

MessageBoxTimed

A Windows Forms message box that automatically closes after a specified timeout period with optional countdown display.

Features

Core Features

✅ Auto-close message boxes after a specified timeout
✅ Optional countdown timer display on buttons
✅ Full MessageBox.Show API compatibility - Drop-in replacement with timeout functionality
✅ Support for all MessageBoxButtons, MessageBoxIcon, MessageBoxDefaultButton, and MessageBoxOptions
✅ Factory pattern for reusable message box configurations
✅ Thread-safe implementation
✅ Multi-target support (.NET Framework 4.8 through .NET 10)

Advanced Features (v3.7+)

✅ Async/Await Support - Modern async patterns with ShowAsync()
✅ Event System - CountdownTick, Timeout, and Closed events
✅ Pause/Resume Control - Interactive timer management
✅ Visual Progress Bar - Custom dialog with progress indicator
✅ Position Control - 7 positioning options + custom coordinates
✅ Sound Control - System sounds, custom .wav files, or silent mode
✅ Toast Notifications - Non-modal popup notifications with animations
✅ Fluent Builder API - Modern, readable syntax

Installation

Install via NuGet Package Manager Console:

Install-Package SGU.Tools_MessageBoxTimed

Or via .NET CLI:

dotnet add package SGU.Tools_MessageBoxTimed

Usage

Basic Usage

using SGU.Tools;

// Simple auto-closing message box (closes after 1000ms by default) 
MessageBoxTimed.Show("Operation completed successfully!");

With Timeout and Buttons

// Wait for user input or auto-close with default result 
var result = MessageBoxTimed.Show(
    text: "Save changes before closing?",
    caption: "Confirm",
    timeout: 5000,
    buttons: MessageBoxButtons.YesNoCancel,
    defaultResult: DialogResult.Cancel
);

With Icons

// Display with standard Windows icons
MessageBoxTimed.Show(
    text: "File saved successfully!",
    caption: "Success",
    timeout: 3000,
    buttons: MessageBoxButtons.OK,
    icon: MessageBoxIcon.Information
);

// Warning message
MessageBoxTimed.Show(
    text: "This action cannot be undone!",
    caption: "Warning",
    timeout: 5000,
    buttons: MessageBoxButtons.OKCancel,
    icon: MessageBoxIcon.Warning
);

With Default Button

// Set which button is focused by default
MessageBoxTimed.Show(
    text: "Delete this item?",
    caption: "Confirm Delete",
    timeout: 10000,
    buttons: MessageBoxButtons.YesNo,
    icon: MessageBoxIcon.Question,
    defaultButton: MessageBoxDefaultButton.Button2  // "No" is default
);

With MessageBoxOptions (RTL, etc.)

// Right-to-left reading for localization
MessageBoxTimed.Show(
    text: "مرحبا بك في التطبيق",
    caption: "ترحيب",
    timeout: 5000,
    buttons: MessageBoxButtons.OK,
    icon: MessageBoxIcon.Information,
    defaultButton: MessageBoxDefaultButton.Button1,
    options: MessageBoxOptions.RtlReading | MessageBoxOptions.RightAlign
);

With Countdown Display

// Show countdown timer on the default button 
MessageBoxTimed.Show(
    text: "This will close automatically...",
    caption: "Auto-Close Demo",
    timeout: 5000,
    buttons: MessageBoxButtons.OK,
    icon: MessageBoxIcon.Information,
    showCountDown: true
);

With Owner Window

// Display as modal to a specific window 
MessageBoxTimed.Show(
    owner: this,
    text: "Processing complete!",
    caption: "Success",
    timeout: 3000,
    buttons: MessageBoxButtons.OK,
    icon: MessageBoxIcon.Information
);

Factory Pattern

// Create reusable message box configuration (basic)
var infoDialog = MessageBoxTimed.Factory(
    showMethod: (caption, buttons) => MessageBox.Show(
        "Operation completed", 
        caption, 
        buttons
    ),
    caption: "Information"
);

// Create factory with icon support
var confirmDialog = MessageBoxTimed.FactoryWithIcon(
    showMethod: (caption, buttons, icon) => MessageBox.Show(
        this, 
        "Are you sure?", 
        caption, 
        buttons, 
        icon
    ),
    caption: "Confirmation Required",
    showCountDown: true
);

// Create factory with full MessageBox.Show compatibility
var fullDialog = MessageBoxTimed.FactoryFull(
    showMethod: (caption, buttons, icon, defaultButton, options) => 
        MessageBox.Show(
            this,
            "Custom message",
            caption,
            buttons,
            icon,
            defaultButton,
            options
        ),
    caption: "My Application"
);

// Use the factory instances
var result = confirmDialog.Show(
    timeout: 10000,
    buttons: MessageBoxButtons.YesNo,
    icon: MessageBoxIcon.Question,
    defaultResult: DialogResult.No
);

var fullResult = fullDialog.Show(
    timeout: 5000,
    buttons: MessageBoxButtons.YesNo,
    icon: MessageBoxIcon.Warning,
    defaultButton: MessageBoxDefaultButton.Button2,
    options: MessageBoxOptions.DefaultDesktopOnly
);

Advanced Features

Async/Await Support

// Display message box asynchronously
var result = await MessageBoxTimed.ShowAsync(
    text: "Processing your request...",
    caption: "Please Wait",
    timeout: 5000,
    buttons: MessageBoxButtons.OKCancel,
    icon: MessageBoxIcon.Information
);

// With cancellation token
var cts = new CancellationTokenSource();
var result = await MessageBoxTimed.ShowAsync(
    text: "Long operation in progress...",
    caption: "Working",
    timeout: 30000,
    defaultResult: DialogResult.Cancel,
    cancellationToken: cts.Token
);

// Multiple async dialogs in parallel
var tasks = new[]
{
    MessageBoxTimed.ShowAsync("Task 1 complete", timeout: 2000),
    MessageBoxTimed.ShowAsync("Task 2 complete", timeout: 2000),
    MessageBoxTimed.ShowAsync("Task 3 complete", timeout: 2000)
};
var results = await Task.WhenAll(tasks);

Event Handling

// Subscribe to countdown tick events
MessageBoxTimed.CountdownTick += (sender, e) =>
{
    Console.WriteLine($"Time remaining: {e.RemainingMilliseconds}ms ({e.PercentComplete}% complete)");
};

// Subscribe to timeout event
MessageBoxTimed.Timeout += (sender, e) =>
{
    Console.WriteLine("Message box timed out!");
    Console.WriteLine($"Default result: {e.Result}");
};

// Subscribe to closed event
MessageBoxTimed.Closed += (sender, e) =>
{
    Console.WriteLine($"Dialog closed with result: {e.Result}");
    Console.WriteLine($"Timed out: {e.TimedOut}");
};

// Show message box with events
MessageBoxTimed.Show(
    text: "This will auto-close...",
    caption: "Countdown Demo",
    timeout: 5000,
    showCountDown: true
);

// Don't forget to unsubscribe when done
MessageBoxTimed.CountdownTick -= handlerMethod;

Fluent Builder API

// Simple fluent syntax
var result = MessageBoxTimed.Create()
    .WithText("Are you sure you want to delete this file?")
    .WithCaption("Confirm Delete")
    .WithTimeout(10000)
    .WithButtons(MessageBoxButtons.YesNo)
    .WithIcon(MessageBoxIcon.Warning)
    .WithDefaultButton(MessageBoxDefaultButton.Button2)
    .WithCountdown()
    .Show();

// With event callbacks
var result = MessageBoxTimed.Create()
    .WithText("Processing your request...")
    .WithCaption("Please Wait")
    .WithTimeout(5000)
    .WithIcon(MessageBoxIcon.Information)
    .OnCountdownTick((sender, e) => 
    {
        Console.WriteLine($"{e.RemainingMilliseconds}ms remaining");
    })
    .OnTimeout((sender, e) => 
    {
        Console.WriteLine("Request timed out!");
    })
    .Show();

// Async with builder
var result = await MessageBoxTimed.Create()
    .WithText("Async operation complete")
    .WithTimeout(3000)
    .WithIcon(MessageBoxIcon.Information)
    .ShowAsync();

// Reusable builder configurations
var warningBuilder = MessageBoxTimed.Create()
    .WithCaption("Warning")
    .WithIcon(MessageBoxIcon.Warning)
    .WithButtons(MessageBoxButtons.YesNo)
    .WithDefaultButton(MessageBoxDefaultButton.Button2)
    .WithTimeout(10000);

// Use the configured builder multiple times
var result1 = warningBuilder.WithText("Delete file A?").Show();
var result2 = warningBuilder.WithText("Delete file B?").Show();

Pause/Resume Control

// Show a controllable message box
var result = MessageBoxTimed.ShowControllable(
    "Processing large file...",
    out IMessageBoxTimedControl control,
    caption: "Please Wait",
    timeout: 30000);

// In another thread or callback:
control.Pause();              // Pause the countdown
control.AddTime(10000);       // Add 10 more seconds
control.Resume();             // Resume countdown
control.ResetTimer();         // Reset to original timeout
control.Cancel();             // Close immediately

// Check status
bool isPaused = control.IsPaused;
bool isRunning = control.IsRunning;
int remaining = control.RemainingMilliseconds;

Visual Progress Bar

// Show message box with progress bar
var result = MessageBoxTimed.ShowWithProgress(
    text: "Downloading update...",
    caption: "Update Manager",
    timeout: 10000,
    buttons: MessageBoxButtons.OKCancel,
    icon: MessageBoxIcon.Information
);

// With owner window
var result = MessageBoxTimed.ShowWithProgress(
    owner: this,
    text: "Processing files...",
    caption: "Please Wait",
    timeout: 15000,
    icon: MessageBoxIcon.Information
);

// Async version
var result = await MessageBoxTimed.ShowWithProgressAsync(
    "Uploading data...",
    timeout: 20000);

Position Control

// Position at bottom-right (notification style)
MessageBoxTimed.ShowAtPosition(
    "Download complete!",
    position: MessageBoxPosition.BottomRight,
    timeout: 3000);

// Custom position
MessageBoxTimed.ShowAtPosition(
    "Custom location",
    position: MessageBoxPosition.Custom,
    customLocation: new Point(100, 100),
    timeout: 5000);

// Available positions:
// - CenterScreen (default)
// - CenterParent
// - TopLeft
// - TopRight
// - TopCenter
// - BottomLeft
// - BottomRight
// - BottomCenter
// - Custom (with customLocation parameter)

Sound Control

// System sound (default behavior based on icon)
MessageBoxTimed.ShowWithSound(
    "File saved successfully!",
    icon: MessageBoxIcon.Information);

// Custom sound file
var soundSettings = MessageBoxTimed.SoundSettings.Custom("C:\\Sounds\\notify.wav");
MessageBoxTimed.ShowWithSound(
    "Download complete!",
    soundSettings: soundSettings,
    icon: MessageBoxIcon.Information);

// Silent (no sound)
MessageBoxTimed.ShowWithSound(
    "Background task complete",
    soundSettings: MessageBoxTimed.SoundSettings.Silent,
    icon: MessageBoxIcon.Information);

// Using builder
MessageBoxTimed.Create()
    .WithText("Operation complete!")
    .WithCustomSound("success.wav")
    .Show();

// Or mute
MessageBoxTimed.Create()
    .WithText("Silent notification")
    .Silent()
    .Show();

// Simple toast
MessageBoxTimed.ShowSuccessToast("File uploaded successfully!");

// Advanced toast with all options
MessageBoxTimed.ShowToast(
    text: "5 files processed successfully",
    caption: "Batch Complete",
    duration: 5000,
    icon: MessageBoxIcon.Information,
    position: ToastPosition.BottomRight,
    animation: ToastAnimation.Fade);

// Toast with custom sound
MessageBoxTimed.ShowToast(
    "Error occurred!",
    "Error",
    3000,
    MessageBoxIcon.Error,
    ToastPosition.TopRight,
    ToastAnimation.Slide,
    soundSettings: MessageBoxTimed.SoundSettings.Custom("error.wav"));

// Quick helper methods
MessageBoxTimed.ShowSuccessToast("Success message");
MessageBoxTimed.ShowErrorToast("Error message");
MessageBoxTimed.ShowWarningToast("Warning message");
MessageBoxTimed.ShowInfoToast("Info message");

// Close all active toasts
MessageBoxTimed.CloseAllToasts();

// Check active toast count
int count = MessageBoxTimed.ActiveToastCount;

// Toast positions:
// - TopLeft, TopCenter, TopRight
// - BottomLeft, BottomCenter, BottomRight
// - Center

// Toast animations:
// - None, Fade, Slide, Pop

Combining Features with Fluent Builder

// Controllable dialog with progress bar
MessageBoxTimed.Create()
    .WithText("Processing large dataset...")
    .WithTimeout(60000)
    .WithProgressBar()
    .Controllable()
    .Show(out var control);

// Toast notification with custom sound
MessageBoxTimed.Create()
    .WithText("Download complete!")
    .WithCaption("Success")
    .WithTimeout(4000)
    .WithIcon(MessageBoxIcon.Information)
    .AsToast(ToastPosition.BottomRight, ToastAnimation.Fade)
    .WithCustomSound("success.wav")
    .Show();

// Positioned dialog with countdown and sound
MessageBoxTimed.Create()
    .WithText("Session expiring soon...")
    .WithCaption("Warning")
    .WithTimeout(30000)
    .WithIcon(MessageBoxIcon.Warning)
    .WithCountdown()
    .AtPosition(MessageBoxPosition.TopRight)
    .WithSound(MessageBoxTimed.SoundSettings.Default)
    .OnTimeout((s, e) => Console.WriteLine("Session expired"))
    .Show();

// Silent, positioned, with progress
MessageBoxTimed.Create()
    .WithText("Background sync in progress...")
    .WithTimeout(15000)
    .AtPosition(MessageBoxPosition.BottomRight)
    .WithProgressBar()
    .Silent()
    .Show();

API Reference

MessageBoxTimed.Show() Overloads

Basic Overload

DialogResult Show(
    string text,
    string caption = null,
    int timeout = 1000,
    MessageBoxButtons buttons = MessageBoxButtons.OK,
    DialogResult defaultResult = DialogResult.None,
    bool showCountDown = false
)

With Icon

DialogResult Show(
    string text,
    string caption,
    int timeout,
    MessageBoxButtons buttons,
    MessageBoxIcon icon,
    DialogResult defaultResult = DialogResult.None,
    bool showCountDown = false
)

With Default Button

DialogResult Show(
    string text,
    string caption,
    int timeout,
    MessageBoxButtons buttons,
    MessageBoxIcon icon,
    MessageBoxDefaultButton defaultButton,
    DialogResult defaultResult = DialogResult.None,
    bool showCountDown = false
)

With Options (Full Compatibility)

DialogResult Show(
    string text,
    string caption,
    int timeout,
    MessageBoxButtons buttons,
    MessageBoxIcon icon,
    MessageBoxDefaultButton defaultButton,
    MessageBoxOptions options,
    DialogResult defaultResult = DialogResult.None,
    bool showCountDown = false
)

With Owner Window

All of the above overloads also have variants that accept an IWin32Window owner as the first parameter.

MessageBoxTimed.ShowAsync() Overloads

Asynchronous versions of all Show() methods with an additional CancellationToken parameter:

Task<DialogResult> ShowAsync(
    string text,
    string caption = null,
    int timeout = 1000,
    MessageBoxButtons buttons = MessageBoxButtons.OK,
    MessageBoxIcon icon = MessageBoxIcon.None,
    MessageBoxDefaultButton defaultButton = MessageBoxDefaultButton.Button1,
    MessageBoxOptions options = 0,
    DialogResult defaultResult = DialogResult.None,
    bool showCountDown = false,
    CancellationToken cancellationToken = default
)

Task<DialogResult> ShowAsync(
    IWin32Window owner,
    string text,
    string caption = null,
    int timeout = 1000,
    MessageBoxButtons buttons = MessageBoxButtons.OK,
    MessageBoxIcon icon = MessageBoxIcon.None,
    MessageBoxDefaultButton defaultButton = MessageBoxDefaultButton.Button1,
    MessageBoxOptions options = 0,
    DialogResult defaultResult = DialogResult.None,
    bool showCountDown = false,
    CancellationToken cancellationToken = default
)

MessageBoxTimed.Create()

Creates a fluent builder for constructing MessageBoxTimed instances:

MessageBoxTimedBuilder Create()

Builder Methods

WithText(string text) - Sets the message text
WithCaption(string caption) - Sets the title
WithTimeout(int timeout) - Sets timeout in milliseconds
WithButtons(MessageBoxButtons buttons) - Sets buttons
WithIcon(MessageBoxIcon icon) - Sets icon
WithDefaultButton(MessageBoxDefaultButton defaultButton) - Sets default button
WithOptions(MessageBoxOptions options) - Sets options
WithDefaultResult(DialogResult defaultResult) - Sets default result
WithCountdown(bool showCountDown = true) - Enables countdown
WithOwner(IWin32Window owner) - Sets owner window
OnCountdownTick(EventHandler<MessageBoxTimedEventArgs> handler) - Sets countdown tick callback
OnTimeout(EventHandler<MessageBoxTimedEventArgs> handler) - Sets timeout callback
OnClosed(EventHandler<MessageBoxTimedEventArgs> handler) - Sets closed callback
Show() - Displays the message box
ShowAsync(CancellationToken cancellationToken = default) - Displays the message box asynchronously

Events

CountdownTick Event

static event EventHandler<MessageBoxTimedEventArgs> CountdownTick

Raised periodically during countdown (when showCountDown is true).

Timeout Event

static event EventHandler<MessageBoxTimedEventArgs> Timeout

Raised when the message box times out.

Closed Event

static event EventHandler<MessageBoxTimedEventArgs> Closed

Raised when the message box is closed.

MessageBoxTimedEventArgs Properties

int RemainingMilliseconds - Time remaining before auto-close
bool TimedOut - Whether the dialog timed out
DialogResult Result - The dialog result
bool Cancel - Can be set to cancel the operation
int TotalTimeout - Total timeout duration
int PercentComplete - Percentage of time elapsed (0-100)

Advanced Methods

ShowControllable - Pause/Resume Control

DialogResult ShowControllable(
    string text,
    out IMessageBoxTimedControl control,
    string caption = null,
    int timeout = 1000,
    MessageBoxButtons buttons = MessageBoxButtons.OK,
    MessageBoxIcon icon = MessageBoxIcon.None,
    MessageBoxDefaultButton defaultButton = MessageBoxDefaultButton.Button1,
    MessageBoxOptions options = 0,
    DialogResult defaultResult = DialogResult.None
)

IMessageBoxTimedControl Interface:

bool IsPaused - Gets whether timer is paused
bool IsRunning - Gets whether timer is running
int RemainingMilliseconds - Gets remaining time
int TotalTimeout - Gets total timeout
void Pause() - Pauses the countdown
void Resume() - Resumes the countdown
void AddTime(int milliseconds) - Adds time to countdown
void ResetTimer() - Resets to original timeout
void Cancel() - Closes the message box immediately

ShowWithProgress - Visual Progress Bar

DialogResult ShowWithProgress(
    string text,
    string caption = null,
    int timeout = 1000,
    MessageBoxButtons buttons = MessageBoxButtons.OK,
    MessageBoxIcon icon = MessageBoxIcon.None,
    DialogResult defaultResult = DialogResult.None
)

Task<DialogResult> ShowWithProgressAsync(
    string text,
    string caption = null,
    int timeout = 1000,
    MessageBoxButtons buttons = MessageBoxButtons.OK,
    MessageBoxIcon icon = MessageBoxIcon.None,
    DialogResult defaultResult = DialogResult.None,
    CancellationToken cancellationToken = default
)

ShowAtPosition - Position Control

DialogResult ShowAtPosition(
    string text,
    string caption = null,
    MessageBoxPosition position = MessageBoxPosition.CenterScreen,
    Point? customLocation = null,
    int timeout = 1000,
    MessageBoxButtons buttons = MessageBoxButtons.OK,
    MessageBoxIcon icon = MessageBoxIcon.None,
    DialogResult defaultResult = DialogResult.None,
    bool showCountDown = false
)

MessageBoxPosition Enum:

CenterScreen - Center of screen (default)
CenterParent - Center of parent window
TopLeft - Top-left corner
TopRight - Top-right corner
TopCenter - Top-center
BottomLeft - Bottom-left corner
BottomRight - Bottom-right corner
BottomCenter - Bottom-center
Custom - Custom location (use with customLocation parameter)

ShowWithSound - Sound Control

DialogResult ShowWithSound(
    string text,
    string caption = null,
    int timeout = 1000,
    MessageBoxButtons buttons = MessageBoxButtons.OK,
    MessageBoxIcon icon = MessageBoxIcon.None,
    SoundSettings soundSettings = null,
    MessageBoxDefaultButton defaultButton = MessageBoxDefaultButton.Button1,
    MessageBoxOptions options = 0,
    DialogResult defaultResult = DialogResult.None,
    bool showCountDown = false
)

SoundSettings Class:

SoundSettings.Default - System sounds based on icon
SoundSettings.Silent - All sounds muted
SoundSettings.Custom(string soundPath) - Custom .wav file
bool PlaySystemSound - Enable/disable system sounds
string CustomSoundPath - Path to custom .wav file
bool UseCustomSound - Use custom sound instead of system
bool Muted - Mute all sounds

ShowToast - Toast Notifications

Form ShowToast(
    string text,
    string caption = null,
    int duration = 3000,
    MessageBoxIcon icon = MessageBoxIcon.Information,
    ToastPosition position = ToastPosition.BottomRight,
    ToastAnimation animation = ToastAnimation.Fade,
    SoundSettings soundSettings = null
)

// Helper methods
Form ShowSuccessToast(string text, string caption = "Success", int duration = 3000)
Form ShowErrorToast(string text, string caption = "Error", int duration = 5000)
Form ShowWarningToast(string text, string caption = "Warning", int duration = 4000)
Form ShowInfoToast(string text, string caption = "Information", int duration = 3000)

void CloseAllToasts()
int ActiveToastCount { get; }

ToastPosition Enum:

TopLeft, TopCenter, TopRight
BottomLeft, BottomCenter, BottomRight
Center

ToastAnimation Enum:

None - No animation
Fade - Fade in/out
Slide - Slide in/out
Pop - Scale in/out

Enhanced Builder Methods

In addition to the core builder methods, the following advanced methods are available:

WithProgressBar(bool showProgressBar = true) - Enables visual progress bar
Controllable(bool controllable = true) - Enables pause/resume control
AtPosition(MessageBoxPosition position) - Sets message box position
AtCustomLocation(Point location) - Sets custom position
WithSound(SoundSettings soundSettings) - Sets sound configuration
Silent() - Mutes all sounds
WithCustomSound(string soundPath) - Uses custom .wav file
AsToast(ToastPosition position, ToastAnimation animation) - Converts to toast notification
Show(out IMessageBoxTimedControl control) - Shows and returns control interface

Platform Support

✅ .NET Framework 4.8 (Windows)
✅ .NET 6.0 (Windows)
✅ .NET 8.0 (Windows)
✅ .NET 10.0 (Windows)
⚠️ Requires Windows OS (uses Win32 APIs for UI manipulation)

Compatibility

MessageBoxTimed is designed as a 100% backward-compatible, drop-in replacement for the standard MessageBox.Show. All standard MessageBoxButtons, MessageBoxIcon, MessageBoxDefaultButton, and MessageBoxOptions are fully supported, plus additional timeout and advanced features.

Migration from MessageBox.Show

Simply replace your MessageBox.Show calls with MessageBoxTimed.Show and add timeout parameters:

// Before
var result = MessageBox.Show(
    "Delete this file?",
    "Confirm",
    MessageBoxButtons.YesNo,
    MessageBoxIcon.Question
);

// After - with 10 second auto-close
var result = MessageBoxTimed.Show(
    "Delete this file?",
    "Confirm",
    10000,  // 10 seconds
    MessageBoxButtons.YesNo,
    MessageBoxIcon.Question,
    defaultResult: DialogResult.No
);

All existing code using MessageBoxTimed from previous versions continues to work without any changes.

Changelog

Version 3.7.1 (Current)

Major Feature Release - 8 New Advanced Features

New Features

✅ Async/Await Support - ShowAsync() methods with CancellationToken support
✅ Event System - CountdownTick, Timeout, and Closed events with MessageBoxTimedEventArgs
✅ Pause/Resume Control - ShowControllable() with IMessageBoxTimedControl interface
- Pause(), Resume(), AddTime(), ResetTimer(), Cancel()
- IsPaused, IsRunning, RemainingMilliseconds properties
✅ Visual Progress Bar - ShowWithProgress() and ShowWithProgressAsync()
- Custom form with integrated progress indicator
- Countdown display on buttons
✅ Position Control - ShowAtPosition() with 9 positioning options
- CenterScreen, CenterParent, TopLeft, TopRight, TopCenter
- BottomLeft, BottomRight, BottomCenter, Custom
✅ Sound Control - ShowWithSound() with SoundSettings class
- System sounds based on icon
- Custom .wav file support
- Silent mode
✅ Toast Notifications - ShowToast() with non-modal popups
- 7 position options with auto-stacking
- 3 animation styles (Fade, Slide, Pop)
- Helper methods: ShowSuccessToast, ShowErrorToast, ShowWarningToast, ShowInfoToast
- CloseAllToasts() and ActiveToastCount property
✅ Fluent Builder API - Create() method with 20+ builder methods
- All core and advanced features supported
- Method chaining for readable code
- Event callback support

Enhancements

Updated package description and tags
Comprehensive XML documentation for all public APIs
Extended test coverage (157+ tests)
Enhanced README with detailed examples

Breaking Changes

None - 100% backward compatible with all previous versions

Version 3.6.4

Core timeout and countdown functionality
Factory pattern support
Multi-framework targeting

Performance Considerations

Lightweight - Minimal overhead compared to standard MessageBox
Thread-safe - Can be called from any thread
Resource efficient - Timers are properly disposed
Toast management - Automatic cleanup of closed toasts
Event efficiency - Events only raised when subscribed

Best Practices

1. Always Specify Timeout

// Good
MessageBoxTimed.Show("Message", timeout: 5000);

// Avoid (relies on default 1000ms)
MessageBoxTimed.Show("Message");

2. Set Appropriate Default Results

// For critical actions, set safe defaults
MessageBoxTimed.Show(
    "Delete all files?",
    buttons: MessageBoxButtons.YesNo,
    defaultResult: DialogResult.No  // Safe default
);

3. Use Async for Long Operations

// Await async methods
var result = await MessageBoxTimed.ShowAsync(
    "Long operation...",
    timeout: 30000
);

4. Unsubscribe from Events

// Always unsubscribe to prevent memory leaks
MessageBoxTimed.CountdownTick += OnTick;
// ... use it ...
MessageBoxTimed.CountdownTick -= OnTick;

// Or use builder with inline handlers (auto-cleanup)
MessageBoxTimed.Create()
    .OnCountdownTick((s, e) => { /* ... */ })
    .Show();

5. Close Toasts Appropriately

// Close specific toasts when done
var toast = MessageBoxTimed.ShowToast("Processing...");
// ... when complete ...
toast.Close();

// Or close all at once
MessageBoxTimed.CloseAllToasts();

Support & Contributing

Issue Reporting

If you encounter any issues or have feature requests, please report them on the GitHub Issues page.

Contributing

Contributions are welcome! Please feel free to submit pull requests.

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Support the Project

If you find this library helpful, consider supporting development:

Made with ❤️ for the .NET community

Enhanced Builder Methods

In addition to the core builder methods, the following advanced methods are available:

WithProgressBar(bool showProgressBar = true) - Enables visual progress bar
Controllable(bool controllable = true) - Enables pause/resume control
AtPosition(MessageBoxPosition position) - Sets message box position
AtCustomLocation(Point location) - Sets custom position
WithSound(SoundSettings soundSettings) - Sets sound configuration
Silent() - Mutes all sounds
WithCustomSound(string soundPath) - Uses custom .wav file
AsToast(ToastPosition position, ToastAnimation animation) - Converts to toast notification
Show(out IMessageBoxTimedControl control) - Shows and returns control interface

With Owner Window

All of the above overloads also have variants that accept an IWin32Window owner as the first parameter.

Parameters

Parameter	Type	Default	Description
owner	IWin32Window	-	Parent window for modal display
text	string	-	The message text to display
caption	string	null	The title bar text
timeout	int	1000	Timeout in milliseconds
buttons	MessageBoxButtons	OK	Buttons to display (OK, OKCancel, YesNo, etc.)
icon	MessageBoxIcon	None	Icon to display (None, Information, Warning, Error, Question)
defaultButton	MessageBoxDefaultButton	Button1	Which button has focus by default
options	MessageBoxOptions	0	Display options (RtlReading, RightAlign, etc.)
defaultResult	DialogResult	None	Result when timeout expires
showCountDown	bool	false	Show countdown timer on button

Factory Methods

MessageBoxTimed.Factory()

IMessageBoxTimed Factory(
    Func<string, MessageBoxButtons, DialogResult> showMethod,
    string caption = null,
    bool showCountDown = false
)

Creates a reusable factory with basic MessageBox functionality.

MessageBoxTimed.FactoryWithIcon()

IMessageBoxTimed FactoryWithIcon(
    Func<string, MessageBoxButtons, MessageBoxIcon, DialogResult> showMethod,
    string caption = null,
    bool showCountDown = false
)

Creates a reusable factory with icon support.

MessageBoxTimed.FactoryFull()

IMessageBoxTimed FactoryFull(
    Func<string, MessageBoxButtons, MessageBoxIcon, MessageBoxDefaultButton, MessageBoxOptions, DialogResult> showMethod,
    string caption = null,
    bool showCountDown = false
)

Creates a reusable factory with full MessageBox.Show compatibility.

IMessageBoxTimed Interface

public interface IMessageBoxTimed
{
    DialogResult Show(
        int timeout = 1000,
        MessageBoxButtons buttons = MessageBoxButtons.OK,
        DialogResult defaultResult = DialogResult.None
    );

    DialogResult Show(
        int timeout,
        MessageBoxButtons buttons,
        MessageBoxIcon icon,
        DialogResult defaultResult = DialogResult.None
    );

    DialogResult Show(
        int timeout,
        MessageBoxButtons buttons,
        MessageBoxIcon icon,
        MessageBoxDefaultButton defaultButton,
        DialogResult defaultResult = DialogResult.None
    );

    DialogResult Show(
        int timeout,
        MessageBoxButtons buttons,
        MessageBoxIcon icon,
        MessageBoxDefaultButton defaultButton,
        MessageBoxOptions options,
        DialogResult defaultResult = DialogResult.None
    );
}

Platform Support

.NET Framework 4.8 (Windows)
.NET 6.0 (Windows)
.NET 8.0 (Windows)
.NET 10.0 (Windows)
Requires Windows OS (uses Win32 APIs)

Compatibility

MessageBoxTimed is designed as a drop-in replacement for the standard MessageBox.Show. All standard MessageBoxButtons, MessageBoxIcon, MessageBoxDefaultButton, and MessageBoxOptions are supported, plus the additional timeout and countdown features.

Migration from MessageBox.Show

Simply replace your MessageBox.Show calls with MessageBoxTimed.Show and add timeout parameters:

// Before
var result = MessageBox.Show(
    "Delete this file?",
    "Confirm",
    MessageBoxButtons.YesNo,
    MessageBoxIcon.Question
);

// After - with 10 second auto-close
var result = MessageBoxTimed.Show(
    "Delete this file?",
    "Confirm",
    10000,  // 10 seconds
    MessageBoxButtons.YesNo,
    MessageBoxIcon.Question,
    defaultResult: DialogResult.No
);

Issue Reporting

If you encounter any issues or have feature requests, please report them on the GitHub Issues.

If you find this library helpful, consider supporting development:

License

Licensed under the MIT License.

Author

Solutions Group Unlimited, LLC

Product	Compatible and additional computed target framework versions.
.NET	net6.0-windows7.0 is compatible. net7.0-windows was computed. net8.0-windows was computed. net8.0-windows7.0 is compatible. net9.0-windows was computed. net10.0-windows was computed. net10.0-windows7.0 is compatible.
.NET Framework	net48 is compatible. net481 was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

.NETFramework 4.8
- No dependencies.
net10.0-windows7.0
- No dependencies.
net6.0-windows7.0
- No dependencies.
net8.0-windows7.0
- No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
3.7.1	89	1/14/2026
3.6.4	94	1/8/2026
3.5.28	93	12/30/2025
3.5.26	88	12/30/2025

SGU.Tools_MessageBoxTimed 3.7.1

MessageBoxTimed

Features

Core Features

Advanced Features (v3.7+)

Installation

Usage

Basic Usage

With Timeout and Buttons

With Icons

With Default Button

With MessageBoxOptions (RTL, etc.)

With Countdown Display

With Owner Window

Factory Pattern

Advanced Features

Async/Await Support

Event Handling

Fluent Builder API

Pause/Resume Control

Visual Progress Bar

Position Control

Sound Control

Toast Notifications (Non-Modal)

Combining Features with Fluent Builder

API Reference

MessageBoxTimed.Show() Overloads

Basic Overload

With Icon

With Default Button

With Options (Full Compatibility)

With Owner Window

MessageBoxTimed.ShowAsync() Overloads

MessageBoxTimed.Create()

Builder Methods

Events

CountdownTick Event

Timeout Event

Closed Event

MessageBoxTimedEventArgs Properties

Advanced Methods

ShowControllable - Pause/Resume Control

ShowWithProgress - Visual Progress Bar

ShowAtPosition - Position Control

ShowWithSound - Sound Control

ShowToast - Toast Notifications

Enhanced Builder Methods

Platform Support

Compatibility

Migration from MessageBox.Show

Changelog

Version 3.7.1 (Current)

New Features

Enhancements

Breaking Changes

Version 3.6.4

Performance Considerations

Best Practices

1. Always Specify Timeout

2. Set Appropriate Default Results

3. Use Async for Long Operations

4. Unsubscribe from Events

5. Close Toasts Appropriately

Support & Contributing

Issue Reporting

Contributing

License

Support the Project

Enhanced Builder Methods

With Owner Window

Parameters

Factory Methods

MessageBoxTimed.Factory()

MessageBoxTimed.FactoryWithIcon()

MessageBoxTimed.FactoryFull()

IMessageBoxTimed Interface

Platform Support

Compatibility

Migration from MessageBox.Show

Issue Reporting