GtkColorSelection

## GtkColorSelection GtkColorSelection — A widget used to select a color |

## Synopsis

    #include <gtk/gtk.h>

    struct              GtkColorSelection;
    GtkWidget *         gtk_color_selection_new             (void);
    void                gtk_color_selection_set_has_opacity_control
                                                            (GtkColorSelection *colorsel,
                                                             gboolean has_opacity);
    gboolean            gtk_color_selection_get_has_opacity_control
                                                            (GtkColorSelection *colorsel);
    void                gtk_color_selection_set_has_palette (GtkColorSelection *colorsel,
                                                             gboolean has_palette);
    gboolean            gtk_color_selection_get_has_palette (GtkColorSelection *colorsel);
    guint16             gtk_color_selection_get_current_alpha
                                                            (GtkColorSelection *colorsel);
    void                gtk_color_selection_set_current_alpha
                                                            (GtkColorSelection *colorsel,
                                                             guint16 alpha);
    void                gtk_color_selection_get_current_color
                                                            (GtkColorSelection *colorsel,
                                                             GdkColor *color);
    void                gtk_color_selection_set_current_color
                                                            (GtkColorSelection *colorsel,
                                                             const GdkColor *color);
    guint16             gtk_color_selection_get_previous_alpha
                                                            (GtkColorSelection *colorsel);
    void                gtk_color_selection_set_previous_alpha
                                                            (GtkColorSelection *colorsel,
                                                             guint16 alpha);
    void                gtk_color_selection_get_previous_color
                                                            (GtkColorSelection *colorsel,
                                                             GdkColor *color);
    void                gtk_color_selection_set_previous_color
                                                            (GtkColorSelection *colorsel,
                                                             const GdkColor *color);
    void                gtk_color_selection_get_current_rgba
                                                            (GtkColorSelection *colorsel,
                                                             GdkRGBA *rgba);
    void                gtk_color_selection_set_current_rgba
                                                            (GtkColorSelection *colorsel,
                                                             const GdkRGBA *rgba);
    void                gtk_color_selection_get_previous_rgba
                                                            (GtkColorSelection *colorsel,
                                                             GdkRGBA *rgba);
    void                gtk_color_selection_set_previous_rgba
                                                            (GtkColorSelection *colorsel,
                                                             const GdkRGBA *rgba);
    gboolean            gtk_color_selection_is_adjusting    (GtkColorSelection *colorsel);
    gboolean            gtk_color_selection_palette_from_string
                                                            (const gchar *str,
                                                             GdkColor **colors,
                                                             gint *n_colors);
    gchar *             gtk_color_selection_palette_to_string
                                                            (const GdkColor *colors,
                                                             gint n_colors);
    void                (*GtkColorSelectionChangePaletteFunc)
                                                            (const GdkColor *colors,
                                                             gint n_colors);
    GtkColorSelectionChangePaletteWithScreenFunc gtk_color_selection_set_change_palette_with_screen_hook
                                                            (GtkColorSelectionChangePaletteWithScreenFunc func);
    void                (*GtkColorSelectionChangePaletteWithScreenFunc)
                                                            (GdkScreen *screen,
                                                             const GdkColor *colors,
                                                             gint n_colors);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBox
                               +----GtkColorSelection

## Implemented Interfaces

GtkColorSelection implements AtkImplementorIface, GtkBuildable and GtkOrientable.

## Properties

      "current-alpha"            guint                 : Read / Write
      "current-color"            GdkColor*             : Read / Write
      "current-rgba"             GdkRGBA*              : Read / Write
      "has-opacity-control"      gboolean              : Read / Write
      "has-palette"              gboolean              : Read / Write

## Signals

      "color-changed"                                  : Run First

## Description

The GtkColorSelection is a widget that is used to select a color. It consists of a color wheel and number of sliders and entry boxes for color parameters such as hue, saturation, value, red, green, blue, and opacity. It is found on the standard color selection dialog box GtkColorSelectionDialog.

## Details

### struct GtkColorSelection

    struct GtkColorSelection;

### gtk_color_selection_new ()

    GtkWidget *         gtk_color_selection_new             (void);

Creates a new GtkColorSelection.

Returns : | a new GtkColorSelection

### gtk_color_selection_set_has_opacity_control ()

    void                gtk_color_selection_set_has_opacity_control
                                                            (GtkColorSelection *colorsel,
                                                             gboolean has_opacity);

Sets the `colorsel` to use or not use opacity.

`colorsel` : | a GtkColorSelection
`has_opacity` : | `TRUE` if `colorsel` can set the opacity, `FALSE` otherwise

