gtkmm 4.7.1

Public Member Functions | Static Public Member Functions | Related Functions | List of all members
Gdk::Drop Class Reference

A Gdk::Drop object represents the target of an ongoing DND operation. More...

`#include <gdkmm/drop.h>`

Inheritance diagram for Gdk::Drop:
[legend]

## Public Member Functions
| Drop (Drop && src) noexcept
Drop & | operator= (Drop && src) noexcept
| ~Drop () noexcept override
GdkDrop * | gobj ()
| Provides access to the underlying C GObject. More...
const GdkDrop * | gobj () const
| Provides access to the underlying C GObject. More...
GdkDrop * | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
Glib::RefPtr< Display > | get_display ()
| Gets the `Gdk::Display` that self was created for. More...
Glib::RefPtr< const Display > | get_display () const
| Gets the `Gdk::Display` that self was created for. More...
Glib::RefPtr< Device > | get_device ()
| Returns the `Gdk::Device` performing the drop. More...
Glib::RefPtr< const Device > | get_device () const
| Returns the `Gdk::Device` performing the drop. More...
Glib::RefPtr< Surface > | get_surface ()
| Returns the `Gdk::Surface` performing the drop. More...
Glib::RefPtr< const Surface > | get_surface () const
| Returns the `Gdk::Surface` performing the drop. More...
Glib::RefPtr< ContentFormats > | get_formats ()
| Returns the `Gdk::ContentFormats` that the drop offers the data to be read in. More...
Glib::RefPtr< const ContentFormats > | get_formats () const
| Returns the `Gdk::ContentFormats` that the drop offers the data to be read in. More...
DragAction | get_actions () const
| Returns the possible actions for this `Gdk::Drop`. More...
Glib::RefPtr< Drag > | get_drag ()
| If this is an in-app drag-and-drop operation, returns the `Gdk::Drag` that corresponds to this drop. More...
Glib::RefPtr< const Drag > | get_drag () const
| If this is an in-app drag-and-drop operation, returns the `Gdk::Drag` that corresponds to this drop. More...
void | status (DragAction actions, DragAction preferred)
| Selects all actions that are potentially supported by the destination. More...
void | refuse ()
| Indicates that a drop will not be accepted. More...
void | finish (DragAction action)
| Ends the drag operation after a drop. More...
void | failed ()
| Ends the drag operation and indicates that the operation failed. More...
void | read_async (const std::vector< Glib::ustring > & mime_types, int io_priority, const Gio::SlotAsyncReady & slot, const Glib::RefPtr< Gio::Cancellable > & cancellable)
| Asynchronously read the dropped data from a `Gdk::Drop` in a format that complies with one of the mime types. More...
void | read_async (const std::vector< Glib::ustring > & mime_types, int io_priority, const Gio::SlotAsyncReady & slot)
| A read_async() convenience overload. More...
Glib::RefPtr< Gio::InputStream > | read_finish (const Glib::RefPtr< Gio::AsyncResult > & result, Glib::ustring & out_mime_type)
| Finishes an async drop read operation. More...
void | read_value_async (GType type, int io_priority, const Gio::SlotAsyncReady & slot, const Glib::RefPtr< Gio::Cancellable > & cancellable)
| Asynchronously request the drag operation's contents converted to the given type. More...
void | read_value_async (GType type, int io_priority, const Gio::SlotAsyncReady & slot)
| A read_value_async() convenience overload. More...
Glib::ValueBase | read_value_finish (const Glib::RefPtr< Gio::AsyncResult > & result)
| Finishes an async drop read. More...
Glib::PropertyProxy_ReadOnly< DragAction > | property_actions () const
| The possible actions for this drop. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Device > > | property_device () const
| The `Gdk::Device` performing the drop. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Display > > | property_display () const
| The `Gdk::Display` that the drop belongs to. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Drag > > | property_drag () const
| The `Gdk::Drag` that initiated this drop. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< ContentFormats > > | property_formats () const
| The possible formats that the drop can provide its data in. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Surface > > | property_surface () const
| The `Gdk::Surface` the drop happens on. More...
Public Member Functions inherited from Glib::Object
| Object (const Object &)=delete
Object & | operator= (const Object &)=delete
| Object (Object &&src) noexcept
Object & | operator= (Object &&src) noexcept
void * | get_data (const QueryQuark &key)
void | set_data (const Quark &key, void *data)
void | set_data (const Quark &key, void *data, DestroyNotify notify)
void | remove_data (const QueryQuark &quark)
void * | steal_data (const QueryQuark &quark)
Glib::RefPtr< Glib::Object > | wrap (GObject *object, bool take_copy=false)
Public Member Functions inherited from Glib::ObjectBase
| ObjectBase (const ObjectBase &)=delete
ObjectBase & | operator= (const ObjectBase &)=delete
void | set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)
void | get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const
void | set_property (const Glib::ustring &property_name, const PropertyType &value)
void | get_property (const Glib::ustring &property_name, PropertyType &value) const
PropertyType | get_property (const Glib::ustring &property_name) const
sigc::connection | connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void()> &slot)
sigc::connection | connect_property_changed (const Glib::ustring &property_name, sigc::slot< void()> &&slot)
void | freeze_notify ()
void | thaw_notify ()
virtual void | reference () const
virtual void | unreference () const
GObject * | gobj ()
const GObject * | gobj () const
GObject * | gobj_copy () const
Public Member Functions inherited from sigc::trackable
| trackable () noexcept
| trackable (const trackable &src) noexcept
| trackable (trackable &&src) noexcept
| ~trackable ()
void | add_destroy_notify_callback (notifiable *data, func_destroy_notify func) const
void | notify_callbacks ()
trackable & | operator= (const trackable &src)
trackable & | operator= (trackable &&src) noexcept
void | remove_destroy_notify_callback (notifiable *data) const

