[gtk+] docs: Clarify replacement for gtk_style_context_get_background_color()

[Emmanuele Bassi <ebassi src gnome org>]

commit 247e62390ba79746edb55a8b2b5278d34db6c33b
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sun Mar 8 14:29:04 2015 +0000

    docs: Clarify replacement for gtk_style_context_get_background_color()
    
    It seems odd that a getter function for the style context state is
    replaced by a rendering call, but it makes sense in context.

 gtk/gtkstylecontext.c |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 17e0c9b..59e158f 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -3246,6 +3246,15 @@ gtk_style_context_get_color (GtkStyleContext *context,
  *
  * Gets the background color for a given state.
  *
+ * This function is far less useful than it seems, and it should not be used in
+ * newly written code. CSS has no concept of "background color", as a background
+ * can be an image, or a gradient, or any other pattern including solid colors.
+ *
+ * The only reason why you would call gtk_style_context_get_background_color() is
+ * to use the returned value to draw the background with it; the correct way to
+ * achieve this result is to use gtk_render_background() instead, along with CSS
+ * style classes to modify the color to be rendered.
+ *
  * Since: 3.0
  *
  * Deprecated: 3.16: Use gtk_render_background() instead.