gio/auto/

notification.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{Icon, NotificationPriority, ffi};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// `GNotification` is a mechanism for creating a notification to be shown
    /// to the user — typically as a pop-up notification presented by the
    /// desktop environment shell.
    ///
    /// The key difference between `GNotification` and other similar APIs is
    /// that, if supported by the desktop environment, notifications sent
    /// with `GNotification` will persist after the application has exited,
    /// and even across system reboots.
    ///
    /// Since the user may click on a notification while the application is
    /// not running, applications using `GNotification` should be able to be
    /// started as a D-Bus service, using [`Application`][crate::Application].
    ///
    /// In order for `GNotification` to work, the application must have installed
    /// a `.desktop` file. For example:
    /// ```text
    /// [Desktop Entry]
    /// Name=Test Application
    /// Comment=Description of what Test Application does
    /// Exec=gnome-test-application
    /// Icon=org.gnome.TestApplication
    /// Terminal=false
    /// Type=Application
    /// Categories=GNOME;GTK;TestApplication Category;
    /// StartupNotify=true
    /// DBusActivatable=true
    /// X-GNOME-UsesNotifications=true
    /// ```
    ///
    /// The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center
    /// that this application uses notifications, so it can be listed in the
    /// Control Center’s ‘Notifications’ panel.
    ///
    /// The `.desktop` file must be named as `org.gnome.TestApplication.desktop`,
    /// where `org.gnome.TestApplication` is the ID passed to
    /// [`Application::new()`][crate::Application::new()].
    ///
    /// User interaction with a notification (either the default action, or
    /// buttons) must be associated with actions on the application (ie:
    /// `app.` actions).  It is not possible to route user interaction
    /// through the notification itself, because the object will not exist if
    /// the application is autostarted as a result of a notification being
    /// clicked.
    ///
    /// A notification can be sent with [`ApplicationExt::send_notification()`][crate::prelude::ApplicationExt::send_notification()].
    ///
    /// In Windows, notification actions are unsupported, when sending the notification
    /// a warning will be printed if a default action or action buttons were added.
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`]
    #[doc(alias = "GNotification")]
    pub struct Notification(Object<ffi::GNotification>);

    match fn {
        type_ => || ffi::g_notification_get_type(),
    }
}

impl Notification {
    /// Creates a new #GNotification with @title as its title.
    ///
    /// After populating @notification with more details, it can be sent to
    /// the desktop shell with g_application_send_notification(). Changing
    /// any properties after this call will not have any effect until
    /// resending @notification.
    /// ## `title`
    /// the title of the notification
    ///
    /// # Returns
    ///
    /// a new #GNotification instance
    #[doc(alias = "g_notification_new")]
    pub fn new(title: &str) -> Notification {
        unsafe { from_glib_full(ffi::g_notification_new(title.to_glib_none().0)) }
    }

    /// Adds a button to @self that activates the action in
    /// @detailed_action when clicked. That action must be an
    /// application-wide action (starting with "app."). If @detailed_action
    /// contains a target, the action will be activated with that target as
    /// its parameter.
    ///
    /// See g_action_parse_detailed_name() for a description of the format
    /// for @detailed_action.
    /// ## `label`
    /// label of the button
    /// ## `detailed_action`
    /// a detailed action name
    #[doc(alias = "g_notification_add_button")]
    pub fn add_button(&self, label: &str, detailed_action: &str) {
        unsafe {
            ffi::g_notification_add_button(
                self.to_glib_none().0,
                label.to_glib_none().0,
                detailed_action.to_glib_none().0,
            );
        }
    }

    //#[doc(alias = "g_notification_add_button_with_target")]
    //pub fn add_button_with_target(&self, label: &str, action: &str, target_format: Option<&str>, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
    //    unsafe { TODO: call ffi:g_notification_add_button_with_target() }
    //}

    /// Adds a button to @self that activates @action when clicked.
    /// @action must be an application-wide action (it must start with "app.").
    ///
    /// If @target is non-[`None`], @action will be activated with @target as
    /// its parameter.
    /// ## `label`
    /// label of the button
    /// ## `action`
    /// an action name
    /// ## `target`
    /// a #GVariant to use as @action's parameter, or [`None`]
    #[doc(alias = "g_notification_add_button_with_target_value")]
    pub fn add_button_with_target_value(
        &self,
        label: &str,
        action: &str,
        target: Option<&glib::Variant>,
    ) {
        unsafe {
            ffi::g_notification_add_button_with_target_value(
                self.to_glib_none().0,
                label.to_glib_none().0,
                action.to_glib_none().0,
                target.to_glib_none().0,
            );
        }
    }

    /// Sets the body of @self to @body.
    /// ## `body`
    /// the new body for @self, or [`None`]
    #[doc(alias = "g_notification_set_body")]
    pub fn set_body(&self, body: Option<&str>) {
        unsafe {
            ffi::g_notification_set_body(self.to_glib_none().0, body.to_glib_none().0);
        }
    }

    /// Sets the type of @self to @category. Categories have a main
    /// type like `email`, `im` or `device` and can have a detail separated
    /// by a `.`, e.g. `im.received` or `email.arrived`. Setting the category
    /// helps the notification server to select proper feedback to the user.
    ///
    /// Standard categories are [listed in the specification](https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html).
    /// ## `category`
    /// the category for @self, or [`None`] for no category
    #[cfg(feature = "v2_70")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_70")))]
    #[doc(alias = "g_notification_set_category")]
    pub fn set_category(&self, category: Option<&str>) {
        unsafe {
            ffi::g_notification_set_category(self.to_glib_none().0, category.to_glib_none().0);
        }
    }

    /// Sets the default action of @self to @detailed_action. This
    /// action is activated when the notification is clicked on.
    ///
    /// The action in @detailed_action must be an application-wide action (it
    /// must start with "app."). If @detailed_action contains a target, the
    /// given action will be activated with that target as its parameter.
    /// See g_action_parse_detailed_name() for a description of the format
    /// for @detailed_action.
    ///
    /// When no default action is set, the application that the notification
    /// was sent on is activated.
    /// ## `detailed_action`
    /// a detailed action name
    #[doc(alias = "g_notification_set_default_action")]
    pub fn set_default_action(&self, detailed_action: &str) {
        unsafe {
            ffi::g_notification_set_default_action(
                self.to_glib_none().0,
                detailed_action.to_glib_none().0,
            );
        }
    }

    //#[doc(alias = "g_notification_set_default_action_and_target")]
    //pub fn set_default_action_and_target(&self, action: &str, target_format: Option<&str>, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
    //    unsafe { TODO: call ffi:g_notification_set_default_action_and_target() }
    //}

    /// Sets the default action of @self to @action. This action is
    /// activated when the notification is clicked on. It must be an
    /// application-wide action (start with "app.").
    ///
    /// If @target is non-[`None`], @action will be activated with @target as
    /// its parameter. If @target is floating, it will be consumed.
    ///
    /// When no default action is set, the application that the notification
    /// was sent on is activated.
    /// ## `action`
    /// an action name
    /// ## `target`
    /// a #GVariant to use as @action's parameter, or [`None`]
    #[doc(alias = "g_notification_set_default_action_and_target_value")]
    pub fn set_default_action_and_target_value(
        &self,
        action: &str,
        target: Option<&glib::Variant>,
    ) {
        unsafe {
            ffi::g_notification_set_default_action_and_target_value(
                self.to_glib_none().0,
                action.to_glib_none().0,
                target.to_glib_none().0,
            );
        }
    }

    /// Sets the icon of @self to @icon.
    /// ## `icon`
    /// the icon to be shown in @self, as a #GIcon
    #[doc(alias = "g_notification_set_icon")]
    pub fn set_icon(&self, icon: &impl IsA<Icon>) {
        unsafe {
            ffi::g_notification_set_icon(self.to_glib_none().0, icon.as_ref().to_glib_none().0);
        }
    }

    /// Sets the priority of @self to @priority. See
    /// #GNotificationPriority for possible values.
    /// ## `priority`
    /// a #GNotificationPriority
    #[doc(alias = "g_notification_set_priority")]
    pub fn set_priority(&self, priority: NotificationPriority) {
        unsafe {
            ffi::g_notification_set_priority(self.to_glib_none().0, priority.into_glib());
        }
    }

    /// Sets the title of @self to @title.
    /// ## `title`
    /// the new title for @self
    #[doc(alias = "g_notification_set_title")]
    pub fn set_title(&self, title: &str) {
        unsafe {
            ffi::g_notification_set_title(self.to_glib_none().0, title.to_glib_none().0);
        }
    }
}