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