Win11Toast for Nim

A pure Nim library for creating Windows 10/11 toast notifications using the Windows Runtime (WinRT) APIs.

Based on the Python win11toast library and valinet's plain C implementation.

Features

• Pure Nim implementation (no C++ shim required)
• Fluent builder API for constructing complex toasts
• Support for:
• Title, body, and attribution text
• App icons and images (local or URL)
• Action buttons
• Text input fields
• Selection dropdowns
• Progress bars
• Custom audio sounds
• Click-to-launch URLs
• Toast scenarios (default, alarm, reminder, incoming call, urgent)
• Toast duration (short/long)
• Tag and group for toast management

Installation

nimble install winim
# Then copy win11toast.nim to your project

Or add to your .nimble file:

requires "winim >= 3.9.0"

Quick Start

import win11toast

# Simple notification (fire and forget)
notify("Hello World", "This is a notification!")

# Notification with click action
notify(
    title  = "Click Me!"
    ,body   = "Click to open Nim website"
    ,launch = "https://nim-lang.org"
)

# Get handle for later use
let handle = toast("Title", "Body")
# ... do something ...
releaseToast(handle)

Builder API

For more complex notifications, use the ToastBuilder:

import win11toast

let xml = newToastBuilder()
    .setTitle("Download Complete")
    .setBody("Your file has been downloaded.")
    .setIcon("https://example.com/icon.png")
    .setImage("https://example.com/preview.png")
    .addButton("Open", "action:open")
    .addButton("Dismiss", "action:dismiss")
    .setAudio("ms-winsoundevent:Notification.Mail")
    .buildXml()

let handle = showToast(xml)
releaseToast(handle)

API Reference

High-Level Functions

notify(...)

Fire-and-forget notification. Resources are automatically released.

proc notify*(
    title      : string = ""
    ,body       : string = ""
    ,appId      : string = DEFAULT_APP_ID
    ,icon       : string = ""
    ,image      : string = ""
    ,duration   : Option[ToastDuration] = none(ToastDuration)
    ,scenario   : ToastScenario = tsDefault
    ,launch     : string = ""
    ,audio      : string = ""
    ,silent     : bool = false
    ,inputs     : seq[string] = @[]
    ,buttons    : seq[string] = @[]
    ,tag        : string = ""
    ,group      : string = ""
)

toast(...)

Show notification and return handle for later use.

proc toast*(...): ToastNotificationHandle

releaseToast(handle)

Release toast notification resources.

ToastBuilder Methods

Enums

ToastScenario

• tsDefault - Standard notification
• tsAlarm - Alarm notification (stays until dismissed)
• tsReminder - Reminder notification
• tsIncoming - Incoming call style
• tsUrgent - Urgent notification

ToastDuration

• tdShort - Short display (~5 seconds)
• tdLong - Long display (~25 seconds)

Audio Sources

Use Microsoft's built-in sounds: - ms-winsoundevent:Notification.Default - ms-winsoundevent:Notification.Mail - ms-winsoundevent:Notification.Reminder - ms-winsoundevent:Notification.SMS - ms-winsoundevent:Notification.Looping.Alarm - ms-winsoundevent:Notification.Looping.Call

App ID

The appId parameter determines which app icon appears on the toast. Use a valid Application User Model ID (AUMID) from an installed app.

To find valid AUMIDs, run in PowerShell:

Get-StartApps

Common examples: - Microsoft.Windows.Explorer - File Explorer - Microsoft.WindowsTerminal_8wekyb3d8bbwe!App - Windows Terminal

Requirements

• Windows 10 or later
• Nim >= 1.6.0
• winim >= 3.9.0

Limitations

1. Event Handlers: This version does not support event handlers for activated/dismissed/failed events. The Python version uses async callbacks which require implementing COM delegate interfaces.

2. Progress Updates: True progress updates (NotificationData) require additional WinRT interfaces. The current implementation shows static progress bars.

3. COM Activation: For activation when the app is closed, you need COM server registration which is beyond this library's scope.

License

MIT License

Credits

• win11toast - Python implementation
• valinet's gist - Plain C implementation
• winim - Windows API for Nim