gio/auto/action_group.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;
6use glib::{
7 object::ObjectType as _,
8 prelude::*,
9 signal::{connect_raw, SignalHandlerId},
10 translate::*,
11};
12use std::boxed::Box as Box_;
13
14glib::wrapper! {
15 /// `GActionGroup` represents a group of actions.
16 ///
17 /// Actions can be used to expose functionality in a structured way, either
18 /// from one part of a program to another, or to the outside world. Action
19 /// groups are often used together with a [type@Gio.MenuModel] that provides additional
20 /// representation data for displaying the actions to the user, e.g. in a menu.
21 ///
22 /// The main way to interact with the actions in a `GActionGroup` is to
23 /// activate them with [`ActionGroupExt::activate_action()`][crate::prelude::ActionGroupExt::activate_action()]. Activating an
24 /// action may require a [type@GLib.Variant] parameter. The required type of the
25 /// parameter can be inquired with [`ActionGroupExt::action_parameter_type()`][crate::prelude::ActionGroupExt::action_parameter_type()].
26 /// Actions may be disabled, see [`ActionGroupExt::is_action_enabled()`][crate::prelude::ActionGroupExt::is_action_enabled()].
27 /// Activating a disabled action has no effect.
28 ///
29 /// Actions may optionally have a state in the form of a [type@GLib.Variant]. The current
30 /// state of an action can be inquired with [`ActionGroupExt::action_state()`][crate::prelude::ActionGroupExt::action_state()].
31 /// Activating a stateful action may change its state, but it is also possible to
32 /// set the state by calling [`ActionGroupExt::change_action_state()`][crate::prelude::ActionGroupExt::change_action_state()].
33 ///
34 /// As typical example, consider a text editing application which has an
35 /// option to change the current font to ‘bold’. A good way to represent
36 /// this would be a stateful action, with a boolean state. Activating the
37 /// action would toggle the state.
38 ///
39 /// Each action in the group has a unique name (which is a string). All
40 /// method calls, except [`ActionGroupExt::list_actions()`][crate::prelude::ActionGroupExt::list_actions()] take the name of
41 /// an action as an argument.
42 ///
43 /// The `GActionGroup` API is meant to be the ‘public’ API to the action
44 /// group. The calls here are exactly the interaction that ‘external
45 /// forces’ (eg: UI, incoming D-Bus messages, etc.) are supposed to have
46 /// with actions. ‘Internal’ APIs (ie: ones meant only to be accessed by
47 /// the action group implementation) are found on subclasses. This is
48 /// why you will find – for example – [`ActionGroupExt::is_action_enabled()`][crate::prelude::ActionGroupExt::is_action_enabled()]
49 /// but not an equivalent `set_action_enabled()` method.
50 ///
51 /// Signals are emitted on the action group in response to state changes
52 /// on individual actions.
53 ///
54 /// Implementations of `GActionGroup` should provide implementations for
55 /// the virtual functions [`ActionGroupExt::list_actions()`][crate::prelude::ActionGroupExt::list_actions()] and
56 /// `Gio::ActionGroup::query_action()`. The other virtual functions should
57 /// not be implemented — their ‘wrappers’ are actually implemented with
58 /// calls to `Gio::ActionGroup::query_action()`.
59 ///
60 /// ## Signals
61 ///
62 ///
63 /// #### `action-added`
64 /// Signals that a new action was just added to the group.
65 ///
66 /// This signal is emitted after the action has been added
67 /// and is now visible.
68 ///
69 /// Detailed
70 ///
71 ///
72 /// #### `action-enabled-changed`
73 /// Signals that the enabled status of the named action has changed.
74 ///
75 /// Detailed
76 ///
77 ///
78 /// #### `action-removed`
79 /// Signals that an action is just about to be removed from the group.
80 ///
81 /// This signal is emitted before the action is removed, so the action
82 /// is still visible and can be queried from the signal handler.
83 ///
84 /// Detailed
85 ///
86 ///
87 /// #### `action-state-changed`
88 /// Signals that the state of the named action has changed.
89 ///
90 /// Detailed
91 ///
92 /// # Implements
93 ///
94 /// [`ActionGroupExt`][trait@crate::prelude::ActionGroupExt]
95 #[doc(alias = "GActionGroup")]
96 pub struct ActionGroup(Interface<ffi::GActionGroup, ffi::GActionGroupInterface>);
97
98 match fn {
99 type_ => || ffi::g_action_group_get_type(),
100 }
101}
102
103impl ActionGroup {
104 pub const NONE: Option<&'static ActionGroup> = None;
105}
106
107mod sealed {
108 pub trait Sealed {}
109 impl<T: super::IsA<super::ActionGroup>> Sealed for T {}
110}
111
112/// Trait containing all [`struct@ActionGroup`] methods.
113///
114/// # Implementors
115///
116/// [`ActionGroup`][struct@crate::ActionGroup], [`Application`][struct@crate::Application], [`DBusActionGroup`][struct@crate::DBusActionGroup], [`RemoteActionGroup`][struct@crate::RemoteActionGroup], [`SimpleActionGroup`][struct@crate::SimpleActionGroup]
117pub trait ActionGroupExt: IsA<ActionGroup> + sealed::Sealed + 'static {
118 /// Emits the [`action-added`][struct@crate::ActionGroup#action-added] signal on @self.
119 ///
120 /// This function should only be called by [type@Gio.ActionGroup] implementations.
121 /// ## `action_name`
122 /// the name of an action in the group
123 #[doc(alias = "g_action_group_action_added")]
124 fn action_added(&self, action_name: &str) {
125 unsafe {
126 ffi::g_action_group_action_added(
127 self.as_ref().to_glib_none().0,
128 action_name.to_glib_none().0,
129 );
130 }
131 }
132
133 /// Emits the [`action-enabled-changed`][struct@crate::ActionGroup#action-enabled-changed] signal on @self.
134 ///
135 /// This function should only be called by [type@Gio.ActionGroup] implementations.
136 /// ## `action_name`
137 /// the name of an action in the group
138 /// ## `enabled`
139 /// whether the action is now enabled
140 #[doc(alias = "g_action_group_action_enabled_changed")]
141 fn action_enabled_changed(&self, action_name: &str, enabled: bool) {
142 unsafe {
143 ffi::g_action_group_action_enabled_changed(
144 self.as_ref().to_glib_none().0,
145 action_name.to_glib_none().0,
146 enabled.into_glib(),
147 );
148 }
149 }
150
151 /// Emits the [`action-removed`][struct@crate::ActionGroup#action-removed] signal on @self.
152 ///
153 /// This function should only be called by [type@Gio.ActionGroup] implementations.
154 /// ## `action_name`
155 /// the name of an action in the group
156 #[doc(alias = "g_action_group_action_removed")]
157 fn action_removed(&self, action_name: &str) {
158 unsafe {
159 ffi::g_action_group_action_removed(
160 self.as_ref().to_glib_none().0,
161 action_name.to_glib_none().0,
162 );
163 }
164 }
165
166 /// Emits the [`action-state-changed`][struct@crate::ActionGroup#action-state-changed] signal on @self.
167 ///
168 /// This function should only be called by [type@Gio.ActionGroup] implementations.
169 /// ## `action_name`
170 /// the name of an action in the group
171 /// ## `state`
172 /// the new state of the named action
173 #[doc(alias = "g_action_group_action_state_changed")]
174 fn action_state_changed(&self, action_name: &str, state: &glib::Variant) {
175 unsafe {
176 ffi::g_action_group_action_state_changed(
177 self.as_ref().to_glib_none().0,
178 action_name.to_glib_none().0,
179 state.to_glib_none().0,
180 );
181 }
182 }
183
184 /// Activate the named action within @self.
185 ///
186 /// If the action is expecting a parameter, then the correct type of
187 /// parameter must be given as @parameter. If the action is expecting no
188 /// parameters then @parameter must be `NULL`. See
189 /// [`action_parameter_type()`][Self::action_parameter_type()].
190 ///
191 /// If the [type@Gio.ActionGroup] implementation supports asynchronous remote
192 /// activation over D-Bus, this call may return before the relevant
193 /// D-Bus traffic has been sent, or any replies have been received. In
194 /// order to block on such asynchronous activation calls,
195 /// [`DBusConnection::flush()`][crate::DBusConnection::flush()] should be called prior to the code, which
196 /// depends on the result of the action activation. Without flushing
197 /// the D-Bus connection, there is no guarantee that the action would
198 /// have been activated.
199 ///
200 /// The following code which runs in a remote app instance, shows an
201 /// example of a ‘quit’ action being activated on the primary app
202 /// instance over D-Bus. Here [`DBusConnection::flush()`][crate::DBusConnection::flush()] is called
203 /// before `exit()`. Without `g_dbus_connection_flush()`, the ‘quit’ action
204 /// may fail to be activated on the primary instance.
205 ///
206 /// **⚠️ The following code is in c ⚠️**
207 ///
208 /// ```c
209 /// // call ‘quit’ action on primary instance
210 /// g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
211 ///
212 /// // make sure the action is activated now
213 /// g_dbus_connection_flush (…);
214 ///
215 /// g_debug ("Application has been terminated. Exiting.");
216 ///
217 /// exit (0);
218 /// ```
219 /// ## `action_name`
220 /// the name of the action to activate
221 /// ## `parameter`
222 /// parameters to the activation
223 #[doc(alias = "g_action_group_activate_action")]
224 fn activate_action(&self, action_name: &str, parameter: Option<&glib::Variant>) {
225 unsafe {
226 ffi::g_action_group_activate_action(
227 self.as_ref().to_glib_none().0,
228 action_name.to_glib_none().0,
229 parameter.to_glib_none().0,
230 );
231 }
232 }
233
234 /// Request for the state of the named action within @self to be
235 /// changed to @value.
236 ///
237 /// The action must be stateful and @value must be of the correct type.
238 /// See [`action_state_type()`][Self::action_state_type()].
239 ///
240 /// This call merely requests a change. The action may refuse to change
241 /// its state or may change its state to something other than @value.
242 /// See [`action_state_hint()`][Self::action_state_hint()].
243 ///
244 /// If the @value GVariant is floating, it is consumed.
245 /// ## `action_name`
246 /// the name of the action to request the change on
247 /// ## `value`
248 /// the new state
249 #[doc(alias = "g_action_group_change_action_state")]
250 fn change_action_state(&self, action_name: &str, value: &glib::Variant) {
251 unsafe {
252 ffi::g_action_group_change_action_state(
253 self.as_ref().to_glib_none().0,
254 action_name.to_glib_none().0,
255 value.to_glib_none().0,
256 );
257 }
258 }
259
260 /// Checks if the named action within @self is currently enabled.
261 ///
262 /// An action must be enabled in order to be activated or in order to
263 /// have its state changed from outside callers.
264 /// ## `action_name`
265 /// the name of the action to query
266 ///
267 /// # Returns
268 ///
269 /// whether the action is currently enabled
270 #[doc(alias = "g_action_group_get_action_enabled")]
271 #[doc(alias = "get_action_enabled")]
272 fn is_action_enabled(&self, action_name: &str) -> bool {
273 unsafe {
274 from_glib(ffi::g_action_group_get_action_enabled(
275 self.as_ref().to_glib_none().0,
276 action_name.to_glib_none().0,
277 ))
278 }
279 }
280
281 /// Queries the type of the parameter that must be given when activating
282 /// the named action within @self.
283 ///
284 /// When activating the action using [`activate_action()`][Self::activate_action()],
285 /// the [type@GLib.Variant] given to that function must be of the type returned
286 /// by this function.
287 ///
288 /// In the case that this function returns `NULL`, you must not give any
289 /// [type@GLib.Variant], but `NULL` instead.
290 ///
291 /// The parameter type of a particular action will never change but it is
292 /// possible for an action to be removed and for a new action to be added
293 /// with the same name but a different parameter type.
294 /// ## `action_name`
295 /// the name of the action to query
296 ///
297 /// # Returns
298 ///
299 /// the parameter type
300 #[doc(alias = "g_action_group_get_action_parameter_type")]
301 #[doc(alias = "get_action_parameter_type")]
302 fn action_parameter_type(&self, action_name: &str) -> Option<glib::VariantType> {
303 unsafe {
304 from_glib_none(ffi::g_action_group_get_action_parameter_type(
305 self.as_ref().to_glib_none().0,
306 action_name.to_glib_none().0,
307 ))
308 }
309 }
310
311 /// Queries the current state of the named action within @self.
312 ///
313 /// If the action is not stateful then `NULL` will be returned. If the
314 /// action is stateful then the type of the return value is the type
315 /// given by [`action_state_type()`][Self::action_state_type()].
316 ///
317 /// The return value (if non-`NULL`) should be freed with
318 /// `GLib::Variant::unref()` when it is no longer required.
319 /// ## `action_name`
320 /// the name of the action to query
321 ///
322 /// # Returns
323 ///
324 /// the current state of the action
325 #[doc(alias = "g_action_group_get_action_state")]
326 #[doc(alias = "get_action_state")]
327 fn action_state(&self, action_name: &str) -> Option<glib::Variant> {
328 unsafe {
329 from_glib_full(ffi::g_action_group_get_action_state(
330 self.as_ref().to_glib_none().0,
331 action_name.to_glib_none().0,
332 ))
333 }
334 }
335
336 /// Requests a hint about the valid range of values for the state of the
337 /// named action within @self.
338 ///
339 /// If `NULL` is returned it either means that the action is not stateful
340 /// or that there is no hint about the valid range of values for the
341 /// state of the action.
342 ///
343 /// If a [type@GLib.Variant] array is returned then each item in the array is a
344 /// possible value for the state. If a [type@GLib.Variant] pair (ie: two-tuple) is
345 /// returned then the tuple specifies the inclusive lower and upper bound
346 /// of valid values for the state.
347 ///
348 /// In any case, the information is merely a hint. It may be possible to
349 /// have a state value outside of the hinted range and setting a value
350 /// within the range may fail.
351 ///
352 /// The return value (if non-`NULL`) should be freed with
353 /// `GLib::Variant::unref()` when it is no longer required.
354 /// ## `action_name`
355 /// the name of the action to query
356 ///
357 /// # Returns
358 ///
359 /// the state range hint
360 #[doc(alias = "g_action_group_get_action_state_hint")]
361 #[doc(alias = "get_action_state_hint")]
362 fn action_state_hint(&self, action_name: &str) -> Option<glib::Variant> {
363 unsafe {
364 from_glib_full(ffi::g_action_group_get_action_state_hint(
365 self.as_ref().to_glib_none().0,
366 action_name.to_glib_none().0,
367 ))
368 }
369 }
370
371 /// Queries the type of the state of the named action within
372 /// @self.
373 ///
374 /// If the action is stateful then this function returns the
375 /// [type@GLib.VariantType] of the state. All calls to
376 /// [`change_action_state()`][Self::change_action_state()] must give a [type@GLib.Variant] of this
377 /// type and [`action_state()`][Self::action_state()] will return a [type@GLib.Variant]
378 /// of the same type.
379 ///
380 /// If the action is not stateful then this function will return `NULL`.
381 /// In that case, [`action_state()`][Self::action_state()] will return `NULL`
382 /// and you must not call [`change_action_state()`][Self::change_action_state()].
383 ///
384 /// The state type of a particular action will never change but it is
385 /// possible for an action to be removed and for a new action to be added
386 /// with the same name but a different state type.
387 /// ## `action_name`
388 /// the name of the action to query
389 ///
390 /// # Returns
391 ///
392 /// the state type, if the action is stateful
393 #[doc(alias = "g_action_group_get_action_state_type")]
394 #[doc(alias = "get_action_state_type")]
395 fn action_state_type(&self, action_name: &str) -> Option<glib::VariantType> {
396 unsafe {
397 from_glib_none(ffi::g_action_group_get_action_state_type(
398 self.as_ref().to_glib_none().0,
399 action_name.to_glib_none().0,
400 ))
401 }
402 }
403
404 /// Checks if the named action exists within @self.
405 /// ## `action_name`
406 /// the name of the action to check for
407 ///
408 /// # Returns
409 ///
410 /// whether the named action exists
411 #[doc(alias = "g_action_group_has_action")]
412 fn has_action(&self, action_name: &str) -> bool {
413 unsafe {
414 from_glib(ffi::g_action_group_has_action(
415 self.as_ref().to_glib_none().0,
416 action_name.to_glib_none().0,
417 ))
418 }
419 }
420
421 /// Lists the actions contained within @self.
422 ///
423 /// The caller is responsible for freeing the list with `strfreev()` when
424 /// it is no longer required.
425 ///
426 /// # Returns
427 ///
428 /// a `NULL`-terminated array
429 /// of the names of the actions in the group
430 #[doc(alias = "g_action_group_list_actions")]
431 fn list_actions(&self) -> Vec<glib::GString> {
432 unsafe {
433 FromGlibPtrContainer::from_glib_full(ffi::g_action_group_list_actions(
434 self.as_ref().to_glib_none().0,
435 ))
436 }
437 }
438
439 /// Signals that a new action was just added to the group.
440 ///
441 /// This signal is emitted after the action has been added
442 /// and is now visible.
443 /// ## `action_name`
444 /// the name of the action in @action_group
445 #[doc(alias = "action-added")]
446 fn connect_action_added<F: Fn(&Self, &str) + 'static>(
447 &self,
448 detail: Option<&str>,
449 f: F,
450 ) -> SignalHandlerId {
451 unsafe extern "C" fn action_added_trampoline<
452 P: IsA<ActionGroup>,
453 F: Fn(&P, &str) + 'static,
454 >(
455 this: *mut ffi::GActionGroup,
456 action_name: *mut std::ffi::c_char,
457 f: glib::ffi::gpointer,
458 ) {
459 let f: &F = &*(f as *const F);
460 f(
461 ActionGroup::from_glib_borrow(this).unsafe_cast_ref(),
462 &glib::GString::from_glib_borrow(action_name),
463 )
464 }
465 unsafe {
466 let f: Box_<F> = Box_::new(f);
467 let detailed_signal_name = detail.map(|name| format!("action-added::{name}\0"));
468 let signal_name: &[u8] = detailed_signal_name
469 .as_ref()
470 .map_or(&b"action-added\0"[..], |n| n.as_bytes());
471 connect_raw(
472 self.as_ptr() as *mut _,
473 signal_name.as_ptr() as *const _,
474 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
475 action_added_trampoline::<Self, F> as *const (),
476 )),
477 Box_::into_raw(f),
478 )
479 }
480 }
481
482 /// Signals that the enabled status of the named action has changed.
483 /// ## `action_name`
484 /// the name of the action in @action_group
485 /// ## `enabled`
486 /// whether the action is enabled
487 #[doc(alias = "action-enabled-changed")]
488 fn connect_action_enabled_changed<F: Fn(&Self, &str, bool) + 'static>(
489 &self,
490 detail: Option<&str>,
491 f: F,
492 ) -> SignalHandlerId {
493 unsafe extern "C" fn action_enabled_changed_trampoline<
494 P: IsA<ActionGroup>,
495 F: Fn(&P, &str, bool) + 'static,
496 >(
497 this: *mut ffi::GActionGroup,
498 action_name: *mut std::ffi::c_char,
499 enabled: glib::ffi::gboolean,
500 f: glib::ffi::gpointer,
501 ) {
502 let f: &F = &*(f as *const F);
503 f(
504 ActionGroup::from_glib_borrow(this).unsafe_cast_ref(),
505 &glib::GString::from_glib_borrow(action_name),
506 from_glib(enabled),
507 )
508 }
509 unsafe {
510 let f: Box_<F> = Box_::new(f);
511 let detailed_signal_name =
512 detail.map(|name| format!("action-enabled-changed::{name}\0"));
513 let signal_name: &[u8] = detailed_signal_name
514 .as_ref()
515 .map_or(&b"action-enabled-changed\0"[..], |n| n.as_bytes());
516 connect_raw(
517 self.as_ptr() as *mut _,
518 signal_name.as_ptr() as *const _,
519 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
520 action_enabled_changed_trampoline::<Self, F> as *const (),
521 )),
522 Box_::into_raw(f),
523 )
524 }
525 }
526
527 /// Signals that an action is just about to be removed from the group.
528 ///
529 /// This signal is emitted before the action is removed, so the action
530 /// is still visible and can be queried from the signal handler.
531 /// ## `action_name`
532 /// the name of the action in @action_group
533 #[doc(alias = "action-removed")]
534 fn connect_action_removed<F: Fn(&Self, &str) + 'static>(
535 &self,
536 detail: Option<&str>,
537 f: F,
538 ) -> SignalHandlerId {
539 unsafe extern "C" fn action_removed_trampoline<
540 P: IsA<ActionGroup>,
541 F: Fn(&P, &str) + 'static,
542 >(
543 this: *mut ffi::GActionGroup,
544 action_name: *mut std::ffi::c_char,
545 f: glib::ffi::gpointer,
546 ) {
547 let f: &F = &*(f as *const F);
548 f(
549 ActionGroup::from_glib_borrow(this).unsafe_cast_ref(),
550 &glib::GString::from_glib_borrow(action_name),
551 )
552 }
553 unsafe {
554 let f: Box_<F> = Box_::new(f);
555 let detailed_signal_name = detail.map(|name| format!("action-removed::{name}\0"));
556 let signal_name: &[u8] = detailed_signal_name
557 .as_ref()
558 .map_or(&b"action-removed\0"[..], |n| n.as_bytes());
559 connect_raw(
560 self.as_ptr() as *mut _,
561 signal_name.as_ptr() as *const _,
562 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
563 action_removed_trampoline::<Self, F> as *const (),
564 )),
565 Box_::into_raw(f),
566 )
567 }
568 }
569
570 /// Signals that the state of the named action has changed.
571 /// ## `action_name`
572 /// the name of the action in @action_group
573 /// ## `value`
574 /// the new value of the state
575 #[doc(alias = "action-state-changed")]
576 fn connect_action_state_changed<F: Fn(&Self, &str, &glib::Variant) + 'static>(
577 &self,
578 detail: Option<&str>,
579 f: F,
580 ) -> SignalHandlerId {
581 unsafe extern "C" fn action_state_changed_trampoline<
582 P: IsA<ActionGroup>,
583 F: Fn(&P, &str, &glib::Variant) + 'static,
584 >(
585 this: *mut ffi::GActionGroup,
586 action_name: *mut std::ffi::c_char,
587 value: *mut glib::ffi::GVariant,
588 f: glib::ffi::gpointer,
589 ) {
590 let f: &F = &*(f as *const F);
591 f(
592 ActionGroup::from_glib_borrow(this).unsafe_cast_ref(),
593 &glib::GString::from_glib_borrow(action_name),
594 &from_glib_borrow(value),
595 )
596 }
597 unsafe {
598 let f: Box_<F> = Box_::new(f);
599 let detailed_signal_name = detail.map(|name| format!("action-state-changed::{name}\0"));
600 let signal_name: &[u8] = detailed_signal_name
601 .as_ref()
602 .map_or(&b"action-state-changed\0"[..], |n| n.as_bytes());
603 connect_raw(
604 self.as_ptr() as *mut _,
605 signal_name.as_ptr() as *const _,
606 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
607 action_state_changed_trampoline::<Self, F> as *const (),
608 )),
609 Box_::into_raw(f),
610 )
611 }
612 }
613}
614
615impl<O: IsA<ActionGroup>> ActionGroupExt for O {}