GwyDataBrowserForeachFunc()

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

Type of data file for-each function.

Such function is passed to gwy_data_browser_foreach().

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

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.

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.

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

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.

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.

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

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.

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.

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

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.

gwy_data_browser_select_data()

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

Selects a file and data item.

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

gwy_data_browser_get_current_file()

GwyFile *
gwy_data_browser_get_current_file (void);

Gets the current file.

gwy_data_browser_get_current_file_id()

gint
gwy_data_browser_get_current_file_id (void);

Gets the numerical id of the 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.

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.

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.

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

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.

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.

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 shut down (but not disable) the data browser.

If browser GUI is disabled, the function returns NULL.

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.

enum GwyAppWhat

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.

enum GwyDataWatchEventType

Type of event reported to GwyDataWatchFunc watcher functions.