Data browser: Gwyddion Application Library Reference Manual

## Data browser Data browser — Manage files and data in them |

## Functions

void | (*GwyDataBrowserForeachFunc) ()
void | (*GwyDataWatchFunc) ()
void | gwy_data_browser_add ()
void | gwy_data_browser_remove ()
GwyFile * | gwy_data_browser_get_file ()
void | gwy_data_browser_foreach ()
gint | gwy_data_browser_copy_data ()
gint | gwy_data_browser_reset_visibility ()
GwyFile * | gwy_data_browser_find_object ()
void | gwy_data_browser_select_widget ()
GtkWindow * | gwy_data_browser_get_window_for_data ()
gboolean | gwy_data_browser_get_data_for_widget ()
void | gwy_data_browser_select_data ()
void | gwy_data_browser_block_switching ()
void | gwy_data_browser_unblock_switching ()
GwyDataKind | gwy_data_browser_get_current_data_kind ()
GwyFile * | gwy_data_browser_get_current_file ()
gint | gwy_data_browser_get_current_file_id ()
gint | gwy_data_browser_get_current_data_id ()
void | gwy_data_browser_get_current ()
gulong | gwy_data_browser_add_watch ()
void | gwy_data_browser_remove_watch ()
gboolean | gwy_data_browser_get_gui_enabled ()
void | gwy_data_browser_set_gui_enabled ()
GtkWidget * | gwy_data_browser_widget ()
GtkAccelGroup * | gwy_data_browser_accel_group ()
void | gwy_data_browser_shut_down ()

## Types and Values

enum | GwyAppWhat
enum | GwyVisibilityResetType
enum | GwyDataWatchEventType

## Includes

    #include <libgwyapp/gwyapp.h>

## Description

The data browser is both an entity that monitors of various data in Gwyddion and the corresponding user interface showing the data lists and letting the user deleting or copying them. The public functions are generally related to the first part.

Data browser functions may only be called from the main thread. Therefore, there is no locking.

An GwyFile that represents an SPM file is managed by functions such as `gwy_data_browser_add()` or `gwy_data_browser_remove()`. Note that the high-level libgwyapp functions generally call the data browser functions as appropriate. Low-level functions, e.g. GwyFile functions, do not. If a GwyFile has not been added to the data browser it is unmanaged and cannot be used with data browser functions (there are, however, quite a few data managing operations GwyFile itself can do).

An important part of the data browser is keeping track which data item is currently selected (to know what a data processing method should process, etc.). You can obtain the information about various currently selected objects using `gwy_data_browser_get_current()`. Making a data item currently selected is accomplished either using function such as `gwy_data_browser_select_widget()`, which corresponds to the user switching windows, or `gwy_data_browser_select_data()` which selects a data item as current in the browser. The latter is less safe and can result in a strange behaviour because for some purposes only data displayed in a window can really be ‘current’.

## Functions

### GwyDataBrowserForeachFunc()

    void
    (*GwyDataBrowserForeachFunc) (GwyFile *file,
                                  gpointer user_data);

Type of data file for-each function.

Such function is passed to `gwy_data_browser_foreach()`.

#### Parameters

file | A data container managed by the data-browser. |
user_data | User data passed to `gwy_data_browser_foreach()`. | [closure]

### GwyDataWatchFunc()

    void
    (*GwyDataWatchFunc) (GwyFile *file,
                         gint id,
                         GwyDataWatchEventType event,
                         gpointer user_data);

Type of data watch function.

Such function is passed to `gwy_data_browser_add_watch()`.

#### Parameters

file | A data container managed by the data-browser. |
id | Object (channel) id in the container. |
event | The type of data change event reported. |
user_data | User data passed to `gwy_data_browser_add_watch()`. | [closure]

### gwy_data_browser_add()

    void
    gwy_data_browser_add (GwyFile *file);

Adds a data file container to the application data browser.

The file becomes managed by the data browser. Use `gwy_data_browser_remove()` to remove it. The data browser takes a reference on the file; you can usually release yours.

