gtk4/auto/

drop_target.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT
#![allow(deprecated)]

use crate::{ffi, EventController, PropagationLimit, PropagationPhase};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// [`DropTarget`][crate::DropTarget] is an event controller to receive Drag-and-Drop operations.
    ///
    /// The most basic way to use a [`DropTarget`][crate::DropTarget] to receive drops on a
    /// widget is to create it via [`new()`][Self::new()], passing in the
    /// `GType` of the data you want to receive and connect to the
    /// [`drop`][struct@crate::DropTarget#drop] signal to receive the data:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// static gboolean
    /// on_drop (GtkDropTarget *target,
    ///          const GValue  *value,
    ///          double         x,
    ///          double         y,
    ///          gpointer       data)
    /// {
    ///   MyWidget *self = data;
    ///
    ///   // Call the appropriate setter depending on the type of data
    ///   // that we received
    ///   if (G_VALUE_HOLDS (value, G_TYPE_FILE))
    ///     my_widget_set_file (self, g_value_get_object (value));
    ///   else if (G_VALUE_HOLDS (value, GDK_TYPE_PIXBUF))
    ///     my_widget_set_pixbuf (self, g_value_get_object (value));
    ///   else
    ///     return FALSE;
    ///
    ///   return TRUE;
    /// }
    ///
    /// static void
    /// my_widget_init (MyWidget *self)
    /// {
    ///   GtkDropTarget *target =
    ///     gtk_drop_target_new (G_TYPE_INVALID, GDK_ACTION_COPY);
    ///
    ///   // This widget accepts two types of drop types: GFile objects
    ///   // and GdkPixbuf objects
    ///   gtk_drop_target_set_gtypes (target, (GType [2]) {
    ///     G_TYPE_FILE,
    ///     GDK_TYPE_PIXBUF,
    ///   }, 2);
    ///
    ///   g_signal_connect (target, "drop", G_CALLBACK (on_drop), self);
    ///   gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (target));
    /// }
    /// ```
    ///
    /// [`DropTarget`][crate::DropTarget] supports more options, such as:
    ///
    ///  * rejecting potential drops via the [`accept`][struct@crate::DropTarget#accept] signal
    ///    and the [`reject()`][Self::reject()] function to let other drop
    ///    targets handle the drop
    ///  * tracking an ongoing drag operation before the drop via the
    ///    [`enter`][struct@crate::DropTarget#enter], [`motion`][struct@crate::DropTarget#motion] and
    ///    [`leave`][struct@crate::DropTarget#leave] signals
    ///  * configuring how to receive data by setting the
    ///    [`preload`][struct@crate::DropTarget#preload] property and listening for its
    ///    availability via the [`value`][struct@crate::DropTarget#value] property
    ///
    /// However, [`DropTarget`][crate::DropTarget] is ultimately modeled in a synchronous way
    /// and only supports data transferred via `GType`. If you want full control
    /// over an ongoing drop, the [`DropTargetAsync`][crate::DropTargetAsync] object gives you
    /// this ability.
    ///
    /// While a pointer is dragged over the drop target's widget and the drop
    /// has not been rejected, that widget will receive the
    /// [`StateFlags::DROP_ACTIVE`][crate::StateFlags::DROP_ACTIVE] state, which can be used to style the widget.
    ///
    /// If you are not interested in receiving the drop, but just want to update
    /// UI state during a Drag-and-Drop operation (e.g. switching tabs), you can
    /// use [`DropControllerMotion`][crate::DropControllerMotion].
    ///
    /// ## Properties
    ///
    ///
    /// #### `actions`
    ///  The `GdkDragActions` that this drop target supports.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `current-drop`
    ///  The [`gdk::Drop`][crate::gdk::Drop] that is currently being performed.
    ///
    /// Readable
    ///
    ///
    /// #### `drop`
    ///  The [`gdk::Drop`][crate::gdk::Drop] that is currently being performed.
    ///
    /// Readable
    ///
    ///
    /// #### `formats`
    ///  The [`gdk::ContentFormats`][crate::gdk::ContentFormats] that determine the supported data formats.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `preload`
    ///  Whether the drop data should be preloaded when the pointer is only
    /// hovering over the widget but has not been released.
    ///
    /// Setting this property allows finer grained reaction to an ongoing
    /// drop at the cost of loading more data.
    ///
    /// The default value for this property is [`false`] to avoid downloading
    /// huge amounts of data by accident.
    ///
    /// For example, if somebody drags a full document of gigabytes of text
    /// from a text editor across a widget with a preloading drop target,
    /// this data will be downloaded, even if the data is ultimately dropped
    /// elsewhere.
    ///
    /// For a lot of data formats, the amount of data is very small (like
    /// `GDK_TYPE_RGBA`), so enabling this property does not hurt at all.
    /// And for local-only Drag-and-Drop operations, no data transfer is done,
    /// so enabling it there is free.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `value`
    ///  The value for this drop operation.
    ///
    /// This is [`None`] if the data has not been loaded yet or no drop
    /// operation is going on.
    ///
    /// Data may be available before the [`drop`][struct@crate::DropTarget#drop]
    /// signal gets emitted - for example when the [`preload`][struct@crate::DropTarget#preload]
    /// property is set. You can use the ::notify signal to be notified
    /// of available data.
    ///
    /// Readable
    /// <details><summary><h4>EventController</h4></summary>
    ///
    ///
    /// #### `name`
    ///  The name for this controller, typically used for debugging purposes.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `propagation-limit`
    ///  The limit for which events this controller will handle.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `propagation-phase`
    ///  The propagation phase at which this controller will handle events.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `widget`
    ///  The widget receiving the `GdkEvents` that the controller will handle.
    ///
    /// Readable
    /// </details>
    ///
    /// ## Signals
    ///
    ///
    /// #### `accept`
    ///  Emitted on the drop site when a drop operation is about to begin.
    ///
    /// If the drop is not accepted, [`false`] will be returned and the drop target
    /// will ignore the drop. If [`true`] is returned, the drop is accepted for now
    /// but may be rejected later via a call to [`DropTarget::reject()`][crate::DropTarget::reject()]
    /// or ultimately by returning [`false`] from a [`drop`][struct@crate::DropTarget#drop]
    /// handler.
    ///
    /// The default handler for this signal decides whether to accept the drop
    /// based on the formats provided by the @drop.
    ///
    /// If the decision whether the drop will be accepted or rejected depends
    /// on the data, this function should return [`true`], the
    /// [`preload`][struct@crate::DropTarget#preload] property should be set and the value
    /// should be inspected via the ::notify:value signal, calling
    /// [`DropTarget::reject()`][crate::DropTarget::reject()] if required.
    ///
    ///
    ///
    ///
    /// #### `drop`
    ///  Emitted on the drop site when the user drops the data onto the widget.
    ///
    /// The signal handler must determine whether the pointer position is in
    /// a drop zone or not. If it is not in a drop zone, it returns [`false`]
    /// and no further processing is necessary.
    ///
    /// Otherwise, the handler returns [`true`]. In this case, this handler will
    /// accept the drop. The handler is responsible for using the given @value
    /// and performing the drop operation.
    ///
    ///
    ///
    ///
    /// #### `enter`
    ///  Emitted on the drop site when the pointer enters the widget.
    ///
    /// It can be used to set up custom highlighting.
    ///
    ///
    ///
    ///
    /// #### `leave`
    ///  Emitted on the drop site when the pointer leaves the widget.
    ///
    /// Its main purpose it to undo things done in
    /// [`enter`][struct@crate::DropTarget#enter].
    ///
    ///
    ///
    ///
    /// #### `motion`
    ///  Emitted while the pointer is moving over the drop target.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`EventControllerExt`][trait@crate::prelude::EventControllerExt], [`trait@glib::ObjectExt`]
    #[doc(alias = "GtkDropTarget")]
    pub struct DropTarget(Object<ffi::GtkDropTarget, ffi::GtkDropTargetClass>) @extends EventController;

    match fn {
        type_ => || ffi::gtk_drop_target_get_type(),
    }
}

