GwyDataChooser: Gwyddion Application Library Reference Manual

GwyDataChooser

GwyDataChooser — Data object choosers

Functions

gboolean	(*GwyDataChooserFilterFunc) ()
GtkWidget *	gwy_data_chooser_new_channels ()
GtkWidget *	gwy_data_chooser_new_volumes ()
GtkWidget *	gwy_data_chooser_new_graphs ()
GtkWidget *	gwy_data_chooser_new_xyzs ()
GwyAppDataId *	gwy_app_data_id_new ()
GwyAppDataId *	gwy_app_data_id_copy ()
void	gwy_app_data_id_free ()
gboolean	gwy_data_chooser_set_active ()
GwyContainer *	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

Object Hierarchy

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

Includes

#include <app/gwyapp.h>

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() or gwy_data_chooser_new_volumes() 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);
}

Functions

GwyDataChooserFilterFunc ()

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

The type of data chooser filter function.

Parameters

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.

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

GtkWidget *
gwy_data_chooser_new_volumes (void);

Creates a data chooser for volume data.

Returns

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

Since: 2.33

gwy_data_chooser_new_graphs ()

GtkWidget *
gwy_data_chooser_new_graphs (void);

Creates a data chooser for graphs.

Returns

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

Since: 2.41

gwy_data_chooser_new_xyzs ()

GtkWidget *
gwy_data_chooser_new_xyzs (void);

Creates a data chooser for XYZ data.

Returns

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

Since: 2.45

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

Since: 2.47

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

Since: 2.47

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.

Since: 2.47

gwy_data_chooser_set_active ()

gboolean
gwy_data_chooser_set_active (GwyDataChooser *chooser,
                             GwyContainer *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 ()

GwyContainer *
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 container 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.

Since: 2.41

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.

Since: 2.41

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.

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.

Since: 2.41

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

1	GwyAppDataId dataid = GWY_APP_DATA_ID_NONE;

Since: 2.41