glib/gobject/auto/
signal_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, prelude::*, translate::*, Object};
6
7crate::wrapper! {
8    /// `GSignalGroup` manages a collection of signals on a `GObject`.
9    ///
10    /// `GSignalGroup` simplifies the process of connecting many signals to a `GObject`
11    /// as a group. As such there is no API to disconnect a signal from the group.
12    ///
13    /// In particular, this allows you to:
14    ///
15    ///  - Change the target instance, which automatically causes disconnection
16    ///  of the signals from the old instance and connecting to the new instance.
17    ///  - Block and unblock signals as a group
18    ///  - Ensuring that blocked state transfers across target instances.
19    ///
20    /// One place you might want to use such a structure is with `GtkTextView` and
21    /// `GtkTextBuffer`. Often times, you'll need to connect to many signals on
22    /// `GtkTextBuffer` from a `GtkTextView` subclass. This allows you to create a
23    /// signal group during instance construction, simply bind the
24    /// `GtkTextView:buffer` property to `GSignalGroup:target` and connect
25    /// all the signals you need. When the `GtkTextView:buffer` property changes
26    /// all of the signals will be transitioned correctly.
27    ///
28    /// ## Properties
29    ///
30    ///
31    /// #### `target`
32    ///  The target instance used when connecting signals.
33    ///
34    /// Readable | Writeable
35    ///
36    ///
37    /// #### `target-type`
38    ///  The `GType` of the target property.
39    ///
40    /// Readable | Writeable | Construct Only
41    ///
42    /// ## Signals
43    ///
44    ///
45    /// #### `bind`
46    ///  This signal is emitted when [`target`][struct@crate::SignalGroup#target] is set to a new value
47    /// other than [`None`]. It is similar to [`notify`][struct@crate::Object#notify] on `target` except it
48    /// will not emit when [`target`][struct@crate::SignalGroup#target] is [`None`] and also allows for
49    /// receiving the [`Object`][crate::Object] without a data-race.
50    ///
51    ///
52    ///
53    ///
54    /// #### `unbind`
55    ///  This signal is emitted when the target instance of `self_` is set to a
56    /// new [`Object`][crate::Object].
57    ///
58    /// This signal will only be emitted if the previous target of `self_` is
59    /// non-[`None`].
60    ///
61    ///
62    ///
63    /// # Implements
64    ///
65    /// [`ObjectExt`][trait@crate::prelude::ObjectExt]
66    #[doc(alias = "GSignalGroup")]
67    pub struct SignalGroup(Object<crate::gobject_ffi::GSignalGroup>);
68
69    match fn {
70        type_ => || crate::gobject_ffi::g_signal_group_get_type(),
71    }
72}
73
74impl SignalGroup {
75    /// Creates a new [`SignalGroup`][crate::SignalGroup] for target instances of `target_type`.
76    /// ## `target_type`
77    /// the `GType` of the target instance.
78    ///
79    /// # Returns
80    ///
81    /// a new [`SignalGroup`][crate::SignalGroup]
82    #[doc(alias = "g_signal_group_new")]
83    #[doc(alias = "new")]
84    pub fn with_type(target_type: crate::types::Type) -> SignalGroup {
85        unsafe {
86            from_glib_full(crate::gobject_ffi::g_signal_group_new(
87                target_type.into_glib(),
88            ))
89        }
90    }
91
92    /// Blocks all signal handlers managed by `self` so they will not
93    /// be called during any signal emissions. Must be unblocked exactly
94    /// the same number of times it has been blocked to become active again.
95    ///
96    /// This blocked state will be kept across changes of the target instance.
97    #[doc(alias = "g_signal_group_block")]
98    pub fn block(&self) {
99        unsafe {
100            crate::gobject_ffi::g_signal_group_block(self.to_glib_none().0);
101        }
102    }
103
104    /// Gets the target instance used when connecting signals.
105    ///
106    /// # Returns
107    ///
108    /// The target instance
109    #[doc(alias = "g_signal_group_dup_target")]
110    #[doc(alias = "dup_target")]
111    pub fn target(&self) -> Option<Object> {
112        unsafe {
113            from_glib_full(crate::gobject_ffi::g_signal_group_dup_target(
114                self.to_glib_none().0,
115            ))
116        }
117    }
118
119    /// Sets the target instance used when connecting signals. Any signal
120    /// that has been registered with `g_signal_group_connect_object()` or
121    /// similar functions will be connected to this object.
122    ///
123    /// If the target instance was previously set, signals will be
124    /// disconnected from that object prior to connecting to `target`.
125    /// ## `target`
126    /// The target instance used
127    ///  when connecting signals.
128    #[doc(alias = "g_signal_group_set_target")]
129    #[doc(alias = "target")]
130    pub fn set_target(&self, target: Option<&impl IsA<Object>>) {
131        unsafe {
132            crate::gobject_ffi::g_signal_group_set_target(
133                self.to_glib_none().0,
134                target.map(|p| p.as_ref()).to_glib_none().0,
135            );
136        }
137    }
138
139    /// Unblocks all signal handlers managed by `self` so they will be
140    /// called again during any signal emissions unless it is blocked
141    /// again. Must be unblocked exactly the same number of times it
142    /// has been blocked to become active again.
143    #[doc(alias = "g_signal_group_unblock")]
144    pub fn unblock(&self) {
145        unsafe {
146            crate::gobject_ffi::g_signal_group_unblock(self.to_glib_none().0);
147        }
148    }
149
150    /// The `GType` of the target property.
151    #[cfg(feature = "v2_72")]
152    #[cfg_attr(docsrs, doc(cfg(feature = "v2_72")))]
153    #[doc(alias = "target-type")]
154    pub fn target_type(&self) -> crate::types::Type {
155        ObjectExt::property(self, "target-type")
156    }
157}
158
159unsafe impl Send for SignalGroup {}
160unsafe impl Sync for SignalGroup {}