gio/auto/notification.rs
1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, Icon, NotificationPriority};
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9 /// `GNotification` is a mechanism for creating a notification to be shown
10 /// to the user — typically as a pop-up notification presented by the
11 /// desktop environment shell.
12 ///
13 /// The key difference between `GNotification` and other similar APIs is
14 /// that, if supported by the desktop environment, notifications sent
15 /// with `GNotification` will persist after the application has exited,
16 /// and even across system reboots.
17 ///
18 /// Since the user may click on a notification while the application is
19 /// not running, applications using `GNotification` should be able to be
20 /// started as a D-Bus service, using [`Application`][crate::Application].
21 ///
22 /// In order for `GNotification` to work, the application must have installed
23 /// a `.desktop` file. For example:
24 /// ```text
25 /// [Desktop Entry]
26 /// Name=Test Application
27 /// Comment=Description of what Test Application does
28 /// Exec=gnome-test-application
29 /// Icon=org.gnome.TestApplication
30 /// Terminal=false
31 /// Type=Application
32 /// Categories=GNOME;GTK;TestApplication Category;
33 /// StartupNotify=true
34 /// DBusActivatable=true
35 /// X-GNOME-UsesNotifications=true
36 /// ```
37 ///
38 /// The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center
39 /// that this application uses notifications, so it can be listed in the
40 /// Control Center’s ‘Notifications’ panel.
41 ///
42 /// The `.desktop` file must be named as `org.gnome.TestApplication.desktop`,
43 /// where `org.gnome.TestApplication` is the ID passed to
44 /// [`Application::new()`][crate::Application::new()].
45 ///
46 /// User interaction with a notification (either the default action, or
47 /// buttons) must be associated with actions on the application (ie:
48 /// `app.` actions). It is not possible to route user interaction
49 /// through the notification itself, because the object will not exist if
50 /// the application is autostarted as a result of a notification being
51 /// clicked.
52 ///
53 /// A notification can be sent with [`ApplicationExt::send_notification()`][crate::prelude::ApplicationExt::send_notification()].
54 ///
55 /// # Implements
56 ///
57 /// [`trait@glib::ObjectExt`]
58 #[doc(alias = "GNotification")]
59 pub struct Notification(Object<ffi::GNotification>);
60
61 match fn {
62 type_ => || ffi::g_notification_get_type(),
63 }
64}
65
66impl Notification {
67 /// Creates a new #GNotification with @title as its title.
68 ///
69 /// After populating @notification with more details, it can be sent to
70 /// the desktop shell with g_application_send_notification(). Changing
71 /// any properties after this call will not have any effect until
72 /// resending @notification.
73 /// ## `title`
74 /// the title of the notification
75 ///
76 /// # Returns
77 ///
78 /// a new #GNotification instance
79 #[doc(alias = "g_notification_new")]
80 pub fn new(title: &str) -> Notification {
81 unsafe { from_glib_full(ffi::g_notification_new(title.to_glib_none().0)) }
82 }
83
84 /// Adds a button to @self that activates the action in
85 /// @detailed_action when clicked. That action must be an
86 /// application-wide action (starting with "app."). If @detailed_action
87 /// contains a target, the action will be activated with that target as
88 /// its parameter.
89 ///
90 /// See g_action_parse_detailed_name() for a description of the format
91 /// for @detailed_action.
92 /// ## `label`
93 /// label of the button
94 /// ## `detailed_action`
95 /// a detailed action name
96 #[doc(alias = "g_notification_add_button")]
97 pub fn add_button(&self, label: &str, detailed_action: &str) {
98 unsafe {
99 ffi::g_notification_add_button(
100 self.to_glib_none().0,
101 label.to_glib_none().0,
102 detailed_action.to_glib_none().0,
103 );
104 }
105 }
106
107 //#[doc(alias = "g_notification_add_button_with_target")]
108 //pub fn add_button_with_target(&self, label: &str, action: &str, target_format: Option<&str>, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
109 // unsafe { TODO: call ffi:g_notification_add_button_with_target() }
110 //}
111
112 /// Adds a button to @self that activates @action when clicked.
113 /// @action must be an application-wide action (it must start with "app.").
114 ///
115 /// If @target is non-[`None`], @action will be activated with @target as
116 /// its parameter.
117 /// ## `label`
118 /// label of the button
119 /// ## `action`
120 /// an action name
121 /// ## `target`
122 /// a #GVariant to use as @action's parameter, or [`None`]
123 #[doc(alias = "g_notification_add_button_with_target_value")]
124 pub fn add_button_with_target_value(
125 &self,
126 label: &str,
127 action: &str,
128 target: Option<&glib::Variant>,
129 ) {
130 unsafe {
131 ffi::g_notification_add_button_with_target_value(
132 self.to_glib_none().0,
133 label.to_glib_none().0,
134 action.to_glib_none().0,
135 target.to_glib_none().0,
136 );
137 }
138 }
139
140 /// Sets the body of @self to @body.
141 /// ## `body`
142 /// the new body for @self, or [`None`]
143 #[doc(alias = "g_notification_set_body")]
144 pub fn set_body(&self, body: Option<&str>) {
145 unsafe {
146 ffi::g_notification_set_body(self.to_glib_none().0, body.to_glib_none().0);
147 }
148 }
149
150 /// Sets the type of @self to @category. Categories have a main
151 /// type like `email`, `im` or `device` and can have a detail separated
152 /// by a `.`, e.g. `im.received` or `email.arrived`. Setting the category
153 /// helps the notification server to select proper feedback to the user.
154 ///
155 /// Standard categories are [listed in the specification](https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html).
156 /// ## `category`
157 /// the category for @self, or [`None`] for no category
158 #[cfg(feature = "v2_70")]
159 #[cfg_attr(docsrs, doc(cfg(feature = "v2_70")))]
160 #[doc(alias = "g_notification_set_category")]
161 pub fn set_category(&self, category: Option<&str>) {
162 unsafe {
163 ffi::g_notification_set_category(self.to_glib_none().0, category.to_glib_none().0);
164 }
165 }
166
167 /// Sets the default action of @self to @detailed_action. This
168 /// action is activated when the notification is clicked on.
169 ///
170 /// The action in @detailed_action must be an application-wide action (it
171 /// must start with "app."). If @detailed_action contains a target, the
172 /// given action will be activated with that target as its parameter.
173 /// See g_action_parse_detailed_name() for a description of the format
174 /// for @detailed_action.
175 ///
176 /// When no default action is set, the application that the notification
177 /// was sent on is activated.
178 /// ## `detailed_action`
179 /// a detailed action name
180 #[doc(alias = "g_notification_set_default_action")]
181 pub fn set_default_action(&self, detailed_action: &str) {
182 unsafe {
183 ffi::g_notification_set_default_action(
184 self.to_glib_none().0,
185 detailed_action.to_glib_none().0,
186 );
187 }
188 }
189
190 //#[doc(alias = "g_notification_set_default_action_and_target")]
191 //pub fn set_default_action_and_target(&self, action: &str, target_format: Option<&str>, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
192 // unsafe { TODO: call ffi:g_notification_set_default_action_and_target() }
193 //}
194
195 /// Sets the default action of @self to @action. This action is
196 /// activated when the notification is clicked on. It must be an
197 /// application-wide action (start with "app.").
198 ///
199 /// If @target is non-[`None`], @action will be activated with @target as
200 /// its parameter. If @target is floating, it will be consumed.
201 ///
202 /// When no default action is set, the application that the notification
203 /// was sent on is activated.
204 /// ## `action`
205 /// an action name
206 /// ## `target`
207 /// a #GVariant to use as @action's parameter, or [`None`]
208 #[doc(alias = "g_notification_set_default_action_and_target_value")]
209 pub fn set_default_action_and_target_value(
210 &self,
211 action: &str,
212 target: Option<&glib::Variant>,
213 ) {
214 unsafe {
215 ffi::g_notification_set_default_action_and_target_value(
216 self.to_glib_none().0,
217 action.to_glib_none().0,
218 target.to_glib_none().0,
219 );
220 }
221 }
222
223 /// Sets the icon of @self to @icon.
224 /// ## `icon`
225 /// the icon to be shown in @self, as a #GIcon
226 #[doc(alias = "g_notification_set_icon")]
227 pub fn set_icon(&self, icon: &impl IsA<Icon>) {
228 unsafe {
229 ffi::g_notification_set_icon(self.to_glib_none().0, icon.as_ref().to_glib_none().0);
230 }
231 }
232
233 /// Sets the priority of @self to @priority. See
234 /// #GNotificationPriority for possible values.
235 /// ## `priority`
236 /// a #GNotificationPriority
237 #[doc(alias = "g_notification_set_priority")]
238 pub fn set_priority(&self, priority: NotificationPriority) {
239 unsafe {
240 ffi::g_notification_set_priority(self.to_glib_none().0, priority.into_glib());
241 }
242 }
243
244 /// Sets the title of @self to @title.
245 /// ## `title`
246 /// the new title for @self
247 #[doc(alias = "g_notification_set_title")]
248 pub fn set_title(&self, title: &str) {
249 unsafe {
250 ffi::g_notification_set_title(self.to_glib_none().0, title.to_glib_none().0);
251 }
252 }
253}