GNOME.org
 

[gtk+/wip/colorchooser-v2: 36/40] Add docs

commit acd32f63922d9dd3a9301baf26d2dedfa447733d
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 3 19:40:36 2012 -0500

    Add docs

 docs/reference/gtk/gtk-docs.sgml     |    6 ++-
 docs/reference/gtk/gtk3-sections.txt |   59 ++++++++++++++++++++++-
 docs/reference/gtk/gtk3.types        |    3 +
 gtk/gtkcolorbutton.c                 |   23 +++++++--
 gtk/gtkcolorchooser.c                |   70 +++++++++++++++++++++++++--
 gtk/gtkcolorchooser.h                |    2 +-
 gtk/gtkcolorchooserdialog.c          |   88 +++++++++++++++++++++-------------
 gtk/gtkcolorchooserwidget.c          |   44 +++++++++++++++++
 8 files changed, 248 insertions(+), 47 deletions(-)
---
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 06b94b6..fa7bcf2 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -210,6 +210,9 @@
     <chapter id="SelectorWidgets">
       <title>Selectors (Color/File/Font)</title>
       <xi:include href="xml/gtkcolorbutton.xml" />
+      <xi:include href="xml/gtkcolorchooser.xml" />
+      <xi:include href="xml/gtkcolorchooserwidget.xml" />
+      <xi:include href="xml/gtkcolorchooserdialog.xml" />
       <xi:include href="xml/gtkcolorseldlg.xml" />
       <xi:include href="xml/gtkcolorsel.xml" />
       <xi:include href="xml/gtkhsv.xml" />
@@ -220,7 +223,8 @@
       <xi:include href="xml/gtkfilefilter.xml" />
       <xi:include href="xml/gtkfontbutton.xml" />
       <xi:include href="xml/gtkfontchooser.xml" />
-      <xi:include href="xml/gtkfontchooserdlg.xml" />
+      <xi:include href="xml/gtkfontchooserwidget.xml" />
+      <xi:include href="xml/gtkfontchooserdialog.xml" />
       <xi:include href="xml/gtkfontsel.xml" />
       <xi:include href="xml/gtkfontseldlg.xml" />
     </chapter>
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index 393e274..f5de9d8 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -1535,7 +1535,7 @@ gtk_font_chooser_widget_get_type
 </SECTION>
 
 <SECTION>
-<FILE>gtkfontchooserdlg</FILE>
+<FILE>gtkfontchooserdialog</FILE>
 <TITLE>GtkFontChooserDialog</TITLE>
 GtkFontChooserDialog
 gtk_font_chooser_dialog_new
@@ -7298,3 +7298,60 @@ GtkOverlayClass
 gtk_overlay_get_type
 GtkOverlayPrivate
 </SECTION>
