gtk4/auto/drop_target_async.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, EventController, PropagationLimit, PropagationPhase};
6use glib::{
7 object::ObjectType as _,
8 prelude::*,
9 signal::{connect_raw, SignalHandlerId},
10 translate::*,
11};
12use std::boxed::Box as Box_;
13
14glib::wrapper! {
15 /// An event controller to receive Drag-and-Drop operations, asynchronously.
16 ///
17 /// It is the more complete but also more complex method of handling drop
18 /// operations compared to [`DropTarget`][crate::DropTarget], and you should only use
19 /// it if [`DropTarget`][crate::DropTarget] doesn't provide all the features you need.
20 ///
21 /// To use a [`DropTargetAsync`][crate::DropTargetAsync] to receive drops on a widget, you create
22 /// a [`DropTargetAsync`][crate::DropTargetAsync] object, configure which data formats and actions
23 /// you support, connect to its signals, and then attach it to the widget
24 /// with [`WidgetExt::add_controller()`][crate::prelude::WidgetExt::add_controller()].
25 ///
26 /// During a drag operation, the first signal that a [`DropTargetAsync`][crate::DropTargetAsync]
27 /// emits is [`accept`][struct@crate::DropTargetAsync#accept], which is meant to determine
28 /// whether the target is a possible drop site for the ongoing drop. The
29 /// default handler for the ::accept signal accepts the drop if it finds
30 /// a compatible data format and an action that is supported on both sides.
31 ///
32 /// If it is, and the widget becomes a target, you will receive a
33 /// [`drag-enter`][struct@crate::DropTargetAsync#drag-enter] signal, followed by
34 /// [`drag-motion`][struct@crate::DropTargetAsync#drag-motion] signals as the pointer moves,
35 /// optionally a [`drop`][struct@crate::DropTargetAsync#drop] signal when a drop happens,
36 /// and finally a [`drag-leave`][struct@crate::DropTargetAsync#drag-leave] signal when the
37 /// pointer moves off the widget.
38 ///
39 /// The ::drag-enter and ::drag-motion handler return a [`gdk::DragAction`][crate::gdk::DragAction]
40 /// to update the status of the ongoing operation. The ::drop handler
41 /// should decide if it ultimately accepts the drop and if it does, it
42 /// should initiate the data transfer and finish the operation by calling
43 /// [`Drop::finish()`][crate::gdk::Drop::finish()].
44 ///
45 /// Between the ::drag-enter and ::drag-leave signals the widget is a
46 /// current drop target, and will receive the [`StateFlags::DROP_ACTIVE`][crate::StateFlags::DROP_ACTIVE]
47 /// state, which can be used by themes to style the widget as a drop target.
48 ///
49 /// ## Properties
50 ///
51 ///
52 /// #### `actions`
53 /// The `GdkDragActions` that this drop target supports.
54 ///
55 /// Readable | Writeable
56 ///
57 ///
58 /// #### `formats`
59 /// The [`gdk::ContentFormats`][crate::gdk::ContentFormats] that determines the supported data formats.
60 ///
61 /// Readable | Writeable
62 /// <details><summary><h4>EventController</h4></summary>
63 ///
64 ///
65 /// #### `name`
66 /// The name for this controller, typically used for debugging purposes.
67 ///
68 /// Readable | Writeable
69 ///
70 ///
71 /// #### `propagation-limit`
72 /// The limit for which events this controller will handle.
73 ///
74 /// Readable | Writeable
75 ///
76 ///
77 /// #### `propagation-phase`
78 /// The propagation phase at which this controller will handle events.
79 ///
80 /// Readable | Writeable
81 ///
82 ///
83 /// #### `widget`
84 /// The widget receiving the `GdkEvents` that the controller will handle.
85 ///
86 /// Readable
87 /// </details>
88 ///
89 /// ## Signals
90 ///
91 ///
92 /// #### `accept`
93 /// Emitted on the drop site when a drop operation is about to begin.
94 ///
95 /// If the drop is not accepted, [`false`] will be returned and the drop target
96 /// will ignore the drop. If [`true`] is returned, the drop is accepted for now
97 /// but may be rejected later via a call to [`DropTargetAsync::reject_drop()`][crate::DropTargetAsync::reject_drop()]
98 /// or ultimately by returning [`false`] from a [`drop`][struct@crate::DropTargetAsync#drop]
99 /// handler.
100 ///
101 /// The default handler for this signal decides whether to accept the drop
102 /// based on the formats provided by the @drop.
103 ///
104 /// If the decision whether the drop will be accepted or rejected needs
105 /// further processing, such as inspecting the data, this function should
106 /// return [`true`] and proceed as is @drop was accepted and if it decides to
107 /// reject the drop later, it should call [`DropTargetAsync::reject_drop()`][crate::DropTargetAsync::reject_drop()].
108 ///
109 ///
110 ///
111 ///
112 /// #### `drag-enter`
113 /// Emitted on the drop site when the pointer enters the widget.
114 ///
115 /// It can be used to set up custom highlighting.
116 ///
117 ///
118 ///
119 ///
120 /// #### `drag-leave`
121 /// Emitted on the drop site when the pointer leaves the widget.
122 ///
123 /// Its main purpose it to undo things done in
124 /// [`DropTargetAsync`][crate::DropTargetAsync]::drag-enter.
125 ///
126 ///
127 ///
128 ///
129 /// #### `drag-motion`
130 /// Emitted while the pointer is moving over the drop target.
131 ///
132 ///
133 ///
134 ///
135 /// #### `drop`
136 /// Emitted on the drop site when the user drops the data onto the widget.
137 ///
138 /// The signal handler must determine whether the pointer position is in a
139 /// drop zone or not. If it is not in a drop zone, it returns [`false`] and no
140 /// further processing is necessary.
141 ///
142 /// Otherwise, the handler returns [`true`]. In this case, this handler will
143 /// accept the drop. The handler must ensure that [`Drop::finish()`][crate::gdk::Drop::finish()]
144 /// is called to let the source know that the drop is done. The call to
145 /// [`Drop::finish()`][crate::gdk::Drop::finish()] must only be done when all data has been received.
146 ///
147 /// To receive the data, use one of the read functions provided by
148 /// [`gdk::Drop`][crate::gdk::Drop] such as [`Drop::read_async()`][crate::gdk::Drop::read_async()] or
149 /// [`Drop::read_value_async()`][crate::gdk::Drop::read_value_async()].
150 ///
151 ///
152 ///
153 /// # Implements
154 ///
155 /// [`EventControllerExt`][trait@crate::prelude::EventControllerExt], [`trait@glib::ObjectExt`]
156 #[doc(alias = "GtkDropTargetAsync")]
157 pub struct DropTargetAsync(Object<ffi::GtkDropTargetAsync, ffi::GtkDropTargetAsyncClass>) @extends EventController;
158
159 match fn {
160 type_ => || ffi::gtk_drop_target_async_get_type(),
161 }
162}
163
164impl DropTargetAsync {
165 /// Creates a new [`DropTargetAsync`][crate::DropTargetAsync] object.
166 /// ## `formats`
167 /// the supported data formats
168 /// ## `actions`
169 /// the supported actions
170 ///
171 /// # Returns
172 ///
173 /// the new [`DropTargetAsync`][crate::DropTargetAsync]
174 #[doc(alias = "gtk_drop_target_async_new")]
175 pub fn new(formats: Option<gdk::ContentFormats>, actions: gdk::DragAction) -> DropTargetAsync {
176 assert_initialized_main_thread!();
177 unsafe {
178 from_glib_full(ffi::gtk_drop_target_async_new(
179 formats.into_glib_ptr(),
180 actions.into_glib(),
181 ))
182 }
183 }
184
185 // rustdoc-stripper-ignore-next
186 /// Creates a new builder-pattern struct instance to construct [`DropTargetAsync`] objects.
187 ///
188 /// This method returns an instance of [`DropTargetAsyncBuilder`](crate::builders::DropTargetAsyncBuilder) which can be used to create [`DropTargetAsync`] objects.
189 pub fn builder() -> DropTargetAsyncBuilder {
190 DropTargetAsyncBuilder::new()
191 }
192
193 /// Gets the actions that this drop target supports.
194 ///
195 /// # Returns
196 ///
197 /// the actions that this drop target supports
198 #[doc(alias = "gtk_drop_target_async_get_actions")]
199 #[doc(alias = "get_actions")]
200 pub fn actions(&self) -> gdk::DragAction {
201 unsafe {
202 from_glib(ffi::gtk_drop_target_async_get_actions(
203 self.to_glib_none().0,
204 ))
205 }
206 }
207
208 /// Gets the data formats that this drop target accepts.
209 ///
210 /// If the result is [`None`], all formats are expected to be supported.
211 ///
212 /// # Returns
213 ///
214 /// the supported data formats
215 #[doc(alias = "gtk_drop_target_async_get_formats")]
216 #[doc(alias = "get_formats")]
217 pub fn formats(&self) -> Option<gdk::ContentFormats> {
218 unsafe {
219 from_glib_full(ffi::gtk_drop_target_async_get_formats(
220 self.to_glib_none().0,
221 ))
222 }
223 }
224
225 /// Sets the @drop as not accepted on this drag site.
226 ///
227 /// This function should be used when delaying the decision
228 /// on whether to accept a drag or not until after reading
229 /// the data.
230 /// ## `drop`
231 /// the [`gdk::Drop`][crate::gdk::Drop] of an ongoing drag operation
232 #[doc(alias = "gtk_drop_target_async_reject_drop")]
233 pub fn reject_drop(&self, drop: &gdk::Drop) {
234 unsafe {
235 ffi::gtk_drop_target_async_reject_drop(self.to_glib_none().0, drop.to_glib_none().0);
236 }
237 }
238
239 /// Sets the actions that this drop target supports.
240 /// ## `actions`
241 /// the supported actions
242 #[doc(alias = "gtk_drop_target_async_set_actions")]
243 #[doc(alias = "actions")]
244 pub fn set_actions(&self, actions: gdk::DragAction) {
245 unsafe {
246 ffi::gtk_drop_target_async_set_actions(self.to_glib_none().0, actions.into_glib());
247 }
248 }
249
250 /// Sets the data formats that this drop target will accept.
251 /// ## `formats`
252 /// the supported data formats or [`None`] for any format
253 #[doc(alias = "gtk_drop_target_async_set_formats")]
254 #[doc(alias = "formats")]
255 pub fn set_formats(&self, formats: Option<&gdk::ContentFormats>) {
256 unsafe {
257 ffi::gtk_drop_target_async_set_formats(self.to_glib_none().0, formats.to_glib_none().0);
258 }
259 }
260
261 /// Emitted on the drop site when a drop operation is about to begin.
262 ///
263 /// If the drop is not accepted, [`false`] will be returned and the drop target
264 /// will ignore the drop. If [`true`] is returned, the drop is accepted for now
265 /// but may be rejected later via a call to [`reject_drop()`][Self::reject_drop()]
266 /// or ultimately by returning [`false`] from a [`drop`][struct@crate::DropTargetAsync#drop]
267 /// handler.
268 ///
269 /// The default handler for this signal decides whether to accept the drop
270 /// based on the formats provided by the @drop.
271 ///
272 /// If the decision whether the drop will be accepted or rejected needs
273 /// further processing, such as inspecting the data, this function should
274 /// return [`true`] and proceed as is @drop was accepted and if it decides to
275 /// reject the drop later, it should call [`reject_drop()`][Self::reject_drop()].
276 /// ## `drop`
277 /// the [`gdk::Drop`][crate::gdk::Drop]
278 ///
279 /// # Returns
280 ///
281 /// [`true`] if @drop is accepted
282 #[doc(alias = "accept")]
283 pub fn connect_accept<F: Fn(&Self, &gdk::Drop) -> bool + 'static>(
284 &self,
285 f: F,
286 ) -> SignalHandlerId {
287 unsafe extern "C" fn accept_trampoline<
288 F: Fn(&DropTargetAsync, &gdk::Drop) -> bool + 'static,
289 >(
290 this: *mut ffi::GtkDropTargetAsync,
291 drop: *mut gdk::ffi::GdkDrop,
292 f: glib::ffi::gpointer,
293 ) -> glib::ffi::gboolean {
294 let f: &F = &*(f as *const F);
295 f(&from_glib_borrow(this), &from_glib_borrow(drop)).into_glib()
296 }
297 unsafe {
298 let f: Box_<F> = Box_::new(f);
299 connect_raw(
300 self.as_ptr() as *mut _,
301 c"accept".as_ptr() as *const _,
302 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
303 accept_trampoline::<F> as *const (),
304 )),
305 Box_::into_raw(f),
306 )
307 }
308 }
309
310 /// Emitted on the drop site when the pointer enters the widget.
311 ///
312 /// It can be used to set up custom highlighting.
313 /// ## `drop`
314 /// the [`gdk::Drop`][crate::gdk::Drop]
315 /// ## `x`
316 /// the x coordinate of the current pointer position
317 /// ## `y`
318 /// the y coordinate of the current pointer position
319 ///
320 /// # Returns
321 ///
322 /// Preferred action for this drag operation.
323 #[doc(alias = "drag-enter")]
324 pub fn connect_drag_enter<F: Fn(&Self, &gdk::Drop, f64, f64) -> gdk::DragAction + 'static>(
325 &self,
326 f: F,
327 ) -> SignalHandlerId {
328 unsafe extern "C" fn drag_enter_trampoline<
329 F: Fn(&DropTargetAsync, &gdk::Drop, f64, f64) -> gdk::DragAction + 'static,
330 >(
331 this: *mut ffi::GtkDropTargetAsync,
332 drop: *mut gdk::ffi::GdkDrop,
333 x: std::ffi::c_double,
334 y: std::ffi::c_double,
335 f: glib::ffi::gpointer,
336 ) -> gdk::ffi::GdkDragAction {
337 let f: &F = &*(f as *const F);
338 f(&from_glib_borrow(this), &from_glib_borrow(drop), x, y).into_glib()
339 }
340 unsafe {
341 let f: Box_<F> = Box_::new(f);
342 connect_raw(
343 self.as_ptr() as *mut _,
344 c"drag-enter".as_ptr() as *const _,
345 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
346 drag_enter_trampoline::<F> as *const (),
347 )),
348 Box_::into_raw(f),
349 )
350 }
351 }
352
353 /// Emitted on the drop site when the pointer leaves the widget.
354 ///
355 /// Its main purpose it to undo things done in
356 /// [`DropTargetAsync`][crate::DropTargetAsync]::drag-enter.
357 /// ## `drop`
358 /// the [`gdk::Drop`][crate::gdk::Drop]
359 #[doc(alias = "drag-leave")]
360 pub fn connect_drag_leave<F: Fn(&Self, &gdk::Drop) + 'static>(&self, f: F) -> SignalHandlerId {
361 unsafe extern "C" fn drag_leave_trampoline<
362 F: Fn(&DropTargetAsync, &gdk::Drop) + 'static,
363 >(
364 this: *mut ffi::GtkDropTargetAsync,
365 drop: *mut gdk::ffi::GdkDrop,
366 f: glib::ffi::gpointer,
367 ) {
368 let f: &F = &*(f as *const F);
369 f(&from_glib_borrow(this), &from_glib_borrow(drop))
370 }
371 unsafe {
372 let f: Box_<F> = Box_::new(f);
373 connect_raw(
374 self.as_ptr() as *mut _,
375 c"drag-leave".as_ptr() as *const _,
376 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
377 drag_leave_trampoline::<F> as *const (),
378 )),
379 Box_::into_raw(f),
380 )
381 }
382 }
383
384 /// Emitted while the pointer is moving over the drop target.
385 /// ## `drop`
386 /// the [`gdk::Drop`][crate::gdk::Drop]
387 /// ## `x`
388 /// the x coordinate of the current pointer position
389 /// ## `y`
390 /// the y coordinate of the current pointer position
391 ///
392 /// # Returns
393 ///
394 /// Preferred action for this drag operation.
395 #[doc(alias = "drag-motion")]
396 pub fn connect_drag_motion<F: Fn(&Self, &gdk::Drop, f64, f64) -> gdk::DragAction + 'static>(
397 &self,
398 f: F,
399 ) -> SignalHandlerId {
400 unsafe extern "C" fn drag_motion_trampoline<
401 F: Fn(&DropTargetAsync, &gdk::Drop, f64, f64) -> gdk::DragAction + 'static,
402 >(
403 this: *mut ffi::GtkDropTargetAsync,
404 drop: *mut gdk::ffi::GdkDrop,
405 x: std::ffi::c_double,
406 y: std::ffi::c_double,
407 f: glib::ffi::gpointer,
408 ) -> gdk::ffi::GdkDragAction {
409 let f: &F = &*(f as *const F);
410 f(&from_glib_borrow(this), &from_glib_borrow(drop), x, y).into_glib()
411 }
412 unsafe {
413 let f: Box_<F> = Box_::new(f);
414 connect_raw(
415 self.as_ptr() as *mut _,
416 c"drag-motion".as_ptr() as *const _,
417 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
418 drag_motion_trampoline::<F> as *const (),
419 )),
420 Box_::into_raw(f),
421 )
422 }
423 }
424
425 /// Emitted on the drop site when the user drops the data onto the widget.
426 ///
427 /// The signal handler must determine whether the pointer position is in a
428 /// drop zone or not. If it is not in a drop zone, it returns [`false`] and no
429 /// further processing is necessary.
430 ///
431 /// Otherwise, the handler returns [`true`]. In this case, this handler will
432 /// accept the drop. The handler must ensure that [`Drop::finish()`][crate::gdk::Drop::finish()]
433 /// is called to let the source know that the drop is done. The call to
434 /// [`Drop::finish()`][crate::gdk::Drop::finish()] must only be done when all data has been received.
435 ///
436 /// To receive the data, use one of the read functions provided by
437 /// [`gdk::Drop`][crate::gdk::Drop] such as [`Drop::read_async()`][crate::gdk::Drop::read_async()] or
438 /// [`Drop::read_value_async()`][crate::gdk::Drop::read_value_async()].
439 /// ## `drop`
440 /// the [`gdk::Drop`][crate::gdk::Drop]
441 /// ## `x`
442 /// the x coordinate of the current pointer position
443 /// ## `y`
444 /// the y coordinate of the current pointer position
445 ///
446 /// # Returns
447 ///
448 /// whether the drop is accepted at the given pointer position
449 #[doc(alias = "drop")]
450 pub fn connect_drop<F: Fn(&Self, &gdk::Drop, f64, f64) -> bool + 'static>(
451 &self,
452 f: F,
453 ) -> SignalHandlerId {
454 unsafe extern "C" fn drop_trampoline<
455 F: Fn(&DropTargetAsync, &gdk::Drop, f64, f64) -> bool + 'static,
456 >(
457 this: *mut ffi::GtkDropTargetAsync,
458 drop: *mut gdk::ffi::GdkDrop,
459 x: std::ffi::c_double,
460 y: std::ffi::c_double,
461 f: glib::ffi::gpointer,
462 ) -> glib::ffi::gboolean {
463 let f: &F = &*(f as *const F);
464 f(&from_glib_borrow(this), &from_glib_borrow(drop), x, y).into_glib()
465 }
466 unsafe {
467 let f: Box_<F> = Box_::new(f);
468 connect_raw(
469 self.as_ptr() as *mut _,
470 c"drop".as_ptr() as *const _,
471 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
472 drop_trampoline::<F> as *const (),
473 )),
474 Box_::into_raw(f),
475 )
476 }
477 }
478
479 #[doc(alias = "actions")]
480 pub fn connect_actions_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
481 unsafe extern "C" fn notify_actions_trampoline<F: Fn(&DropTargetAsync) + 'static>(
482 this: *mut ffi::GtkDropTargetAsync,
483 _param_spec: glib::ffi::gpointer,
484 f: glib::ffi::gpointer,
485 ) {
486 let f: &F = &*(f as *const F);
487 f(&from_glib_borrow(this))
488 }
489 unsafe {
490 let f: Box_<F> = Box_::new(f);
491 connect_raw(
492 self.as_ptr() as *mut _,
493 c"notify::actions".as_ptr() as *const _,
494 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
495 notify_actions_trampoline::<F> as *const (),
496 )),
497 Box_::into_raw(f),
498 )
499 }
500 }
501
502 #[doc(alias = "formats")]
503 pub fn connect_formats_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
504 unsafe extern "C" fn notify_formats_trampoline<F: Fn(&DropTargetAsync) + 'static>(
505 this: *mut ffi::GtkDropTargetAsync,
506 _param_spec: glib::ffi::gpointer,
507 f: glib::ffi::gpointer,
508 ) {
509 let f: &F = &*(f as *const F);
510 f(&from_glib_borrow(this))
511 }
512 unsafe {
513 let f: Box_<F> = Box_::new(f);
514 connect_raw(
515 self.as_ptr() as *mut _,
516 c"notify::formats".as_ptr() as *const _,
517 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
518 notify_formats_trampoline::<F> as *const (),
519 )),
520 Box_::into_raw(f),
521 )
522 }
523 }
524}
525
526impl Default for DropTargetAsync {
527 fn default() -> Self {
528 glib::object::Object::new::<Self>()
529 }
530}
531
532// rustdoc-stripper-ignore-next
533/// A [builder-pattern] type to construct [`DropTargetAsync`] objects.
534///
535/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
536#[must_use = "The builder must be built to be used"]
537pub struct DropTargetAsyncBuilder {
538 builder: glib::object::ObjectBuilder<'static, DropTargetAsync>,
539}
540
541impl DropTargetAsyncBuilder {
542 fn new() -> Self {
543 Self {
544 builder: glib::object::Object::builder(),
545 }
546 }
547
548 /// The `GdkDragActions` that this drop target supports.
549 pub fn actions(self, actions: gdk::DragAction) -> Self {
550 Self {
551 builder: self.builder.property("actions", actions),
552 }
553 }
554
555 /// The [`gdk::ContentFormats`][crate::gdk::ContentFormats] that determines the supported data formats.
556 pub fn formats(self, formats: &gdk::ContentFormats) -> Self {
557 Self {
558 builder: self.builder.property("formats", formats.clone()),
559 }
560 }
561
562 /// The name for this controller, typically used for debugging purposes.
563 pub fn name(self, name: impl Into<glib::GString>) -> Self {
564 Self {
565 builder: self.builder.property("name", name.into()),
566 }
567 }
568
569 /// The limit for which events this controller will handle.
570 pub fn propagation_limit(self, propagation_limit: PropagationLimit) -> Self {
571 Self {
572 builder: self
573 .builder
574 .property("propagation-limit", propagation_limit),
575 }
576 }
577
578 /// The propagation phase at which this controller will handle events.
579 pub fn propagation_phase(self, propagation_phase: PropagationPhase) -> Self {
580 Self {
581 builder: self
582 .builder
583 .property("propagation-phase", propagation_phase),
584 }
585 }
586
587 // rustdoc-stripper-ignore-next
588 /// Build the [`DropTargetAsync`].
589 #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
590 pub fn build(self) -> DropTargetAsync {
591 assert_initialized_main_thread!();
592 self.builder.build()
593 }
594}