## file

file — High level file functions

## Synopsis

    #include <app/gwyapp.h>

    const gchar*        gwy_app_get_current_directory       (void);
    void                gwy_app_set_current_directory       (const gchar *directory);
    GwyContainer*       gwy_app_file_load                   (const gchar *filename_utf8,
                                                             const gchar *filename_sys,
                                                             const gchar *name);
    void                gwy_app_file_open                   (void);
    void                gwy_app_file_merge                  (void);
    gboolean            gwy_app_file_write                  (GwyContainer *data,
                                                             const gchar *filename_utf8,
                                                             const gchar *filename_sys,
                                                             const gchar *name);
    void                gwy_app_file_save                   (void);
    void                gwy_app_file_save_as                (void);
    gboolean            gwy_app_file_confirm_overwrite      (GtkWidget *chooser);

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

## Details

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

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

    GwyContainer*       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.

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

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

Since 2.7

### gwy_app_file_write ()

    gboolean            gwy_app_file_write                  (GwyContainer *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.

`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 open 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_confirm_overwrite ()

    gboolean            gwy_app_file_confirm_overwrite      (GtkWidget *chooser);

Asks for file overwrite for a file save chooser.

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