If the file is still marked in construction, the construction is finished. If some data objects that need an image representation (e.g. volume or XYZ data) lack previews, default previews are created for them.

If GUI is running, windows are created, showing `file` 's data according to visibility flags. If nothing is marked visible, the first found data are displayed.

#### Parameters

file | A data file container. | [transfer full]

### gwy_data_browser_remove()

    void
    gwy_data_browser_remove (GwyFile *file);

Removes a data file container to the application data browser.

If GUI is running, all windows displaying `file` 's data are closed. The file ceases being managed by the data browser. The data browser releases its reference on the file. This often leads to `file` 's destruction.

The current file may not be removed while switching is blocked with `gwy_data_browser_block_switching()`. It would lead to a contradiction: the browser must switch away from `file` but it is not allowed to change the current file.

#### Parameters

file | A data file container. | [transfer none]

### gwy_data_browser_get_file()

    GwyFile *
    gwy_data_browser_get_file (gint id);

Finds a file by its numerical id.

Only files managed by the data browser have an id. It is not an error to request a file which does not exist. In such case, `NULL` is returned. See also `gwy_file_get_id()`.

#### Parameters

id | Identifier of a data file container. |

#### Returns

The file identified by `id` , or `NULL`.

[transfer none][nullable]

### gwy_data_browser_foreach()

    void
    gwy_data_browser_foreach (GwyDataBrowserForeachFunc function,
                              gpointer user_data,
                              GDestroyNotify destroy);

Calls a function for every file managed by the data browser.

The function must not remove files from the data browser nor add new ones to it.

#### Parameters

function | Function to call for each file. | [scope call][closure user_data][destroy destroy]
user_data | User data to pass to `function` . |
destroy | Function to destroy user data when done, possibly `NULL`. |

### gwy_data_browser_copy_data()

    gint
    gwy_data_browser_copy_data (GwyFile *source,
                                GwyDataKind data_kind,
                                gint id,
                                GwyFile *dest);

Adds a new data items as a duplicate of existing data including all auxiliary information.

The function differs from `gwy_file_copy_data()` in two primary aspects: It adds a log entry and it makes the new data visible. Therefore, it suitable for data duplication in a running GUI, as opposed to mere file manipulation function.

#### Parameters

source | Source data file container. |
data_kind | Type of data to copy. |
id | Data item id. |
dest | Target data file container. |

#### Returns

The id of copied data in `dest` .

### gwy_data_browser_reset_visibility()

    gint
    gwy_data_browser_reset_visibility (GwyFile *file,
                                       GwyVisibilityResetType reset_type);

Resets visibility of all data objects in a container.

It is possible to perform the reset when GUI is disabled. In such case the visibility flags in the file are set, but no windows are created or closed. The `GWY_VISIBILITY_RESET_RESTORE` mode is a no-op in such case because it does not change the visibility flags. `GWY_VISIBILITY_RESET_DEFAULT` is often also no-op, but it may set the flag for some data if none are currently marked visible.

This function prevents the file from being closed when all windows are closed. Usually, a GUI caller should close the file when getting a zero return value.

#### Parameters

file | A data file container. | [transfer none]
reset_type | Type of visibility reset. |

#### Returns

The number of data objects marked visible in `file` after the reset (if GUI is running, it will be also the number of data objects shown in windows now).

### gwy_data_browser_find_object()

    GwyFile *
    gwy_data_browser_find_object (GObject *object,
                                  GQuark *key);

Finds file and the corresponding key for any data object.

The function does not actually scan all open files and is relatively cheap. The behaviour during changes in the file, such as data replacement, addition or removal, is currently undefined (it may return values corresponding either to the old or the new state).

#### Parameters

object | Data object, presumably in an data file managed the data browser. |
key | Location to store the key corresponding to `object` in returned file. Possibly `NULL`. | [out][nullable]

#### Returns

The file containing `object` , if any. Otherwise `NULL`.

[nullable]

### gwy_data_browser_select_widget()

    void
    gwy_data_browser_select_widget (GtkWidget *widget);

