gtk/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::{EventController, PadActionType, PropagationPhase, Widget, Window, ffi};
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9    /// [`PadController`][crate::PadController] is an event controller for the pads found in drawing
10    /// tablets (The collection of buttons and tactile sensors often found around
11    /// the stylus-sensitive area).
12    ///
13    /// These buttons and sensors have no implicit meaning, and by default they
14    /// perform no action, this event controller is provided to map those to
15    /// `GAction` objects, thus letting the application give those a more semantic
16    /// meaning.
17    ///
18    /// Buttons and sensors are not constrained to triggering a single action, some
19    /// `GDK_SOURCE_TABLET_PAD` devices feature multiple "modes", all these input
20    /// elements have one current mode, which may determine the final action
21    /// being triggered. Pad devices often divide buttons and sensors into groups,
22    /// all elements in a group share the same current mode, but different groups
23    /// may have different modes. See `gdk_device_pad_get_n_groups()` and
24    /// `gdk_device_pad_get_group_n_modes()`.
25    ///
26    /// Each of the actions that a given button/strip/ring performs for a given
27    /// mode is defined by [`PadActionEntry`][crate::PadActionEntry], it contains an action name that
28    /// will be looked up in the given [`gio::ActionGroup`][crate::gio::ActionGroup] and activated whenever the
29    /// specified input element and mode are triggered.
30    ///
31    /// A simple example of [`PadController`][crate::PadController] usage, assigning button 1 in all
32    /// modes and pad devices to an "invert-selection" action:
33    ///
34    /// ```text
35    ///   GtkPadActionEntry *pad_actions[] = {
36    ///     { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" },
37    ///     …
38    ///   };
39    ///
40    ///   …
41    ///   action_group = g_simple_action_group_new ();
42    ///   action = g_simple_action_new ("pad-actions.invert-selection", NULL);
43    ///   g_signal_connect (action, "activate", on_invert_selection_activated, NULL);
44    ///   g_action_map_add_action (G_ACTION_MAP (action_group), action);
45    ///   …
46    ///   pad_controller = gtk_pad_controller_new (window, action_group, NULL);
47    /// ```
48    ///
49    /// The actions belonging to rings/strips will be activated with a parameter
50    /// of type `G_VARIANT_TYPE_DOUBLE` bearing the value of the given axis, it
51    /// is required that those are made stateful and accepting this [`glib::VariantType`][crate::glib::VariantType].
52    ///
53    /// ## Properties
54    ///
55    ///
56    /// #### `action-group`
57    ///  Readable | Writable | Construct Only
58    ///
59    ///
60    /// #### `pad`
61    ///  Readable | Writable | Construct Only
62    /// <details><summary><h4>EventController</h4></summary>
63    ///
64    ///
65    /// #### `propagation-phase`
66    ///  The propagation phase at which this controller will handle events.
67    ///
68    /// Readable | Writable
69    ///
70    ///
71    /// #### `widget`
72    ///  The widget receiving the `GdkEvents` that the controller will handle.
73    ///
74    /// Readable | Writable | Construct Only
75    /// </details>
76    ///
77    /// # Implements
78    ///
79    /// [`EventControllerExt`][trait@crate::prelude::EventControllerExt], [`trait@glib::ObjectExt`]
80    #[doc(alias = "GtkPadController")]
81    pub struct PadController(Object<ffi::GtkPadController, ffi::GtkPadControllerClass>) @extends EventController;
82
83    match fn {
84        type_ => || ffi::gtk_pad_controller_get_type(),
85    }
86}
87
88impl PadController {
89    /// Creates a new [`PadController`][crate::PadController] that will associate events from `pad` to
90    /// actions. A [`None`] pad may be provided so the controller manages all pad devices
91    /// generically, it is discouraged to mix [`PadController`][crate::PadController] objects with [`None`]
92    /// and non-[`None`] `pad` argument on the same `window`, as execution order is not
93    /// guaranteed.
94    ///
95    /// The [`PadController`][crate::PadController] is created with no mapped actions. In order to map pad
96    /// events to actions, use [`set_action_entries()`][Self::set_action_entries()] or
97    /// [`set_action()`][Self::set_action()].
98    /// ## `window`
99    /// a [`Window`][crate::Window]
100    /// ## `group`
101    /// [`gio::ActionGroup`][crate::gio::ActionGroup] to trigger actions from
102    /// ## `pad`
103    /// A `GDK_SOURCE_TABLET_PAD` device, or [`None`] to handle all pads
104    ///
105    /// # Returns
106    ///
107    /// A newly created [`PadController`][crate::PadController]
108    #[doc(alias = "gtk_pad_controller_new")]
109    pub fn new(
110        window: &impl IsA<Window>,
111        group: &impl IsA<gio::ActionGroup>,
112        pad: Option<&gdk::Device>,
113    ) -> PadController {
114        skip_assert_initialized!();
115        unsafe {
116            from_glib_full(ffi::gtk_pad_controller_new(
117                window.as_ref().to_glib_none().0,
118                group.as_ref().to_glib_none().0,
119                pad.to_glib_none().0,
120            ))
121        }
122    }
123
124    // rustdoc-stripper-ignore-next
125    /// Creates a new builder-pattern struct instance to construct [`PadController`] objects.
126    ///
127    /// This method returns an instance of [`PadControllerBuilder`](crate::builders::PadControllerBuilder) which can be used to create [`PadController`] objects.
128    pub fn builder() -> PadControllerBuilder {
129        PadControllerBuilder::new()
130    }
131
132    /// Adds an individual action to `self`. This action will only be activated
133    /// if the given button/ring/strip number in `index` is interacted while
134    /// the current mode is `mode`. -1 may be used for simple cases, so the action
135    /// is triggered on all modes.
136    ///
137    /// The given `label` should be considered user-visible, so internationalization
138    /// rules apply. Some windowing systems may be able to use those for user
139    /// feedback.
140    /// ## `type_`
141    /// the type of pad feature that will trigger this action
142    /// ## `index`
143    /// the 0-indexed button/ring/strip number that will trigger this action
144    /// ## `mode`
145    /// the mode that will trigger this action, or -1 for all modes.
146    /// ## `label`
147    /// Human readable description of this action, this string should
148    ///  be deemed user-visible.
149    /// ## `action_name`
150    /// action name that will be activated in the [`gio::ActionGroup`][crate::gio::ActionGroup]
151    #[doc(alias = "gtk_pad_controller_set_action")]
152    pub fn set_action(
153        &self,
154        type_: PadActionType,
155        index: i32,
156        mode: i32,
157        label: &str,
158        action_name: &str,
159    ) {
160        unsafe {
161            ffi::gtk_pad_controller_set_action(
162                self.to_glib_none().0,
163                type_.into_glib(),
164                index,
165                mode,
166                label.to_glib_none().0,
167                action_name.to_glib_none().0,
168            );
169        }
170    }
171
172    #[doc(alias = "action-group")]
173    pub fn action_group(&self) -> Option<gio::ActionGroup> {
174        ObjectExt::property(self, "action-group")
175    }
176
177    pub fn pad(&self) -> Option<gdk::Device> {
178        ObjectExt::property(self, "pad")
179    }
180}
181
182impl Default for PadController {
183    fn default() -> Self {
184        glib::object::Object::new::<Self>()
185    }
186}
187
188// rustdoc-stripper-ignore-next
189/// A [builder-pattern] type to construct [`PadController`] objects.
190///
191/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
192#[must_use = "The builder must be built to be used"]
193pub struct PadControllerBuilder {
194    builder: glib::object::ObjectBuilder<'static, PadController>,
195}
196
197impl PadControllerBuilder {
198    fn new() -> Self {
199        Self {
200            builder: glib::object::Object::builder(),
201        }
202    }
203
204    pub fn action_group(self, action_group: &impl IsA<gio::ActionGroup>) -> Self {
205        Self {
206            builder: self
207                .builder
208                .property("action-group", action_group.clone().upcast()),
209        }
210    }
211
212    pub fn pad(self, pad: &gdk::Device) -> Self {
213        Self {
214            builder: self.builder.property("pad", pad.clone()),
215        }
216    }
217
218    /// The propagation phase at which this controller will handle events.
219    pub fn propagation_phase(self, propagation_phase: PropagationPhase) -> Self {
220        Self {
221            builder: self
222                .builder
223                .property("propagation-phase", propagation_phase),
224        }
225    }
226
227    /// The widget receiving the `GdkEvents` that the controller will handle.
228    pub fn widget(self, widget: &impl IsA<Widget>) -> Self {
229        Self {
230            builder: self.builder.property("widget", widget.clone().upcast()),
231        }
232    }
233
234    // rustdoc-stripper-ignore-next
235    /// Build the [`PadController`].
236    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
237    pub fn build(self) -> PadController {
238        assert_initialized_main_thread!();
239        self.builder.build()
240    }
241}
gtk/auto/pad_controller.rs

gtk/auto/
pad_controller.rs