## Static Public Member Functions
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...

## Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Gdk::Drop > | wrap (GdkDrop * object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Additional Inherited Members
Public Types inherited from Glib::Object
typedef void(*)(gpointer data | DestroyNotify)
Public Types inherited from sigc::trackable
typedef internal::func_destroy_notify | func_destroy_notify
Public Types inherited from sigc::notifiable
typedef internal::func_destroy_notify | func_destroy_notify
Protected Member Functions inherited from Glib::Object
| Object ()
| Object (const Glib::ConstructParams &construct_params)
| Object (GObject *castitem)
| ~Object () noexcept override
Protected Member Functions inherited from Glib::ObjectBase
| ObjectBase ()
| ObjectBase (const char *custom_type_name)
| ObjectBase (const std::type_info &custom_type_info)
| ObjectBase (ObjectBase &&src) noexcept
ObjectBase & | operator= (ObjectBase &&src) noexcept
virtual | ~ObjectBase () noexcept=0
void | initialize (GObject *castitem)
void | initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)

## Detailed Description

A Gdk::Drop object represents the target of an ongoing DND operation.

Possible drop sites get informed about the status of the ongoing drag operation with events of type Gdk::Event::Type::DRAG_ENTER, Gdk::Event::Type::DRAG_LEAVE, Gdk::Event::Type::DRAG_MOTION and Gdk::Event::Type::DROP_START. The Gdk::Drop object can be obtained from a DND event using Gdk::Event::get_dnd_drop().

The actual data transfer is initiated from the target side via an async read, using one of the Gdk::Drop methods for this purpose: read_async() or read_value_async().

GTK provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK applications.

Since gtkmm 3.94:

## Constructor & Destructor Documentation

## ◆ Drop()

Gdk::Drop::Drop | ( | Drop && | src | ) |
| noexcept

## ◆ ~Drop()

Gdk::Drop::~Drop | ( |  | ) |
| override noexcept

## Member Function Documentation

## ◆ failed()

void Gdk::Drop::failed | ( |  | ) |

Ends the drag operation and indicates that the operation failed.

Alternatively, call finish() to indicate which drag action was performed.

## ◆ finish()

void Gdk::Drop::finish | ( | DragAction | action | ) |

Ends the drag operation after a drop.

The action must be a single action selected from the actions available via get_actions().

Parameters

  action | The action performed by the destination or 0 if the drop failed.

## ◆ get_actions()

DragAction Gdk::Drop::get_actions | ( |  | ) | const

Returns the possible actions for this `Gdk::Drop`.

If this value contains multiple actions - i.e. Gdk::Drag::action_is_unique() returns `false` for the result - finish() must choose the action to use when accepting the drop. This will only happen if you passed Gdk::DragAction::ASK as one of the possible actions in status(). Gdk::DragAction::ASK itself will not be included in the actions returned by this function.

