gtk4/auto/
pad_controller.rs

Help
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 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    ///
60    /// ## Properties
61    ///
62    ///
63    /// #### `action-group`
64    ///  The action group of the controller.
65    ///
66    /// Readable | Writeable | Construct Only
67    ///
68    ///
69    /// #### `pad`
70    ///  The pad of the controller.
71    ///
72    /// Readable | Writeable | Construct Only
73    /// <details><summary><h4>EventController</h4></summary>
74    ///
75    ///
76    /// #### `name`
77    ///  The name for this controller, typically used for debugging purposes.
78    ///
79    /// Readable | Writeable
80    ///
81    ///
82    /// #### `propagation-limit`
83    ///  The limit for which events this controller will handle.
84    ///
85    /// Readable | Writeable
86    ///
87    ///
88    /// #### `propagation-phase`
89    ///  The propagation phase at which this controller will handle events.
90    ///
91    /// Readable | Writeable
92    ///
93    ///
94    /// #### `widget`
95    ///  The widget receiving the `GdkEvents` that the controller will handle.
96    ///
97    /// Readable
98    /// </details>
99    ///
100    /// # Implements
101    ///
102    /// [`EventControllerExt`][trait@crate::prelude::EventControllerExt], [`trait@glib::ObjectExt`]
103    #[doc(alias = "GtkPadController")]
104    pub struct PadController(Object<ffi::GtkPadController, ffi::GtkPadControllerClass>) @extends EventController;
105
106    match fn {
107        type_ => || ffi::gtk_pad_controller_get_type(),
108    }
109}
110
111impl PadController {
112    /// Creates a new [`PadController`][crate::PadController] that will associate events from @pad to
113    /// actions.
114    ///
115    /// A [`None`] pad may be provided so the controller manages all pad devices
116    /// generically, it is discouraged to mix [`PadController`][crate::PadController] objects with
117    /// [`None`] and non-[`None`] @pad argument on the same toplevel window, as execution
118    /// order is not guaranteed.
119    ///
120    /// The [`PadController`][crate::PadController] is created with no mapped actions. In order to
121    /// map pad events to actions, use [`set_action_entries()`][Self::set_action_entries()]
122    /// or [`set_action()`][Self::set_action()].
123    ///
124    /// Be aware that pad events will only be delivered to [`Window`][crate::Window]s, so adding
125    /// a pad controller to any other type of widget will not have an effect.
126    /// ## `group`
127    /// `GActionGroup` to trigger actions from
128    /// ## `pad`
129    /// A `GDK_SOURCE_TABLET_PAD` device, or [`None`] to handle all pads
130    ///
131    /// # Returns
132    ///
133    /// A newly created [`PadController`][crate::PadController]
134    #[doc(alias = "gtk_pad_controller_new")]
135    pub fn new(group: &impl IsA<gio::ActionGroup>, pad: Option<&gdk::Device>) -> PadController {
136        assert_initialized_main_thread!();
137        unsafe {
138            from_glib_full(ffi::gtk_pad_controller_new(
139                group.as_ref().to_glib_none().0,
140                pad.to_glib_none().0,
141            ))
142        }
143    }
144
145    // rustdoc-stripper-ignore-next
146    /// Creates a new builder-pattern struct instance to construct [`PadController`] objects.
147    ///
148    /// This method returns an instance of [`PadControllerBuilder`](crate::builders::PadControllerBuilder) which can be used to create [`PadController`] objects.
149    pub fn builder() -> PadControllerBuilder {
150        PadControllerBuilder::new()
151    }
152
153    /// Adds an individual action to @self.
154    ///
155    /// This action will only be activated if the given button/ring/strip number
156    /// in @index is interacted while the current mode is @mode. -1 may be used
157    /// for simple cases, so the action is triggered on all modes.
158    ///
159    /// The given @label should be considered user-visible, so internationalization
160    /// rules apply. Some windowing systems may be able to use those for user
161    /// feedback.
162    /// ## `type_`
163    /// the type of pad feature that will trigger this action
164    /// ## `index`
165    /// the 0-indexed button/ring/strip number that will trigger this action
166    /// ## `mode`
167    /// the mode that will trigger this action, or -1 for all modes.
168    /// ## `label`
169    /// Human readable description of this action, this string should
170    ///   be deemed user-visible.
171    /// ## `action_name`
172    /// action name that will be activated in the `GActionGroup`
173    #[doc(alias = "gtk_pad_controller_set_action")]
174    pub fn set_action(
175        &self,
176        type_: PadActionType,
177        index: i32,
178        mode: i32,
179        label: &str,
180        action_name: &str,
181    ) {
182        unsafe {
183            ffi::gtk_pad_controller_set_action(
184                self.to_glib_none().0,
185                type_.into_glib(),
186                index,
187                mode,
188                label.to_glib_none().0,
189                action_name.to_glib_none().0,
190            );
191        }
192    }
193
194    /// A convenience function to add a group of action entries on
195    /// @self.
196    ///
197    /// See [`PadActionEntry`][crate::PadActionEntry] and [`set_action()`][Self::set_action()].
198    /// ## `entries`
199    /// the action entries to set on @self
200    #[doc(alias = "gtk_pad_controller_set_action_entries")]
201    pub fn set_action_entries(&self, entries: &[PadActionEntry]) {
202        let n_entries = entries.len() as _;
203        unsafe {
204            ffi::gtk_pad_controller_set_action_entries(
205                self.to_glib_none().0,
206                entries.to_glib_none().0,
207                n_entries,
208            );
209        }
210    }
211
212    /// The action group of the controller.
213    #[doc(alias = "action-group")]
214    pub fn action_group(&self) -> Option<gio::ActionGroup> {
215        ObjectExt::property(self, "action-group")
216    }
217
218    /// The pad of the controller.
219    pub fn pad(&self) -> Option<gdk::Device> {
220        ObjectExt::property(self, "pad")
221    }
222}
223
224impl Default for PadController {
225    fn default() -> Self {
226        glib::object::Object::new::<Self>()
227    }
228}
229
230// rustdoc-stripper-ignore-next
231/// A [builder-pattern] type to construct [`PadController`] objects.
232///
233/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
234#[must_use = "The builder must be built to be used"]
235pub struct PadControllerBuilder {
236    builder: glib::object::ObjectBuilder<'static, PadController>,
237}
238
239impl PadControllerBuilder {
240    fn new() -> Self {
241        Self {
242            builder: glib::object::Object::builder(),
243        }
244    }
245
246    /// The action group of the controller.
247    pub fn action_group(self, action_group: &impl IsA<gio::ActionGroup>) -> Self {
248        Self {
249            builder: self
250                .builder
251                .property("action-group", action_group.clone().upcast()),
252        }
253    }
254
255    /// The pad of the controller.
256    pub fn pad(self, pad: &gdk::Device) -> Self {
257        Self {
258            builder: self.builder.property("pad", pad.clone()),
259        }
260    }
261
262    /// The name for this controller, typically used for debugging purposes.
263    pub fn name(self, name: impl Into<glib::GString>) -> Self {
264        Self {
265            builder: self.builder.property("name", name.into()),
266        }
267    }
268
269    /// The limit for which events this controller will handle.
270    pub fn propagation_limit(self, propagation_limit: PropagationLimit) -> Self {
271        Self {
272            builder: self
273                .builder
274                .property("propagation-limit", propagation_limit),
275        }
276    }
277
278    /// The propagation phase at which this controller will handle events.
279    pub fn propagation_phase(self, propagation_phase: PropagationPhase) -> Self {
280        Self {
281            builder: self
282                .builder
283                .property("propagation-phase", propagation_phase),
284        }
285    }
286
287    // rustdoc-stripper-ignore-next
288    /// Build the [`PadController`].
289    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
290    pub fn build(self) -> PadController {
291        assert_initialized_main_thread!();
292        self.builder.build()
293    }
294}
gtk4/auto/pad_controller.rs

gtk4/auto/
pad_controller.rs