### gtk_color_selection_get_has_opacity_control ()

    gboolean            gtk_color_selection_get_has_opacity_control
                                                            (GtkColorSelection *colorsel);

Determines whether the colorsel has an opacity control.

`colorsel` : | a GtkColorSelection
Returns : | `TRUE` if the `colorsel` has an opacity control, `FALSE` if it does't

### gtk_color_selection_set_has_palette ()

    void                gtk_color_selection_set_has_palette (GtkColorSelection *colorsel,
                                                             gboolean has_palette);

Shows and hides the palette based upon the value of `has_palette`.

`colorsel` : | a GtkColorSelection
`has_palette` : | `TRUE` if palette is to be visible, `FALSE` otherwise

### gtk_color_selection_get_has_palette ()

    gboolean            gtk_color_selection_get_has_palette (GtkColorSelection *colorsel);

Determines whether the color selector has a color palette.

`colorsel` : | a GtkColorSelection
Returns : | `TRUE` if the selector has a palette, `FALSE` if it hasn't

### gtk_color_selection_get_current_alpha ()

    guint16             gtk_color_selection_get_current_alpha
                                                            (GtkColorSelection *colorsel);

Returns the current alpha value.

`colorsel` : | a GtkColorSelection
Returns : | an integer between 0 and 65535

### gtk_color_selection_set_current_alpha ()

    void                gtk_color_selection_set_current_alpha
                                                            (GtkColorSelection *colorsel,
                                                             guint16 alpha);

Sets the current opacity to be `alpha`.

The first time this is called, it will also set the original opacity to be `alpha` too.

`colorsel` : | a GtkColorSelection
`alpha` : | an integer between 0 and 65535

### gtk_color_selection_get_current_color ()

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

### Warning

`gtk_color_selection_get_current_color` has been deprecated since version 3.4 and should not be used in newly-written code. Use `gtk_color_selection_get_current_rgba()` instead.

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

`colorsel` : | a GtkColorSelection
`color` : | a GdkColor to fill in with the current color. [out]

### gtk_color_selection_set_current_color ()

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

### Warning

`gtk_color_selection_set_current_color` has been deprecated since version 3.4 and should not be used in newly-written code. Use `gtk_color_selection_set_current_rgba()` instead.

Sets the current color to be `color`.

The first time this is called, it will also set the original color to be `color` too.

`colorsel` : | a GtkColorSelection
`color` : | a GdkColor to set the current color with

### gtk_color_selection_get_previous_alpha ()

    guint16             gtk_color_selection_get_previous_alpha
                                                            (GtkColorSelection *colorsel);

Returns the previous alpha value.

`colorsel` : | a GtkColorSelection
Returns : | an integer between 0 and 65535

### gtk_color_selection_set_previous_alpha ()

    void                gtk_color_selection_set_previous_alpha
                                                            (GtkColorSelection *colorsel,
                                                             guint16 alpha);

Sets the 'previous' alpha to be `alpha`.

This function should be called with some hesitations, as it might seem confusing to have that alpha change.

`colorsel` : | a GtkColorSelection
`alpha` : | an integer between 0 and 65535

### gtk_color_selection_get_previous_color ()

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

### Warning

`gtk_color_selection_get_previous_color` has been deprecated since version 3.4 and should not be used in newly-written code. Use `gtk_color_selection_get_previous_rgba()` instead.

Fills `color` in with the original color value.

`colorsel` : | a GtkColorSelection
`color` : | a GdkColor to fill in with the original color value. [out]

### gtk_color_selection_set_previous_color ()

    void                gtk_color_selection_set_previous_color
                                                            (GtkColorSelection *colorsel,
                                                             const GdkColor *color);

### Warning

`gtk_color_selection_set_previous_color` has been deprecated since version 3.4 and should not be used in newly-written code. Use `gtk_color_selection_set_previous_rgba()` instead.

Sets the 'previous' color to be `color`.

This function should be called with some hesitations, as it might seem confusing to have that color change. Calling `gtk_color_selection_set_current_color()` will also set this color the first time it is called.

`colorsel` : | a GtkColorSelection
`color` : | a GdkColor to set the previous color with

### gtk_color_selection_get_current_rgba ()

    void                gtk_color_selection_get_current_rgba
                                                            (GtkColorSelection *colorsel,
                                                             GdkRGBA *rgba);

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

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

Since 3.0

