docs: Clarify gtk_widget_activate()ebassi/activate-signal

We need to tell people what signal will be emitted when calling
gtk_widget_activate(), and that the shortcuts API might be more
appropriate to what they are looking for.

1 files changed, 12 insertions, 3 deletions

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 61f1fabe3e..b2636ffa58 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -4659,9 +4659,18 @@ gtk_widget_class_set_activate_signal_from_name (GtkWidgetClass *widget_class,
  * @widget: a #GtkWidget that’s activatable
  *
  * For widgets that can be “activated” (buttons, menu items, etc.)
- * this function activates them. Activation is what happens when you
- * press Enter on a widget during key navigation. If @widget isn't
- * activatable, the function returns %FALSE.
+ * this function activates them. The activation will emit the signal
+ * set using gtk_widget_class_set_activate_signal() during class
+ * initialization.
+ *
+ * Activation is what happens when you press Enter on a widget during
+ * key navigation.
+ *
+ * If you wish to handle the activation keybinding yourself, it is
+ * recommended to use gtk_widget_class_add_shortcut() with an action
+ * created with gtk_signal_action_new().
+ *
+ * If @widget isn't activatable, the function returns %FALSE.
  *
  * Returns: %TRUE if the widget was activatable
  **/