The color selection widget is, not surprisingly, a widget for interactive selection of colors. This composite widget lets the user select a color by manipulating RGB (Red, Green, Blue) and HSV (Hue, Saturation, Value) triples. This is done either by adjusting single values with sliders or entries, or by picking the desired color from a hue-saturation wheel/value bar. Optionally, the opacity of the color can also be set.

The color selection widget currently emits only one signal, "color_changed", which is emitted whenever the current color in the widget changes, either when the user changes it or if it's set explicitly through gtk_color_selection_set_color().

Lets have a look at what the color selection widget has to offer us. The widget comes in two flavours: GtkColorSelection and GtkColorSelectionDialog.

GtkWidget *gtk_color_selection_new( void );

You'll probably not be using this constructor directly. It creates an orphan ColorSelection widget which you'll have to parent yourself. The ColorSelection widget inherits from the VBox widget.

GtkWidget *gtk_color_selection_dialog_new( const gchar *title );

This is the most common color selection constructor. It creates a ColorSelectionDialog. It consists of a Frame containing a ColorSelection widget, an HSeparator and an HBox with three buttons, "Ok", "Cancel" and "Help". You can reach these buttons by accessing the "ok_button", "cancel_button" and "help_button" widgets in the ColorSelectionDialog structure, (i.e., GTK_COLOR_SELECTION_DIALOG (colorseldialog)->ok_button)).

void gtk_color_selection_set_has_opacity_control( GtkColorSelection *colorsel,
                                                  gboolean           has_opacity );

The color selection widget supports adjusting the opacity of a color (also known as the alpha channel). This is disabled by default. Calling this function with has_opacity set to TRUE enables opacity. Likewise, has_opacity set to FALSE will disable opacity.

void gtk_color_selection_set_current_color( GtkColorSelection *colorsel,
                                            GdkColor          *color );

void gtk_color_selection_set_current_alpha( GtkColorSelection *colorsel,
                                            guint16            alpha );

You can set the current color explicitly by calling gtk_color_selection_set_current_color() with a pointer to a GdkColor. Setting the opacity (alpha channel) is done with gtk_color_selection_set_current_alpha(). The alpha value should be between 0 (fully transparent) and 65636 (fully opaque).

void gtk_color_selection_get_current_color( GtkColorSelection *colorsel,
	                                    GdkColor *color );

void gtk_color_selection_get_current_alpha( GtkColorSelection *colorsel,
                                            guint16           *alpha );

When you need to query the current color, typically when you've received a "color_changed" signal, you use these functions.

The color sample areas (right under the hue-saturation wheel) supports drag and drop. The type of drag and drop is "application/x-color". The message data consists of an array of 4 (or 5 if opacity is enabled) gdouble values, where the value at position 0 is 0.0 (opacity on) or 1.0 (opacity off) followed by the red, green and blue values at positions 1,2 and 3 respectively. If opacity is enabled, the opacity is passed in the value at position 4.

Here's a simple example demonstrating the use of the ColorSelectionDialog. The program displays a window containing a drawing area. Clicking on it opens a color selection dialog, and changing the color in the color selection dialog changes the background color.

use Glib qw/TRUE FALSE/;
use Gtk2 '-init';

Gtk2->main;

0;