Expand description
Desktop Notifications for Rust.
Desktop notifications are popup messages generated to notify the user of certain events.
§Platform Support
This library was originally conceived with the XDG notification specification in mind. Since version 3.3 this crate also builds on macOS, however the semantics of the XDG specification and macOS NSNotifications are quite different. Therefore only the a very small subset of functions is supported on macOS. Certain methods don’t have any effect there, others will explicitly fail to compile, in these cases you will have to add platform specific toggles to your code. For more see platform differences
§Examples
§Example 1: Simple Notification
Notification::new()
.summary("Firefox News")
.body("This will almost look like a real firefox notification.")
.icon("firefox")
.timeout(Timeout::Milliseconds(6000)) //milliseconds
.show().unwrap();§Example 2: Persistent Notification
Notification::new()
.summary("Category:email")
.body("This has nothing to do with emails.\nIt should not go away until you acknoledge it.")
.icon("thunderbird")
.appname("thunderbird")
.hint(NotificationHint::Category("email".to_owned()))
.hint(NotificationHint::Resident(true)) // this is not supported by all implementations
.timeout(Timeout::Never) // this however is
.show().unwrap();Careful! There are no checks whether you use hints twice.
It is possible to set urgency=Low AND urgency=Critical, in which case the behavior of the server is undefined.
§Example 3: Ask the user to do something
Notification::new().summary("click me")
.action("default", "default")
.action("clicked", "click here")
.hint(NotificationHint::Resident(true))
.show()
.unwrap()
.wait_for_action(|action| match action {
"default" => println!("you clicked \"default\""),
"clicked" => println!("that was correct"),
// here "__closed" is a hardcoded keyword
"__closed" => println!("the notification was closed"),
_ => ()
});§Minimal Example
You can ommit almost everything
Notification::new().show();more examples in the repository.
§Platform Differences
✔︎ = works
❌ = will not compile
§Notification
| method | XDG | macOS |
| fn appname(...) | ✔︎ | |
| fn summary(...) | ✔︎ | ✔︎ |
| fn subtitle(...) | ✔︎ | |
| fn body(...) | ✔︎ | ✔︎ |
| fn icon(...) | ✔︎ | |
| fn auto_icon(...) | ✔︎ | |
| fn hint(...) | ✔︎ | |
| fn timeout(...) | ✔︎ | |
| fn urgency(...) | ✔︎ | |
| fn action(...) | ✔︎ | |
| fn id(...) | ✔︎ | |
| fn finalize(...) | ✔︎ | ✔︎ |
| fn show(...) | ✔︎ | ✔︎ |
§NotificationHandle
| method | XDG | macOS |
| fn wait_for_action(...) | ✔︎ | ❌ |
| fn close(...) | ✔︎ | ❌ |
| fn on_close(...) | ✔︎ | ❌ |
| fn update(...) | ✔︎ | ❌ |
| fn id(...) | ✔︎ | ❌ |
§Functions
| XDG | macOS | |
| fn get_capabilities(...) | ✔︎ | ❌ |
| fn get_server_information(...) | ✔︎ | ❌ |
| fn set_application(...) | ❌ | ✔︎ |
| fn get_bundle_identifier_or_default(...) | ❌ | ✔︎ |
§Toggles
Please use target_os toggles if you plan on using methods labeled with ❌.
#[cfg(target_os = "macos")]
// or
// #### #[cfg(all(unix, not(target_os = "macos")))]Re-exports§
pub use hints::NotificationHint;pub use error::Error;
Modules§
- error
- hints
NotificationHintsallow to pass extra information to the server.- server
- Experimental server taking the place of your Desktop Environments Notification Server.
Structs§
- Notification
- Desktop notification.
- Notification
Handle - A handle to a shown notification.
- Server
Information - Return value of
get_server_information().
Enums§
- Notification
Urgency - Levels of Urgency.
- Timeout
- Describes the timeout of a notification
Functions§
- get_
capabilities - Get list of all capabilities of the running notification server.
- get_
server_ information - Returns a struct containing
ServerInformation. - handle_
actions - Listens for the
ActionInvoked(UInt32, String)Signal. - stop_
server - Strictly internal. The Notificationserver implemented here exposes a “Stop” function. stops the notification server