app: Gwyddion Application Library Reference Manual

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

## Functions

void | gwy_app_switch_tool ()
const gchar * | gwy_app_current_tool_name ()
GwyTool * | gwy_app_current_tool ()
void | gwy_app_add_main_accel_group ()
void | gwy_app_save_window_position ()
void | gwy_app_restore_window_position ()
GtkWidget * | gwy_app_main_window_get ()
void | gwy_app_main_window_set ()
void | gwy_app_data_view_change_mask_color ()
gboolean | gwy_app_quit ()
void | gwy_app_init_widget_styles ()
void | gwy_app_init_i18n ()
gboolean | gwy_app_init_common ()
void | gwy_app_init_nongui ()

## Includes

    #include <app/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.

Since: 2.38

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

Since: 2.55

### gwy_app_add_main_accel_group ()

    void
    gwy_app_add_main_accel_group (GtkWindow *window);

Adds main (global) application accelerator group to a window.

This includes accelerators for terminating Gwyddion, opening files, etc.

#### Parameters

window | A window. |

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

    GtkWidget *
    gwy_app_main_window_get (void);

Returns Gwyddion main application window (toolbox).

#### Returns

The Gwyddion toolbox.

### gwy_app_main_window_set ()

    void
    gwy_app_main_window_set (GtkWidget *window);

Sets the main application window.

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

It needs to be called exactly once at Gwyddion startup. It restores the toolbox position and makes `gwy_app_main_window_get()` work.

#### Parameters

window | A window, presumably the Gwyddion toolbox. |

### gwy_app_data_view_change_mask_color ()

    void
    gwy_app_data_view_change_mask_color (GwyDataView *data_view);

Runs mask color selector on a data view.

This is a convenience function to run `gwy_color_selector_for_mask()`, possibly taking the initial color from settings.

#### Parameters

data_view | A data view (of application's data window). It must have a mask. |

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

    void
    gwy_app_init_widget_styles (void);

Sets up style properties for special Gwyddion widgets.

Normally not needed to call explicitly.

### gwy_app_init_i18n ()

    void
    gwy_app_init_i18n (void);

Initializes internationalization.

Normally not needed to call explicitly.

### gwy_app_init_common ()

    gboolean
    gwy_app_init_common (GError **error,
                         ...);

Performs common application initialization.

This function can be useful in Gwyddion-based programs and includes: widget class initialisation, internationalisation initialisation, stock item and resource class loading, settings loading, and module registration.

#### Parameters

error | Error location for settings loading error. |
... | List of module types to load, terminated with `NULL`. Possible types are "cmap", "file", "graph", "layer", "process", "tool", "volume" and "xyz", plus two special values "" and "all" for untyped modules (like pygwy or plug-in proxy) and all modules, respectively. |

#### Returns

Settings loading status.

### gwy_app_init_nongui ()

    void
    gwy_app_init_nongui (const gchar *option,
                         ...);

Performs common initialisations useful in non-GUI (batch) programs utilising Gwyddion libraries.

This function does not initialise GTK+ and does not set up anything related or requiring a display. It sets up logging to console, runs `gwy_widgets_type_init()`, disables undo, disables GUI for the data browser and waiting, and loads resources, settings and all modules. However, it prevents the plugin-proxy and pygwy modules from loading.

There are currently the following options:

"enable-threads" with gboolean value. If `TRUE` or `FALSE` is passed `gwy_threads_set_enabled()` will be called with this settings. By default, the multithread processing state is unchanged.

"enable-pygwy" with gboolean value. If `TRUE` is passed then pygwy will not be prevented from loading. Passing `FALSE` is the same as not setting the option at all.

So, for instance a program wanting to enable multithread processing in Gwyddion functions (provided it is built in) can run

    1
    gwy_app_init_nongui("enable-threads", TRUE, NULL);

#### Parameters

option | Name of the first initialisation option, or `NULL` if there are no options. |
... | Value of the first option, if any, followed by another option name and value, etc. Terminated by `NULL`. |

Since: 2.55