File operations: Gwyddion Application Library Reference Manual

## File operations File operations — High level file functions |

## Functions

const gchar * | gwy_app_get_current_directory ()
void | gwy_app_set_current_directory ()
GwyFile * | gwy_app_file_load ()
void | gwy_app_file_open ()
void | gwy_app_file_merge ()
gboolean | gwy_app_file_write ()
void | gwy_app_file_save ()
void | gwy_app_file_save_as ()
void | gwy_app_file_close ()
gboolean | gwy_app_file_confirm_overwrite ()

## Includes

    #include <libgwyapp/gwyapp.h>

## Description

High-level functions `gwy_app_file_load()` and `gwy_app_file_write()` wrap low-level file handling functions from gwymodule-file and handle registration of loaded containers in data browser, showing windows, remembering file types, or the differenced between save and export.

They are complemented by application-level functions `gwy_app_file_open()`, `gwy_app_file_save()`, and `gwy_app_file_save_as()` that perform the corresponding operations of File menu. These are probably not of general interest.

Beside that, functions to maintain application-level idea of current directory are provided: `gwy_app_get_current_directory()`, `gwy_app_set_current_directory()`. They should be used in place of system `chdir()` which has various unwanted side-effect, like change of the directory where core is dumped on segfault.

## Functions

### gwy_app_get_current_directory()

    const gchar *
    gwy_app_get_current_directory (void);

Returns what the app uses as `current directory'.

Warning: This function is probably temporary.

#### Returns

A string in GLib file name encoding that should not be modified neither freed, valid only until next call to `gwy_app_set_current_directory()`. It ends with a `G_DIR_SEPARATOR_S`.

### gwy_app_set_current_directory()

    void
    gwy_app_set_current_directory (const gchar *directory);

Sets what the app should use as `current directory'.

Warning: This function is probably temporary.

#### Parameters

directory | The directory to set, or a filename to take directory part from, it must be an absolute path. In GLib file name encoding. |

### gwy_app_file_load()

    GwyFile *
    gwy_app_file_load (const gchar *filename_utf8,
                       const gchar *filename_sys,
                       const gchar *name);

Loads a file into application (a high-level function).

At least one of `filename_utf8` , `filename_sys` must be non-`NULL`.

The file is loaded in interactive mode, modules can ask for user input. Upon a successful load all necessary setup tasks are performed. If the load fails, an error dialog is presented.

#### Parameters

filename_utf8 | Name of file to load, in UTF-8. |
filename_sys | Name of file to load, in GLib encoding. |
name | File type to open file as, but normally `NULL` to automatically detect from file contents. |

#### Returns

Container of the just loaded file on success, `NULL` on failure. The caller does not own the reference, the container is only owned by the data browser.

### gwy_app_file_open()

    void
    gwy_app_file_open (void);

Opens a user-selected file (very high-level app function).

### gwy_app_file_merge()

    void
    gwy_app_file_merge (void);

Merges a user-selected file (very high-level app function).

### gwy_app_file_write()

    gboolean
    gwy_app_file_write (GwyFile *data,
                        const gchar *filename_utf8,
                        const gchar *filename_sys,
                        const gchar *name);

Writes container to a file (a high-level function).

At least one of `filename_utf8` , `filename_sys` must be non-`NULL`.

The file is saved in interactive mode, modules can ask for user input. If the write fails, an error dialog is presented.

#### Parameters

data | Data to write. |
filename_utf8 | Name of file to write data to, in UTF-8. |
filename_sys | Name of file to write data to, in GLib encoding. |
name | File type to save file as, but normally `NULL` to automatically detect from file name. |

#### Returns

`TRUE` on success.

### gwy_app_file_save()

    void
    gwy_app_file_save (void);

Saves current data to a file (very high-level app function).

May fall back to `gwy_app_file_save_as()` when current data has no file name associated with it, or the format it was loaded from is not saveable.

### gwy_app_file_save_as()

    void
    gwy_app_file_save_as (void);

Saves current data to a user-selected file (very high-level app function).

### gwy_app_file_close()

    void
    gwy_app_file_close (void);

Closes the current file file (very high-level app function).

### gwy_app_file_confirm_overwrite()

    gboolean
    gwy_app_file_confirm_overwrite (GtkWidget *chooser);

Asks for file overwrite for a file save chooser.

#### Parameters

chooser | A file chooser for save action. |

#### Returns

`TRUE` if it is OK to overwrite the file, `FALSE` when user cancelled it or there was other problem.