Selects the file and data item corresponding to a data displaying widget as current.

Selecting an image window switches the active tool to this window.

You can pass `NULL` to select no data. Usually when some data exist, some data are selected as current. However, it is possible to have no data selected when data exist.

It is an error to pass non-data-displaying widgets.

#### Parameters

widget | A data displaying widget. | [transfer none][nullable]

### gwy_data_browser_get_window_for_data()

    GtkWindow *
    gwy_data_browser_get_window_for_data (GwyFile *file,
                                          GwyDataKind data_kind,
                                          gint id);

Gets the top-level window displaying given data.

It is not an error to ask for nonexistend windows, even windows which could not exist (for example because `data` is not a managed file or `id` is negative).

#### Parameters

file | A data file container. | [transfer none]
data_kind | Type of the data object. |
id | Data item id. |

#### Returns

The window displaying data in `data` identified by (`data_kind` , `id` ), possibly `NULL`.

[transfer none][nullable]

### gwy_data_browser_get_data_for_widget()

    gboolean
    gwy_data_browser_get_data_for_widget (GtkWidget *widget,
                                          GwyFile **file,
                                          GwyDataKind *data_kind,
                                          gint *id);

Identifies the data displayed by a data displaying widget.

The preferred argument for `widget` is the top-level window. However, there is some liberty. The function also identifies the data correctly when given the data displaying widget such as GwyDataWindow or GwyGraph. It is not an error to pass a window not showing any data, although there should not be any reasong for doing so. If the function return `FALSE`, the values of `file` , `data_kind` and `id` are kept intact.

The returned data kind is the primary data kind for that window.

#### Parameters

widget | A data displaying widget. | [transfer none]
file | Location to store the corresponding data file. | [out][optional][transfer none]
data_kind | Location to store the corresponding data kind. | [out][optional]
id | Location to store the corresponding data id. | [out][optional]

#### Returns

`TRUE` if the data displayed by `widget` was identified, `FALSE` otherwise.

### gwy_data_browser_select_data()

    void
    gwy_data_browser_select_data (GwyFile *file,
                                  GwyDataKind data_kind,
                                  gint id);

Selects a file and data item.

#### Parameters

file | A data file container managed by the data-browser. |
data_kind | Type of the data object. |
id | Data item id. |

### gwy_data_browser_block_switching()

    void
    gwy_data_browser_block_switching (void);

Temporarily blocks data switching.

Normally, the current data item is switched according to the active window.

This may be necessary during operations which would be derailed by data switching. For instance DnD from tree views showing the contents of active data does not work correctly if the window manager switches active windows during the DnD, so at the drop time the tree view content no longer matches the dragged row. While switching is blocked, functions such as `gwy_data_browser_select_data()` will only queue the change.

Use `gwy_data_browser_unblock_switching()` to restore data switching. It will also switch data to the window that should be currently active, if the active window has changed (but without any intermediate steps if the active window has changed multiple times).

Switching must not be blocked permanently because it would get the data browser out of sync.

### gwy_data_browser_unblock_switching()

    void
    gwy_data_browser_unblock_switching (void);

Stops temporarily blocking of data switching.

If some data switching has been blocked, the most recent will be realised now.

The blocking is started by `gwy_data_browser_block_switching()`. See its description for details.

### gwy_data_browser_get_current_data_kind()

    GwyDataKind
    gwy_data_browser_get_current_data_kind
                                   (void);

Gets the kind of current data.

This is what the active data lists shows, for instance. However, even the inactive lists have their own current data items which you can get using `gwy_data_browser_get_current_data_id()`.

#### Returns

The data kind, possibly `GWY_FILE_NONE` if there are no current data.

### gwy_data_browser_get_current_file()

    GwyFile *
    gwy_data_browser_get_current_file (void);

Gets the current file.

#### Returns

The current file, possibly `NULL` if there is no current file.

[transfer none][nullable]

### gwy_data_browser_get_current_file_id()

    gint
    gwy_data_browser_get_current_file_id (void);

