## gtk_colorComboBoxWidget gtk_colorComboBoxWidget — Defines a specialised GtkComboBox to choose stored colours. |

## Synopsis

    #include <coreTools/toolColor.h>

    #define             COLOR_COMBOX_TYPE
    #define             COLOR_COMBOX                        (obj)
    #define             COLOR_COMBOX_CLASS                  (klass)
    #define             IS_COLOR_COMBOX                     (obj)
    #define             IS_COLOR_COMBOX_CLASS               (klass)
                        ColorComboBox;
                        ColorComboBoxClass;
    GType               colorComboBox_get_type              (void);
    GtkWidget*          colorComboBox_new                   (gboolean hasAlphaChannel);
    GtkWidget*          colorComboBox_newWithRanges         (gboolean hasAlphaChannel);
    gboolean            colorComboBoxSet_selectionByColor   (ColorComboBox *colorComboBox,
                                                             ToolColor *color);
    void                colorComboBoxSet_color              (ColorComboBox *colorComboBox,
                                                             float rgba[4],
                                                             gboolean raiseSignal);
    void                colorComboBoxSet_material           (ColorComboBox *colorComboBox,
                                                             float material[nb_material],
                                                             gboolean raiseSignal);
    GdkPixbuf*          colorComboBoxGet_selectedPixbuf     (ColorComboBox *colorComboBox);
    ToolColor*          colorComboBoxGet_selectedColor      (ColorComboBox *colorComboBox);
    GdkPixbuf*          colorComboBoxGet_pixbufFromColor    (ColorComboBox *colorComboBox,
                                                             ToolColor *color);
    float*              colorComboBoxGet_material           (ColorComboBox *colorComboBox);
    float*              colorComboBoxGet_color              (ColorComboBox *colorComboBox);
    GdkPixbuf*          colorComboBoxBuild_colorStamp       (ToolColor *color,
                                                             gboolean alpha);
    void                colorComboBoxSet_expanded           (ColorComboBox *colorComboBox,
                                                             gboolean value);
    GtkWidget*          colorComboBoxGet_rangesWidgets      (ColorComboBox *colorComboBox);
    void                colorComboBoxSet_printValues        (ColorComboBox *colorComboBox,
                                                             gboolean value);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBin
                                     +----GtkComboBox
                                           +----ColorComboBox

## Implemented Interfaces

ColorComboBox implements AtkImplementorIface, GtkBuildable, GtkCellLayout and GtkCellEditable.

## Signals

      "color-selected"                                 : Run First / Action
      "color-value-changed"                            : Run First / Action
      "material-value-changed"                         : Run First / Action

## Description

This widget looks like a GtkComboBox and it displays a list of stored colours. These colours may come from the configuration files or can be selected and stored by the user actions. To do it, the first entry of the combo box is 'new / modify', that opens a GTK colour picker. The new values are used to craete a new colour entry in the combo box. In a complete version, the combo box can have a GtkVBox associated to modify colours without creating new entries, see `colorComboBox_newWithRanges()` method. Otherwise, only already selected colours are available. The stored colours are shared by all widgets of this class. It is thus a convenient way to have coherent colour picker through V_Sim.

When the widget is created with ranges, the additional part can be retrieve with `colorComboBoxGet_rangesWidgets()` and attached whereever is convenient. When the ranges are modified, the new colour is not added to the combo box. It can be read using `colorComboBoxGet_color()` or `colorComboBoxGet_material()`. The combo box is set thus to an unselected state and `colorComboBoxGet_selectedColor()` will return a NULL pointer. Besides the colour ranges, there is an add button to insert the newly defined colour into the combo box.

This widget can emit a "color-selected" signal that is a wrapper around the "changed" signal, but it is emitted only when a new colour is selected (either an existing one or a newly created from the picker). This colour is passed to the callback. The two other signals, "color-value-changed" and "material-value-changed", are generated when the widget have been created with ranges and that one of these ranges is modified.

## Details

### COLOR_COMBOX_TYPE

    #define COLOR_COMBOX_TYPE         (colorComboBox_get_type ())

Return the associated GType to the ColorComboBox objects.

Since 3.1

### COLOR_COMBOX()

    #define COLOR_COMBOX(obj)         (G_TYPE_CHECK_INSTANCE_CAST ((obj), COLOR_COMBOX_TYPE, ColorComboBox))

Cast the given object to a ColorComboBox object.

