GtkColorPickerButton

[Matthias Clasen <maclas gmx de>]

Proposal: GtkColorPickerButton
==============================

http://bugzilla.gnome.org/show_bug.cgi?id=107597

This is a clone of the GnomeColorPicker widget currently found in
libgnomeui. To cite its documentation:

The GtkColorPickerButton widget is a simple color picker in a button.  
It displays a sample of the currently selected color.  When the user 
clicks on the button, a color selection dialog pops up.  The color
picker emits the "color_set" signal when the color is set.

I have made the following changes to the GnomeColorPicker while moving
it to the Gtk namespace:

* adjust the API to GTK conventions: colors are handled as GdkColor,
  not alternatively as quadruples of gdouble, guint16 or guint8; add
  getters for all setters; add notification for properties

* simplify by removing the "dither" parameter

* make the color swatch scale with the button

* append "Button" to the widget name to prevent confusion between 
  GtkColorSelection and GtkColorPicker


API details
===========

/**
 * gtk_color_picker_button_new:
 *
 * Creates a new color picker widget. This returns a widget in the form
of
 * a small button containing a swatch representing the current selected 
 * color. When the button is clicked, a color-selection dialog will
open, 
 * allowing the user to select a color. The swatch will be updated to
reflect 
 * the new color when the user finishes.
 *
 * Returns: Pointer to new color picker widget.
 */
GtkWidget *
gtk_color_picker_button_new (void)

/**
 * gtk_color_picker_button_set_color:
 * @cp: a #GtkColorPickerButton.
 * @color: A #GdkColor to set the current color with.
 *
 * Sets the current color to be @color.
 **/
void 
gtk_color_picker_button_set_color (GtkColorPickerButton *cp,
                                   GdkColor             *color)

/**
 * gtk_color_picker_button_get_color:
 * @cp: a #GtkColorPickerButton.
 * @color: a #GdkColor to fill in with the current color.
 *
 * Sets @color to be the current color in the 
 * #GtkColorPickerButton widget.
 **/
void 
gtk_color_picker_button_get_color (GtkColorPickerButton *cp,
                                   GdkColor       *color)

/**
 * gtk_color_picker_button_set_alpha:
 * @colorsel: a #GtkColorPickerButton.
 * @alpha: an integer between 0 and 65535.
 *
 * Sets the current opacity to be @alpha.  
 **/
void 
gtk_color_picker_button_set_alpha (GtkColorPickerButton *cp,
                                   guint16               alpha)

/**
 * gtk_color_picker_button_get_alpha:
 * @cp: a #GtkColorPickerButton.
 *
 * Returns the current alpha value.
 *
 * Return value: an integer between 0 and 65535.
 **/
guint16 
gtk_color_picker_button_get_alpha (GtkColorPickerButton *cp)

/**
 * gtk_color_picker_button_set_use_alpha:
 * @cp: a #GtkColorPickerButton.
 * @use_alpha: %TRUE if color sample should use alpha channel, %FALSE if
not.
 *
 * Sets whether or not the picker should use the alpha channel.
 */
void 
gtk_color_picker_button_set_use_alpha (GtkColorPickerButton *cp, 
                                       gboolean              use_alpha)

/**
 * gtk_color_picker_button_get_use_alpha:
 * @cp: a #GtkColorPickerButton.
 *
 * Does the picker use the alpha channel?
 *
 * Returns: %TRUE if color sample uses alpha channel, %FALSE if not.
 */
gboolean 
gtk_color_picker_button_get_use_alpha (GtkColorPickerButton *cp)

/**
 * gtk_color_picker_button_set_title:
 * @cp: a #GtkColorPickerButton
 * @title: String containing new window title.
 *
 * Sets the title for the color selection dialog.
 */
void 
gtk_color_picker_button_set_title (GtkColorPickerButton *cp, 
                                   const gchar    *title)

/**
 * gtk_color_picker_button_get_title:
 * @cp: a #GtkColorPickerButton
 *
 * Gets the title of the color selection dialog.
 *
 * Returns: An internal string, do not free the return value
 */

G_CONST_RETURN gchar *
gtk_color_picker_button_get_title (GtkColorPickerButton *cp)