INotificationManager14.1 Beta

Remarks

Notifications respect the style that the user has selected under Options. Plugins cannot force a particular presentation style. Big Box does not currently provide a notification system, so operations return an unavailable result there.

Messages and action labels accept a required fallback through Unbroken.LaunchBox.Plugins.PluginText and an optional package string-resource key. LaunchBox selects the user's language and formats any supplied values.

LaunchBox visibly attributes notifications to the requesting plugin. The default image comes from the plugin manifest or the conventional plugin.icon package image resource; no image is displayed when neither is available. Plugins can select another image by resource ID, but cannot replace the host-controlled attribution.

Operations can be called from any thread. A returned task completes after LaunchBox has processed the request. When the selected presentation is a message box, that can include waiting for the user to dismiss it.

New notifications contribute to the unread count until the user reads or dismisses them. Plugins can observe that state but cannot change it.

An identical message is suppressed for five seconds after publication. Notifications are also subject to an overall rate limit and a 50-notification retention limit. A suppressed request returns a result instead of displaying another notification.

Argument validation and cancellation use normal .NET exceptions. Runtime presentation failures are reported through Unbroken.LaunchBox.Plugins.Notifications.PluginNotificationResult.Status instead of being thrown. Added in LaunchBox 14.1.

Example

PluginProgressNotificationResult result = await notifications.StartProgressAsync(
    new PluginProgressNotificationArgs(
        new PluginText("Importing {0:N0} games...", gameCount)
        {
            ResourceKey = "notifications.import.running"
        })
    {
        Icon = new PluginNotificationIcon("import.progress")
    },
    cancellationToken);
if (result.Notification is IPluginProgressNotification progress)
{
    await progress.CompleteAsync(
        new PluginProgressCompletionArgs("Import complete."),
        cancellationToken);
}