Crate notify_rust

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 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 acknowledge it.")
    .icon("thunderbird")
    .appname("thunderbird")
    .hint(Hint::Category("email".to_owned()))
    .hint(Hint::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(Hint::Resident(true))
                   .show()
                   .unwrap()
                   .wait_for_action(|action| match action {
                                        "default" => println!("you clicked \"default\""),
                                        "clicked" => println!("that was correct"),
                                        // here "__closed" is a hard coded keyword
                                        "__closed" => println!("the notification was closed"),
                                        _ => ()
                                    });

Minimal Example

You can omit almost everything

Notification::new().show();

more examples in the repository.

Platform Differences

✔︎ = works
❌ = will not compile

Notification

method	XDG	macOS	windows
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	windows
fn wait_for_action(...)	✔︎	❌	❌
fn close(...)	✔︎	❌	❌
fn on_close(...)	✔︎	❌	❌
fn update(...)	✔︎	❌	❌
fn id(...)	✔︎	❌	❌

Functions

	XDG	macOS	windows
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")))]

Modules

• error

Structs

• Notification
  Desktop notification.
• NotificationHandle
  A handle to a shown notification.
• ServerInformation
  Return value of get_server_information().

Enums

• ActionResponse
  Response to an action
• CloseReason
  Reason passed to NotificationClosed Signal
• DbusStack
  Which Dbus implementation are we using?
• Hint
  Hints allow you to pass extra information to the server.
• Timeout
  Describes the timeout of a notification
• Urgency
  Levels of Urgency.

Traits

• CloseHandler
  Your handy callback for the Close signal of your Notification.

Functions

• dbus_stack
  Get the currently used DbusStack
• get_capabilities
  Get list of all capabilities of the running notification server.
• get_server_information
  Returns a struct containing ServerInformation.
• handle_action
  Listens for the ActionInvoked(UInt32, String) Signal.