`obj` : | the widget to cast.

Since 3.1

### COLOR_COMBOX_CLASS()

    #define COLOR_COMBOX_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), COLOR_COMBOX_TYPE, ColorComboBoxClass))

Cast the given class to a ColorComboBoxClass object.

`klass` : | the class to cast.

Since 3.1

### IS_COLOR_COMBOX()

    #define IS_COLOR_COMBOX(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), COLOR_COMBOX_TYPE))

Return if the given object is a valid ColorComboBox object.

`obj` : | the object to test.

Since 3.1

### IS_COLOR_COMBOX_CLASS()

    #define IS_COLOR_COMBOX_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), COLOR_COMBOX_TYPE))

Return if the given class is a valid ColorComboBoxClass class.

`klass` : | the class to test.

Since 3.1

### ColorComboBox

    typedef struct _ColorComboBox ColorComboBox;

Private structure to store informations of a ColorComboBox object.

Since 3.1

### ColorComboBoxClass

    typedef struct _ColorComboBoxClass ColorComboBoxClass;

Private structure to store informations of a ColorComboBoxClass object.

Since 3.1

### colorComboBox_get_type ()

    GType               colorComboBox_get_type              (void);

GType are unique numbers to identify objects.

Returns : | the GType associated with ColorComboBox objects.

Since 3.1

### colorComboBox_new ()

    GtkWidget*          colorComboBox_new                   (gboolean hasAlphaChannel);

A ColorComboBox widget is like a GtkComboBox widget, but it is already filled with the colors stores in the structures adhoc in visu_tools.h. Using this widget is a convienient way to share colors between all part of V_Sim and to give a consistent look of all color selection. If the argument `hasAlphaChannel` is FALSE, the widget display all colors but without their alpha channel, assuming it to be fully opaque.

`hasAlphaChannel` : | a boolean.
Returns : | a newly created ColorComboBox widget.

Since 3.1

### colorComboBox_newWithRanges ()

    GtkWidget*          colorComboBox_newWithRanges         (gboolean hasAlphaChannel);

Create a color combo and several ranges.

`hasAlphaChannel` : | a boolean.
Returns : | a newly created ColorComboBox widget.

Since 3.3

### colorComboBoxSet_selectionByColor ()

    gboolean            colorComboBoxSet_selectionByColor   (ColorComboBox *colorComboBox,
                                                             ToolColor *color);

Use this method to set the ComboBox on the given color. This emits a 'color-channel' signal if the color is changed, which means, a previous color has been modified, or a new color is selected.

`colorComboBox` : | a ColorComboBox widget ;
`color` : | a ToolColor object.
Returns : | TRUE if the `color` already exists in the model.

Since 3.1

### colorComboBoxSet_color ()

    void                colorComboBoxSet_color              (ColorComboBox *colorComboBox,
                                                             float rgba[4],
                                                             gboolean raiseSignal);

Change the values for the ranges that control the color. If the color exists in the list, it is also selected. This is possible only if the `colorComboBox` has been created with `colorComboBox_newWithRanges()`.

`colorComboBox` : | a ColorComboBox widget ;
`rgba` : | 4 floating point values ;
`raiseSignal` : | if TRUE a material-value-changed can be raised.

Since 3.3

### colorComboBoxSet_material ()

    void                colorComboBoxSet_material           (ColorComboBox *colorComboBox,
                                                             float material[nb_material],
                                                             gboolean raiseSignal);

Change the values for the ranges that control the light (emission, diffuse...). This is possible only if the `colorComboBox` has been created with `colorComboBox_newWithRanges()`.

`colorComboBox` : | a ColorComboBox widget ;
`material` : | nb_material (see Material) floating point values ;
`raiseSignal` : | if TRUE a material-value-changed can be raised.

Since 3.3

### colorComboBoxGet_selectedPixbuf ()

    GdkPixbuf*          colorComboBoxGet_selectedPixbuf     (ColorComboBox *colorComboBox);

The `colorComboBox` has little pixbufs to represent the color. User methods can use these pixbufs but should considered them read-only.

`colorComboBox` : | a ColorComboBox widget.
Returns : | a pixbuf pointer corresponding to the little image shown on the `colorComboBox`.

Since 3.1

### colorComboBoxGet_selectedColor ()

    ToolColor*          colorComboBoxGet_selectedColor      (ColorComboBox *colorComboBox);