+
+<SECTION>
+<FILE>gtkcolorchooser</FILE>
+<TITLE>GtkColorChooser</TITLE>
+GtkColorChooser
+gtk_color_chooser_get_rgba
+gtk_color_chooser_set_rgba
+gtk_color_chooser_get_use_alpha
+gtk_color_chooser_set_use_alpha
+
+<SUBSECTION Standard>
+GTK_TYPE_COLOR_CHOOSER
+GTK_COLOR_CHOOSER
+GTK_IS_COLOR_CHOOSER
+GTK_COLOR_CHOOSER_GET_IFACE
+
+<SUBSECTION Private>
+gtk_color_chooser_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gtkcolorchooserwidget</FILE>
+<TITLE>GtkColorChooserWidget</TITLE>
+GtkColorChooserWidget
+gtk_color_chooser_widget_new
+
+<SUBSECTION Standard>
+GTK_TYPE_COLOR_CHOOSER_WIDGET
+GTK_COLOR_CHOOSER_WIDGET
+GTK_COLOR_CHOOSER_WIDGET_CLASS
+GTK_IS_COLOR_CHOOSER_WIDGET
+GTK_IS_COLOR_CHOOSER_WIDGET_CLASS
+GTK_COLOR_CHOOSER_WIDGET_GET_CLASS
+
+<SUBSECTION Private>
+gtk_color_chooser_widget_get_type
+GtkColorChooserWidgetPrivate
+</SECTION>
+
+<SECTION>
+<FILE>gtkcolorchooserdialog</FILE>
+<TITLE>GtkColorChooserDialog</TITLE>
+GtkColorChooserDialog
+gtk_color_chooser_dialog_new
+
+<SUBSECTION Standard>
+GTK_TYPE_COLOR_CHOOSER_DIALOG
+GTK_COLOR_CHOOSER_DIALOG
+GTK_COLOR_CHOOSER_DIALOG_CLASS
+GTK_IS_COLOR_CHOOSER_DIALOG
+GTK_IS_COLOR_CHOOSER_DIALOG_CLASS
+GTK_COLOR_CHOOSER_DIALOG_GET_CLASS
+
+<SUBSECTION Private>
+GtkColorChooserDialogPrivate
+gtk_color_chooser_dialog_get_type
+</SECTION>
diff --git a/docs/reference/gtk/gtk3.types b/docs/reference/gtk/gtk3.types
index 7fe92ad..c67ac72 100644
--- a/docs/reference/gtk/gtk3.types
+++ b/docs/reference/gtk/gtk3.types
@@ -47,6 +47,9 @@ gtk_check_button_get_type
 gtk_check_menu_item_get_type
 gtk_clipboard_get_type
 gtk_color_button_get_type
+gtk_color_chooser_get_type
+gtk_color_chooser_dialog_get_type
+gtk_color_chooser_widget_get_type
 gtk_color_selection_dialog_get_type
 gtk_color_selection_get_type
 gtk_combo_box_get_type
diff --git a/gtk/gtkcolorbutton.c b/gtk/gtkcolorbutton.c
index e43d240..ecc8088 100644
--- a/gtk/gtkcolorbutton.c
+++ b/gtk/gtkcolorbutton.c
@@ -164,9 +164,9 @@ gtk_color_button_class_init (GtkColorButtonClass *klass)
   /**
    * GtkColorButton:use-alpha:
    *
-   * If this property is set to %TRUE, the color swatch on the button is rendered against a
-   * checkerboard background to show its opacity and the opacity slider is displayed in the
-   * color selection dialog.
+   * If this property is set to %TRUE, the color swatch on the button is
+   * rendered against a checkerboard background to show its opacity and
+   * the opacity slider is displayed in the color selection dialog.
    *
    * Since: 2.4
    */
@@ -489,7 +489,6 @@ gtk_color_button_init (GtkColorButton *button)
   button->priv->title = g_strdup (_("Pick a Color")); /* default title */
 
   /* Start with opaque black, alpha disabled */
-
   button->priv->rgba.red = 0;
   button->priv->rgba.green = 0;
   button->priv->rgba.blue = 0;
@@ -671,7 +670,7 @@ gtk_color_button_clicked (GtkButton *b)
  *
  * Since: 2.4
  *
