Crate notify_rust

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. macOS support has grown significantly; most notification methods work on both backends. Some methods are no-ops or backend-specific; see the platform differences table.

§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 (`NSUserNotifictation`)	macOS (`UNUserNotificationCenter`)	windows
`fn appname(...)`	✔︎	silent no-op	silent no-op
`fn summary(...)`	✔︎	✔︎	✔︎	✔︎
`fn subtitle(...)`		✔︎	✔︎	✔︎
`fn body(...)`	✔︎	✔︎	✔︎	✔︎
`fn icon(...)`	✔︎	silent no-op	silent no-op
`fn image_path(...)`	✔︎	✔︎	✔︎	✔︎
`fn hint(...)`	✔︎	-	-	-
`fn timeout(...)`	✔︎	ignored	✔︎	✔︎
`fn urgency(...)`	✔︎	-	✔︎ (→ `InterruptionLevel`)	✔︎
`fn interruption_level(...)`			✔︎
`fn action(...)`	✔︎	⚠︎ (labels only)	✔︎
`fn id(...)`	✔︎ (u32)	ignored	✔︎
`fn show(...)`	✔︎	✔︎	✔︎	✔︎
`fn show_async(...)`	✔︎		✔︎
`fn schedule(...)`		✔︎	✔︎

§`NotificationHandle`

method	XDG	macOS (`NSUserNotifictation`)	macOS (`UNUserNotification`)	windows
`fn wait_for_action(...)`	✔︎	✔︎	✔︎	✔︎
`fn on_close(...)`	✔︎	✔︎	✔︎	✔︎
`fn 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, a backward-compatible facade.
CloseReason: Reason a notification was closed without an action being invoked.
DbusStack: Which D-Bus implementation is in use.
Hint: Hints allow you to pass extra information to the notification server.
NotificationId: A platform-independent notification identifier.
NotificationResponse: The outcome of a shown notification.
Timeout: Describes the timeout of a notification
Urgency: Levels of Urgency.

Traits§

CloseHandler: Callback for the close signal of a notification.
ResponseHandler: Helper trait implemented by closures used with NotificationHandle::wait_for_response.

Functions§

dbus_stack: Get the currently active DbusStack.
get_capabilities: Returns a list of all capabilities of the running notification server.
get_server_information: Returns a [ServerInformation] struct describing the running notification server.
handle_action: Listens for the ActionInvoked(UInt32, String) signal.