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 {}