## 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);
    GtkWidget *         gtk_color_button_new_with_rgba      (const GdkRGBA *rgba);
    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_rgba           (GtkColorButton *color_button,
                                                             const GdkRGBA *rgba);
    void                gtk_color_button_get_rgba           (GtkColorButton *color_button,
                                                             GdkRGBA *rgba);
    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);
    const gchar *       gtk_color_button_get_title          (GtkColorButton *color_button);

## Object Hierarchy

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

## Implemented Interfaces

GtkColorButton implements AtkImplementorIface, GtkBuildable and GtkActivatable.

## Properties

      "alpha"                    guint                 : Read / Write
      "color"                    GdkColor*             : Read / Write
      "rgba"                     GdkRGBA*              : Read / Write
      "title"                    gchar*                : Read / Write
      "use-alpha"                gboolean              : Read / Write

## Signals

      "color-set"                                      : Run First

## 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_new_with_rgba ()

    GtkWidget *         gtk_color_button_new_with_rgba      (const GdkRGBA *rgba);

Creates a new color button.

`rgba` : | A GdkRGBA to set the current color with
Returns : | a new color button

Since 3.0

### 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. [out]

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_rgba ()

    void                gtk_color_button_set_rgba           (GtkColorButton *color_button,
                                                             const GdkRGBA *rgba);

Sets the current color to be `rgba`.

`color_button` : | a GtkColorButton
`rgba` : | a GdkRGBA to set the current color with

Since 3.0

### gtk_color_button_get_rgba ()

    void                gtk_color_button_get_rgba           (GtkColorButton *color_button,
                                                             GdkRGBA *rgba);

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

`color_button` : | a GtkColorButton
`rgba` : | a GdkRGBA to fill in with the current color. [out]

Since 3.0

### 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 ()

    const 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

## Property Details

### 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 `"rgba"` property

      "rgba"                     GdkRGBA*              : Read / Write

The RGBA color.

Since 3.0

### The `"title"` property

      "title"                    gchar*                : 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

## Signal Details

### The `"color-set"` signal

    void                user_function                      (GtkColorButton *widget,
                                                            gpointer        user_data)      : Run First

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()` (or `gtk_color_button_get_rgba()`) to find out which color was just selected.

Note that this signal is only emitted when the user changes the color. If you need to react to programmatic color changes as well, use the notify::color signal.

`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