Gets the numerical id of the current file.

#### Returns

The numerical id, poissbly `GWY_FILE_ID_NONE` if there is no current file.

### gwy_data_browser_get_current_data_id()

    gint
    gwy_data_browser_get_current_data_id (GwyDataKind data_kind);

Gets the numerical id of the current data of given kind.

Use in conjuction with `gwy_data_browser_get_current_data_kind()` to get the selected data in the active data list of the browser.

#### Parameters

data_kind | Type of the data object. |

#### Returns

The numerical id, possible -1 if there are no current data of given kind.

### gwy_data_browser_get_current()

    void
    gwy_data_browser_get_current (GwyAppWhat what,
                                  ...);

Gets information about current objects.

All output arguments are always set to some value, even if the requested object does not exist. Object arguments are set to pointer to the object if it exists (no reference is added), or cleared to `NULL` if no such object exists.

Quark arguments are set to the corresponding key even if no such object is actually present (use object arguments to check for object presence) but the location where it would be stored is known. This is common with presentations and masks. They are be set to 0 if no corresponding location exists -- for example, when the current mask key is requested but the current data contains no channel (or there is no current data at all).

The rules for id arguments are similar to quarks, except they are set to -1 to indicate undefined result.

The current objects can change due to user interaction even during the execution of modal dialogs (typically used by modules). Therefore to achieve consistency one has to ask for the complete set of current objects at once.

#### Parameters

what | First information about current objects to obtain. |
... | pointer to store the information to (object pointer for objects, GQuark pointer for keys, gint pointer for ids), followed by 0-terminated list of GwyAppWhat, pointer couples. |

### gwy_data_browser_add_watch()

    gulong
    gwy_data_browser_add_watch (GwyDataWatchFunc function,
                                GwyDataKind data_kind,
                                gpointer user_data,
                                GDestroyNotify destroy);

Adds a function watching a specific kind of data.

#### Parameters

function | Function to call when data change, are added or removed. | [scope notified][closure user_data][destroy destroy]
data_kind | Data kind to watch. |
user_data | User data to pass to `function` . |
destroy | Function to destroy user data when done, possibly `NULL`. |

#### Returns

Identifier of the watching function to be used with `gwy_data_browser_remove_watch()`.

### gwy_data_browser_remove_watch()

    void
    gwy_data_browser_remove_watch (gulong id);

Removes a function watching a specific kind of data.

The identifier is obtained when adding such function with `gwy_data_browser_add_watch()`.

#### Parameters

id | Watch function identifier. |

### gwy_data_browser_get_gui_enabled()

    gboolean
    gwy_data_browser_get_gui_enabled (void);

Reports whether creation of windows by the data-browser is enabled.

See `gwy_data_browser_set_gui_enabled()` for discussion.

#### Returns

`TRUE` if the data-browser is permitted to create windows, `FALSE` if it is not.

### gwy_data_browser_set_gui_enabled()

    void
    gwy_data_browser_set_gui_enabled (gboolean setting);

Globally enables or disables creation of widgets by the data-browser.

At present, the browser GUI state needs to be decided before any files are added to the data browser. Changing the GUI state later is not supported. Usually, this function is not called explicitly. The state is set by `gwy_app_init()` according to its `for_gui` flag. By default, the GUI is enabled.

If GUI is enabled, the data-browser creates windows for data objects automatically, for instance when reconstructing the view of a loaded file or after a module function creates a new image or graph and marks it visible. Non-GUI applications that run module functions usually wish to disable such behaviour.

If GUI is disabled the data browser never creates windows showing data objects and also its own GUI becomes unavailable. This mode has some utility, in particular when processing multiple files, thanks to function such as `gwy_data_browser_foreach()`. Nevertheless, GwyFile already offers a number of data management functions that are sufficient for many non-GUI use cases.

#### Parameters

setting | `TRUE` to enable creation of widgets by the data-browser, `FALSE` to disable it. |

### gwy_data_browser_widget()

    GtkWidget *
    gwy_data_browser_widget (void);

