CeltreSoftware.NativeMessageBox 1.2.1

CeltreSoftware's Native Message Box

A small .NET library for showing native message boxes through the operating system's own dialog APIs or tools.

The goal is simple: call one API from your application and let the library choose the most native implementation available for the current platform.

Installation

dotnet add package CeltreSoftware.NativeMessageBox

Usage

using CeltreSoftware.NativeMessageBox;

MessageBox.ShowInfo("Finished", "The operation completed successfully.");
MessageBox.ShowWarning("Low Disk Space", "You are running out of storage.");
MessageBox.ShowError("Import Failed", "The file could not be processed.");

If you prefer a non-throwing API, use the TryShow... methods:

var shown = MessageBox.TryShowInfo("Finished", "The operation completed successfully.");

Supported Message Box Types

The current public API supports three message box variants:

• ShowInfo and TryShowInfo
• ShowWarning and TryShowWarning
• ShowError and TryShowError

All currently supported dialogs are single-button acknowledgement dialogs. They are meant for notifying the user, not for collecting a choice.

That means the library currently does not expose:

• yes/no dialogs
• ok/cancel dialogs
• retry/cancel dialogs
• custom button text
• custom icons beyond the built-in info, warning, and error variants

How Each Platform Generates Message Boxes

Windows

On Windows, the library calls the native Win32 MessageBoxW function from user32.dll.

• ShowInfo uses the Win32 information icon.
• ShowWarning uses the Win32 warning icon.
• ShowError uses the Win32 error icon.

This is the most direct implementation in the project because it uses the platform API itself rather than launching an external process.

macOS

On macOS, the library uses Cocoa (AppKit) by calling Objective-C runtime APIs through .NET interop.

• ShowInfo maps to an informational NSAlert.
• ShowWarning maps to a warning-style NSAlert.
• ShowError maps to a critical-style NSAlert.

Linux and FreeBSD

On Linux and FreeBSD, the library uses freedesktop/XDG desktop environment hints (XDG_CURRENT_DESKTOP, XDG_SESSION_DESKTOP, and DESKTOP_SESSION) to decide whether to use Zenity or KDialog.

• KDE/Plasma/LXQt-like environments prefer kdialog.
• GNOME/GTK-like environments prefer zenity.
• If the preferred tool is missing but the other one is installed, the library falls back to the available tool.
• If both tools are installed but no desktop hint can be resolved, the library treats the environment as ambiguous and fails instead of enforcing a global priority.
• If neither tool is installed, the library fails.

In throwing APIs, these failure cases raise PlatformNotSupportedException. In TryShow... APIs, they return false.

Zenity

When Zenity is selected by the environment-aware resolver, the library launches it with these dialog modes:

• ShowInfo uses zenity --info
• ShowWarning uses zenity --warning
• ShowError uses zenity --error

KDialog

When KDialog is selected by the environment-aware resolver, the library launches it with these dialog modes:

• ShowInfo uses kdialog --msgbox
• ShowWarning uses kdialog --sorry
• ShowError uses kdialog --error

Platform Notes

• Windows support is implemented through Win32.
• macOS support is implemented through Cocoa (AppKit) interop.
• Linux and FreeBSD support depend on either zenity or kdialog being installed and available on PATH.
• Linux and FreeBSD tool selection is based on XDG/freedesktop desktop environment hints rather than a fixed global priority.

Error Behavior

• ShowInfo, ShowWarning, and ShowError throw if the current platform is unsupported or if the dialog cannot be shown.
• TryShowInfo, TryShowWarning, and TryShowError catch failures and return false instead.

License

This project is licensed under the MIT license. See LICENSE.md.