### gtk_color_selection_set_current_rgba ()

    void                gtk_color_selection_set_current_rgba
                                                            (GtkColorSelection *colorsel,
                                                             const GdkRGBA *rgba);

Sets the current color to be `rgba`.

The first time this is called, it will also set the original color to be `rgba` too.

`colorsel` : | a GtkColorSelection
`rgba` : | A GdkRGBA to set the current color with

Since 3.0

### gtk_color_selection_get_previous_rgba ()

    void                gtk_color_selection_get_previous_rgba
                                                            (GtkColorSelection *colorsel,
                                                             GdkRGBA *rgba);

Fills `rgba` in with the original color value.

`colorsel` : | a GtkColorSelection
`rgba` : | a GdkRGBA to fill in with the original color value. [out]

Since 3.0

### gtk_color_selection_set_previous_rgba ()

    void                gtk_color_selection_set_previous_rgba
                                                            (GtkColorSelection *colorsel,
                                                             const GdkRGBA *rgba);

Sets the 'previous' color to be `rgba`.

This function should be called with some hesitations, as it might seem confusing to have that color change. Calling `gtk_color_selection_set_current_rgba()` will also set this color the first time it is called.

`colorsel` : | a GtkColorSelection
`rgba` : | a GdkRGBA to set the previous color with

Since 3.0

### gtk_color_selection_is_adjusting ()

    gboolean            gtk_color_selection_is_adjusting    (GtkColorSelection *colorsel);

Gets the current state of the `colorsel`.

`colorsel` : | a GtkColorSelection
Returns : | `TRUE` if the user is currently dragging a color around, and `FALSE` if the selection has stopped

### gtk_color_selection_palette_from_string ()

    gboolean            gtk_color_selection_palette_from_string
                                                            (const gchar *str,
                                                             GdkColor **colors,
                                                             gint *n_colors);

Parses a color palette string; the string is a colon-separated list of color names readable by `gdk_color_parse()`.

`str` : | a string encoding a color palette
`colors` : | return location for allocated array of GdkColor. [out][array length=n_colors]
`n_colors` : | return location for length of array
Returns : | `TRUE` if a palette was successfully parsed

### gtk_color_selection_palette_to_string ()

    gchar *             gtk_color_selection_palette_to_string
                                                            (const GdkColor *colors,
                                                             gint n_colors);

Encodes a palette as a string, useful for persistent storage.

`colors` : | an array of colors. [array length=n_colors]
`n_colors` : | length of the array
Returns : | allocated string encoding the palette

### GtkColorSelectionChangePaletteFunc ()

    void                (*GtkColorSelectionChangePaletteFunc)
                                                            (const GdkColor *colors,
                                                             gint n_colors);

### gtk_color_selection_set_change_palette_with_screen_hook ()

    GtkColorSelectionChangePaletteWithScreenFunc gtk_color_selection_set_change_palette_with_screen_hook
                                                            (GtkColorSelectionChangePaletteWithScreenFunc func);

Installs a global function to be called whenever the user tries to modify the palette in a color selection.

This function should save the new palette contents, and update the "gtk-color-palette" GtkSettings property so all GtkColorSelection widgets will be modified.

`func` : | a function to call when the custom palette needs saving
Returns : | the previous change palette hook (that was replaced)

Since 2.2

### GtkColorSelectionChangePaletteWithScreenFunc ()

    void                (*GtkColorSelectionChangePaletteWithScreenFunc)
                                                            (GdkScreen *screen,
                                                             const GdkColor *colors,
                                                             gint n_colors);

Since 2.2

## Property Details

### The `"current-alpha"` property

      "current-alpha"            guint                 : Read / Write

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

Allowed values: <= 65535

Default value: 65535

### The `"current-color"` property

      "current-color"            GdkColor*             : Read / Write

### Warning

`GtkColorSelection:current-color` has been deprecated since version 3.4 and should not be used in newly-written code. Use "current-rgba" instead.

The current GdkColor color.

### The `"current-rgba"` property

      "current-rgba"             GdkRGBA*              : Read / Write

The current RGBA color.

Since 3.0

### The `"has-opacity-control"` property

      "has-opacity-control"      gboolean              : Read / Write

Whether the color selector should allow setting opacity.

Default value: FALSE

### The `"has-palette"` property

      "has-palette"              gboolean              : Read / Write

Whether a palette should be used.

Default value: FALSE

## Signal Details

### The `"color-changed"` signal

    void                user_function                      (GtkColorSelection *colorselection,
                                                            gpointer           user_data)           : Run First

This signal is emitted when the color changes in the GtkColorSelection according to its update policy.

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