## gwycombobox

gwycombobox — Combo box constructors

## Synopsis

    #include <libgwydgets/gwydgets.h>

    GtkWidget*          gwy_enum_combo_box_new              (const GwyEnum *entries,
                                                             gint nentries,
                                                             GCallback callback,
                                                             gpointer cbdata,
                                                             gint active,
                                                             gboolean translate);
    GtkWidget*          gwy_enum_combo_box_newl             (GCallback callback,
                                                             gpointer cbdata,
                                                             gint active,
                                                             ...);
    GtkWidget*          gwy_combo_box_metric_unit_new       (GCallback callback,
                                                             gpointer cbdata,
                                                             gint from,
                                                             gint to,
                                                             GwySIUnit *unit,
                                                             gint active);
    void                gwy_combo_box_metric_unit_set_unit  (GtkComboBox *combo,
                                                             gint from,
                                                             gint to,
                                                             GwySIUnit *unit);
    void                gwy_enum_combo_box_set_active       (GtkComboBox *combo,
                                                             gint active);
    gint                gwy_enum_combo_box_get_active       (GtkComboBox *combo);
    void                gwy_enum_combo_box_update_int       (GtkComboBox *combo,
                                                             gint *integer);

## Description

Combo boxes can be easily constructed from GwyEnum's with `gwy_enum_combo_box_new()`. Here's an example of construction of a combo box with three items:

    typedef enum {
        MY_ENUM_FOO, MY_ENUM_BAR, MY_ENUM_BAZ
    } MyEnum;

    static GwyEnum my_enum_fields[] = {
        { N_("Foo"), MY_ENUM_FOO },
        { N_("Bar"), MY_ENUM_BAR },
        { N_("Baz"), MY_ENUM_BAZ },
    };

    static void
    menu_callback(GtkWidget *combo, gpointer cbdata)
    {
        MyEnum value;

        value = gwy_enum_combo_box_get_active(GTK_COMBO_BOX(combo));
        ...
    }

    static void
    function(void) {
        GtkWidget *combo;
        ...

        combo = gwy_enum_combo_box_new(fields, G_N_ELEMENTS(fields),
                                       G_CALLBACK(menu_callback), NULL,
                                       MY_ENUM_FOO, TRUE);
        ...
    }

Many common Gwyddion enumerations have companion function returning corresponding GwyEnum, see for example gwyprocessenums, making combo box construction even easier.

For example, a combo box with possible interpolation types can be constructed:

    combo = gwy_enum_combo_box_new(gwy_interpolation_type_get_enum(), -1,
                                   G_CALLBACK(menu_callback), NULL,
                                   GWY_INTERPOLATION_BILINEAR, TRUE);

## Details

### gwy_enum_combo_box_new ()

    GtkWidget*          gwy_enum_combo_box_new              (const GwyEnum *entries,
                                                             gint nentries,
                                                             GCallback callback,
                                                             gpointer cbdata,
                                                             gint active,
                                                             gboolean translate);

Creates a combo box with choices from a enum.

The array `entries` must exist during the whole lifetime of the combo box because it is used directly as the model.

`entries` : | An enum with choices.
`nentries` : | The number of items in `entries`, may be -1 when `entries` is terminated with `NULL` enum name.
`callback` : | A callback called when a new choice is selected (may be `NULL`). If you want to just update an integer, you can use `gwy_enum_combo_box_update_int()` here.
`cbdata` : | User data passed to the callback.
`active` : | The enum value to show as currently selected. If it isn't equal to any `entries` value, first item is selected.
`translate` : | Whether to apply translation function (`gwy_sgettext()`) to item names.
Returns : | A newly created combo box as GtkWidget.

### gwy_enum_combo_box_newl ()

    GtkWidget*          gwy_enum_combo_box_newl             (GCallback callback,
                                                             gpointer cbdata,
                                                             gint active,
                                                             ...);

Creates a combo box with choices from a list of label/value pairs.

The string values passed as label texts must exist through the whole lifetime of the widget.

`callback` : | A callback called when a new choice is selected (may be `NULL`).
`cbdata` : | User data passed to the callback.
`active` : | The enum value to show as currently selected. If it isn't equal to any `entries` value, the first item is selected.
`...` : | First item label, first item value, second item label, second item value, etc. Terminated with `NULL`.
Returns : | A newly created combo box as GtkWidget.

Since 2.5

### gwy_combo_box_metric_unit_new ()

    GtkWidget*          gwy_combo_box_metric_unit_new       (GCallback callback,
                                                             gpointer cbdata,
                                                             gint from,
                                                             gint to,
                                                             GwySIUnit *unit,
                                                             gint active);

Creates an enum combo box with SI power of 10 multiplies.

The integer value is the power of 10.

`callback` : | A callback called when a menu item is activated (or `NULL` for
`cbdata` : | User data passed to the callback.
`from` : | The exponent of 10 the menu should start at (a multiple of 3, will be rounded downward if isn't).
`to` : | The exponent of 10 the menu should end at (a multiple of 3, will be rounded upward if isn't).
`unit` : | The unit to be prefixed.
`active` : | The power of 10 to show as currently selected (a multiple of 3).
Returns : | The newly created combo box as GtkWidget.

### gwy_combo_box_metric_unit_set_unit ()

    void                gwy_combo_box_metric_unit_set_unit  (GtkComboBox *combo,
                                                             gint from,
                                                             gint to,
                                                             GwySIUnit *unit);

Changes the unit selection displayed by a metric unit combo box.

`combo` : | A combo box which was created with `gwy_combo_box_metric_unit_new()`.
`from` : | The exponent of 10 the menu should start at (a multiple of 3, will be rounded downward if isn't).
`to` : | The exponent of 10 the menu should end at (a multiple of 3, will be rounded upward if isn't).
`unit` : | The unit to be prefixed.

Since 2.5

### gwy_enum_combo_box_set_active ()

    void                gwy_enum_combo_box_set_active       (GtkComboBox *combo,
                                                             gint active);

Sets the active combo box item by corresponding enum value.

`combo` : | A combo box which was created with `gwy_enum_combo_box_new()`.
`active` : | The enum value to show as currently selected.

### gwy_enum_combo_box_get_active ()

    gint                gwy_enum_combo_box_get_active       (GtkComboBox *combo);

Gets the enum value corresponding to currently active combo box item.

`combo` : | A combo box which was created with `gwy_enum_combo_box_new()`.
Returns : | The selected enum value.

### gwy_enum_combo_box_update_int ()

    void                gwy_enum_combo_box_update_int       (GtkComboBox *combo,
                                                             gint *integer);

Convenience callback keeping an integer synchronized with selected enum combo box value.

`combo` : | A combo box which was created with `gwy_enum_combo_box_new()`.
`integer` : | Pointer to an integer to update to selected enum value.

## See Also

gwyradiobuttons -- radio button constructors