gtk4/auto/
pad_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::{
6    ffi, EventController, PadActionEntry, PadActionType, PropagationLimit, PropagationPhase,
7};
8use glib::{prelude::*, translate::*};
9
10glib::wrapper! {
11    /// Handles input from the pads found in drawing tablets.
12    ///
13    /// Pads are the collection of buttons and tactile sensors often found around
14    /// the stylus-sensitive area.
15    ///
16    /// These buttons and sensors have no implicit meaning, and by default they
17    /// perform no action. [`PadController`][crate::PadController] is provided to map those to
18    /// [`gio::Action`][crate::gio::Action] objects, thus letting the application give them a more
19    /// semantic meaning.
20    ///
21    /// Buttons and sensors are not constrained to triggering a single action,
22    /// some `GDK_SOURCE_TABLET_PAD` devices feature multiple "modes". All these
23    /// input elements have one current mode, which may determine the final action
24    /// being triggered.
25    ///
26    /// Pad devices often divide buttons and sensors into groups. All elements
27    /// in a group share the same current mode, but different groups may have
28    /// different modes. See `Gdk::DevicePad::get_n_groups()` and
29    /// `Gdk::DevicePad::get_group_n_modes()`.
30    ///
31    /// Each of the actions that a given button/strip/ring performs for a given mode
32    /// is defined by a [`PadActionEntry`][crate::PadActionEntry]. It contains an action name that
33    /// will be looked up in the given [`gio::ActionGroup`][crate::gio::ActionGroup] and activated whenever
34    /// the specified input element and mode are triggered.
35    ///
36    /// A simple example of [`PadController`][crate::PadController] usage: Assigning button 1 in all
37    /// modes and pad devices to an "invert-selection" action:
38    ///
39    /// **⚠️ The following code is in c ⚠️**
40    ///
41    /// ```c
42    /// GtkPadActionEntry *pad_actions[] = {
43    ///   { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" },
44    ///   …
45    /// };
46    ///
47    /// …
48    /// action_group = g_simple_action_group_new ();
49    /// action = g_simple_action_new ("pad-actions.invert-selection", NULL);
50    /// g_signal_connect (action, "activate", on_invert_selection_activated, NULL);
51    /// g_action_map_add_action (G_ACTION_MAP (action_group), action);
52    /// …
53    /// pad_controller = gtk_pad_controller_new (action_group, NULL);
54    /// ```
55    ///
56    /// The actions belonging to rings/strips/dials will be activated with a parameter
57    /// of type `G_VARIANT_TYPE_DOUBLE` bearing the value of the given axis, it
58    /// is required that those are made stateful and accepting this `GVariantType`.
59    /// For rings the value is the angle of the ring position in degrees with 0
60    /// facing up. For strips the value is the absolute position on the strip, normalized
61    /// to the [0.0, 1.0] range.
62    /// For dials the value is the relative movement of the dial, normalized so that the
63    /// value 120 represents one logical scroll wheel detent in the positive direction.
64    /// Devices that support high-resolution scrolling may send events with fractions of
65    /// 120 to signify a smaller motion.
66    ///
67    /// ## Properties
68    ///
69    ///
70    /// #### `action-group`
71    ///  The action group of the controller.
72    ///
73    /// Readable | Writeable | Construct Only
74    ///
75    ///
76    /// #### `pad`
77    ///  The pad of the controller.
78    ///
79    /// Readable | Writeable | Construct Only
80    /// <details><summary><h4>EventController</h4></summary>
81    ///
82    ///
83    /// #### `name`
84    ///  The name for this controller, typically used for debugging purposes.
85    ///
86    /// Readable | Writeable
87    ///
88    ///
89    /// #### `propagation-limit`
90    ///  The limit for which events this controller will handle.
91    ///
92    /// Readable | Writeable
93    ///
94    ///
95    /// #### `propagation-phase`
96    ///  The propagation phase at which this controller will handle events.
97    ///
98    /// Readable | Writeable
99    ///
100    ///
101    /// #### `widget`
102    ///  The widget receiving the `GdkEvents` that the controller will handle.
103    ///
104    /// Readable
105    /// </details>
106    ///
107    /// # Implements
108    ///
109    /// [`EventControllerExt`][trait@crate::prelude::EventControllerExt], [`trait@glib::ObjectExt`], [`EventControllerExtManual`][trait@crate::prelude::EventControllerExtManual]
110    #[doc(alias = "GtkPadController")]
111    pub struct PadController(Object<ffi::GtkPadController, ffi::GtkPadControllerClass>) @extends EventController;
112
113    match fn {
114        type_ => || ffi::gtk_pad_controller_get_type(),
115    }
116}
117
118impl PadController {
119    /// Creates a new [`PadController`][crate::PadController] that will associate events from @pad to
120    /// actions.
121    ///
122    /// A [`None`] pad may be provided so the controller manages all pad devices
123    /// generically, it is discouraged to mix [`PadController`][crate::PadController] objects with
124    /// [`None`] and non-[`None`] @pad argument on the same toplevel window, as execution
125    /// order is not guaranteed.
126    ///
127    /// The [`PadController`][crate::PadController] is created with no mapped actions. In order to
128    /// map pad events to actions, use [`set_action_entries()`][Self::set_action_entries()]
129    /// or [`set_action()`][Self::set_action()].
130    ///
131    /// Be aware that pad events will only be delivered to [`Window`][crate::Window]s, so adding
132    /// a pad controller to any other type of widget will not have an effect.
133    /// ## `group`
134    /// `GActionGroup` to trigger actions from
135    /// ## `pad`
136    /// A `GDK_SOURCE_TABLET_PAD` device, or [`None`] to handle all pads
137    ///
138    /// # Returns
139    ///
140    /// A newly created [`PadController`][crate::PadController]
141    #[doc(alias = "gtk_pad_controller_new")]
142    pub fn new(group: &impl IsA<gio::ActionGroup>, pad: Option<&gdk::Device>) -> PadController {
143        assert_initialized_main_thread!();
144        unsafe {
145            from_glib_full(ffi::gtk_pad_controller_new(
146                group.as_ref().to_glib_none().0,
147                pad.to_glib_none().0,
148            ))
149        }
150    }
151
152    // rustdoc-stripper-ignore-next
153    /// Creates a new builder-pattern struct instance to construct [`PadController`] objects.
154    ///
155    /// This method returns an instance of [`PadControllerBuilder`](crate::builders::PadControllerBuilder) which can be used to create [`PadController`] objects.
156    pub fn builder() -> PadControllerBuilder {
157        PadControllerBuilder::new()
158    }
159
160    /// Adds an individual action to @self.
161    ///
162    /// This action will only be activated if the given button/ring/strip number
163    /// in @index is interacted while the current mode is @mode. -1 may be used
164    /// for simple cases, so the action is triggered on all modes.
165    ///
166    /// The given @label should be considered user-visible, so internationalization
167    /// rules apply. Some windowing systems may be able to use those for user
168    /// feedback.
169    /// ## `type_`
170    /// the type of pad feature that will trigger this action
171    /// ## `index`
172    /// the 0-indexed button/ring/strip number that will trigger this action
173    /// ## `mode`
174    /// the mode that will trigger this action, or -1 for all modes.
175    /// ## `label`
176    /// Human readable description of this action, this string should
177    ///   be deemed user-visible.
178    /// ## `action_name`
179    /// action name that will be activated in the `GActionGroup`
180    #[doc(alias = "gtk_pad_controller_set_action")]
181    pub fn set_action(
182        &self,
183        type_: PadActionType,
184        index: i32,
185        mode: i32,
186        label: &str,
187        action_name: &str,
188    ) {
189        unsafe {
190            ffi::gtk_pad_controller_set_action(
191                self.to_glib_none().0,
192                type_.into_glib(),
193                index,
194                mode,
195                label.to_glib_none().0,
196                action_name.to_glib_none().0,
197            );
198        }
199    }
200
201    /// A convenience function to add a group of action entries on
202    /// @self.
203    ///
204    /// See [`PadActionEntry`][crate::PadActionEntry] and [`set_action()`][Self::set_action()].
205    /// ## `entries`
206    /// the action entries to set on @self
207    #[doc(alias = "gtk_pad_controller_set_action_entries")]
208    pub fn set_action_entries(&self, entries: &[PadActionEntry]) {
209        let n_entries = entries.len() as _;
210        unsafe {
211            ffi::gtk_pad_controller_set_action_entries(
212                self.to_glib_none().0,
213                entries.to_glib_none().0,
214                n_entries,
215            );
216        }
217    }
218
219    /// The action group of the controller.
220    #[doc(alias = "action-group")]
221    pub fn action_group(&self) -> Option<gio::ActionGroup> {
222        ObjectExt::property(self, "action-group")
223    }
224
225    /// The pad of the controller.
226    pub fn pad(&self) -> Option<gdk::Device> {
227        ObjectExt::property(self, "pad")
228    }
229}
230
231impl Default for PadController {
232    fn default() -> Self {
233        glib::object::Object::new::<Self>()
234    }
235}
236
237// rustdoc-stripper-ignore-next
238/// A [builder-pattern] type to construct [`PadController`] objects.
239///
240/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
241#[must_use = "The builder must be built to be used"]
242pub struct PadControllerBuilder {
243    builder: glib::object::ObjectBuilder<'static, PadController>,
244}
245
246impl PadControllerBuilder {
247    fn new() -> Self {
248        Self {
249            builder: glib::object::Object::builder(),
250        }
251    }
252
253    /// The action group of the controller.
254    pub fn action_group(self, action_group: &impl IsA<gio::ActionGroup>) -> Self {
255        Self {
256            builder: self
257                .builder
258                .property("action-group", action_group.clone().upcast()),
259        }
260    }
261
262    /// The pad of the controller.
263    pub fn pad(self, pad: &gdk::Device) -> Self {
264        Self {
265            builder: self.builder.property("pad", pad.clone()),
266        }
267    }
268
269    /// The name for this controller, typically used for debugging purposes.
270    pub fn name(self, name: impl Into<glib::GString>) -> Self {
271        Self {
272            builder: self.builder.property("name", name.into()),
273        }
274    }
275
276    /// The limit for which events this controller will handle.
277    pub fn propagation_limit(self, propagation_limit: PropagationLimit) -> Self {
278        Self {
279            builder: self
280                .builder
281                .property("propagation-limit", propagation_limit),
282        }
283    }
284
285    /// The propagation phase at which this controller will handle events.
286    pub fn propagation_phase(self, propagation_phase: PropagationPhase) -> Self {
287        Self {
288            builder: self
289                .builder
290                .property("propagation-phase", propagation_phase),
291        }
292    }
293
294    // rustdoc-stripper-ignore-next
295    /// Build the [`PadController`].
296    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
297    pub fn build(self) -> PadController {
298        assert_initialized_main_thread!();
299        self.builder.build()
300    }
301}
gtk4/auto/pad_controller.rs

gtk4/auto/
pad_controller.rs
