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.

1 files changed, 56 insertions, 0 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)