[gtk+] widget: Export gtk_widget_set_cursor()

[Benjamin Otte <otte src gnome org>]

commit b38a4cb824a9ffeb83d88ccc7ca5f66ee4dfe05a
Author: Benjamin Otte <otte redhat com>
Date:   Sat Nov 4 00:58:57 2017 +0100

    widget: Export gtk_widget_set_cursor()
    
    Widgets can now set their favorite cursor using public API.
    
    This is very necessary because all cursor-setting APIs are still
    setting it on their GdkWindow, which by now is the toplevel - oops.

 docs/reference/gtk/gtk4-sections.txt |    3 +
 gtk/gtkwidget.c                      |   91 ++++++++++++++++++++++++++++++++++
 gtk/gtkwidget.h                      |    9 +++
 gtk/gtkwidgetprivate.h               |    4 --
 4 files changed, 103 insertions(+), 4 deletions(-)
---
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 60c29a6..fdbf953 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -4541,6 +4541,9 @@ gtk_widget_get_font_map
 gtk_widget_create_pango_layout
 gtk_widget_queue_draw_area
 gtk_widget_queue_draw_region
+gtk_widget_get_cursor
+gtk_widget_set_cursor
+gtk_widget_set_cursor_from_name
 gtk_widget_mnemonic_activate
 gtk_widget_send_focus_change
 gtk_widget_class_set_accessible_type
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index bdac230..70152b9 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -565,6 +565,7 @@ enum {
   PROP_CAN_DEFAULT,
   PROP_HAS_DEFAULT,
   PROP_RECEIVES_DEFAULT,
+  PROP_CURSOR,
   PROP_HAS_TOOLTIP,
   PROP_TOOLTIP_MARKUP,
   PROP_TOOLTIP_TEXT,
@@ -1189,6 +1190,20 @@ gtk_widget_class_init (GtkWidgetClass *klass)
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
 /**
+ * GtkWidget:cursor:
+ *
+ * The cursor used by @widget. See gtk_widget_set_cursor() for details.
+ *
+ * Since: 3.94
+ */
+  widget_props[PROP_CURSOR] =
+      g_param_spec_object("cursor",
+                          P_("Cursor"),
+                          P_("The cursor to show when hoving above widget"),
+                          GDK_TYPE_CURSOR,
+                          GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+
+/**
  * GtkWidget:has-tooltip:
  *
  * Enables or disables the emission of #GtkWidget::query-tooltip on @widget.
@@ -3205,6 +3220,9 @@ gtk_widget_set_property (GObject         *object,
     case PROP_RECEIVES_DEFAULT:
       gtk_widget_set_receives_default (widget, g_value_get_boolean (value));
       break;
+    case PROP_CURSOR:
+      gtk_widget_set_cursor (widget, g_value_get_object (value));
+      break;
     case PROP_HAS_TOOLTIP:
       gtk_widget_real_set_has_tooltip (widget,
                                       g_value_get_boolean (value), FALSE);
@@ -3371,6 +3389,9 @@ gtk_widget_get_property (GObject         *object,
     case PROP_RECEIVES_DEFAULT:
       g_value_set_boolean (value, gtk_widget_get_receives_default (widget));
       break;
+    case PROP_CURSOR:
+      g_value_set_object (value, gtk_widget_get_cursor (widget));
+      break;
     case PROP_HAS_TOOLTIP:
       g_value_set_boolean (value, gtk_widget_get_has_tooltip (widget));
       break;
@@ -15457,23 +15478,93 @@ gtk_widget_get_focus_child (GtkWidget *widget)
   return priv->focus_child;
 }
 
+/**
+ * gtk_widget_set_cursor:
+ * @widget: a #GtkWidget
+ * @cursor: (allow-none): the new cursor or %NULL to use the default
+ *     cursor
+ *
+ * Sets the cursor to be shown when pointer devices point towards @widget.
+ *
+ * If the @cursor is NULL, @widget will use the cursor specified via CSS
+ * or the parent widget. If neither specifies a cursor, the default cursor
+ * will be shown. This is the default behavior.
+ *
+ * Since: 3.94
+ **/
 void
 gtk_widget_set_cursor (GtkWidget *widget,
                        GdkCursor *cursor)
 {
   GtkWidget *toplevel;
 
+  g_return_if_fail (GTK_IS_WIDGET (widget));
+  g_return_if_fail (cursor == NULL || GDK_IS_CURSOR (cursor));
+
   if (!g_set_object (&widget->priv->cursor, cursor))
     return;
 
   toplevel = gtk_widget_get_toplevel (widget);
   if (GTK_IS_WINDOW (toplevel))
     gtk_window_maybe_update_cursor (GTK_WINDOW (toplevel), widget, NULL);
+
+  g_object_notify_by_pspec (G_OBJECT (widget), widget_props[PROP_CURSOR]);
 }
 
+/**
+ * gtk_widget_set_cursor_from_name:
+ * @widget: a #GtkWidget
+ * @name: (allow-none): The name of the cursor or %NULL to use the default
+ *     cursor
+ *
+ * Sets a named cursor to be shown when pointer devices point towards @widget.
+ *
+ * This is a utility function that calls creates a cursor via
+ * gdk_cursor_new_from_name() and then sets it on @widget with
+ * gtk_widget_set_cursor(). See those 2 functions for details.
+ *
+ * On top of that, this function allows @name to be %NULL, which will
+ * do the same as calling gtk_widget_set_cursor() with a %NULL cursor.
+ *
+ * Since: 3.94
+ **/
+void
+gtk_widget_set_cursor_from_name (GtkWidget  *widget,
+                                 const char *name)
+{
+  g_return_if_fail (GTK_IS_WIDGET (widget));
+
+  if (name)
+    {
+      GdkCursor *cursor;
+
+      cursor = gdk_cursor_new_from_name (name, NULL);
+      gtk_widget_set_cursor (widget, cursor);
+      g_object_unref (cursor);
+    }
+  else
+    {
+      gtk_widget_set_cursor (widget, NULL);
+    }
+}
+
+/**
+ * gtk_widget_get_cursor:
+ * @widget: a #GtkWidget
+ *
+ * Queries the cursor set via gtk_widget_set_cursor(). See that function for
+ * details.
+ *
+ * Returns: (nullable) (transfer none): the cursor curently in use or %NULL
+ *     to use the default.
+ *
+ * Since: 3.94
+ **/
 GdkCursor *
 gtk_widget_get_cursor (GtkWidget *widget)
 {
+  g_return_val_if_fail (GTK_IS_WIDGET (widget), NULL);
+
   return widget->priv->cursor;
 }
 
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index 243e80d..0f4a785 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -937,6 +937,15 @@ GDK_AVAILABLE_IN_ALL
 void        gtk_widget_input_shape_combine_region (GtkWidget *widget,
                                                     cairo_region_t *region);
 
+GDK_AVAILABLE_IN_3_94
+void                    gtk_widget_set_cursor                   (GtkWidget              *widget,
+                                                                 GdkCursor              *cursor);
+GDK_AVAILABLE_IN_3_94
+void                    gtk_widget_set_cursor_from_name         (GtkWidget              *widget,
+                                                                 const char             *name);
+GDK_AVAILABLE_IN_3_94
+GdkCursor *             gtk_widget_get_cursor                   (GtkWidget              *widget);
+
 GDK_AVAILABLE_IN_ALL
 GList* gtk_widget_list_mnemonic_labels  (GtkWidget *widget);
 GDK_AVAILABLE_IN_ALL
diff --git a/gtk/gtkwidgetprivate.h b/gtk/gtkwidgetprivate.h
index 3db75b1..e528e8a 100644
--- a/gtk/gtkwidgetprivate.h
+++ b/gtk/gtkwidgetprivate.h
@@ -326,10 +326,6 @@ void              gtk_widget_get_window_allocation         (GtkWidget *widget,
 GtkWidget *       gtk_widget_common_ancestor               (GtkWidget *widget_a,
                                                             GtkWidget *widget_b);
 
-void              gtk_widget_set_cursor                    (GtkWidget *widget,
-                                                            GdkCursor *cursor);
-GdkCursor *       gtk_widget_get_cursor                    (GtkWidget *widget);
-
 void              gtk_widget_set_pass_through              (GtkWidget *widget,
                                                             gboolean   pass_through);
 gboolean          gtk_widget_get_pass_through              (GtkWidget *widget);