From 23a5f7a22c6fda1e28415584e2b266b9ce1fe3ef Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 3 Feb 2012 19:40:36 -0500 Subject: [PATCH] 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 06b94b6167..fa7bcf2cfb 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -210,6 +210,9 @@ Selectors (Color/File/Font) + + + @@ -220,7 +223,8 @@ - + + diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt index 393e274eff..f5de9d8e3e 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
-gtkfontchooserdlg +gtkfontchooserdialog GtkFontChooserDialog GtkFontChooserDialog gtk_font_chooser_dialog_new @@ -7298,3 +7298,60 @@ GtkOverlayClass gtk_overlay_get_type GtkOverlayPrivate
+ +
+gtkcolorchooser +GtkColorChooser +GtkColorChooser +gtk_color_chooser_get_rgba +gtk_color_chooser_set_rgba +gtk_color_chooser_get_use_alpha +gtk_color_chooser_set_use_alpha + + +GTK_TYPE_COLOR_CHOOSER +GTK_COLOR_CHOOSER +GTK_IS_COLOR_CHOOSER +GTK_COLOR_CHOOSER_GET_IFACE + + +gtk_color_chooser_get_type +
+ +
+gtkcolorchooserwidget +GtkColorChooserWidget +GtkColorChooserWidget +gtk_color_chooser_widget_new + + +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 + + +gtk_color_chooser_widget_get_type +GtkColorChooserWidgetPrivate +
+ +
+gtkcolorchooserdialog +GtkColorChooserDialog +GtkColorChooserDialog +gtk_color_chooser_dialog_new + + +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 + + +GtkColorChooserDialogPrivate +gtk_color_chooser_dialog_get_type +
diff --git a/docs/reference/gtk/gtk3.types b/docs/reference/gtk/gtk3.types index 7fe92ad4cb..c67ac722a0 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 e43d2406c3..ecc808864a 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 563ba9a006..153180bbb5 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 287c551cd3..7a82ddfbbc 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 32e77cccf5..5013996ccf 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 b079b907b0..f71060f85a 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) {