This value may change over the lifetime of the Gdk::Drop both as a response to source side actions as well as to calls to status() or finish(). The source side will not change this value anymore once a drop has started.

Returns
  The possible `Gdk::DragActions`.

## ◆ get_device() [1/2]

Glib::RefPtr<Device> Gdk::Drop::get_device | ( |  | ) |

Returns the `Gdk::Device` performing the drop.

Returns
  The `Gdk::Device` performing the drop.

## ◆ get_device() [2/2]

Glib::RefPtr<const Device> Gdk::Drop::get_device | ( |  | ) | const

Returns the `Gdk::Device` performing the drop.

Returns
  The `Gdk::Device` performing the drop.

## ◆ get_display() [1/2]

Glib::RefPtr<Display> Gdk::Drop::get_display | ( |  | ) |

Gets the `Gdk::Display` that self was created for.

Returns
  A `Gdk::Display`.

## ◆ get_display() [2/2]

Glib::RefPtr<const Display> Gdk::Drop::get_display | ( |  | ) | const

Gets the `Gdk::Display` that self was created for.

Returns
  A `Gdk::Display`.

## ◆ get_drag() [1/2]

Glib::RefPtr<Drag> Gdk::Drop::get_drag | ( |  | ) |

If this is an in-app drag-and-drop operation, returns the `Gdk::Drag` that corresponds to this drop.

If it is not, `nullptr` is returned.

Returns
  The corresponding `Gdk::Drag`.

## ◆ get_drag() [2/2]

Glib::RefPtr<const Drag> Gdk::Drop::get_drag | ( |  | ) | const

If this is an in-app drag-and-drop operation, returns the `Gdk::Drag` that corresponds to this drop.

If it is not, `nullptr` is returned.

Returns
  The corresponding `Gdk::Drag`.

## ◆ get_formats() [1/2]

Glib::RefPtr<ContentFormats> Gdk::Drop::get_formats | ( |  | ) |

Returns the `Gdk::ContentFormats` that the drop offers the data to be read in.

Returns
  The possible `Gdk::ContentFormats`.

## ◆ get_formats() [2/2]

Glib::RefPtr<const ContentFormats> Gdk::Drop::get_formats | ( |  | ) | const

Returns the `Gdk::ContentFormats` that the drop offers the data to be read in.

Returns
  The possible `Gdk::ContentFormats`.

## ◆ get_surface() [1/2]

Glib::RefPtr<Surface> Gdk::Drop::get_surface | ( |  | ) |

Returns the `Gdk::Surface` performing the drop.

Returns
  The `Gdk::Surface` performing the drop.

## ◆ get_surface() [2/2]

Glib::RefPtr<const Surface> Gdk::Drop::get_surface | ( |  | ) | const

Returns the `Gdk::Surface` performing the drop.

Returns
  The `Gdk::Surface` performing the drop.

## ◆ get_type()

static GType Gdk::Drop::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

## ◆ gobj() [1/2]

GdkDrop* Gdk::Drop::gobj | ( |  | ) |
| inline

Provides access to the underlying C GObject.

## ◆ gobj() [2/2]

const GdkDrop* Gdk::Drop::gobj | ( |  | ) | const
| inline

Provides access to the underlying C GObject.

## ◆ gobj_copy()

GdkDrop* Gdk::Drop::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

## ◆ operator=()

Drop& Gdk::Drop::operator= | ( | Drop && | src | ) |
| noexcept

## ◆ property_actions()

Glib::PropertyProxy_ReadOnly< DragAction > Gdk::Drop::property_actions | ( |  | ) | const

The possible actions for this drop.

Default value: Gdk::DragAction::COPY | Gdk::DragAction::MOVE | Gdk::DragAction::LINK

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_device()

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Device> > Gdk::Drop::property_device | ( |  | ) | const

The `Gdk::Device` performing the drop.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_display()

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Display> > Gdk::Drop::property_display | ( |  | ) | const

The `Gdk::Display` that the drop belongs to.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_drag()

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Drag> > Gdk::Drop::property_drag | ( |  | ) | const

The `Gdk::Drag` that initiated this drop.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_formats()

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<ContentFormats> > Gdk::Drop::property_formats | ( |  | ) | const

The possible formats that the drop can provide its data in.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_surface()

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Surface> > Gdk::Drop::property_surface | ( |  | ) | const