- * Deprecated: Use gtk_color_button_set_rgba() instead.
+ * Deprecated: Use gtk_color_chooser_set_rgba() instead.
  */
 void
 gtk_color_button_set_color (GtkColorButton *button,
@@ -699,6 +698,8 @@ gtk_color_button_set_color (GtkColorButton *button,
  * Sets the current opacity to be @alpha.
  *
  * Since: 2.4
+ *
+ * Deprecated: 3.4: Use gtk_color_chooser_set_rgba() instead.
  */
 void
 gtk_color_button_set_alpha (GtkColorButton *button,
@@ -723,7 +724,7 @@ gtk_color_button_set_alpha (GtkColorButton *button,
  *
  * Since: 2.4
  *
- * Deprecated: 3.4: Use gtk_color_button_get_rgba() instead.
+ * Deprecated: 3.4: Use gtk_color_chooser_get_rgba() instead.
  */
 void
 gtk_color_button_get_color (GtkColorButton *button,
@@ -745,6 +746,8 @@ gtk_color_button_get_color (GtkColorButton *button,
  * Return value: an integer between 0 and 65535
  *
  * Since: 2.4
+ *
+ * Deprecated: 3.4: Use gtk_color_chooser_get_rgba() instead.
  */
 guint16
 gtk_color_button_get_alpha (GtkColorButton *button)
@@ -762,6 +765,8 @@ gtk_color_button_get_alpha (GtkColorButton *button)
  * Sets the current color to be @rgba.
  *
  * Since: 3.0
+ *
+ * Deprecated: 3.4: Use gtk_color_chooser_set_rgba() instead.
  */
 void
 gtk_color_button_set_rgba (GtkColorButton *button,
@@ -786,6 +791,8 @@ gtk_color_button_set_rgba (GtkColorButton *button,
  * Sets @rgba to be the current color in the #GtkColorButton widget.
  *
  * Since: 3.0
+ *
+ * Deprecated: 3.4: Use gtk_color_chooser_get_rgba() instead.
  */
 void
 gtk_color_button_get_rgba (GtkColorButton *button,
@@ -805,6 +812,8 @@ gtk_color_button_get_rgba (GtkColorButton *button,
  * Sets whether or not the color button should use the alpha channel.
  *
  * Since: 2.4
+ *
+ * Deprecated: 3.4: Use gtk_color_chooser_set_use_alpha() instead.
  */
 void
 gtk_color_button_set_use_alpha (GtkColorButton *button,
@@ -833,6 +842,8 @@ gtk_color_button_set_use_alpha (GtkColorButton *button,
  * Returns: %TRUE if the color sample uses alpha channel, %FALSE if not
  *
  * Since: 2.4
+ *
+ * Deprecated: 3.4: Use gtk_color_chooser_get_use_alpha() instead.
  */
 gboolean
 gtk_color_button_get_use_alpha (GtkColorButton *button)
diff --git a/gtk/gtkcolorchooser.c b/gtk/gtkcolorchooser.c
index 563ba9a..153180b 100644
--- a/gtk/gtkcolorchooser.c
+++ b/gtk/gtkcolorchooser.c
@@ -26,6 +26,22 @@
 #include "gtktypebuiltins.h"
 #include "gtkprivate.h"
 
+/**
+ * SECTION:gtkcolorchooser
+ * @Short_description: Interface implemented by widgets for choosing colors
+ * @Title: GtkColorChooser
+ * @See_also: #GtkColorChooserDialog, #GtkColorChooserWidget, #GtkColorButton
+ *
+ * #GtkColorChooser is an interface that is implemented by widgets
+ * for choosing colors. Depending on the situation, colors may be
+ * allowed to have alpha (translucency).
+ *
+ * In GTK+, the main widgets that implement this interface are
+ * #GtkColorChooserWidget, #GtkColorChooserDialog and #GtkColorButton.
+ *
+ * Since: 3.4
+ */
+
 enum
 {
   COLOR_ACTIVATED,
@@ -39,6 +55,15 @@ G_DEFINE_INTERFACE (GtkColorChooser, gtk_color_chooser, G_TYPE_OBJECT);
 static void
 gtk_color_chooser_default_init (GtkColorChooserInterface *iface)
 {
+  /**
+   * GtkColorChooser:rgba:
+   *
+   * The ::rgba property contains the currently selected color,
+   * as a #GdkRGBA struct. The property can be set to change
+   * the current selection programmatically.
+   *
+   * Since: 3.4
+   */
   g_object_interface_install_property (iface,
       g_param_spec_boxed ("rgba",
                           P_("Color"),
@@ -46,6 +71,19 @@ gtk_color_chooser_default_init (GtkColorChooserInterface *iface)
                           GDK_TYPE_RGBA,
                           GTK_PARAM_READWRITE));
 
+  /**
+   * GtkColorChooser:use-alpha:
+   *
+   * When ::use-alpha is %TRUE, colors may have alpha (translucency)
+   * information. When it is %FALSE, the #GdkRGBA struct obtained
+   * via the #GtkColorChooser:rgba property will be forced to have
+   * alpha == 1.
+   *
+   * Implementations are expected to show alpha by rendering the color
+   * over a non-uniform background (like a checkerboard pattern).
+   *
+   * Since: 3.4
+   */
   g_object_interface_install_property (iface,
       g_param_spec_boolean ("use-alpha",
                             P_("Use alpha"),
@@ -55,14 +93,16 @@ gtk_color_chooser_default_init (GtkColorChooserInterface *iface)
 
   /**
    * GtkColorChooser::color-activated:
-   * @self: the object which received the signal
+   * @chooser: the object which received the signal
    * @color: the color
    *
    * Emitted when a color is activated from the color chooser.
    * This usually happens when the user clicks a color swatch,
    * or a color is selected and the user presses one of the keys
    * Space, Shift+Space, Return or Enter.
-    */
+   *
+   * Since: 3.4
+   */
   signals[COLOR_ACTIVATED] =
     g_signal_new ("color-activated",
                   GTK_TYPE_COLOR_CHOOSER,
@@ -80,6 +120,8 @@ gtk_color_chooser_default_init (GtkColorChooserInterface *iface)
  * @color: return location for the color
  *
  * Gets the currently-selected color.
+ *
+ * Since: 3.4
  */
 void
 gtk_color_chooser_get_rgba (GtkColorChooser *chooser,
@@ -95,7 +137,7 @@ gtk_color_chooser_get_rgba (GtkColorChooser *chooser,
  * @chooser: a #GtkColorChooser
  * @color: the new color
  *
- * Sets the currently-selected color.
+ * Sets the color.
  */
 void
 gtk_color_chooser_set_rgba (GtkColorChooser *chooser,
@@ -111,11 +153,20 @@ void
 _gtk_color_chooser_color_activated (GtkColorChooser *chooser,
                                     const GdkRGBA   *color)
 {
-  g_return_if_fail (GTK_IS_COLOR_CHOOSER (chooser));
-
   g_signal_emit (chooser, signals[COLOR_ACTIVATED], 0, color);
 }
 
+/**
+ * gtk_color_chooser_get_use_alpha:
+ * @chooser: a #GtkColorChooser
+ *
+ * Returns whether the color chooser shows the alpha channel.
+ *
+ * Returns: %TRUE if the color chooser uses the alpha channel,
+ *     %FALSE if not
+ *
+ * Since: 3.4
+ */
 gboolean
 gtk_color_chooser_get_use_alpha (GtkColorChooser *chooser)
 {
@@ -128,6 +179,15 @@ gtk_color_chooser_get_use_alpha (GtkColorChooser *chooser)
   return use_alpha;
 }
 
+/**
+ * gtk_color_chooser_set_use_alpha:
+ * @chooser: a #GtkColorChooser
+ * @use_alpha: %TRUE if color chooser should use alpha channel, %FALSE if not
+ *
+ * Sets whether or not the color chooser should use the alpha channel.
+ *
+ * Since: 3.4
+ */
 void
 gtk_color_chooser_set_use_alpha (GtkColorChooser *chooser,
                                  gboolean         use_alpha)
diff --git a/gtk/gtkcolorchooser.h b/gtk/gtkcolorchooser.h
index 287c551..7a82ddf 100644
--- a/gtk/gtkcolorchooser.h
+++ b/gtk/gtkcolorchooser.h
@@ -63,7 +63,7 @@ void     gtk_color_chooser_set_rgba       (GtkColorChooser *chooser,
                                            const GdkRGBA   *color);
 gboolean gtk_color_chooser_get_use_alpha  (GtkColorChooser *chooser);
 void     gtk_color_chooser_set_use_alpha  (GtkColorChooser *chooser,
-                                           gboolean         show_alpha);
+                                           gboolean         use_alpha);
 
 G_END_DECLS
 
diff --git a/gtk/gtkcolorchooserdialog.c b/gtk/gtkcolorchooserdialog.c
index 32e77cc..5013996 100644
--- a/gtk/gtkcolorchooserdialog.c
+++ b/gtk/gtkcolorchooserdialog.c
@@ -29,10 +29,21 @@
 #include "gtkcolorchooserdialog.h"
 #include "gtkcolorchooserwidget.h"
 
+/**
+ * SECTION:gtkcolorchooserdialog
+ * @Short_description: A dialog for choosing colors
+ * @Title: GtkColorChooserDialog
+ * @See_also: #GtkColorChooser, #GtkDialog
+ *
+ * The #GtkColorChooserDialog widget is a dialog for choosing
+ * a color. It implements the #GtkColorChooser interface.
+ *
+ * Since: 3.4
+ */
 
 struct _GtkColorChooserDialogPrivate
 {
-  GtkWidget *color_chooser;
+  GtkWidget *chooser;
 
   GtkWidget *select_button;
   GtkWidget *cancel_button;
@@ -41,8 +52,8 @@ struct _GtkColorChooserDialogPrivate
 enum
 {
   PROP_ZERO,
-  PROP_COLOR,
-  PROP_SHOW_ALPHA,
+  PROP_RGBA,
+  PROP_USE_ALPHA,
   PROP_SHOW_EDITOR
 };
 
@@ -57,7 +68,7 @@ propagate_notify (GObject               *o,
                   GParamSpec            *pspec,
                   GtkColorChooserDialog *cc)
 {
-  g_object_notify (G_OBJECT (cc), "color");
+  g_object_notify (G_OBJECT (cc), "rgba");
 }
 
 static void
@@ -93,16 +104,16 @@ gtk_color_chooser_dialog_init (GtkColorChooserDialog *cc)
   gtk_window_set_resizable (GTK_WINDOW (cc), FALSE);
 
   /* Create the content area */
-  priv->color_chooser = gtk_color_chooser_widget_new ();
-  gtk_container_set_border_width (GTK_CONTAINER (priv->color_chooser), 5);
-  gtk_widget_show (priv->color_chooser);
+  priv->chooser = gtk_color_chooser_widget_new ();
+  gtk_container_set_border_width (GTK_CONTAINER (priv->chooser), 5);
+  gtk_widget_show (priv->chooser);
   gtk_box_pack_start (GTK_BOX (content_area),
-                      priv->color_chooser, TRUE, TRUE, 0);
+                      priv->chooser, TRUE, TRUE, 0);
 
-  g_signal_connect (priv->color_chooser, "notify::color",
+  g_signal_connect (priv->chooser, "notify::rgba",
                     G_CALLBACK (propagate_notify), cc);
 
-  g_signal_connect (priv->color_chooser, "color-activated",
+  g_signal_connect (priv->chooser, "color-activated",
                     G_CALLBACK (color_activated_cb), cc);
 
   /* Create the action area */
@@ -132,11 +143,11 @@ gtk_color_chooser_dialog_response (GtkDialog *dialog,
     {
       GdkRGBA color;
 
-      gtk_color_chooser_get_color (GTK_COLOR_CHOOSER (dialog), &color);
-      gtk_color_chooser_set_color (GTK_COLOR_CHOOSER (dialog), &color);
+      gtk_color_chooser_get_rgba (GTK_COLOR_CHOOSER (dialog), &color);
+      gtk_color_chooser_set_rgba (GTK_COLOR_CHOOSER (dialog), &color);
     }
 
-  g_object_set (GTK_COLOR_CHOOSER_DIALOG (dialog)->priv->color_chooser,
+  g_object_set (GTK_COLOR_CHOOSER_DIALOG (dialog)->priv->chooser,
                 "show-editor", FALSE, NULL);
 }
 
@@ -151,21 +162,21 @@ gtk_color_chooser_dialog_get_property (GObject    *object,
 
   switch (prop_id)
     {
-    case PROP_COLOR:
+    case PROP_RGBA:
       {
         GdkRGBA color;
 
-        gtk_color_chooser_get_color (cc, &color);
+        gtk_color_chooser_get_rgba (cc, &color);
         g_value_set_boxed (value, &color);
       }
       break;
-    case PROP_SHOW_ALPHA:
-      g_value_set_boolean (value, gtk_color_chooser_get_show_alpha (GTK_COLOR_CHOOSER (cd->priv->color_chooser)));
+    case PROP_USE_ALPHA:
+      g_value_set_boolean (value, gtk_color_chooser_get_use_alpha (GTK_COLOR_CHOOSER (cd->priv->chooser)));
       break;
     case PROP_SHOW_EDITOR:
       {
         gboolean show_editor;
-        g_object_get (cd->priv->color_chooser, "show-editor", &show_editor, NULL);
+        g_object_get (cd->priv->chooser, "show-editor", &show_editor, NULL);
         g_value_set_boolean (value, show_editor);
       }
       break;
@@ -186,14 +197,14 @@ gtk_color_chooser_dialog_set_property (GObject      *object,
 
   switch (prop_id)
     {
-    case PROP_COLOR:
-      gtk_color_chooser_set_color (cc, g_value_get_boxed (value));
+    case PROP_RGBA:
+      gtk_color_chooser_set_rgba (cc, g_value_get_boxed (value));
       break;
-    case PROP_SHOW_ALPHA:
-      gtk_color_chooser_set_show_alpha (GTK_COLOR_CHOOSER (cd->priv->color_chooser), g_value_get_boolean (value));
+    case PROP_USE_ALPHA:
+      gtk_color_chooser_set_use_alpha (GTK_COLOR_CHOOSER (cd->priv->chooser), g_value_get_boolean (value));
       break;
     case PROP_SHOW_EDITOR:
-      g_object_set (cd->priv->color_chooser,
+      g_object_set (cd->priv->chooser,
                     "show-editor", g_value_get_boolean (value),
                     NULL);
       break;
@@ -214,8 +225,8 @@ gtk_color_chooser_dialog_class_init (GtkColorChooserDialogClass *class)
 
   dialog_class->response = gtk_color_chooser_dialog_response;
 
-  g_object_class_override_property (object_class, PROP_COLOR, "color");
-  g_object_class_override_property (object_class, PROP_SHOW_ALPHA, "show-alpha");
+  g_object_class_override_property (object_class, PROP_RGBA, "rgba");
+  g_object_class_override_property (object_class, PROP_USE_ALPHA, "use-alpha");
   g_object_class_install_property (object_class, PROP_SHOW_EDITOR,
       g_param_spec_boolean ("show-editor", P_("Show editor"), P_("Show editor"),
                             FALSE, GTK_PARAM_READWRITE));
@@ -225,30 +236,41 @@ gtk_color_chooser_dialog_class_init (GtkColorChooserDialogClass *class)
 }
 
 static void
-gtk_color_chooser_dialog_get_color (GtkColorChooser *chooser,
-                                    GdkRGBA         *color)
+gtk_color_chooser_dialog_get_rgba (GtkColorChooser *chooser,
+                                   GdkRGBA         *color)
 {
   GtkColorChooserDialog *cc = GTK_COLOR_CHOOSER_DIALOG (chooser);
 
-  gtk_color_chooser_get_color (GTK_COLOR_CHOOSER (cc->priv->color_chooser), color);
+  gtk_color_chooser_get_rgba (GTK_COLOR_CHOOSER (cc->priv->chooser), color);
 }
 
 static void
-gtk_color_chooser_dialog_set_color (GtkColorChooser *chooser,
-                                    const GdkRGBA   *color)
+gtk_color_chooser_dialog_set_rgba (GtkColorChooser *chooser,
+                                   const GdkRGBA   *color)
 {
   GtkColorChooserDialog *cc = GTK_COLOR_CHOOSER_DIALOG (chooser);
 
-  gtk_color_chooser_set_color (GTK_COLOR_CHOOSER (cc->priv->color_chooser), color);
+  gtk_color_chooser_set_rgba (GTK_COLOR_CHOOSER (cc->priv->chooser), color);
 }
 
 static void
 gtk_color_chooser_dialog_iface_init (GtkColorChooserInterface *iface)
 {
-  iface->get_color = gtk_color_chooser_dialog_get_color;
-  iface->set_color = gtk_color_chooser_dialog_set_color;
+  iface->get_rgba = gtk_color_chooser_dialog_get_rgba;
+  iface->set_rgba = gtk_color_chooser_dialog_set_rgba;
 }
 
+/**
+ * gtk_color_chooser_dialog_new:
+ * @title: (allow-none): Title of the dialog, or %NULL
+ * @parent: (allow-none): Transient parent of the dialog, or %NULL
+ *
+ * Creates a new #GtkColorChooserDialog.
+ *
+ * Return value: a new #GtkColorChooserDialog
+ *
+ * Since: 3.4
+ */
 GtkWidget *
 gtk_color_chooser_dialog_new (const gchar *title,
                               GtkWindow   *parent)
diff --git a/gtk/gtkcolorchooserwidget.c b/gtk/gtkcolorchooserwidget.c
index b079b90..f71060f 100644
--- a/gtk/gtkcolorchooserwidget.c
+++ b/gtk/gtkcolorchooserwidget.c
@@ -34,6 +34,32 @@
 #include "gtksizegroup.h"
 #include "gtkalignment.h"
 
+/**
+ * SECTION:gtkcolorchooserwidget
+ * @Short_description: A widget for choosing colors
+ * @Title: GtkColorChooserWidget
+ * @See_also: #GtkColorChooserDialog
+ *
+ * The #GtkColorChooserWidget widget lets the user select a
+ * color. By default, the chooser presents a prefined palette
+ * of colors, plus a small number of settable custom colors.
+ * It is also possible to select a different color with the
+ * single-color editor. To enter the single-color editing mode,
+ * use the context menu of any color of the palette, or use the
+ * '+' button to add a new custom color.
+ *
+ * The chooser automatically remembers the last selection, as well
+ * as custom colors.
+ *
+ * To change the initially selected color, use gtk_color_chooser_set_rgba().
+ * To get the selected font use gtk_color_chooser_get_rgba().
+ *
+ * The #GtkColorChooserWidget is used in the #GtkColorChooserDialog
+ * to provide a dialog for selecting colors.
+ *
+ * Since: 3.4
+ */
+
 struct _GtkColorChooserWidgetPrivate
 {
   GtkWidget *palette;
@@ -472,6 +498,15 @@ gtk_color_chooser_widget_class_init (GtkColorChooserWidgetClass *class)
   g_object_class_override_property (object_class, PROP_RGBA, "rgba");
   g_object_class_override_property (object_class, PROP_USE_ALPHA, "use-alpha");
 
+  /**
+   * GtkColorChooserWidget:show-editor:
+   *
+   * The ::show-editor property is %TRUE when the color chooser
+   * is showing the single-color editor. It can be set to switch
+   * the color chooser into single-color editing mode.
+   *
+   * Since: 3.4
+   */
   g_object_class_install_property (object_class, PROP_SHOW_EDITOR,
       g_param_spec_boolean ("show-editor", P_("Show editor"), P_("Show editor"),
                             FALSE, GTK_PARAM_READWRITE));
@@ -580,6 +615,15 @@ gtk_color_chooser_widget_iface_init (GtkColorChooserInterface *iface)
   iface->set_rgba = gtk_color_chooser_widget_set_rgba;
 }
 
+/**
+ * gtk_color_chooser_widget_new:
+ *
+ * Creates a new #GtkColorChooserWidget.
+ *
+ * Returns: a new #GtkColorChooserWidget
+ *
+ * Since: 3.4
+ */
 GtkWidget *
 gtk_color_chooser_widget_new (void)
 {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]