docs: try to clarify widget_get_state_flags vs context_get_state

2 files changed, 10 insertions, 1 deletions

diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 26b578f713..dd242f139e 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -959,7 +959,12 @@ gtk_style_context_set_state (GtkStyleContext *context,
  * gtk_style_context_get_state:
  * @context: a #GtkStyleContext
  *
- * Returns the state used when rendering.
+ * Returns the state used when rendering. This method should
+ * only be used to retrieve the #GtkStateFlags to pass to
+ * #GtkStyleContext methods, like gtk_style_context_get_padding().
+ *
+ * If you need to retrieve the current state of a #GtkWidget you
+ * should look at gtk_widget_get_state_flags().
  *
  * Returns: the state flags
  *
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 564f795360..24a7249151 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -8968,6 +8968,10 @@ gtk_widget_unset_state_flags (GtkWidget     *widget,
  * returned, that is, also based on parent insensitivity, even if
  * @widget itself is sensitive.
  *
+ * Also note that if you are looking for a way to obtain the
+ * #GtkStateFlags to pass to a #GtkStyleContext method, you
+ * should look at gtk_style_context_get_state().
+ *
  * Returns: The state flags for widget
  *
  * Since: 3.0