[gtk/matthiasc/for-master: 1/2] docs: Explain the symbolic icon paintable situation

[Matthias Clasen <matthiasc src gnome org>]

commit abdbcdf66dfcdd857e005b3bbb834dc5228cb321
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Oct 15 10:08:03 2020 -0400

    docs: Explain the symbolic icon paintable situation
    
    Add a paragraph to the migration guide that explains
    how to properly render symbolic GtkIconPaintables.
    
    Also mention this in the GtkIconPaintable docs.
    
    There's a reason you can't spell 'paintable' without
    'pain'...

 docs/reference/gtk/migrating-3to4.md | 8 ++++++++
 gtk/gtkicontheme.c                   | 3 +++
 2 files changed, 11 insertions(+)
---
diff --git a/docs/reference/gtk/migrating-3to4.md b/docs/reference/gtk/migrating-3to4.md
index 278ec2221d..6ce96a8878 100644
--- a/docs/reference/gtk/migrating-3to4.md
+++ b/docs/reference/gtk/migrating-3to4.md
@@ -1037,6 +1037,14 @@ of a #GtkIconInfo. It always returns a paintable in the requested size, and
 never fails. A number of no-longer-relevant lookup flags and API variants
 have been removed.
 
+Note that while GTK 4 is moving towards #GdkPaintable as a primary API
+for paintable content, it is meant to be a 'pure' content producer, therefore
+a #GtkIconPaintable for a symbolic icon will *not* get recolored depending
+on the context it is rendered it. To properly render a symbolic icon that
+is provided in the form of a #GtkIconPaintable (this can be checked with
+gtk_icon_paintable_is_symbolic()), you have to call
+gtk_icon_paintable_get_icon_name() and set the icon name on a #GtkImage.
+
 ### Update to GtkFileChooser API changes
 
 GtkFileChooser moved to a GFile-based API. If you need to convert a
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index cc0cfaa2c5..8792135846 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -3670,6 +3670,9 @@ gtk_icon_paintable_get_icon_name (GtkIconPaintable *icon)
  * the file name and not the file contents for determining this.
  * This behaviour may change in the future.
  *
+ * Note that to render a symbolic #GtkIconPaintable properly (with
+ * recoloring), you have to set its icon name on a #GtkImage.
+ *
  * Returns: %TRUE if the icon is symbolic, %FALSE otherwise
  */
 gboolean