TeplFileSaver: Tepl 3 Reference Manual

## TeplFileSaver TeplFileSaver — Save a TeplBuffer into a file |

## Functions

TeplFileSaver * | tepl_file_saver_new ()
TeplFileSaver * | tepl_file_saver_new_with_target ()
TeplBuffer * | tepl_file_saver_get_buffer ()
TeplFile * | tepl_file_saver_get_file ()
GFile * | tepl_file_saver_get_location ()
void | tepl_file_saver_set_encoding ()
const TeplEncoding * | tepl_file_saver_get_encoding ()
void | tepl_file_saver_set_newline_type ()
TeplNewlineType | tepl_file_saver_get_newline_type ()
void | tepl_file_saver_set_compression_type ()
TeplCompressionType | tepl_file_saver_get_compression_type ()
void | tepl_file_saver_set_flags ()
TeplFileSaverFlags | tepl_file_saver_get_flags ()
void | tepl_file_saver_save_async ()
gboolean | tepl_file_saver_save_finish ()

## Properties

GtkSourceBuffer * | buffer | Read / Write / Construct Only
GtkSourceCompressionType | compression-type | Read / Write / Construct
TeplEncoding * | encoding | Read / Write / Construct
TeplFile * | file | Read / Write / Construct Only
TeplFileSaverFlags | flags | Read / Write / Construct
GFile * | location | Read / Write / Construct Only
GtkSourceNewlineType | newline-type | Read / Write / Construct

## Types and Values

| TeplFileSaver
#define | TEPL_FILE_SAVER_ERROR
enum | TeplFileSaverError
enum | TeplFileSaverFlags

## Object Hierarchy

        GEnum
        ╰── TeplFileSaverError
        GFlags
        ╰── TeplFileSaverFlags
        GObject
        ╰── TeplFileSaver

## Includes

    #include <tepl/tepl.h>

## Description

A TeplFileSaver object permits to save a TeplBuffer into a GFile.

A file saver should be used only for one save operation, including errors handling. If an error occurs, you can reconfigure the saver and relaunch the operation with `tepl_file_saver_save_async()`.

TeplFileSaver is a fork of GtkSourceFileSaver, the code has been a little improved (but no major changes). See the description of TeplFile for more background on why a fork was needed.

## Functions

### tepl_file_saver_new ()

    TeplFileSaver *
    tepl_file_saver_new (TeplBuffer *buffer,
                         TeplFile *file);

Creates a new TeplFileSaver object. The `buffer` will be saved to the TeplFile's location.

This constructor is suitable for a simple "save" operation, when the `file` already contains a non-`NULL` “location”.

#### Parameters

buffer | the TeplBuffer to save. |
file | the TeplFile. |

#### Returns

a new TeplFileSaver object.

Since: 1.0

### tepl_file_saver_new_with_target ()

    TeplFileSaver *
    tepl_file_saver_new_with_target (TeplBuffer *buffer,
                                     TeplFile *file,
                                     GFile *target_location);

Creates a new TeplFileSaver object with a target location. When the file saving is finished successfully, `target_location` is set to the `file` 's “location” property. If an error occurs, the previous valid location is still available in TeplFile.

This constructor adds `TEPL_FILE_SAVER_FLAGS_IGNORE_MODIFICATION_TIME` to the “flags” property.

This constructor is suitable for a "save as" operation, or for saving a new buffer for the first time.

#### Parameters

buffer | the TeplBuffer to save. |
file | the TeplFile. |
target_location | the GFile where to save the buffer to. |

#### Returns

a new TeplFileSaver object.

Since: 1.0

### tepl_file_saver_get_buffer ()

    TeplBuffer *
    tepl_file_saver_get_buffer (TeplFileSaver *saver);

#### Parameters

saver | a TeplFileSaver. |

#### Returns

the TeplBuffer to save.

[transfer none]

Since: 1.0

### tepl_file_saver_get_file ()

    TeplFile *
    tepl_file_saver_get_file (TeplFileSaver *saver);

#### Parameters

saver | a TeplFileSaver. |

#### Returns

the TeplFile.

[transfer none]

Since: 1.0

### tepl_file_saver_get_location ()

    GFile *
    tepl_file_saver_get_location (TeplFileSaver *saver);

#### Parameters

saver | a TeplFileSaver. |

#### Returns

the GFile where to save the buffer to.

[transfer none]

Since: 1.0

### tepl_file_saver_set_encoding ()

    void
    tepl_file_saver_set_encoding (TeplFileSaver *saver,
                                  const TeplEncoding *encoding);

Sets the encoding. If `encoding` is `NULL`, the UTF-8 encoding will be set. By default the encoding is taken from the TeplFile.

#### Parameters

saver | a TeplFileSaver. |
encoding | the new encoding, or `NULL` for UTF-8. | [allow-none]

Since: 1.0

### tepl_file_saver_get_encoding ()

    const TeplEncoding *
    tepl_file_saver_get_encoding (TeplFileSaver *saver);

#### Parameters

saver | a TeplFileSaver. |

#### Returns

the encoding.

Since: 1.0

### tepl_file_saver_set_newline_type ()

    void
    tepl_file_saver_set_newline_type (TeplFileSaver *saver,
                                      TeplNewlineType newline_type);

Sets the newline type. By default the newline type is taken from the TeplFile.

#### Parameters

saver | a TeplFileSaver. |
newline_type | the new newline type. |

Since: 1.0

### tepl_file_saver_get_newline_type ()

    TeplNewlineType
    tepl_file_saver_get_newline_type (TeplFileSaver *saver);

