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