TeplFileSaver: Tepl 6 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_newline_type ()
TeplNewlineType | tepl_file_saver_get_newline_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

TeplBuffer * | buffer | Read / Write / Construct Only
TeplFile * | file | Read / Write / Construct Only
TeplFileSaverFlags | flags | Read / Write / Construct
GFile * | location | Read / Write / Construct Only
TeplNewlineType | newline-type | Read / Write / Construct

## Types and Values

struct | TeplFileSaver
enum | TeplFileSaverFlags

## Object Hierarchy

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

### Things that need to be done at a higher level

Make the GtkTextView non-editable during the save operation. See `gtk_text_view_set_editable()`. Because the save operation is asynchronous, and `gtk_text_buffer_set_modified()` must be called (with a `FALSE` value) only when the file has been successfully saved. So that's why `gtk_text_buffer_set_modified()` is called by `tepl_file_saver_save_finish()`, not at the beginning of the save operation. If the view/buffer is editable during the save operation, `gtk_text_buffer_set_modified()` may be called at the wrong place in the undo/redo history.

## 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 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_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_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,
                                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]
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | user data to pass to `callback` . |

Since: 5.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 and the newline 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

### struct TeplFileSaver

    struct TeplFileSaver;

### enum TeplFileSaverFlags

Flags to define the behavior of a TeplFileSaver.

#### Members

TEPL_FILE_SAVER_FLAGS_NONE | No flags. |
TEPL_FILE_SAVER_FLAGS_CREATE_BACKUP | Create a backup before saving the file. |

Since: 1.0

## Property Details

### The `“buffer”` property

      “buffer”                   TeplBuffer *

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

Owner: TeplFileSaver

Flags: Read / Write / Construct Only

Since: 1.0

### The `“file”` property

      “file”                     TeplFile *

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

Owner: TeplFileSaver

Flags: Read / Write / Construct Only

Since: 1.0

### The `“flags”` property

      “flags”                    TeplFileSaverFlags

File saving flags.

Owner: TeplFileSaver

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.

Owner: TeplFileSaver

Flags: Read / Write / Construct Only

Since: 1.0

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

      “newline-type”             TeplNewlineType

The newline type.

Owner: TeplFileSaver

Flags: Read / Write / Construct

Default value: TEPL_NEWLINE_TYPE_LF

Since: 1.0

## See Also

TeplFile, TeplFileLoader