Crate notify_icon 

notify-icon-rs

A safe, ergonomic Rust wrapper around the Windows Shell_NotifyIcon API for managing system tray icons on Windows platforms.

This library provides a high-level interface to create, modify, and manage notification icons in the Windows system tray. It handles the complexities of the underlying Windows API while providing a builder pattern for easy configuration and Rust-style error handling.

Features

• Safe wrapper: Memory-safe abstraction over the raw Windows API
• Builder pattern: Fluent, chainable API for configuring notification icons
• Error handling: Proper Rust Result types instead of raw Windows error codes
• UTF-16 handling: Automatic conversion of Rust strings to Windows-compatible UTF-16
• Version support: Support for different Windows notification icon interface versions
• Comprehensive functionality: Support for tooltips, balloon notifications, GUIDs, and more

Supported Windows Versions

This library should supports Windows 95 and later versions, with enhanced functionality on:

• Windows Vista and later (improved balloon notification behavior)
• Windows 7 and later (additional notification features)

Platform Requirements

• Target: Windows only (#[cfg(windows)] should be used when integrating)
• Dependencies: Requires the windows crate for Windows API bindings

Basic Usage

use windows::Win32::Foundation::HWND;
use windows::Win32::UI::WindowsAndMessaging::LoadIconW;
use windows::Win32::UI::WindowsAndMessaging::WM_USER;
use notify_icon::NotifyIcon;

const IDI_APP_ICON: PCWSTR = PCWSTR(101 as *const u16);

// Create and configure a notification icon
let icon = unsafe { LoadIconW(hinstance, IDI_APP_ICON) }.unwrap_or_default();
let icon = NotifyIcon::new()
    .window_handle(hwnd)                    // Window to receive messages
    .tip("My Application")                  // Tooltip text
    .icon(icon_handle)                      // Icon to display
    .callback_message(WM_USER + 1);        // Message ID for callbacks

// Add the icon to the system tray
icon.notify_add()?;

// Later, remove the icon
icon.notify_delete()?;

Advanced Usage

Using GUIDs for Icon Persistence

use windows::core::GUID;

let icon = NotifyIcon::new()
    .window_handle(hwnd)
    .guid(GUID::from_u128(0x12345678_1234_1234_1234_123456789ABC))
    .tip("Persistent Icon")
    .icon(icon_handle);

icon.notify_add()?;

Setting Interface Version for Enhanced Features

use notify_icon::NotifyIcon;

// Use Windows Vista+ behavior
let icon = NotifyIcon::new()
    .window_handle(hwnd)
    .version(3)  // NOTIFYICON_VERSION_4
    .tip("Modern Icon");

icon.notify_add()?;
icon.notify_set_version()?;  // Apply the version setting

Modifying Existing Icons

// Change the tooltip of an existing icon
let updated_icon = icon.tip("Updated tooltip text");
updated_icon.notify_modify()?;

Message Handling

When users interact with the notification icon, Windows sends messages to the specified window. Common message handling pattern:

// In your window procedure
match msg {
    WM_USER + 1 => {  // Your callback message
        match lparam {
            WM_LBUTTONUP => {
                // Handle left click
            },
            WM_RBUTTONUP => {
                // Handle right click - typically show context menu
            },
            _ => {}
        }
    },
    _ => {}
}

Error Handling

All notification operations return windows::core::Result<()>.

Thread Safety

The NotifyIcon struct is safe to use across threads.

Limitations

• Windows only: This library only works on Windows platforms

Structs

NotifyIcon

A wrapper around the Windows NOTIFYICONDATAW structure for managing system tray icons in Windows.