Struct notify_rust::Notification

#[non_exhaustive]
pub struct Notification {
    pub appname: String,
    pub summary: String,
    pub subtitle: Option<String>,
    pub body: String,
    pub icon: String,
    pub hints: HashSet<Hint>,
    pub actions: Vec<String>,
    pub timeout: Timeout,
    /* private fields */
}

Desktop notification.

A desktop notification is configured via builder pattern, before it is launched with show().

Example

    Notification::new()
        .summary("☝️ A notification")
        .show()?;

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

appname: String

Filled by default with executable name.

summary: String

Single line to summarize the content.

subtitle: Option<String>

Subtitle for macOS

body: String

Multiple lines possible, may support simple markup, check out get_capabilities() -> body-markup and body-hyperlinks.

icon: String

Use a file:// URI or a name in an icon theme, must be compliant freedesktop.org.

hints: HashSet<Hint>

Check out Hint

warning

this does not hold all hints, Hint::Custom and Hint::CustomInt are held elsewhere,

actions: Vec<String>

See Notification::actions() and Notification::action()

timeout: Timeout

Lifetime of the Notification in ms. Often not respected by server, sorry.

Implementations

impl Notification

pub fn new() -> Notification

Constructs a new Notification.

Most fields are empty by default, only appname is initialized with the name of the current executable. The appname is used by some desktop environments to group notifications.

pub fn appname(&mut self, appname: &str) -> &mut Notification

Overwrite the appname field used for Notification.

Platform Support

Please note that this method has no effect on macOS. Here you can only set the application via set_application()

pub fn summary(&mut self, summary: &str) -> &mut Notification

Set the summary.

Often acts as title of the notification. For more elaborate content use the body field.

pub fn subtitle(&mut self, subtitle: &str) -> &mut Notification

Set the subtitle.

This is only useful on macOS, it’s not part of the XDG specification and will therefore be eaten by gremlins under your CPU 😈🤘.

pub fn image_path(&mut self, path: &str) -> &mut Notification

Wrapper for Hint::ImagePath

pub fn sound_name(&mut self, name: &str) -> &mut Notification

Wrapper for Hint::SoundName

pub fn body(&mut self, body: &str) -> &mut Notification

Set the content of the body field.

Multiline textual content of the notification. Each line should be treated as a paragraph. Simple html markup should be supported, depending on the server implementation.

pub fn icon(&mut self, icon: &str) -> &mut Notification

Set the icon field.

You can use common icon names here, usually those in /usr/share/icons can all be used. You can also use an absolute path to file.

Platform support

macOS does not have support manually setting the icon. However you can pretend to be another app using set_application()

pub fn auto_icon(&mut self) -> &mut Notification

Set the icon field automatically.

This looks at your binary’s name and uses it to set the icon.

Platform support

macOS does not support manually setting the icon. However you can pretend to be another app using set_application()

pub fn hint(&mut self, hint: Hint) -> &mut Notification

Adds a hint.

This method will add a hint to the internal hint HashSet. Hints must be of type Hint.

Many of these are again wrapped by more convenient functions such as:

• sound_name(...)
• urgency(...)
• image(...) or
  • image_data(...)
  • image_path(...)

Notification::new().summary("Category:email")
                   .body("This should not go away until you acknowledge it.")
                   .icon("thunderbird")
                   .appname("thunderbird")
                   .hint(Hint::Category("email".to_owned()))
                   .hint(Hint::Resident(true))
                   .show();

Platform support

Most of these hints don’t even have an effect on the big XDG Desktops, they are completely tossed on macOS.

pub fn timeout<T: Into<Timeout>>(&mut self, timeout: T) -> &mut Notification

Set the timeout.

Accepts multiple types that implement Into<Timeout>.

i31

This sets the time (in milliseconds) from the time the notification is displayed until it is closed again by the Notification Server. According to specification -1 will leave the timeout to be set by the server and 0 will cause the notification never to expire.

Duration

When passing a Duration we will try convert it into milliseconds.

assert_eq!(Timeout::from(Duration::from_millis(2000)), Timeout::Milliseconds(2000));

Caveats!

1. If the duration is zero milliseconds then the original behavior will apply and the notification will Never timeout.
2. Should the number of milliseconds not fit within an i32 then we will fall back to the default timeout.

assert_eq!(Timeout::from(Duration::from_millis(0)), Timeout::Never);
assert_eq!(Timeout::from(Duration::from_millis(u64::MAX)), Timeout::Default);

Platform support

This only works on XDG Desktops, macOS does not support manually setting the timeout.

pub fn urgency(&mut self, urgency: Urgency) -> &mut Notification

Set the urgency.

Pick between Medium, Low and High.

Platform support

Most Desktops on linux and bsd are far too relaxed to pay any attention to this. In macOS this does not exist

pub fn actions(&mut self, actions: Vec<String>) -> &mut Notification

👎Deprecated: please use .action() only

Set actions.

To quote http://www.galago-project.org/specs/notification/0.9/x408.html#command-notify

Actions are sent over as a list of pairs. Each even element in the list (starting at index 0) represents the identifier for the action. Each odd element in the list is the localized string that will be displayed to the user.y

There is nothing fancy going on here yet. Careful! This replaces the internal list of actions!

(xdg only)

pub fn action(&mut self, identifier: &str, label: &str) -> &mut Notification

Add an action.

This adds a single action to the internal list of actions.

(xdg only)

pub fn id(&mut self, id: u32) -> &mut Notification

Set an Id ahead of time

Setting the id ahead of time allows overriding a known other notification. Though if you want to update a notification, it is easier to use the update() method of the NotificationHandle object that show() returns.

(xdg only)

pub fn finalize(&self) -> Notification

Finalizes a Notification.

Part of the builder pattern, returns a complete copy of the built notification.

pub fn show(&self) -> Result<NotificationHandle>

Sends Notification to D-Bus.

Returns a handle to a notification

pub async fn show_async(&self) -> Result<NotificationHandle>

Sends Notification to D-Bus.

Returns a handle to a notification

pub async fn show_async_at_bus( &self, sub_bus: &str ) -> Result<NotificationHandle>

Sends Notification to D-Bus.

Returns a handle to a notification

pub fn show_debug(&mut self) -> Result<NotificationHandle>

👎Deprecated: this was never meant to be public API

Wraps [show()] but prints notification to stdout.

Trait Implementations

impl Clone for Notification

fn clone(&self) -> Notification

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Notification

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Notification

fn default() -> Notification

Returns the “default value” for a type.