Make focus helpers available

These functions are very useful in implementing
common cases for focus handling in composite widgets.
libadwaita and a few other places are copying them
now. We might as well make them available and
make everybody's life easier.

gdk/gdkversionmacros.h.in

@@ -128,6 +128,16 @@
  */
 #define GDK_VERSION_4_10        (G_ENCODE_VERSION (4, 10))
 
+/**
+ * GDK_VERSION_4_12:
+ *
+ * A macro that evaluates to the 4.12 version of GDK, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 4.12
+ */
+#define GDK_VERSION_4_12        (G_ENCODE_VERSION (4, 12))
+
 
 /* evaluates to the current stable version; for development cycles,
  * this means the next stable target, with a hard backstop to the
@@ -297,4 +307,18 @@
 # define GDK_DEPRECATED_IN_4_10_FOR(f)          _GDK_EXTERN
 #endif
 
+#if GDK_VERSION_MAX_ALLOWED < GDK_VERSION_4_12
+# define GDK_AVAILABLE_IN_4_12                  GDK_UNAVAILABLE(4, 12)
+#else
+# define GDK_AVAILABLE_IN_4_12                  _GDK_EXTERN
+#endif
+
+#if GDK_VERSION_MIN_REQUIRED >= GDK_VERSION_4_12
+# define GDK_DEPRECATED_IN_4_12                 GDK_DEPRECATED
+# define GDK_DEPRECATED_IN_4_12_FOR(f)          GDK_DEPRECATED_FOR(f)
+#else
+# define GDK_DEPRECATED_IN_4_12                 _GDK_EXTERN
+# define GDK_DEPRECATED_IN_4_12_FOR(f)          _GDK_EXTERN
+#endif
+
 #endif  /* __GDK_VERSION_MACROS_H__ */

gtk/gtkwidget.c

@@ -4868,6 +4868,19 @@ gtk_widget_grab_focus (GtkWidget *widget)
   return GTK_WIDGET_GET_CLASS (widget)->grab_focus (widget);
 }
 
+/**
+ * gtk_widget_grab_focus_self:
+ * @widget: a #GtkWidget
+ *
+ * A helper function for widget implementations.
+ *
+ * This function can be used as grab_focus vfunc implementation
+ * for focusable widgets with children that don't receive focus.
+ *
+ * Also see [method@Gtk.Widget.focus_self].
+ *
+ * Since: 4.12
+ */
 gboolean
 gtk_widget_grab_focus_self (GtkWidget *widget)
 {
@@ -4881,6 +4894,19 @@ gtk_widget_grab_focus_self (GtkWidget *widget)
   return TRUE;
 }
 
+/**
+ * gtk_widget_grab_focus_child:
+ * @widget: a #GtkWidget
+ *
+ * A helper function for widget implementations.
+ *
+ * This function can be used as grab_focus vfunc implementation
+ * for non-focusable widgets with children that receive focus.
+ *
+ * Also see [method@Gtk.Widget.focus_child].
+ *
+ * Since: 4.12
+ */
 gboolean
 gtk_widget_grab_focus_child (GtkWidget *widget)
 {
@@ -5051,6 +5077,21 @@ gtk_widget_real_focus (GtkWidget        *widget,
     }
 }
 
+/**
+ * gtk_widget_focus_self:
+ * @widget: a #GtkWidget
+ *
+ * A helper function for widget implementations.
+ *
+ * This function can be used as focus vfunc implementation
+ * for focusable widgets with children that don't receive focus.
+ *
+ * Also see [method@Gtk.Widget.grab_focus_self].
+ *
+ * Returns: whether the focus was moved.
+ *
+ * Since: 4.12
+ */
 gboolean
 gtk_widget_focus_self (GtkWidget         *widget,
                        GtkDirectionType   direction)
@@ -5063,6 +5104,21 @@ gtk_widget_focus_self (GtkWidget         *widget,
   return FALSE;
 }
 
+/**
+ * gtk_widget_focus_child:
+ * @widget: a #GtkWidget
+ *
+ * A helper function for widget implementations.
+ *
+ * This function can be used as focus vfunc implementation
+ * for non-focusable widgets with children that receive focus.
+ *
+ * Also see [method@Gtk.Widget.grab_focus_child].
+ *
+ * Returns: whether the focus was moved.
+ *
+ * Since: 4.12
+ */
 gboolean
 gtk_widget_focus_child (GtkWidget         *widget,
                         GtkDirectionType   direction)

gtk/gtkwidget.h

@@ -979,6 +979,17 @@ void                    gtk_widget_class_set_accessible_role    (GtkWidgetClass
 GDK_AVAILABLE_IN_ALL
 GtkAccessibleRole       gtk_widget_class_get_accessible_role    (GtkWidgetClass    *widget_class);
 
+GDK_AVAILABLE_IN_4_12
+gboolean                gtk_widget_grab_focus_child             (GtkWidget        *widget);
+GDK_AVAILABLE_IN_4_12
+gboolean                gtk_widget_focus_child                  (GtkWidget        *widget,
+                                                                 GtkDirectionType  direction);
+GDK_AVAILABLE_IN_4_12
+gboolean                gtk_widget_grab_focus_self              (GtkWidget        *widget);
+GDK_AVAILABLE_IN_4_12
+gboolean                gtk_widget_focus_self                   (GtkWidget        *widget,
+                                                                 GtkDirectionType  direction);
+
 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GtkWidget, g_object_unref)
 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GtkRequisition, gtk_requisition_free)
 

gtk/gtkwidgetprivate.h

@@ -355,15 +355,6 @@ void              gtk_widget_remove_surface_transform_changed_callback (GtkWidge
 
 gboolean          gtk_widget_can_activate       (GtkWidget *widget);
 
-/* focus vfuncs for non-focusable containers with focusable children */
-gboolean gtk_widget_grab_focus_child (GtkWidget        *widget);
-gboolean gtk_widget_focus_child      (GtkWidget        *widget,
-                                      GtkDirectionType  direction);
-/* focus vfuncs for focusable widgets with children that don't receive focus */
-gboolean gtk_widget_grab_focus_self  (GtkWidget        *widget);
-gboolean gtk_widget_focus_self       (GtkWidget        *widget,
-                                      GtkDirectionType  direction);
-
 void    gtk_widget_update_orientation   (GtkWidget      *widget,
                                          GtkOrientation  orientation);