## GtkColorButton

GtkColorButton — A button to launch a color selection dialog

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkColorButton;
    GtkWidget*  gtk_color_button_new            (void);
    GtkWidget*  gtk_color_button_new_with_color (const GdkColor *color);
    void        gtk_color_button_set_color      (GtkColorButton *color_button,
                                                 const GdkColor *color);
    void        gtk_color_button_get_color      (GtkColorButton *color_button,
                                                 GdkColor *color);
    void        gtk_color_button_set_alpha      (GtkColorButton *color_button,
                                                 guint16 alpha);
    guint16     gtk_color_button_get_alpha      (GtkColorButton *color_button);
    void        gtk_color_button_set_use_alpha  (GtkColorButton *color_button,
                                                 gboolean use_alpha);
    gboolean    gtk_color_button_get_use_alpha  (GtkColorButton *color_button);
    void        gtk_color_button_set_title      (GtkColorButton *color_button,
                                                 const gchar *title);
    G_CONST_RETURN gchar* gtk_color_button_get_title
                                                (GtkColorButton *color_button);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkButton
                                     +----GtkColorButton

## Implemented Interfaces

GtkColorButton implements AtkImplementorIface.

## Properties

      "alpha"                guint                 : Read / Write
      "color"                GdkColor              : Read / Write
      "title"                gchararray            : Read / Write
      "use-alpha"            gboolean              : Read / Write

## Signal Prototypes

    "color-set" void        user_function      (GtkColorButton *widget,
                                                gpointer user_data);

## Description

The GtkColorButton is a button which displays the currently selected color an allows to open a color selection dialog to change the color. It is suitable widget for selecting a color in a preference dialog.

## Details

### struct GtkColorButton

    struct GtkColorButton;

### gtk_color_button_new ()

    GtkWidget*  gtk_color_button_new            (void);

Creates a new color button. 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 : | a new color button.

Since 2.4

### gtk_color_button_new_with_color ()

    GtkWidget*  gtk_color_button_new_with_color (const GdkColor *color);

Creates a new color button.

`color` : | A GdkColor to set the current color with.
Returns : | a new color button.

Since 2.4

### gtk_color_button_set_color ()

    void        gtk_color_button_set_color      (GtkColorButton *color_button,
                                                 const GdkColor *color);

Sets the current color to be `color`.

`color_button` : | a GtkColorButton.
`color` : | A GdkColor to set the current color with.

Since 2.4

### gtk_color_button_get_color ()

    void        gtk_color_button_get_color      (GtkColorButton *color_button,
                                                 GdkColor *color);

Sets `color` to be the current color in the GtkColorButton widget.

`color_button` : | a GtkColorButton.
`color` : | a GdkColor to fill in with the current color.

Since 2.4

### gtk_color_button_set_alpha ()

    void        gtk_color_button_set_alpha      (GtkColorButton *color_button,
                                                 guint16 alpha);

Sets the current opacity to be `alpha`.

`color_button` : | a GtkColorButton.
`alpha` : | an integer between 0 and 65535.

Since 2.4

### gtk_color_button_get_alpha ()

    guint16     gtk_color_button_get_alpha      (GtkColorButton *color_button);

Returns the current alpha value.

`color_button` : | a GtkColorButton.
Returns : | an integer between 0 and 65535.

Since 2.4

### gtk_color_button_set_use_alpha ()

    void        gtk_color_button_set_use_alpha  (GtkColorButton *color_button,
                                                 gboolean use_alpha);

Sets whether or not the color button should use the alpha channel.

`color_button` : | a GtkColorButton.
`use_alpha` : | `TRUE` if color button should use alpha channel, `FALSE` if not.

Since 2.4

### gtk_color_button_get_use_alpha ()

    gboolean    gtk_color_button_get_use_alpha  (GtkColorButton *color_button);

Does the color selection dialog use the alpha channel?

`color_button` : | a GtkColorButton.
Returns : | `TRUE` if the color sample uses alpha channel, `FALSE` if not.

Since 2.4

### gtk_color_button_set_title ()

    void        gtk_color_button_set_title      (GtkColorButton *color_button,
                                                 const gchar *title);

Sets the title for the color selection dialog.

`color_button` : | a GtkColorButton
`title` : | String containing new window title.

Since 2.4

### gtk_color_button_get_title ()

    G_CONST_RETURN gchar* gtk_color_button_get_title
                                                (GtkColorButton *color_button);

Gets the title of the color selection dialog.

`color_button` : | a GtkColorButton
Returns : | An internal string, do not free the return value

Since 2.4

## Properties

### The "`alpha`" property

      "alpha"                guint                 : Read / Write

The selected opacity value (0 fully transparent, 65535 fully opaque).

Allowed values: <= 65535

Default value: 65535

Since 2.4

### The "`color`" property

      "color"                GdkColor              : Read / Write

The selected color.

Since 2.4

### The "`title`" property

      "title"                gchararray            : Read / Write

The title of the color selection dialog

Default value: "Pick a Color"

Since 2.4

### The "`use-alpha`" property

      "use-alpha"            gboolean              : Read / Write

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.

Default value: FALSE

Since 2.4

## Signals

### The "color-set" signal

    void        user_function                  (GtkColorButton *widget,
                                                gpointer user_data);

The ::color-set signal is emitted when the user selects a color. When handling this signal, use `gtk_color_button_get_color()` and `gtk_color_button_get_alpha()` to find out which color was just selected.

`widget` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

Since 2.4

## See Also

GtkColorSelectionDialog, GtkFontButton