impl DropTarget {
    /// Creates a new [`DropTarget`][crate::DropTarget] object.
    ///
    /// If the drop target should support more than 1 type, pass
    /// `G_TYPE_INVALID` for @type_ and then call
    /// [`set_types()`][Self::set_types()].
    /// ## `type_`
    /// The supported type or `G_TYPE_INVALID`
    /// ## `actions`
    /// the supported actions
    ///
    /// # Returns
    ///
    /// the new [`DropTarget`][crate::DropTarget]
    #[doc(alias = "gtk_drop_target_new")]
    pub fn new(type_: glib::types::Type, actions: gdk::DragAction) -> DropTarget {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::gtk_drop_target_new(
                type_.into_glib(),
                actions.into_glib(),
            ))
        }
    }

    // rustdoc-stripper-ignore-next
    /// Creates a new builder-pattern struct instance to construct [`DropTarget`] objects.
    ///
    /// This method returns an instance of [`DropTargetBuilder`](crate::builders::DropTargetBuilder) which can be used to create [`DropTarget`] objects.
    pub fn builder() -> DropTargetBuilder {
        DropTargetBuilder::new()
    }

    /// Gets the actions that this drop target supports.
    ///
    /// # Returns
    ///
    /// the actions that this drop target supports
    #[doc(alias = "gtk_drop_target_get_actions")]
    #[doc(alias = "get_actions")]
    pub fn actions(&self) -> gdk::DragAction {
        unsafe { from_glib(ffi::gtk_drop_target_get_actions(self.to_glib_none().0)) }
    }

    /// Gets the currently handled drop operation.
    ///
    /// If no drop operation is going on, [`None`] is returned.
    ///
    /// # Returns
    ///
    /// The current drop
    #[cfg(feature = "v4_4")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_4")))]
    #[doc(alias = "gtk_drop_target_get_current_drop")]
    #[doc(alias = "get_current_drop")]
    #[doc(alias = "current-drop")]
    pub fn current_drop(&self) -> Option<gdk::Drop> {
        unsafe { from_glib_none(ffi::gtk_drop_target_get_current_drop(self.to_glib_none().0)) }
    }

    /// Gets the currently handled drop operation.
    ///
    /// If no drop operation is going on, [`None`] is returned.
    ///
    /// # Deprecated since 4.4
    ///
    /// Use [`current_drop()`][Self::current_drop()] instead
    ///
    /// # Returns
    ///
    /// The current drop
    #[cfg_attr(feature = "v4_4", deprecated = "Since 4.4")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_drop_target_get_drop")]
    #[doc(alias = "get_drop")]
    pub fn drop(&self) -> Option<gdk::Drop> {
        unsafe { from_glib_none(ffi::gtk_drop_target_get_drop(self.to_glib_none().0)) }
    }

    /// Gets the data formats that this drop target accepts.
    ///
    /// If the result is [`None`], all formats are expected to be supported.
    ///
    /// # Returns
    ///
    /// the supported data formats
    #[doc(alias = "gtk_drop_target_get_formats")]
    #[doc(alias = "get_formats")]
    pub fn formats(&self) -> Option<gdk::ContentFormats> {
        unsafe { from_glib_none(ffi::gtk_drop_target_get_formats(self.to_glib_none().0)) }
    }

    /// Gets whether data should be preloaded on hover.
    ///
    /// # Returns
    ///
    /// [`true`] if drop data should be preloaded
    #[doc(alias = "gtk_drop_target_get_preload")]
    #[doc(alias = "get_preload")]
    #[doc(alias = "preload")]
    pub fn is_preload(&self) -> bool {
        unsafe { from_glib(ffi::gtk_drop_target_get_preload(self.to_glib_none().0)) }
    }

    /// Gets the current drop data, as a `GValue`.
    ///
    /// # Returns
    ///
    /// The current drop data
    #[doc(alias = "gtk_drop_target_get_value")]
    #[doc(alias = "get_value")]
    pub fn value(&self) -> Option<glib::Value> {
        unsafe { from_glib_none(ffi::gtk_drop_target_get_value(self.to_glib_none().0)) }
    }

    /// Rejects the ongoing drop operation.
    ///
    /// If no drop operation is ongoing, i.e when [`current-drop`][struct@crate::DropTarget#current-drop]
    /// is [`None`], this function does nothing.
    ///
    /// This function should be used when delaying the decision
    /// on whether to accept a drag or not until after reading
    /// the data.
    #[doc(alias = "gtk_drop_target_reject")]
    pub fn reject(&self) {
        unsafe {
            ffi::gtk_drop_target_reject(self.to_glib_none().0);
        }
    }

    /// Sets the actions that this drop target supports.
    /// ## `actions`
    /// the supported actions
    #[doc(alias = "gtk_drop_target_set_actions")]
    #[doc(alias = "actions")]
    pub fn set_actions(&self, actions: gdk::DragAction) {
        unsafe {
            ffi::gtk_drop_target_set_actions(self.to_glib_none().0, actions.into_glib());
        }
    }

    /// Sets whether data should be preloaded on hover.
    /// ## `preload`
    /// [`true`] to preload drop data
    #[doc(alias = "gtk_drop_target_set_preload")]
    #[doc(alias = "preload")]
    pub fn set_preload(&self, preload: bool) {
        unsafe {
            ffi::gtk_drop_target_set_preload(self.to_glib_none().0, preload.into_glib());
        }
    }

    /// Emitted on the drop site when a drop operation is about to begin.
    ///
    /// If the drop is not accepted, [`false`] will be returned and the drop target
    /// will ignore the drop. If [`true`] is returned, the drop is accepted for now
    /// but may be rejected later via a call to [`reject()`][Self::reject()]
    /// or ultimately by returning [`false`] from a [`drop`][struct@crate::DropTarget#drop]
    /// handler.
    ///
    /// The default handler for this signal decides whether to accept the drop
    /// based on the formats provided by the @drop.
    ///
    /// If the decision whether the drop will be accepted or rejected depends
    /// on the data, this function should return [`true`], the
    /// [`preload`][struct@crate::DropTarget#preload] property should be set and the value
    /// should be inspected via the ::notify:value signal, calling
    /// [`reject()`][Self::reject()] if required.
    /// ## `drop`
    /// the [`gdk::Drop`][crate::gdk::Drop]
    ///
    /// # Returns
    ///
    /// [`true`] if @drop is accepted
    #[doc(alias = "accept")]
    pub fn connect_accept<F: Fn(&Self, &gdk::Drop) -> bool + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn accept_trampoline<F: Fn(&DropTarget, &gdk::Drop) -> bool + 'static>(
            this: *mut ffi::GtkDropTarget,
            drop: *mut gdk::ffi::GdkDrop,
            f: glib::ffi::gpointer,
        ) -> glib::ffi::gboolean {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this), &from_glib_borrow(drop)).into_glib()
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"accept\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    accept_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted on the drop site when the pointer enters the widget.
    ///
    /// It can be used to set up custom highlighting.
    /// ## `x`
    /// the x coordinate of the current pointer position
    /// ## `y`
    /// the y coordinate of the current pointer position
    ///
    /// # Returns
    ///
    /// Preferred action for this drag operation or 0 if
    ///   dropping is not supported at the current @x,@y location.
    #[doc(alias = "enter")]
    pub fn connect_enter<F: Fn(&Self, f64, f64) -> gdk::DragAction + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn enter_trampoline<
            F: Fn(&DropTarget, f64, f64) -> gdk::DragAction + 'static,
        >(
            this: *mut ffi::GtkDropTarget,
            x: std::ffi::c_double,
            y: std::ffi::c_double,
            f: glib::ffi::gpointer,
        ) -> gdk::ffi::GdkDragAction {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this), x, y).into_glib()
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"enter\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    enter_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted on the drop site when the pointer leaves the widget.
    ///
    /// Its main purpose it to undo things done in
    /// [`enter`][struct@crate::DropTarget#enter].
    #[doc(alias = "leave")]
    pub fn connect_leave<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn leave_trampoline<F: Fn(&DropTarget) + 'static>(
            this: *mut ffi::GtkDropTarget,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"leave\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    leave_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted while the pointer is moving over the drop target.
    /// ## `x`
    /// the x coordinate of the current pointer position
    /// ## `y`
    /// the y coordinate of the current pointer position
    ///
    /// # Returns
    ///
    /// Preferred action for this drag operation or 0 if
    ///   dropping is not supported at the current @x,@y location.
    #[doc(alias = "motion")]
    pub fn connect_motion<F: Fn(&Self, f64, f64) -> gdk::DragAction + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn motion_trampoline<
            F: Fn(&DropTarget, f64, f64) -> gdk::DragAction + 'static,
        >(
            this: *mut ffi::GtkDropTarget,
            x: std::ffi::c_double,
            y: std::ffi::c_double,
            f: glib::ffi::gpointer,
        ) -> gdk::ffi::GdkDragAction {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this), x, y).into_glib()
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"motion\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    motion_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "actions")]
    pub fn connect_actions_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_actions_trampoline<F: Fn(&DropTarget) + 'static>(
            this: *mut ffi::GtkDropTarget,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::actions\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_actions_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[cfg(feature = "v4_4")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_4")))]
    #[doc(alias = "current-drop")]
    pub fn connect_current_drop_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_current_drop_trampoline<F: Fn(&DropTarget) + 'static>(
            this: *mut ffi::GtkDropTarget,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::current-drop\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_current_drop_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[cfg_attr(feature = "v4_4", deprecated = "Since 4.4")]
    #[doc(alias = "drop")]
    pub fn connect_drop_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_drop_trampoline<F: Fn(&DropTarget) + 'static>(
            this: *mut ffi::GtkDropTarget,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::drop\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_drop_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "preload")]
    pub fn connect_preload_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_preload_trampoline<F: Fn(&DropTarget) + 'static>(
            this: *mut ffi::GtkDropTarget,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::preload\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_preload_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "value")]
    pub fn connect_value_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_value_trampoline<F: Fn(&DropTarget) + 'static>(
            this: *mut ffi::GtkDropTarget,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::value\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_value_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl Default for DropTarget {
    fn default() -> Self {
        glib::object::Object::new::<Self>()
    }
}

