gtk4/auto/shortcut_controller.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, Buildable, EventController, Shortcut, ShortcutScope};
6use glib::{
7 prelude::*,
8 signal::{connect_raw, SignalHandlerId},
9 translate::*,
10};
11use std::boxed::Box as Box_;
12
13glib::wrapper! {
14 /// [`ShortcutController`][crate::ShortcutController] is an event controller that manages shortcuts.
15 ///
16 /// Most common shortcuts are using this controller implicitly, e.g. by
17 /// adding a mnemonic underline to a [`Label`][crate::Label], or by installing a key
18 /// binding using [`WidgetClassExt::add_binding()`][crate::subclass::prelude::WidgetClassExt::add_binding()], or by adding accelerators
19 /// to global actions using [`GtkApplicationExt::set_accels_for_action()`][crate::prelude::GtkApplicationExt::set_accels_for_action()].
20 ///
21 /// But it is possible to create your own shortcut controller, and add
22 /// shortcuts to it.
23 ///
24 /// [`ShortcutController`][crate::ShortcutController] implements [`gio::ListModel`][crate::gio::ListModel] for querying the
25 /// shortcuts that have been added to it.
26 ///
27 /// # GtkShortcutController as GtkBuildable
28 ///
29 /// [`ShortcutController`][crate::ShortcutController]s can be created in [`Builder`][crate::Builder] ui files, to set up
30 /// shortcuts in the same place as the widgets.
31 ///
32 /// An example of a UI definition fragment with [`ShortcutController`][crate::ShortcutController]:
33 /// ```xml
34 /// <object class='GtkButton'>
35 /// <child>
36 /// <object class='GtkShortcutController'>
37 /// <property name='scope'>managed</property>
38 /// <child>
39 /// <object class='GtkShortcut'>
40 /// <property name='trigger'><Control>k</property>
41 /// <property name='action'>activate</property>
42 /// </object>
43 /// </child>
44 /// </object>
45 /// </child>
46 /// </object>
47 /// ```
48 ///
49 /// This example creates a [`ActivateAction`][crate::ActivateAction] for triggering the
50 /// `activate` signal of the [`Button`][crate::Button]. See [`ShortcutAction::parse_string()`][crate::ShortcutAction::parse_string()]
51 /// for the syntax for other kinds of [`ShortcutAction`][crate::ShortcutAction]. See
52 /// [`ShortcutTrigger::parse_string()`][crate::ShortcutTrigger::parse_string()] to learn more about the syntax
53 /// for triggers.
54 ///
55 /// ## Properties
56 ///
57 ///
58 /// #### `item-type`
59 /// The type of items. See [`ListModelExtManual::item_type()`][crate::gio::prelude::ListModelExtManual::item_type()].
60 ///
61 /// Readable
62 ///
63 ///
64 /// #### `mnemonic-modifiers`
65 /// The modifiers that need to be pressed to allow mnemonics activation.
66 ///
67 /// Readable | Writeable
68 ///
69 ///
70 /// #### `model`
71 /// A list model to take shortcuts from.
72 ///
73 /// Writeable | Construct Only
74 ///
75 ///
76 /// #### `n-items`
77 /// The number of items. See [`ListModelExtManual::n_items()`][crate::gio::prelude::ListModelExtManual::n_items()].
78 ///
79 /// Readable
80 ///
81 ///
82 /// #### `scope`
83 /// What scope the shortcuts will be handled in.
84 ///
85 /// Readable | Writeable
86 /// <details><summary><h4>EventController</h4></summary>
87 ///
88 ///
89 /// #### `name`
90 /// The name for this controller, typically used for debugging purposes.
91 ///
92 /// Readable | Writeable
93 ///
94 ///
95 /// #### `propagation-limit`
96 /// The limit for which events this controller will handle.
97 ///
98 /// Readable | Writeable
99 ///
100 ///
101 /// #### `propagation-phase`
102 /// The propagation phase at which this controller will handle events.
103 ///
104 /// Readable | Writeable
105 ///
106 ///
107 /// #### `widget`
108 /// The widget receiving the `GdkEvents` that the controller will handle.
109 ///
110 /// Readable
111 /// </details>
112 ///
113 /// # Implements
114 ///
115 /// [`EventControllerExt`][trait@crate::prelude::EventControllerExt], [`trait@glib::ObjectExt`], [`trait@gio::prelude::ListModelExt`], [`BuildableExt`][trait@crate::prelude::BuildableExt]
116 #[doc(alias = "GtkShortcutController")]
117 pub struct ShortcutController(Object<ffi::GtkShortcutController, ffi::GtkShortcutControllerClass>) @extends EventController, @implements gio::ListModel, Buildable;
118
119 match fn {
120 type_ => || ffi::gtk_shortcut_controller_get_type(),
121 }
122}
123
124impl ShortcutController {
125 /// Creates a new shortcut controller.
126 ///
127 /// # Returns
128 ///
129 /// a newly created shortcut controller
130 #[doc(alias = "gtk_shortcut_controller_new")]
131 pub fn new() -> ShortcutController {
132 assert_initialized_main_thread!();
133 unsafe { EventController::from_glib_full(ffi::gtk_shortcut_controller_new()).unsafe_cast() }
134 }
135
136 /// Creates a new shortcut controller that takes its shortcuts from
137 /// the given list model.
138 ///
139 /// A controller created by this function does not let you add or
140 /// remove individual shortcuts using the shortcut controller api,
141 /// but you can change the contents of the model.
142 /// ## `model`
143 /// a `GListModel` containing shortcuts
144 ///
145 /// # Returns
146 ///
147 /// a newly created shortcut controller
148 #[doc(alias = "gtk_shortcut_controller_new_for_model")]
149 #[doc(alias = "new_for_model")]
150 pub fn for_model(model: &impl IsA<gio::ListModel>) -> ShortcutController {
151 assert_initialized_main_thread!();
152 unsafe {
153 EventController::from_glib_full(ffi::gtk_shortcut_controller_new_for_model(
154 model.as_ref().to_glib_none().0,
155 ))
156 .unsafe_cast()
157 }
158 }
159
160 /// Adds @shortcut to the list of shortcuts handled by @self.
161 ///
162 /// If this controller uses an external shortcut list, this
163 /// function does nothing.
164 /// ## `shortcut`
165 /// a [`Shortcut`][crate::Shortcut]
166 #[doc(alias = "gtk_shortcut_controller_add_shortcut")]
167 pub fn add_shortcut(&self, shortcut: Shortcut) {
168 unsafe {
169 ffi::gtk_shortcut_controller_add_shortcut(
170 self.to_glib_none().0,
171 shortcut.into_glib_ptr(),
172 );
173 }
174 }
175
176 /// Gets the mnemonics modifiers for when this controller activates its shortcuts.
177 ///
178 /// # Returns
179 ///
180 /// the controller's mnemonics modifiers
181 #[doc(alias = "gtk_shortcut_controller_get_mnemonics_modifiers")]
182 #[doc(alias = "get_mnemonics_modifiers")]
183 #[doc(alias = "mnemonic-modifiers")]
184 pub fn mnemonics_modifiers(&self) -> gdk::ModifierType {
185 unsafe {
186 from_glib(ffi::gtk_shortcut_controller_get_mnemonics_modifiers(
187 self.to_glib_none().0,
188 ))
189 }
190 }
191
192 /// Gets the scope for when this controller activates its shortcuts.
193 ///
194 /// See [`set_scope()`][Self::set_scope()] for details.
195 ///
196 /// # Returns
197 ///
198 /// the controller's scope
199 #[doc(alias = "gtk_shortcut_controller_get_scope")]
200 #[doc(alias = "get_scope")]
201 pub fn scope(&self) -> ShortcutScope {
202 unsafe {
203 from_glib(ffi::gtk_shortcut_controller_get_scope(
204 self.to_glib_none().0,
205 ))
206 }
207 }
208
209 /// Removes @shortcut from the list of shortcuts handled by @self.
210 ///
211 /// If @shortcut had not been added to @controller or this controller
212 /// uses an external shortcut list, this function does nothing.
213 /// ## `shortcut`
214 /// a [`Shortcut`][crate::Shortcut]
215 #[doc(alias = "gtk_shortcut_controller_remove_shortcut")]
216 pub fn remove_shortcut(&self, shortcut: &Shortcut) {
217 unsafe {
218 ffi::gtk_shortcut_controller_remove_shortcut(
219 self.to_glib_none().0,
220 shortcut.to_glib_none().0,
221 );
222 }
223 }
224
225 /// Sets the controller to use the given modifier for mnemonics.
226 ///
227 /// The mnemonics modifiers determines which modifiers need to be pressed to allow
228 /// activation of shortcuts with mnemonics triggers.
229 ///
230 /// GTK normally uses the Alt modifier for mnemonics, except in [`PopoverMenu`][crate::PopoverMenu]s,
231 /// where mnemonics can be triggered without any modifiers. It should be very
232 /// rarely necessary to change this, and doing so is likely to interfere with
233 /// other shortcuts.
234 ///
235 /// This value is only relevant for local shortcut controllers. Global and managed
236 /// shortcut controllers will have their shortcuts activated from other places which
237 /// have their own modifiers for activating mnemonics.
238 /// ## `modifiers`
239 /// the new mnemonics_modifiers to use
240 #[doc(alias = "gtk_shortcut_controller_set_mnemonics_modifiers")]
241 #[doc(alias = "mnemonic-modifiers")]
242 pub fn set_mnemonics_modifiers(&self, modifiers: gdk::ModifierType) {
243 unsafe {
244 ffi::gtk_shortcut_controller_set_mnemonics_modifiers(
245 self.to_glib_none().0,
246 modifiers.into_glib(),
247 );
248 }
249 }
250
251 /// Sets the controller to have the given @scope.
252 ///
253 /// The scope allows shortcuts to be activated outside of the normal
254 /// event propagation. In particular, it allows installing global
255 /// keyboard shortcuts that can be activated even when a widget does
256 /// not have focus.
257 ///
258 /// With [`ShortcutScope::Local`][crate::ShortcutScope::Local], shortcuts will only be activated
259 /// when the widget has focus.
260 /// ## `scope`
261 /// the new scope to use
262 #[doc(alias = "gtk_shortcut_controller_set_scope")]
263 #[doc(alias = "scope")]
264 pub fn set_scope(&self, scope: ShortcutScope) {
265 unsafe {
266 ffi::gtk_shortcut_controller_set_scope(self.to_glib_none().0, scope.into_glib());
267 }
268 }
269
270 #[doc(alias = "mnemonic-modifiers")]
271 pub fn connect_mnemonic_modifiers_notify<F: Fn(&Self) + 'static>(
272 &self,
273 f: F,
274 ) -> SignalHandlerId {
275 unsafe extern "C" fn notify_mnemonic_modifiers_trampoline<
276 F: Fn(&ShortcutController) + 'static,
277 >(
278 this: *mut ffi::GtkShortcutController,
279 _param_spec: glib::ffi::gpointer,
280 f: glib::ffi::gpointer,
281 ) {
282 let f: &F = &*(f as *const F);
283 f(&from_glib_borrow(this))
284 }
285 unsafe {
286 let f: Box_<F> = Box_::new(f);
287 connect_raw(
288 self.as_ptr() as *mut _,
289 b"notify::mnemonic-modifiers\0".as_ptr() as *const _,
290 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
291 notify_mnemonic_modifiers_trampoline::<F> as *const (),
292 )),
293 Box_::into_raw(f),
294 )
295 }
296 }
297
298 #[doc(alias = "scope")]
299 pub fn connect_scope_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
300 unsafe extern "C" fn notify_scope_trampoline<F: Fn(&ShortcutController) + 'static>(
301 this: *mut ffi::GtkShortcutController,
302 _param_spec: glib::ffi::gpointer,
303 f: glib::ffi::gpointer,
304 ) {
305 let f: &F = &*(f as *const F);
306 f(&from_glib_borrow(this))
307 }
308 unsafe {
309 let f: Box_<F> = Box_::new(f);
310 connect_raw(
311 self.as_ptr() as *mut _,
312 b"notify::scope\0".as_ptr() as *const _,
313 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
314 notify_scope_trampoline::<F> as *const (),
315 )),
316 Box_::into_raw(f),
317 )
318 }
319 }
320}
321
322impl Default for ShortcutController {
323 fn default() -> Self {
324 Self::new()
325 }
326}