Struct notify_rust::NotificationHandle
source · pub struct NotificationHandle { /* private fields */ }
Expand description
A handle to a shown notification.
This keeps a connection alive to ensure actions work on certain desktops.
Implementations§
source§impl NotificationHandle
impl NotificationHandle
sourcepub fn wait_for_action<F>(self, invocation_closure: F)
pub fn wait_for_action<F>(self, invocation_closure: F)
Waits for the user to act on a notification and then calls
invocation_closure
with the name of the corresponding action.
sourcepub fn close(self)
pub fn close(self)
Manually close the notification
§Example
let handle: NotificationHandle = Notification::new()
.summary("oh no")
.hint(notify_rust::Hint::Transient(true))
.body("I'll be here till you close me!")
.hint(Hint::Resident(true)) // does not work on kde
.timeout(Timeout::Never) // works on kde and gnome
.show()
.unwrap();
// ... and then later
handle.close();
sourcepub fn on_close<A>(self, handler: impl CloseHandler<A>)
pub fn on_close<A>(self, handler: impl CloseHandler<A>)
Executes a closure after the notification has closed.
§Example 1: I don’t care about why it closed (the good ole API)
Notification::new().summary("Time is running out")
.body("This will go away.")
.icon("clock")
.show()
.unwrap()
.on_close(|| println!("closed"));
§Example 2: I do care about why it closed (added in v4.5.0)
Notification::new().summary("Time is running out")
.body("This will go away.")
.icon("clock")
.show()
.unwrap()
.on_close(|reason| println!("closed: {:?}", reason));
sourcepub fn update(&mut self)
pub fn update(&mut self)
Replace the original notification with an updated version
§Example
let mut notification = Notification::new().summary("Latest News")
.body("Bayern Dortmund 3:2")
.show()
.unwrap();
std::thread::sleep_ms(1_500);
notification.summary("Latest News (Correction)")
.body("Bayern Dortmund 3:3");
notification.update();
Watch out for different implementations of the notification server! On plasma5 for instance, you should also change the appname, so the old message is really replaced and not just amended. Xfce behaves well, all others have not been tested by the developer.
Methods from Deref<Target = Notification>§
sourcepub fn appname(&mut self, appname: &str) -> &mut Notification
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()
sourcepub fn summary(&mut self, summary: &str) -> &mut Notification
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.
sourcepub fn subtitle(&mut self, subtitle: &str) -> &mut Notification
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 😈🤘.
sourcepub fn image_path(&mut self, path: &str) -> &mut Notification
pub fn image_path(&mut self, path: &str) -> &mut Notification
Wrapper for Hint::ImagePath
sourcepub fn sound_name(&mut self, name: &str) -> &mut Notification
pub fn sound_name(&mut self, name: &str) -> &mut Notification
Wrapper for Hint::SoundName
sourcepub fn body(&mut self, body: &str) -> &mut Notification
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.
sourcepub fn icon(&mut self, icon: &str) -> &mut Notification
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()
sourcepub fn auto_icon(&mut self) -> &mut Notification
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()
sourcepub fn hint(&mut self, hint: Hint) -> &mut Notification
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
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.
sourcepub fn timeout<T: Into<Timeout>>(&mut self, timeout: T) -> &mut Notification
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!
- If the duration is zero milliseconds then the original behavior will apply and the notification will Never timeout.
- 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.
sourcepub fn urgency(&mut self, urgency: Urgency) -> &mut Notification
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
sourcepub fn actions(&mut self, actions: Vec<String>) -> &mut Notification
👎Deprecated: please use .action() only
pub fn actions(&mut self, actions: Vec<String>) -> &mut Notification
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)
sourcepub fn action(&mut self, identifier: &str, label: &str) -> &mut Notification
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)
sourcepub fn id(&mut self, id: u32) -> &mut Notification
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)
sourcepub fn finalize(&self) -> Notification
pub fn finalize(&self) -> Notification
Finalizes a Notification.
Part of the builder pattern, returns a complete copy of the built notification.
sourcepub fn show(&self) -> Result<NotificationHandle>
pub fn show(&self) -> Result<NotificationHandle>
Sends Notification to D-Bus.
Returns a handle to a notification
sourcepub async fn show_async(&self) -> Result<NotificationHandle>
pub async fn show_async(&self) -> Result<NotificationHandle>
Sends Notification to D-Bus.
Returns a handle to a notification
sourcepub async fn show_async_at_bus(
&self,
sub_bus: &str,
) -> Result<NotificationHandle>
pub async fn show_async_at_bus( &self, sub_bus: &str, ) -> Result<NotificationHandle>
Sends Notification to D-Bus.
Returns a handle to a notification
sourcepub fn show_debug(&mut self) -> Result<NotificationHandle>
👎Deprecated: this was never meant to be public API
pub fn show_debug(&mut self) -> Result<NotificationHandle>
Wraps Notification::show()
but prints notification to stdout.
Trait Implementations§
source§impl Debug for NotificationHandle
impl Debug for NotificationHandle
source§impl Deref for NotificationHandle
impl Deref for NotificationHandle
Required for DerefMut
source§type Target = Notification
type Target = Notification
source§fn deref(&self) -> &Notification
fn deref(&self) -> &Notification
source§impl DerefMut for NotificationHandle
impl DerefMut for NotificationHandle
Allow you to easily modify notification properties