// rustdoc-stripper-ignore-next
/// A [builder-pattern] type to construct [`DropTarget`] objects.
///
/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
#[must_use = "The builder must be built to be used"]
pub struct DropTargetBuilder {
    builder: glib::object::ObjectBuilder<'static, DropTarget>,
}

impl DropTargetBuilder {
    fn new() -> Self {
        Self {
            builder: glib::object::Object::builder(),
        }
    }

    /// The `GdkDragActions` that this drop target supports.
    pub fn actions(self, actions: gdk::DragAction) -> Self {
        Self {
            builder: self.builder.property("actions", actions),
        }
    }

    /// The [`gdk::ContentFormats`][crate::gdk::ContentFormats] that determine the supported data formats.
    pub fn formats(self, formats: &gdk::ContentFormats) -> Self {
        Self {
            builder: self.builder.property("formats", formats.clone()),
        }
    }

    /// Whether the drop data should be preloaded when the pointer is only
    /// hovering over the widget but has not been released.
    ///
    /// Setting this property allows finer grained reaction to an ongoing
    /// drop at the cost of loading more data.
    ///
    /// The default value for this property is [`false`] to avoid downloading
    /// huge amounts of data by accident.
    ///
    /// For example, if somebody drags a full document of gigabytes of text
    /// from a text editor across a widget with a preloading drop target,
    /// this data will be downloaded, even if the data is ultimately dropped
    /// elsewhere.
    ///
    /// For a lot of data formats, the amount of data is very small (like
    /// `GDK_TYPE_RGBA`), so enabling this property does not hurt at all.
    /// And for local-only Drag-and-Drop operations, no data transfer is done,
    /// so enabling it there is free.
    pub fn preload(self, preload: bool) -> Self {
        Self {
            builder: self.builder.property("preload", preload),
        }
    }

    /// The name for this controller, typically used for debugging purposes.
    pub fn name(self, name: impl Into<glib::GString>) -> Self {
        Self {
            builder: self.builder.property("name", name.into()),
        }
    }

    /// The limit for which events this controller will handle.
    pub fn propagation_limit(self, propagation_limit: PropagationLimit) -> Self {
        Self {
            builder: self
                .builder
                .property("propagation-limit", propagation_limit),
        }
    }

    /// The propagation phase at which this controller will handle events.
    pub fn propagation_phase(self, propagation_phase: PropagationPhase) -> Self {
        Self {
            builder: self
                .builder
                .property("propagation-phase", propagation_phase),
        }
    }

    // rustdoc-stripper-ignore-next
    /// Build the [`DropTarget`].
    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
    pub fn build(self) -> DropTarget {
        assert_initialized_main_thread!();
        self.builder.build()
    }
}