Make focus helpers availablefocus-helpers

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.

3 files changed, 67 insertions, 9 deletions

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 21f666c601..3ff97347d4 100644
--- a/gtk/gtkwidget.c
+++ b/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)
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index d02521a4f4..de8041a54f 100644
--- a/gtk/gtkwidget.h
+++ b/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)
 
diff --git a/gtk/gtkwidgetprivate.h b/gtk/gtkwidgetprivate.h
index d902e7117f..b33c4a794c 100644
--- a/gtk/gtkwidgetprivate.h
+++ b/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);