GwyDataChooser: Gwyddion Application Library Reference Manual

## GwyDataChooser GwyDataChooser — Data object choosers |

## Functions

GwyAppDataId * | gwy_app_data_id_new ()
GwyAppDataId * | gwy_app_data_id_copy ()
void | gwy_app_data_id_free ()
gboolean | (*GwyDataChooserFilterFunc) ()
GtkWidget * | gwy_data_chooser_new ()
GwyDataKind | gwy_data_chooser_get_data_kind ()
gboolean | gwy_data_chooser_set_active ()
GwyFile * | gwy_data_chooser_get_active ()
gboolean | gwy_data_chooser_set_active_id ()
gboolean | gwy_data_chooser_get_active_id ()
void | gwy_data_chooser_set_filter ()
const gchar * | gwy_data_chooser_get_none ()
void | gwy_data_chooser_set_none ()
GtkTreeModel * | gwy_data_chooser_get_filter ()
void | gwy_data_chooser_refilter ()

## Types and Values

#define | GWY_APP_DATA_ID_NONE
| GwyAppDataId
| GwyDataChooser
| GwyDataChooserClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkComboBox
                            ╰── GwyDataChooser

## Implemented Interfaces

GwyDataChooser implements AtkImplementorIface, GtkBuildable, GtkCellLayout and GtkCellEditable.

## Includes

    #include <libgwyapp/gwyapp.h>

## Description

GwyDataChooser is an base data object chooser class. Choosers for particular data objects can be created with `gwy_data_chooser_new()` 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:

    1
    2
    3
    4
    5
    6
    GtkWidget *chooser;
    GwyField *model;

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

where the filter function looks like

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    static gboolean
    compatible_field_filter(GwyFile *data,
                            gint id,
                            gpointer user_data)
    {
        GwyField *model, *field;
        GQuark quark;

        quark = gwy_app_get_data_key_for_id(id);
        field = gwy_dict_get_object(data, quark);
        model = GWY_FIELD(user_data);
        return !gwy_field_is_incompatible(field, model,
                                                   GWY_DATA_MISMATCH_RES
                                                   | GWY_DATA_MISMATCH_REAL
                                                   | GWY_DATA_MISMATCH_LATERAL
                                                   | GWY_DATA_MISMATCH_VALUE);
    }

## Functions

### gwy_app_data_id_new()

    GwyAppDataId *
    gwy_app_data_id_new (gint datano,
                         gint id);

Creates a new data identifier on heap.

This is mostly useful for language bindings.

#### Parameters

datano | Numeric identifier of data data. Zero is used for none. |
id | Numeric identifier of a specific data item, such as channel or graph number. Value -1 is used for none. |

#### Returns

Newly allocated data id. It must be freed with `gwy_app_data_id_free()`.

### gwy_app_data_id_copy()

    GwyAppDataId *
    gwy_app_data_id_copy (GwyAppDataId *dataid);

Creates a copy of data identifier.

This is mostly useful for language bindings.

#### Parameters

dataid | Data identifier. |

#### Returns

Newly allocated data id. It must be freed with `gwy_app_data_id_free()`.

### gwy_app_data_id_free()

    void
    gwy_app_data_id_free (GwyAppDataId *dataid);

Frees a data identifier.

This is mostly useful for language bindings.

#### Parameters

dataid | Data identifier. |

### GwyDataChooserFilterFunc()

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

The type of data chooser filter function.

#### Parameters

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

### gwy_data_chooser_new()

    GtkWidget *
    gwy_data_chooser_new (GwyDataKind data_kind);

Creates a data chooser for a given kind of data.

#### Parameters

data_kind | Data kind the chooser should display. |

#### Returns

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

[transfer full]

### gwy_data_chooser_get_data_kind()

    GwyDataKind
    gwy_data_chooser_get_data_kind (GwyDataChooser *chooser);

Reports the type of data a chooser was created for.

#### Parameters

chooser | A data chooser. |

#### Returns

The data kind of the chooser.

### gwy_data_chooser_set_active()

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

Selects a data in a data chooser.

#### Parameters

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

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

Gets the selected item in a data chooser.

#### Parameters

chooser | A data chooser. |
id | Location to store selected data id to (may be `NULL`). |

#### Returns

The data selected data lies in, `NULL` if nothing is selected or `none' item is selected.

### gwy_data_chooser_set_active_id()

    gboolean
    gwy_data_chooser_set_active_id (GwyDataChooser *chooser,
                                    const GwyAppDataId *id);

Selects a data in a data chooser using numerical identifiers.

Passing `NULL` as `id` is permitted as a request to select the ‘none’ item.

#### Parameters

chooser | A data chooser. |
id | Data item to select. |

#### Returns

`TRUE` if selected item was set.

### gwy_data_chooser_get_active_id()

    gboolean
    gwy_data_chooser_get_active_id (GwyDataChooser *chooser,
                                    GwyAppDataId *id);

Gets the selected item in a data chooser as numerical identifiers.

#### Parameters

chooser | A data chooser. |
id | Location for the id selected data item. |

#### Returns

`TRUE` if any actual data item is selected. `FALSE` is nothing is selected or the ‘none’ item is selected.

### gwy_data_chooser_set_filter()

    void
    gwy_data_chooser_set_filter (GwyDataChooser *chooser,
                                 GwyDataChooserFilterFunc filter,
                                 gpointer user_data,
                                 GDestroyNotify 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.

Use `gwy_data_chooser_refilter()` to update the list if the filter depends on external state and that changes.

#### Parameters

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.

#### Parameters

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 the no-data 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.

#### Parameters

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

### gwy_data_chooser_get_filter()

    GtkTreeModel *
    gwy_data_chooser_get_filter (GwyDataChooser *chooser);

Gets the tree model filter used in a data chooser.

In general, you should not access the filter directly. An exception being `gtk_tree_model_filter_refilter()` when the filtering functions given in `gwy_data_chooser_set_filter()` depends on external state and that state changes. However, `gwy_data_chooser_refilter()` is usually more useful.

#### Parameters

chooser | A data chooser. |

#### Returns

The GtkTreeModelFilter object used by the chooser.

### gwy_data_chooser_refilter()

    void
    gwy_data_chooser_refilter (GwyDataChooser *chooser);

Reruns the filter function of a data chooser.

This function is useful when the filtering functions given in `gwy_data_chooser_set_filter()` depends on external state and that state changes.

If the currently selected item becomes filtered out the chooser selects the no-data item if enabled. If the no-data item is disabled but the list contains some items then an arbitrary item is selected. At present, this means the first item in the list.

#### Parameters

chooser | A data chooser. |

## Types and Values

### GWY_APP_DATA_ID_NONE

    #define GWY_APP_DATA_ID_NONE { 0, -1 }

Initialiser for GwyAppDataId that corresponds to no data.

The macro would be typically used in initialisation as

    1
    GwyAppDataId dataid = GWY_APP_DATA_ID_NONE;

### GwyAppDataId

    typedef struct {
        gint datano;
        gint id;
    } GwyAppDataId;

Auxiliary structure representing one data item in an open file.

The file data container number can be obtained with `gwy_data_browser_get()` and used to look up the data with `gwy_data_browser_get_number()`.

#### Members

gint `datano`; | Numeric identifier of data data. Zero is used for none. |
gint `id`; | Numeric identifier of a specific data item, such as channel or graph number. Value -1 is used for none. |

### GwyDataChooser

    typedef struct _GwyDataChooser GwyDataChooser;

### GwyDataChooserClass

    typedef struct _GwyDataChooserClass GwyDataChooserClass;