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}