## gwygrainvaluemenu

gwygrainvaluemenu — Grain value display/selector

## Synopsis

    #include <libgwydgets/gwydgets.h>

    enum                GwyGrainValueStoreColumn;
    GtkWidget*          gwy_grain_value_tree_view_new       (gboolean show_id,
                                                             const gchar *first_column,
                                                             ...);
    void                gwy_grain_value_tree_view_set_expanded_groups
                                                            (GtkTreeView *treeview,
                                                             guint expanded_bits);
    guint               gwy_grain_value_tree_view_get_expanded_groups
                                                            (GtkTreeView *treeview);
    gint                gwy_grain_value_tree_view_n_enabled (GtkTreeView *treeview);
    const gchar**       gwy_grain_value_tree_view_get_enabled
                                                            (GtkTreeView *treeview);
    void                gwy_grain_value_tree_view_set_enabled
                                                            (GtkTreeView *treeview,
                                                             gchar **names);
    void                gwy_grain_value_tree_view_select    (GtkTreeView *treeview,
                                                             GwyGrainValue *gvalue);
    void                gwy_grain_value_tree_view_set_same_units
                                                            (GtkTreeView *treeview,
                                                             gboolean same_units);

## Description

## Details

### enum GwyGrainValueStoreColumn

    typedef enum {
        GWY_GRAIN_VALUE_STORE_COLUMN_ITEM,
        GWY_GRAIN_VALUE_STORE_COLUMN_GROUP,
        GWY_GRAIN_VALUE_STORE_COLUMN_ENABLED
    } GwyGrainValueStoreColumn;

Columns of the grain value tree view GtkTreeStore model.

It must not be assumed these are the only columns in the tree store.

`GWY_GRAIN_VALUE_STORE_COLUMN_ITEM` | Grain value itself (`NULL` for non-leaves), the column type is GwyGrainValue.
`GWY_GRAIN_VALUE_STORE_COLUMN_GROUP` | Grain value group, useful namely for non-leaves (identical to the value group for leaves), the column type is GwyGrainValueGroup.
`GWY_GRAIN_VALUE_STORE_COLUMN_ENABLED` | Enabled/disabled state (meaning is undefined for non-leaves and reserved for future use), the column type is gboolean.

Since 2.8

### gwy_grain_value_tree_view_new ()

    GtkWidget*          gwy_grain_value_tree_view_new       (gboolean show_id,
                                                             const gchar *first_column,
                                                             ...);

Creates a new tree view selector of grain values.

Possible column names are `"name"` for the grain value name, `"symbol_markup"` for the rich text symbol, `"symbol"` for identifier-style symbol and `"enabled"` for a checkbox column.

The tree view selection is set to `GTK_SELECTION_BROWSE` mode and it is allowed only on leaves.

`show_id` : | `TRUE` to include grain id number among the values, `FALSE` to exclude it.
`first_column` : | The first column to show (may be `NULL` for no columns).
`...` : | `NULL`-terminated list of columns to show.
Returns : | A new tree view with grain values.

Since 2.8

### gwy_grain_value_tree_view_set_expanded_groups ()

    void                gwy_grain_value_tree_view_set_expanded_groups
                                                            (GtkTreeView *treeview,
                                                             guint expanded_bits);

Restores a grain value tree view group expansion state.

`treeview` : | A tree view with grain values.
`expanded_bits` : | Integer with bits of GwyGrainValueGroup set if the corresponding group should be expanded. Typically this is either zero or a value previously obtained from `gwy_grain_value_tree_view_get_expanded_groups()`.

Since 2.8

### gwy_grain_value_tree_view_get_expanded_groups ()

    guint               gwy_grain_value_tree_view_get_expanded_groups
                                                            (GtkTreeView *treeview);

Obtains the group expansion state of a grain value tree view.

`treeview` : | A tree view with grain values.
Returns : | The expansion state, see `gwy_grain_value_tree_view_set_expanded_groups()` for details.

Since 2.8

### gwy_grain_value_tree_view_n_enabled ()

    gint                gwy_grain_value_tree_view_n_enabled (GtkTreeView *treeview);

Gets the number of enabled values in a grain value tree view.

Enabled values are those with `GWY_GRAIN_VALUE_STORE_COLUMN_ENABLED` column set to `TRUE` in the model.

`treeview` : | A tree view with grain values.
Returns : | The number of enabled values.

Since 2.8

### gwy_grain_value_tree_view_get_enabled ()

    const gchar**       gwy_grain_value_tree_view_get_enabled
                                                            (GtkTreeView *treeview);

Obtains the list of enabled values in a grain value tree view.

`treeview` : | A tree view with grain values.
Returns : | The list of grain value names. The list must be freed by the caller, the strings are however owned by the individual grain values and must not be freed.

Since 2.8

### gwy_grain_value_tree_view_set_enabled ()

    void                gwy_grain_value_tree_view_set_enabled
                                                            (GtkTreeView *treeview,
                                                             gchar **names);

Sets the set of enabled values in a grain value tree view.

The tree is possibly expanded so that all enabled values are visible.

`treeview` : | A tree view with grain values.
`names` : | Array of grain value names to enables. All grain values not present here are disabled.

Since 2.8

### gwy_grain_value_tree_view_select ()

    void                gwy_grain_value_tree_view_select    (GtkTreeView *treeview,
                                                             GwyGrainValue *gvalue);

Selects a particular grain value in a grain value tree view.

If the `gvalue` group is currently unexpanded, it will be expanded to show it, and the tree view may scroll to make it visible.

`treeview` : | A tree view with grain values.
`gvalue` : | The grain value to select.

Since 2.8

### gwy_grain_value_tree_view_set_same_units ()

    void                gwy_grain_value_tree_view_set_same_units
                                                            (GtkTreeView *treeview,
                                                             gboolean same_units);

Sets the availability of grain values that require the same lateral and value units.

This `same_units` is `FALSE`, grain values requiring matching units will be disabled. This means they will not be selectable, names and symbols will be displayed greyed out, checkboxes will be made non-activatable (if they are currently checked, they will not be unchecked but they will be displayed as inconsistent).

By default `same_units` is `TRUE`.

`treeview` : | A tree view with grain values.
`same_units` : | `TRUE` if the lateral and value units match and therefore all grain values are calculable, `FALSE` if they don't match and values that require same units are disabled.

Since 2.8