## GwyDataChooser

GwyDataChooser — Data object choosers

## Synopsis

    #include <app/gwyapp.h>

    gboolean            (*GwyDataChooserFilterFunc)         (GwyContainer *data,
                                                             gint id,
                                                             gpointer user_data);
                        GwyDataChooser;
                        GwyDataChooserClass;
    GtkWidget*          gwy_data_chooser_new_channels       (void);
    gboolean            gwy_data_chooser_set_active         (GwyDataChooser *chooser,
                                                             GwyContainer *data,
                                                             gint id);
    GwyContainer*       gwy_data_chooser_get_active         (GwyDataChooser *chooser,
                                                             gint *id);
    void                gwy_data_chooser_set_filter         (GwyDataChooser *chooser,
                                                             GwyDataChooserFilterFunc filter,
                                                             gpointer user_data,
                                                             GtkDestroyNotify destroy);
    const gchar*        gwy_data_chooser_get_none           (GwyDataChooser *chooser);
    void                gwy_data_chooser_set_none           (GwyDataChooser *chooser,
                                                             const gchar *none);

## Object Hierarchy

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

## Implemented Interfaces

GwyDataChooser implements AtkImplementorIface, GtkBuildable, GtkCellLayout and GtkCellEditable.

## Description

GwyDataChooser is an base data object chooser class. Choosers for particular data objects can be created with functions like `gwy_data_chooser_new_channels()` and then manipulated through GwyDataChooser interface.

The widget type used to implement choosers is not a part of the interface and may be subject of future changes. In any case GwyDataChooser has a `"changed"` signal emitted when the selected item changes.

It is possible to offer only data objects matching some criteria. For example to offer only data fields compatible with another data field, one can use:

    GtkWidget *chooser;
    GwyDataField *model;

    model = ...;
    chooser = gwy_data_chooser_new_channels();
    gwy_data_chooser_set_filter(GWY_DATA_CHOOSER(chooser),
                                compatible_field_filter, model,
                                NULL);

where the filter function looks like

    static gboolean
    compatible_field_filter(GwyContainer *data,
                            gint id,
                            gpointer user_data)
    {
        GwyDataField *model, *data_field;
        GQuark quark;

        quark = gwy_app_get_data_key_for_id(id);
        data_field = gwy_container_get_object(data, quark);
        model = GWY_DATA_FIELD(user_data);
        return !gwy_data_field_check_compatibility
                             (data_field, model,
                              GWY_DATA_COMPATIBILITY_RES
                              | GWY_DATA_COMPATIBILITY_REAL
                              | GWY_DATA_COMPATIBILITY_LATERAL
                              | GWY_DATA_COMPATIBILITY_VALUE);
    }

## Details

### GwyDataChooserFilterFunc ()

    gboolean            (*GwyDataChooserFilterFunc)         (GwyContainer *data,
                                                             gint id,
                                                             gpointer user_data);

The type of data chooser filter function.

`data` : | Data container.
`id` : | Id of particular data in `data`.
`user_data` : | Data passed to `gwy_data_chooser_set_filter()`.
Returns : | `TRUE` to display this data in the chooser, `FALSE` to omit it.

### GwyDataChooser

    typedef struct _GwyDataChooser GwyDataChooser;

### GwyDataChooserClass

    typedef struct _GwyDataChooserClass GwyDataChooserClass;

### gwy_data_chooser_new_channels ()

    GtkWidget*          gwy_data_chooser_new_channels       (void);

Creates a data chooser for data channels.

Returns : | A new channel chooser. Nothing may be assumed about the type and properties of the returned widget as they can change in the future.

### gwy_data_chooser_set_active ()

    gboolean            gwy_data_chooser_set_active         (GwyDataChooser *chooser,
                                                             GwyContainer *data,
                                                             gint id);

Selects a data in a data chooser.

`chooser` : | A data chooser.
`data` : | Container to select, `NULL` to select none (if the chooser contains `none' item).
`id` : | Id of particular data to select in `data`.
Returns : | `TRUE` if selected item was set.

### gwy_data_chooser_get_active ()

    GwyContainer*       gwy_data_chooser_get_active         (GwyDataChooser *chooser,
                                                             gint *id);

Gets the selected item in a data chooser.

`chooser` : | A data chooser.
`id` : | Location to store selected data id to (may be `NULL`).
Returns : | The container selected data lies in, `NULL` if nothing is selected or `none' item is selected.

### gwy_data_chooser_set_filter ()

    void                gwy_data_chooser_set_filter         (GwyDataChooser *chooser,
                                                             GwyDataChooserFilterFunc filter,
                                                             gpointer user_data,
                                                             GtkDestroyNotify destroy);

Sets the filter applied to a data chooser.

The display of an item corresponding to no data is controlled by `gwy_data_chooser_set_none()`, `filter` function is only called for real data.

`chooser` : | A data chooser.
`filter` : | The filter function.
`user_data` : | The data passed to `filter`.
`destroy` : | Destroy notifier of `user_data` or `NULL`.

### gwy_data_chooser_get_none ()

    const gchar*        gwy_data_chooser_get_none           (GwyDataChooser *chooser);

Gets the label of the item corresponding to no data.

`chooser` : | A data chooser.
Returns : | The label corresponding to no data, an empty string for the default label and `NULL` if the chooser does not display `none' item.

### gwy_data_chooser_set_none ()

    void                gwy_data_chooser_set_none           (GwyDataChooser *chooser,
                                                             const gchar *none);

Sets the label of the item corresponding to no data.

`chooser` : | A data chooser.
`none` : | Label to use for item corresponding to no data. Passing `NULL`, disables such an item, an empty string enables it with the default label.