## GwyGrainValueTreeView

GwyGrainValueTreeView — Grain value display/selector

## Functions

GtkWidget * | gwy_grain_value_tree_view_new ()
void | gwy_grain_value_tree_view_set_expanded_groups ()
guint | gwy_grain_value_tree_view_get_expanded_groups ()
gint | gwy_grain_value_tree_view_n_enabled ()
const gchar ** | gwy_grain_value_tree_view_get_enabled ()
void | gwy_grain_value_tree_view_set_enabled ()
void | gwy_grain_value_tree_view_select ()
void | gwy_grain_value_tree_view_set_same_units ()

## Types and Values

enum | GwyGrainValueStoreColumn

## Includes

    #include <libgwyui/gwyui.h>

## Description

## Functions

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

#### Parameters

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.

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

#### Parameters

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()`. |

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

#### Parameters

treeview | A tree view with grain values. |

#### Returns

The expansion state, see `gwy_grain_value_tree_view_set_expanded_groups()` for details.

### 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_STORE_COLUMN_ENABLED` column set to `TRUE` in the model.

#### Parameters

treeview | A tree view with grain values. |

#### Returns

The number of enabled values.

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

#### Parameters

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.

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

#### Parameters

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

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

#### Parameters

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

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

#### Parameters

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

## Types and Values

### enum GwyGrainValueStoreColumn

Columns of the grain value tree view GtkTreeStore model.

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

#### Members

GWY_GRAIN_STORE_COLUMN_ITEM | Grain value itself (`NULL` for non-leaves), the column type is GwyGrainValue. |
GWY_GRAIN_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_STORE_COLUMN_ENABLED | Enabled/disabled state (meaning is undefined for non-leaves and reserved for future use), the column type is gboolean. |