Application: Gwyddion Application Library Reference Manual

## Application Application — Core application interface, window management |

## Functions

void | gwy_app_switch_tool ()
const gchar * | gwy_app_current_tool_name ()
GwyTool * | gwy_app_current_tool ()
GtkAccelGroup * | gwy_app_main_accel_group ()
void | gwy_app_save_window_position ()
void | gwy_app_restore_window_position ()
GtkWindow * | gwy_app_main_window ()
void | gwy_app_set_main_window ()
gboolean | gwy_app_quit ()
const gchar * | gwy_app_get_tree_model_kind ()
void | gwy_app_set_tree_model_kind ()

## Includes

    #include <libgwyapp/gwyapp.h>

## Description

## Functions

### gwy_app_switch_tool()

    void
    gwy_app_switch_tool (const gchar *toolname);

Switches the current tool to given tool.

If the tool is already active it is shown when hidden and hidden when visible.

#### Parameters

toolname | Tool name, that is type name of the tool object in the GLib type system. This can be for instance "GwyToolGrainMeasure". |

### gwy_app_current_tool_name()

    const gchar *
    gwy_app_current_tool_name (void);

Obtains the name of currently active tool.

See `gwy_app_switch_tool()` for the name description.

In some rare circumstances, this function can return `NULL` because no tool is active. This includes program startup and shutdown and during the construction of a new GwyTool object while switching tools. Also, `NULL` is typically returned outside Gwyddion in programs just using the libraries.

#### Returns

The tool name.

### gwy_app_current_tool()

    GwyTool *
    gwy_app_current_tool (void);

Obtains the currently active tool object.

In some rare circumstances, this function can return `NULL` because no tool is active. This includes program startup and shutdown and during the construction of a new GwyTool object while switching tools. Also, `NULL` is typically returned outside Gwyddion in programs just using the libraries.

#### Returns

The current tool object.

### gwy_app_main_accel_group()

    GtkAccelGroup *
    gwy_app_main_accel_group (void);

Obtains the main application accelerator group.

The group includes accelerators for terminating Gwyddion, opening and saving files and similar operations. You should add it to other windows where these global keyboard shortcuts should work.

If the main accelerator group does not exist yet, it will be created.

Return: (transfer none): The main accelerator group.

### gwy_app_save_window_position()

    void
    gwy_app_save_window_position (GtkWindow *window,
                                  const gchar *prefix,
                                  gboolean position,
                                  gboolean size);

Saves position and/or size of a window to settings.

Some sanity checks are included, therefore if window position and/or size is too suspicious, it is not saved.

#### Parameters

window | A window to save position of. |
prefix | Unique prefix in settings to store the information under. |
position | `TRUE` to save position information. |
size | `TRUE` to save size information. |

### gwy_app_restore_window_position()

    void
    gwy_app_restore_window_position (GtkWindow *window,
                                     const gchar *prefix,
                                     gboolean grow_only);

Restores a window position and/or size from settings.

Unlike `gwy_app_save_window_position()`, this function has no `position` and `size` arguments, it simply restores all attributes that were saved.

Note to restore position (not size) it should be called twice for each window to accommodate sloppy window managers: once before the window is shown, second time immediately after showing the window.

Some sanity checks are included, therefore if saved window position and/or size is too suspicious, it is not restored.

#### Parameters

window | A window to restore position of. |
prefix | Unique prefix in settings to get the information from (the same as in `gwy_app_save_window_position()`). |
grow_only | `TRUE` to only attempt set the window default size bigger than it requests, never smaller. |

### gwy_app_main_window()

    GtkWindow *
    gwy_app_main_window (void);

Returns the main application window.

In a running Gwyddion GUI, the main window is always the toolbox. Technically, the function returns whatever was set with `gwy_app_set_main_window()` during program startup. Including possibly `NULL` is nothing has been set.

#### Returns

The main window.

[transfer none][nullable]

### gwy_app_set_main_window()

    void
    gwy_app_set_main_window (GtkWindow *window);

Sets the main application window.

This function is probably only useful in Gwyddion itself and should be ignored.

It should to be called exactly once at Gwyddion startup. It makes `gwy_app_main_window()` work and adds the main accelerator group to the window. It also restores the main window position and size, so it really makes sense for the Gwyddion toolbox.

#### Parameters

window | A window, presumably the Gwyddion toolbox. |

### gwy_app_quit()

    gboolean
    gwy_app_quit (void);

Quits the application.

This function may present a confirmation dialog to the user and it may let the application to continue running. If it quits the application, it performs some shutdown actions and then quits the Gtk+ main loop with `gtk_main_quit()`.

#### Returns

Always `TRUE` to be usable as an event handler. However, if the application is actually terminated, this function does not return.

### gwy_app_get_tree_model_kind()

    const gchar *
    gwy_app_get_tree_model_kind (GtkTreeModel *model);

Identifies the kind of tree model.

Receivers of tree model drag data can use this function to see if the source is a known Gwyddion DnD data source. The known kinds include data browser lists "image", "graph", "spectra", "volume", "xyz" and "cmap". However, these lists store only to internal data browser structures, making them useful drag sources only within libgwyapp itself.

Graph window curve lists are of "graph-curves" kind and the selection manager tool selection list is "image-selections".

#### Parameters

model | A tree model. |

#### Returns

String identifier of the tree model kind. It may be `NULL` if the drag source is not identified as any standard kind.

[nullable]

### gwy_app_set_tree_model_kind()

    void
    gwy_app_set_tree_model_kind (GtkTreeModel *model,
                                 const gchar *kind);

Sets the kind of a tree model.

You should almost never need this function because all standard tree models usable as drag sources set the kind themselves. See also `gwy_app_get_tree_model_kind()`.

#### Parameters

model | A tree model. |
kind | String identifier of the tree model kind. | [nullable]