The `Gdk::Surface` the drop happens on.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ read_async() [1/2]

void Gdk::Drop::read_async | ( | const std::vector< Glib::ustring > & | mime_types,
|  | int | io_priority,
|  | const Gio::SlotAsyncReady & | slot
| ) |  |

A read_async() convenience overload.

## ◆ read_async() [2/2]

void Gdk::Drop::read_async | ( | const std::vector< Glib::ustring > & | mime_types,
|  | int | io_priority,
|  | const Gio::SlotAsyncReady & | slot,
|  | const Glib::RefPtr< Gio::Cancellable > & | cancellable
| ) |  |

Asynchronously read the dropped data from a `Gdk::Drop` in a format that complies with one of the mime types.

Parameters

  mime_types | Pointer to an array of mime types.
  io_priority | The I/O priority for the read operation.
  cancellable | Optional `Gio::Cancellable` object.
  slot | A `SlotAsyncReady` to call when the request is satisfied.

## ◆ read_finish()

Glib::RefPtr<Gio::InputStream> Gdk::Drop::read_finish | ( | const Glib::RefPtr< Gio::AsyncResult > & | result,
|  | Glib::ustring & | out_mime_type
| ) |  |

Finishes an async drop read operation.

Note that you must not use blocking read calls on the returned stream in the GTK thread, since some platforms might require communication with GTK to complete the data transfer. You can use async APIs such as Glib::input_stream_read_bytes_async().

See read_async().

Parameters

  result | A `Gio::AsyncResult`.
  out_mime_type | Return location for the used mime type.

Returns
  The `Gio::InputStream`.

Exceptions

  Glib::Error |

## ◆ read_value_async() [1/2]

void Gdk::Drop::read_value_async | ( | GType | type,
|  | int | io_priority,
|  | const Gio::SlotAsyncReady & | slot
| ) |  |

A read_value_async() convenience overload.

## ◆ read_value_async() [2/2]

void Gdk::Drop::read_value_async | ( | GType | type,
|  | int | io_priority,
|  | const Gio::SlotAsyncReady & | slot,
|  | const Glib::RefPtr< Gio::Cancellable > & | cancellable
| ) |  |

Asynchronously request the drag operation's contents converted to the given type.

When the operation is finished slot will be called. You must then call read_value_finish() to get the resulting `Glib::Value`.

For local drag-and-drop operations that are available in the given `GType`, the value will be copied directly. Otherwise, GDK will try to use gdk_content_deserialize_async() to convert the data.

Parameters

  type | A `GType` to read.
  io_priority | The I/O priority of the request.
  cancellable | Optional `Gio::Cancellable` object, `nullptr` to ignore.
  slot | Callback to call when the request is satisfied.

## ◆ read_value_finish()

Glib::ValueBase Gdk::Drop::read_value_finish | ( | const Glib::RefPtr< Gio::AsyncResult > & | result | ) |

Finishes an async drop read.

See read_value_async().

Parameters

  result | A `Gio::AsyncResult`.

Returns
  A `Glib::Value` containing the result.

## ◆ refuse()

void Gdk::Drop::refuse | ( |  | ) |

Indicates that a drop will not be accepted.

This function may be called by the drag destination in response to Gdk::Event::Type::DRAG_ENTER or Gdk::Event::Type::DRAG_MOTION events. Alternatively, call status() to indicate which drag actions will be accepted.

## ◆ status()

void Gdk::Drop::status | ( | DragAction | actions,
|  | DragAction | preferred
| ) |  |

Selects all actions that are potentially supported by the destination.

When calling this function, do not restrict the passed in actions to the ones provided by get_actions(). Those actions may change in the future, even depending on the actions you provide here.

The preferred action is a hint to the drag-and-drop mechanism about which action to use when multiple actions are possible.

This function should be called by drag destinations in response to Gdk::Event::Type::DRAG_ENTER or Gdk::Event::Type::DRAG_MOTION events. If the destination does not yet know the exact actions it supports, it should set any possible actions first and then later call this function again.

Parameters

  actions | Supported actions of the destination, or 0 to indicate that a drop will not be accepted.
  preferred | A unique action that's a member of actions indicating the preferred action.

## Friends And Related Function Documentation

## ◆ wrap()

Glib::RefPtr< Gdk::Drop > wrap | ( | GdkDrop * | object,
|  | bool | take_copy = `false`
| ) |  |
| related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.