## Combo boxes

Combo boxes — Common combo box constructors

## Functions

GtkWidget * | gwy_enum_combo_box_new ()
GtkWidget * | gwy_enum_combo_box_newl ()
GtkWidget * | gwy_combo_box_metric_unit_new ()
void | gwy_combo_box_metric_unit_set_unit ()
GtkWidget * | gwy_combo_box_graph_curve_new ()
GtkWidget * | gwy_combo_box_lawn_curve_new ()
GtkWidget * | gwy_combo_box_lawn_segment_new ()
GtkWidget * | gwy_combo_box_scatter_data_new ()
void | gwy_enum_combo_box_set_active ()
gint | gwy_enum_combo_box_get_active ()

## Includes

    #include <libgwyui/gwyui.h>

## 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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29

    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:

    1
    2
    3

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

## Functions

### 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.

#### Parameters

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. It 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, 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.

#### Parameters

callback | A callback called when a new choice is selected. It 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.

### gwy_combo_box_metric_unit_new()

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

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

The integer value is the power of 10.

#### Parameters

callback | A callback called when a new choice is selected. It may be `NULL`. Callbacks set later may get extra updates during model changes which are prevented for `callback` . |
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,
                                        GwyUnit *unit);

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

#### Parameters

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. |

### gwy_combo_box_graph_curve_new()

    GtkWidget *
    gwy_combo_box_graph_curve_new (GCallback callback,
                                   gpointer cbdata,
                                   GwyGraphModel *gmodel,
                                   gint current);

Creates an enum combo box with curves from a graph model.

The graph model can change and the combo box reflects such changes.

#### Parameters

callback | A callback called when a new choice is selected. It may be `NULL`. Callbacks set later may get extra updates during model changes which are prevented for `callback` . |
cbdata | User data passed to the callback. |
gmodel | A graph model. |
current | Index of currently selected curve. |

#### Returns

The newly created combo box as GtkWidget.

### gwy_combo_box_lawn_curve_new()

    GtkWidget *
    gwy_combo_box_lawn_curve_new (GCallback callback,
                                  gpointer cbdata,
                                  GwyLawn *lawn,
                                  gint current);

Creates an enum combo box with curves from a lawn curve map object.

This function is intended for selection of curves from static lawn objects. The lawn object is not permitted to change.

#### Parameters

callback | A callback called when a new choice is selected. It may be `NULL`. Callbacks set later may get extra updates during model changes which are prevented for `callback` . |
cbdata | User data passed to the callback. |
lawn | A lawn curve map object. |
current | Index of currently selected curve. |

#### Returns

The newly created combo box as GtkWidget.

### gwy_combo_box_lawn_segment_new()

    GtkWidget *
    gwy_combo_box_lawn_segment_new (GCallback callback,
                                    gpointer cbdata,
                                    GwyLawn *lawn,
                                    gint current);

Creates an enum combo box with segments from a lawn curve map object.

This function is intended for selection of segments from static lawn objects. The lawn object is not permitted to change.

#### Parameters

callback | A callback called when a new choice is selected. It may be `NULL`. Callbacks set later may get extra updates during model changes which are prevented for `callback` . |
cbdata | User data passed to the callback. |
lawn | A lawn curve map object. |
current | Index of currently selected segment. |

#### Returns

The newly created combo box as GtkWidget.

### gwy_combo_box_scatter_data_new()

    GtkWidget *
    gwy_combo_box_scatter_data_new (GCallback callback,
                                    gpointer cbdata,
                                    GwyScatter *scatter,
                                    gint current);

Creates an enum combo box with data from a scattered XYZ data object.

This function is intended for selection of data from static scattered data objects. The scatter object is not permitted to change.

#### Parameters

callback | A callback called when a new choice is selected. It may be `NULL`. Callbacks set later may get extra updates during model changes which are prevented for `callback` . |
cbdata | User data passed to the callback. |
scatter | A scattered data object. |
current | Index of currently selected value. |

#### Returns

The newly created combo box as GtkWidget.

### 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.

#### Parameters

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.

Similarly to GtkComboBox, the value -1 is returned when nothing active (which can happen when there are no selectable items in the combo box).

#### Parameters

combo | A combo box which was created with `gwy_enum_combo_box_new()`. |

#### Returns

The selected enum value.

## See Also

gwyradiobuttons -- radio button constructors