Revert "Remove gdk_device_grab/ungrab from the API"

This reverts commit efc37d08556ed8516442a18a67e3035f13cf05a7.

Turns out we need to clean up the dnd code some more, first.

6 files changed, 94 insertions, 24 deletions

diff --git a/docs/reference/gdk/gdk4-sections.txt b/docs/reference/gdk/gdk4-sections.txt
index c413044d44..f5b3c6dcf6 100644
--- a/docs/reference/gdk/gdk4-sections.txt
+++ b/docs/reference/gdk/gdk4-sections.txt
@@ -699,6 +699,10 @@ gdk_device_warp
 gdk_device_get_seat
 
 <SUBSECTION>
+gdk_device_grab
+gdk_device_ungrab
+
+<SUBSECTION>
 gdk_device_get_state
 gdk_device_get_position
 gdk_device_get_position_double
diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index 56080b92c2..13451a5400 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -544,7 +544,7 @@ gdk_device_get_property (GObject    *object,
  * Gets the current state of a pointer device relative to @window. As a slave
  * device’s coordinates are those of its master pointer, this
  * function may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE,
- * unless there is an ongoing grab on them. See gdk_seat_grab().
+ * unless there is an ongoing grab on them. See gdk_device_grab().
  */
 void
 gdk_device_get_state (GdkDevice       *device,
@@ -573,7 +573,7 @@ gdk_device_get_state (GdkDevice       *device,
  * Gets the current location of @device in double precision. As a slave device's
  * coordinates are those of its master pointer, this function
  * may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE,
- * unless there is an ongoing grab on them. See gdk_seat_grab().
+ * unless there is an ongoing grab on them. See gdk_device_grab().
  *
  * Since: 3.10
  **/
@@ -623,7 +623,7 @@ gdk_device_get_position_double (GdkDevice        *device,
  * Gets the current location of @device. As a slave device
  * coordinates are those of its master pointer, This function
  * may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE,
- * unless there is an ongoing grab on them, see gdk_seat_grab().
+ * unless there is an ongoing grab on them, see gdk_device_grab().
  *
  * Since: 3.0
  **/
@@ -657,7 +657,7 @@ gdk_device_get_position (GdkDevice        *device,
  *
  * As a slave device coordinates are those of its master pointer, This
  * function may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE,
- * unless there is an ongoing grab on them, see gdk_seat_grab().
+ * unless there is an ongoing grab on them, see gdk_device_grab().
  *
  * Returns: (nullable) (transfer none): the #GdkWindow under the
  *   device position, or %NULL.
@@ -707,7 +707,7 @@ gdk_device_get_window_at_position_double (GdkDevice  *device,
  *
  * As a slave device coordinates are those of its master pointer, This
  * function may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE,
- * unless there is an ongoing grab on them, see gdk_seat_grab().
+ * unless there is an ongoing grab on them, see gdk_device_grab().
  *
  * Returns: (nullable) (transfer none): the #GdkWindow under the
  * device position, or %NULL.
@@ -1386,6 +1386,58 @@ get_native_grab_event_mask (GdkEventMask grab_mask)
        GDK_BUTTON3_MOTION_MASK));
 }
 
+/**
+ * gdk_device_grab:
+ * @device: a #GdkDevice. To get the device you can use gtk_get_current_event_device()
+ *   or gdk_event_get_device() if the grab is in reaction to an event. Also, you can use
+ *   gdk_device_manager_get_client_pointer() but only in code that isn’t triggered by a
+ *   #GdkEvent and there aren’t other means to get a meaningful #GdkDevice to operate on.
+ * @window: the #GdkWindow which will own the grab (the grab window)
+ * @grab_ownership: specifies the grab ownership.
+ * @owner_events: if %FALSE then all device events are reported with respect to
+ *                @window and are only reported if selected by @event_mask. If
+ *                %TRUE then pointer events for this application are reported
+ *                as normal, but pointer events outside this application are
+ *                reported with respect to @window and only if selected by
+ *                @event_mask. In either mode, unreported events are discarded.
+ * @event_mask: specifies the event mask, which is used in accordance with
+ *              @owner_events.
+ * @cursor: (allow-none): the cursor to display while the grab is active if the device is
+ *          a pointer. If this is %NULL then the normal cursors are used for
+ *          @window and its descendants, and the cursor for @window is used
+ *          elsewhere.
+ * @time_: the timestamp of the event which led to this pointer grab. This
+ *         usually comes from the #GdkEvent struct, though %GDK_CURRENT_TIME
+ *         can be used if the time isn’t known.
+ *
+ * Grabs the device so that all events coming from this device are passed to
+ * this application until the device is ungrabbed with gdk_device_ungrab(),
+ * or the window becomes unviewable. This overrides any previous grab on the device
+ * by this client.
+ *
+ * Note that @device and @window need to be on the same display.
+ *
+ * Device grabs are used for operations which need complete control over the
+ * given device events (either pointer or keyboard). For example in GTK+ this
+ * is used for Drag and Drop operations, popup menus and such.
+ *
+ * Note that if the event mask of an X window has selected both button press
+ * and button release events, then a button press event will cause an automatic
+ * pointer grab until the button is released. X does this automatically since
+ * most applications expect to receive button press and release events in pairs.
+ * It is equivalent to a pointer grab on the window with @owner_events set to
+ * %TRUE.
+ *
+ * If you set up anything at the time you take the grab that needs to be
+ * cleaned up when the grab ends, you should handle the #GdkEventGrabBroken
+ * events that are emitted when the grab ends unvoluntarily.
+ *
+ * Returns: %GDK_GRAB_SUCCESS if the grab was successful.
+ *
+ * Since: 3.0
+ *
+ * Deprecated: 3.20. Use gdk_seat_grab() instead.
+ **/
 GdkGrabStatus
 gdk_device_grab (GdkDevice        *device,
                  GdkWindow        *window,
@@ -1438,6 +1490,17 @@ gdk_device_grab (GdkDevice        *device,
   return res;
 }
 
+/**
+ * gdk_device_ungrab:
+ * @device: a #GdkDevice
+ * @time_: a timestap (e.g. %GDK_CURRENT_TIME).
+ *
+ * Release any grab on @device.
+ *
+ * Since: 3.0
+ *
+ * Deprecated: 3.20. Use gdk_seat_ungrab() instead.
+ */
 void
 gdk_device_ungrab (GdkDevice  *device,
                    guint32     time_)
diff --git a/gdk/gdkdevice.h b/gdk/gdkdevice.h
index 1fc9a6b0b4..c9ca3c6fd8 100644
--- a/gdk/gdkdevice.h
+++ b/gdk/gdkdevice.h
@@ -226,6 +226,19 @@ GList *      gdk_device_list_slave_devices    (GdkDevice     *device);
 GDK_AVAILABLE_IN_ALL
 GdkDeviceType gdk_device_get_device_type (GdkDevice *device);
 
+GDK_DEPRECATED_IN_3_20_FOR(gdk_seat_grab)
+GdkGrabStatus gdk_device_grab        (GdkDevice        *device,
+                                      GdkWindow        *window,
+                                      GdkGrabOwnership  grab_ownership,
+                                      gboolean          owner_events,
+                                      GdkEventMask      event_mask,
+                                      GdkCursor        *cursor,
+                                      guint32           time_);
+
+GDK_DEPRECATED_IN_3_20_FOR(gdk_seat_ungrab)
+void          gdk_device_ungrab      (GdkDevice        *device,
+                                      guint32           time_);
+
 GDK_AVAILABLE_IN_ALL
 void          gdk_device_warp        (GdkDevice        *device,
                                       GdkScreen        *screen,
diff --git a/gdk/gdkdeviceprivate.h b/gdk/gdkdeviceprivate.h
index ff84e28c50..22d5097d12 100644
--- a/gdk/gdkdeviceprivate.h
+++ b/gdk/gdkdeviceprivate.h
@@ -193,18 +193,6 @@ void           gdk_device_update_tool (GdkDevice     *device,
 
 GdkInputMode gdk_device_get_input_mode (GdkDevice *device);
 
-GdkGrabStatus gdk_device_grab        (GdkDevice        *device,
-                                      GdkWindow        *window,
-                                      GdkGrabOwnership  grab_ownership,
-                                      gboolean          owner_events,
-                                      GdkEventMask      event_mask,
-                                      GdkCursor        *cursor,
-                                      guint32           time_);
-
-void          gdk_device_ungrab      (GdkDevice        *device,
-                                      guint32           time_);
-
-
 G_END_DECLS
 
 #endif /* __GDK_DEVICE_PRIVATE_H__ */
diff --git a/gdk/gdkseatdefault.c b/gdk/gdkseatdefault.c
index a9411e238d..dc3f2887d3 100644
--- a/gdk/gdkseatdefault.c
+++ b/gdk/gdkseatdefault.c
@@ -18,7 +18,6 @@
  */
 
 #include "gdkseatdefaultprivate.h"
-#include "gdkdeviceprivate.h"
 #include "gdkdevicetoolprivate.h"
 
 typedef struct _GdkSeatDefaultPrivate GdkSeatDefaultPrivate;
diff --git a/gdk/x11/gdkdnd-x11.c b/gdk/x11/gdkdnd-x11.c
index 633fcc6ae0..89460744d1 100644
--- a/gdk/x11/gdkdnd-x11.c
+++ b/gdk/x11/gdkdnd-x11.c
@@ -29,7 +29,6 @@
 
 #include "gdkmain.h"
 #include "gdkinternals.h"
-#include "gdkdeviceprivate.h"
 #include "gdkasync.h"
 #include "gdkproperty.h"
 #include "gdkprivate-x11.h"
@@ -2817,11 +2816,15 @@ gdk_x11_drag_context_set_cursor (GdkDragContext *context,
     return;
 
   if (x11_context->grab_seat)
-    gdk_device_grab (gdk_seat_get_pointer (x11_context->grab_seat),
-                     x11_context->ipc_window,
-                     GDK_OWNERSHIP_APPLICATION, FALSE,
-                     GDK_POINTER_MOTION_MASK | GDK_BUTTON_RELEASE_MASK,
-                     cursor, GDK_CURRENT_TIME);
+    {
+      G_GNUC_BEGIN_IGNORE_DEPRECATIONS;
+      gdk_device_grab (gdk_seat_get_pointer (x11_context->grab_seat),
+                       x11_context->ipc_window,
+                       GDK_OWNERSHIP_APPLICATION, FALSE,
+                       GDK_POINTER_MOTION_MASK | GDK_BUTTON_RELEASE_MASK,
+                       cursor, GDK_CURRENT_TIME);
+      G_GNUC_END_IGNORE_DEPRECATIONS;
+    }
 }
 
 static void