[gtkmm] Gdk::Drag, Gdk::Drop: Improve the class descriptions



commit 4172ee7e5ff46be54cbdb313466a2b2ad9aeea58
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Mon Jul 4 16:35:08 2022 +0200

    Gdk::Drag, Gdk::Drop: Improve the class descriptions

 gdk/src/drag.hg | 11 +++++++++--
 gdk/src/drop.hg | 16 ++++++++++++++--
 2 files changed, 23 insertions(+), 4 deletions(-)
---
diff --git a/gdk/src/drag.hg b/gdk/src/drag.hg
index 3d549274..fee521d5 100644
--- a/gdk/src/drag.hg
+++ b/gdk/src/drag.hg
@@ -33,8 +33,15 @@ class GDKMM_API Surface;
 
 _WRAP_ENUM(DragCancelReason, GdkDragCancelReason, decl_prefix GDKMM_API)
 
-/** A %Gdk::Drag holds information about a drag in progress.
- * It is used on both source and destination sides.
+/** A %Gdk::Drag object represents the source of an ongoing DND operation.
+ *
+ * A %Gdk::Drag is created when a drag is started, and stays alive for the
+ * duration of the DND operation. After a drag has been started with
+ * Gdk::Surface::drag_begin_from_point(), the caller gets informed about the
+ * status of the ongoing drag operation with signals on the %Gdk::Drag object.
+ *
+ * GTK provides a higher level abstraction based on top of these functions,
+ * and so they are not normally needed in GTK applications.
  */
 class GDKMM_API Drag : public Glib::Object
 {
diff --git a/gdk/src/drop.hg b/gdk/src/drop.hg
index ded72b5a..cd9a1c0f 100644
--- a/gdk/src/drop.hg
+++ b/gdk/src/drop.hg
@@ -35,8 +35,20 @@ class GDKMM_API Drag;
 class GDKMM_API Display;
 class GDKMM_API Surface;
 
-/** A %Gdk::Drop holds information about a drag in progress.
- * It is used on the destination side.
+/** 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.
  *
  * @newin{3,94}
  */


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]