[gtk+] Document gtk_color_chooser_add_palette

[Matthias Clasen <matthiasc src gnome org>]

commit 1fd311803a56916ca32261a7a097c6fd3edb623e
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Feb 8 21:25:02 2012 -0500

    Document gtk_color_chooser_add_palette

 docs/reference/gtk/gtk3-sections.txt |    1 +
 gtk/gtkcolorchooser.c                |   28 +++++++++++++++++++++++++++-
 2 files changed, 28 insertions(+), 1 deletions(-)
---
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index f5de9d8..4674beb 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -7307,6 +7307,7 @@ gtk_color_chooser_get_rgba
 gtk_color_chooser_set_rgba
 gtk_color_chooser_get_use_alpha
 gtk_color_chooser_set_use_alpha
+gtk_color_chooser_add_palette
 
 <SUBSECTION Standard>
 GTK_TYPE_COLOR_CHOOSER
diff --git a/gtk/gtkcolorchooser.c b/gtk/gtkcolorchooser.c
index bc6195e..075331b 100644
--- a/gtk/gtkcolorchooser.c
+++ b/gtk/gtkcolorchooser.c
@@ -198,6 +198,31 @@ gtk_color_chooser_set_use_alpha (GtkColorChooser *chooser,
   g_object_set (chooser, "use-alpha", use_alpha, NULL);
 }
 
+/**
+ * gtk_color_chooser_add_palette:
+ * @chooser: a #GtkColorChooser
+ * @horizontal: %TRUE if the palette should be displayed in rows,
+ *     %FALSE for columns
+ * @colors_per_line: the number of colors to show in each row/column
+ * @n_colors: the total number of elements in @colors
+ * @colors: (array length=n_colors): the colors of the palette
+ *
+ * Adds a palette to the color chooser. If @horizontal is %TRUE,
+ * the colors are grouped in rows, with @colors_per_line colors
+ * in each row. If @horizontal is %FALSE, the colors are grouped
+ * in columns instead.
+ *
+ * The default color palette of #GtkColorChooserWidget has
+ * 27 colors, organized in columns of 3 colors. The default gray
+ * palette has 9 grays in a single row.
+ *
+ * The layout of the color chooser widget works best when the
+ * palettes have 9-10 columns.
+ *
+ * Calling this function is called for the first time has the
+ * side effect of removing the default color and gray palettes
+ * from the color chooser.
+ */
 void
 gtk_color_chooser_add_palette (GtkColorChooser *chooser,
                                gboolean         horizontal,
@@ -207,5 +232,6 @@ gtk_color_chooser_add_palette (GtkColorChooser *chooser,
 {
   g_return_if_fail (GTK_IS_COLOR_CHOOSER (chooser));
 
-  GTK_COLOR_CHOOSER_GET_IFACE (chooser)->add_palette (chooser, horizontal, colors_per_line, n_colors, colors);
+  if (GTK_COLOR_CHOOSER_GET_IFACE (chooser)->add_palette)
+    GTK_COLOR_CHOOSER_GET_IFACE (chooser)->add_palette (chooser, horizontal, colors_per_line, n_colors, colors);
 }