The user can access to the selected ToolColor object using this method.

`colorComboBox` : | a ColorComboBox widget.
Returns : | a pointer to the selected ToolColor object (or NULL). This object is read-only.

Since 3.1

### colorComboBoxGet_pixbufFromColor ()

    GdkPixbuf*          colorComboBoxGet_pixbufFromColor    (ColorComboBox *colorComboBox,
                                                             ToolColor *color);

The `colorComboBox` has little pixbufs to represent the color. User methods can use these pixbufs but should considered them read-only.

`colorComboBox` : | a ColorComboBox widget ;
`color` : | a ToolColor object.
Returns : | a pixbuf pointer corresponding to the little image shown on the `colorComboBox`.

Since 3.1

### colorComboBoxGet_material ()

    float*              colorComboBoxGet_material           (ColorComboBox *colorComboBox);

If the `colorComboBox` uses ranges (see `colorComboBox_newWithRanges()`), this method is used to get the values from the material ranges.

`colorComboBox` : | a ColorComboBox widget.
Returns : | a newly created array of size nb_material (see Material). Use `g_free()` to delete it.

Since 3.3

### colorComboBoxGet_color ()

    float*              colorComboBoxGet_color              (ColorComboBox *colorComboBox);

If the `colorComboBox` uses ranges (see `colorComboBox_newWithRanges()`), this method is used to get the values from the color ranges.

`colorComboBox` : | a ColorComboBox widget.
Returns : | a newly created array of size 4. Use `g_free()` to delete it.

Since 3.2

### colorComboBoxBuild_colorStamp ()

    GdkPixbuf*          colorComboBoxBuild_colorStamp       (ToolColor *color,
                                                             gboolean alpha);

This method is used by ColorComboBox object to create little stamps representing the color. If the pixbuf of such stamps are needed, use `colorComboBoxGet_pixbufFromColor()` if the color is registered in an already existing ColorComboBox object or use this method to create a new stamp.

`color` : | a ToolColor object ;
`alpha` : | a boolean.
Returns : | a pixbuf pointer corresponding to the little image as shown on a `colorComboBox` (use `g_object_unref()` to free this pixbuf).

Since 3.1

### colorComboBoxSet_expanded ()

    void                colorComboBoxSet_expanded           (ColorComboBox *colorComboBox,
                                                             gboolean value);

Set the expanded state of the ranges. This is usable only if the colorComboBox has been created with ranges.

`colorComboBox` : | a ToolColor object ;
`value` : | a boolean value.

Since 3.3

### colorComboBoxGet_rangesWidgets ()

    GtkWidget*          colorComboBoxGet_rangesWidgets      (ColorComboBox *colorComboBox);

Retrieve the wiodget using to represent the ranges, or NULL if the object has no ranges.

`colorComboBox` : | a ToolColor object.
Returns : | a widget owned by `color`.

Since 3.3

### colorComboBoxSet_printValues ()

    void                colorComboBoxSet_printValues        (ColorComboBox *colorComboBox,
                                                             gboolean value);

Print or not the RGB values.

`colorComboBox` : | a ToolColor object ;
`value` : | a boolean.

Since 3.4

## Signal Details

### The `"color-selected"` signal

    void                user_function                      (ColorComboBox *combo,
                                                            gpointer       color,
                                                            gpointer       user_data)      : Run First / Action

This signal is emitted when a new valid colour is selected, either an existing one or newly created one.

`combo` : | the ColorComboBox that emits the signal ;
`color` : | the newly selected ToolColor.
`user_data` : | user data set when the signal handler was connected.

Since 3.1

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

    void                user_function                      (ColorComboBox *combo,
                                                            guint          RGBA,
                                                            gpointer       user_data)      : Run First / Action

This signal is emitted when the range of a colour is modified.

`combo` : | the ColorComboBox that emits the signal ;
`RGBA` : | the modified channel.
`user_data` : | user data set when the signal handler was connected.

Since 3.3

### The `"material-value-changed"` signal

    void                user_function                      (ColorComboBox *combo,
                                                            guint          mat,
                                                            gpointer       user_data)      : Run First / Action

This signal is emitted when the range of a material is modified.

`combo` : | the ColorComboBox that emits the signal ;
`mat` : | the modified material channel (see Material).
`user_data` : | user data set when the signal handler was connected.

Since 3.3

## See Also

ToolColor, StippleComboBox, ShadeComboBox