[gtk+] Improve the migration guide

[Carlos Garnacho <carlosg src gnome org>]

commit ab0a8fc17f91a18ecca64c50f41bed7e1a8ce4fb
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Nov 24 21:09:23 2010 -0500

    Improve the migration guide
    
    Add some hints about dealing with colors.

 docs/reference/gtk/migrating-GtkStyleContext.xml |   32 ++++++++++++++++++++++
 1 files changed, 32 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gtk/migrating-GtkStyleContext.xml b/docs/reference/gtk/migrating-GtkStyleContext.xml
index b366e65..775fee0 100644
--- a/docs/reference/gtk/migrating-GtkStyleContext.xml
+++ b/docs/reference/gtk/migrating-GtkStyleContext.xml
@@ -140,6 +140,7 @@
       although custom widgets may define their own, which themes may
       attempt to handle.
     </para>
+
   </refsect2>
 
   <refsect2 id="gtk-migrating-GtkStyleContext-parser-extensions">
@@ -358,6 +359,37 @@
     </para>
 
     <para>
+      Access to colors has also changed a bit. With #GtkStyle, the common
+      way to access colors is:
+      <informalexample><programlisting>
+      GdkColor *color1;
+      GdkColor color2;
+
+      color1 = &amp;style->bg[GTK_STATE_PRELIGHT];
+      gtk_style_lookup_color (style, "focus_color", &amp;color2);
+      </programlisting></informalexample>
+      With #GtkStyleContext, you generally use #GdkRGBA instead of #GdkColor
+      and the code looks like this:
+      <informalexample><programlisting>
+      GdkRGBA *color1;
+      GdkRGBA  color2;
+
+      gtk_style_context_get (context, GTK_STATE_FLAG_PRELIGHT,
+                             "background-color", &amp;color1,
+                             NULL);
+      gtk_style_context_lookup_color (context, "focus_color", &amp;color2);
+
+      ...
+
+      gdk_rgba_free (color1);
+      </programlisting></informalexample>
+      Note that the memory handling here is different: gtk_style_context_get()
+      expects the address of a GdkRGBA* and returns a newly allocated struct,
+      gtk_style_context_lookup_color() expects the address of an existing
+      struct, and fills it.
+    </para>
+
+    <para>
       It is worth mentioning that the new file format does not support
       custom keybindings nor stock icon mappings as the RC format did.
     </para>