https://github.com/kkent030315/notify-icon-rs
A safe, ergonomic Rust wrapper around the Windows Shell_NotifyIcon API for managing system tray icons on Windows platforms
https://github.com/kkent030315/notify-icon-rs
Last synced: 15 days ago
JSON representation
A safe, ergonomic Rust wrapper around the Windows Shell_NotifyIcon API for managing system tray icons on Windows platforms
- Host: GitHub
- URL: https://github.com/kkent030315/notify-icon-rs
- Owner: kkent030315
- License: mit
- Created: 2025-08-17T07:46:45.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2025-08-17T08:30:08.000Z (about 2 months ago)
- Last Synced: 2025-09-13T11:47:53.099Z (24 days ago)
- Language: Rust
- Homepage: https://docs.rs/notify-icon/latest
- Size: 17.6 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/kkent030315/notify-icon-rs/actions/workflows/ci.yml)
# 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 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
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
notify-icon = "0.1.0"
```
or invoke command:
```bash
cargo add notify-icon
```
## Quick Start
```rust
use windows::Win32::Foundation::HWND;
use windows::Win32::UI::WindowsAndMessaging::{LoadIconW, WM_USER};
use windows_tray_icon::NotifyIcon;
// Create and configure a notification icon
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()?;
```
## Usage Examples
### Using GUIDs for Icon Persistence
```rust
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
```rust
// 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
```rust
// 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. Here's a common message handling pattern:
```rust
use windows::Win32::UI::WindowsAndMessaging::{WM_USER, WM_LBUTTONUP, WM_RBUTTONUP};
// In your window procedure
match msg {
WM_USER + 1 => { // Your callback message
match lparam {
x if x == WM_LBUTTONUP as isize => {
// Handle left click
println!("Left click on tray icon");
},
x if x == WM_RBUTTONUP as isize => {
// Handle right click - typically show context menu
show_context_menu();
},
_ => {}
}
},
_ => {}
}
```
## Error Handling
All notification operations return `windows::core::Result<()>`.
```rust
match icon.notify_add() {
Ok(()) => println!("Icon added successfully"),
Err(e) => eprintln!("Failed to add icon: {}", e),
}
```
## Thread Safety
The `NotifyIcon` struct is safe to use across threads.
## Limitations
- **Windows only**: This library only works on Windows platforms
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
## License
MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Built on top of the excellent [`windows`](https://github.com/microsoft/windows-rs) crate