Obtains the data browser widget.

The data browser is a singleton. If browser GUI is enabled and the widget already exists, it is simply returned. It may be newly created as necessary. In any case, the widget is owned by the browser. Destroy it to disable the shut down the GUI, but keep the data browser itself.

Use `gwy_data_browser_shut_down()` when tearing down the program in an arbitrary manner.

If browser GUI is disabled, the function returns `NULL`.

#### Returns

The browser widget, possibly `NULL`.

[transfer none][nullable]

### gwy_data_browser_accel_group()

    GtkAccelGroup *
    gwy_data_browser_accel_group (void);

Obtains the data browser GUI accelerator group.

The group contains accelerators for actions such as data duplication or deletion, which are generally expected to work also in various data windows.

The data browser is a singleton; see `gwy_data_browser_widget()`. When the browser GUI is destroyed, it releases its own reference on the accelerator group and forgets it.

If browser GUI is disabled or not yet created, the function returns `NULL`. Just calling this function does not force the creation of the accelerator group.

#### Returns

The accelerator group, possibly `NULL`.

[transfer none][nullable]

### gwy_data_browser_shut_down()

    void
    gwy_data_browser_shut_down (void);

Shuts down the data browser when quitting the application.

The function is meant to avoid spurious signals and notifications in a quick shutdown. It does not go through all files and remove them from the browser and does not destroy the GUI. It just makes the data browser ignore any signals and data changes, assuming the program is already terminating.

## Types and Values

### enum GwyAppWhat

#### Members

GWY_APP_FILE |  |
GWY_APP_DATA_KIND |  |
GWY_APP_DATA_VIEW |  |
GWY_APP_GRAPH |  |
GWY_APP_FIELD |  |
GWY_APP_FIELD_KEY |  |
GWY_APP_FIELD_ID |  |
GWY_APP_MASK_FIELD |  |
GWY_APP_MASK_FIELD_KEY |  |
GWY_APP_SHOW_FIELD |  |
GWY_APP_SHOW_FIELD_KEY |  |
GWY_APP_GRAPH_MODEL |  |
GWY_APP_GRAPH_MODEL_KEY |  |
GWY_APP_GRAPH_MODEL_ID |  |
GWY_APP_SPECTRA |  |
GWY_APP_SPECTRA_KEY |  |
GWY_APP_SPECTRA_ID |  |
GWY_APP_VOLUME_VIEW |  |
GWY_APP_BRICK |  |
GWY_APP_BRICK_KEY |  |
GWY_APP_BRICK_ID |  |
GWY_APP_FILE_ID |  |
GWY_APP_XYZ_VIEW |  |
GWY_APP_SCATTER |  |
GWY_APP_SCATTER_KEY |  |
GWY_APP_SCATTER_ID |  |
GWY_APP_LAWN |  |
GWY_APP_LAWN_KEY |  |
GWY_APP_LAWN_ID |  |
GWY_APP_CURVE_MAP_VIEW |  |

### enum GwyVisibilityResetType

Data object visibility reset type.

The precise behaviour of `GWY_VISIBILITY_RESET_DEFAULT` may be subject of further changes. It indicates the wish to restore saved visibilities and do something reasonable when there are no visibilities to restore.

#### Members

GWY_VISIBILITY_RESET_DEFAULT | Restore visibilities from container and if nothing would be visible, make an arbitrary data object visible. |
GWY_VISIBILITY_RESET_RESTORE | Restore visibilities from container. |
GWY_VISIBILITY_RESET_SHOW_ALL | Show all data objects. |
GWY_VISIBILITY_RESET_HIDE_ALL | Hide all data objects. This normally makes the file inaccessible. |

### enum GwyDataWatchEventType

Type of event reported to GwyDataWatchFunc watcher functions.

#### Members

GWY_DATA_WATCH_EVENT_ADDED | A new data object has appeared. |
GWY_DATA_WATCH_EVENT_CHANGED | A data object has changed. |
GWY_DATA_WATCH_EVENT_REMOVED | A data object has been removed. |