#### Parameters

saver | a TeplFileSaver. |

#### Returns

the newline type.

Since: 1.0

### tepl_file_saver_set_compression_type ()

    void
    tepl_file_saver_set_compression_type (TeplFileSaver *saver,
                                          TeplCompressionType compression_type);

Sets the compression type. By default the compression type is taken from the TeplFile.

#### Parameters

saver | a TeplFileSaver. |
compression_type | the new compression type. |

Since: 1.0

### tepl_file_saver_get_compression_type ()

    TeplCompressionType
    tepl_file_saver_get_compression_type (TeplFileSaver *saver);

#### Parameters

saver | a TeplFileSaver. |

#### Returns

the compression type.

Since: 1.0

### tepl_file_saver_set_flags ()

    void
    tepl_file_saver_set_flags (TeplFileSaver *saver,
                               TeplFileSaverFlags flags);

#### Parameters

saver | a TeplFileSaver. |
flags | the new flags. |

Since: 1.0

### tepl_file_saver_get_flags ()

    TeplFileSaverFlags
    tepl_file_saver_get_flags (TeplFileSaver *saver);

#### Parameters

saver | a TeplFileSaver. |

#### Returns

the flags.

Since: 1.0

### tepl_file_saver_save_async ()

    void
    tepl_file_saver_save_async (TeplFileSaver *saver,
                                gint io_priority,
                                GCancellable *cancellable,
                                GFileProgressCallback progress_callback,
                                gpointer progress_callback_data,
                                GDestroyNotify progress_callback_notify,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Saves asynchronously the buffer into the file. See the GAsyncResult documentation to know how to use this function.

#### Parameters

saver | a TeplFileSaver. |
io_priority | the I/O priority of the request. E.g. `G_PRIORITY_LOW`, `G_PRIORITY_DEFAULT` or `G_PRIORITY_HIGH`. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
progress_callback | function to call back with progress information, or `NULL` if progress information is not needed. | [scope notified][nullable]
progress_callback_data | user data to pass to `progress_callback` . | [closure]
progress_callback_notify | function to call on `progress_callback_data` when the `progress_callback` is no longer needed, or `NULL`. | [nullable]
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | user data to pass to `callback` . |

Since: 1.0

### tepl_file_saver_save_finish ()

    gboolean
    tepl_file_saver_save_finish (TeplFileSaver *saver,
                                 GAsyncResult *result,
                                 GError **error);

Finishes a file saving started with `tepl_file_saver_save_async()`.

If the file has been saved successfully, the following TeplFile properties will be updated: the location, the encoding, the newline type and the compression type.

gtk_text_buffer_set_modified() is called with `FALSE` if the file has been saved successfully.

#### Parameters

saver | a TeplFileSaver. |
result | a GAsyncResult. |
error | a GError, or `NULL`. |

#### Returns

whether the file was saved successfully.

Since: 1.0

## Types and Values

### TeplFileSaver

    typedef struct _TeplFileSaver TeplFileSaver;

### TEPL_FILE_SAVER_ERROR

    #define TEPL_FILE_SAVER_ERROR tepl_file_saver_error_quark ()

### enum TeplFileSaverError

An error code used with the `TEPL_FILE_SAVER_ERROR` domain.

#### Members

TEPL_FILE_SAVER_ERROR_INVALID_CHARS | The buffer contains invalid characters. |
TEPL_FILE_SAVER_ERROR_EXTERNALLY_MODIFIED | The file is externally modified. |

Since: 1.0

### enum TeplFileSaverFlags

Flags to define the behavior of a TeplFileSaver.

#### Members

TEPL_FILE_SAVER_FLAGS_NONE | No flags. |
TEPL_FILE_SAVER_FLAGS_IGNORE_INVALID_CHARS | Ignore invalid characters. |
TEPL_FILE_SAVER_FLAGS_IGNORE_MODIFICATION_TIME | Save file despite external modifications. |
TEPL_FILE_SAVER_FLAGS_CREATE_BACKUP | Create a backup before saving the file. |

Since: 1.0

## Property Details

### The `“buffer”` property

      “buffer”                   GtkSourceBuffer *

The TeplBuffer to save. The TeplFileSaver object has a weak reference to the buffer.

Flags: Read / Write / Construct Only

Since: 1.0

### The `“compression-type”` property

      “compression-type”         GtkSourceCompressionType

The compression type.

Flags: Read / Write / Construct

Default value: GTK_SOURCE_COMPRESSION_TYPE_NONE

Since: 1.0

### The `“encoding”` property

      “encoding”                 TeplEncoding *

The file's encoding.

Flags: Read / Write / Construct

Since: 1.0

### The `“file”` property

      “file”                     TeplFile *

The TeplFile. The TeplFileSaver object has a weak reference to the file.

Flags: Read / Write / Construct Only

Since: 1.0

### The `“flags”` property

      “flags”                    TeplFileSaverFlags

File saving flags.

Flags: Read / Write / Construct

Since: 1.0

### The `“location”` property

      “location”                 GFile *

The GFile where to save the buffer. By default the location is taken from the TeplFile at construction time.

Flags: Read / Write / Construct Only

Since: 1.0

### The `“newline-type”` property

      “newline-type”             GtkSourceNewlineType

The newline type.

Flags: Read / Write / Construct

Default value: GTK_SOURCE_NEWLINE_TYPE_LF

Since: 1.0

## See Also

TeplFile, TeplFileLoader