## BtChangeLog

BtChangeLog — class for the editor action journaling

## Synopsis

    #include "bt-edit.h"

    struct              BtChangeLog;
    BtChangeLog *       bt_change_log_new                   (void);
    gboolean            bt_change_log_is_active             (BtChangeLog *self);
    void                bt_change_log_add                   (BtChangeLog *self,
                                                             BtChangeLogger *owner,
                                                             gchar *undo_data,
                                                             gchar *redo_data);
    void                bt_change_log_redo                  (BtChangeLog *self);
    void                bt_change_log_undo                  (BtChangeLog *self);
    void                bt_change_log_start_group           (BtChangeLog *self);
    void                bt_change_log_end_group             (BtChangeLog *self);
    gboolean            bt_change_log_recover               (BtChangeLog *self,
                                                             const gchar *log_name);
    void                bt_change_log_register              (BtChangeLog *self,
                                                             BtChangeLogger *logger);

## Object Hierarchy

      GObject
       +----BtChangeLog

## Properties

      "can-redo"                 gboolean              : Read
      "can-undo"                 gboolean              : Read
      "crash-logs"               gpointer              : Read

## Description

Tracks edits actions since last save. Provides undo/redo. Supports grouping of edits into single undo/redo items (see `bt_change_log_start_group()`).

Edit actions are logged to disk for crash recovery. Groups are logged atomically, when they are closed (to have a recoverable log).

Logs are reset when saving a song. The log is removed when a song is closed.

BtEditApplication checks for left-over logs at startup and uses BtCrashRecoverDialog to offer a list of recoverable songs to the user.

## Details

### struct BtChangeLog

    struct BtChangeLog;

Editor action journal.

### bt_change_log_new ()

    BtChangeLog *       bt_change_log_new                   (void);

Create a new instance on first call and return a reference later on.

Returns : | the new signleton instance

### bt_change_log_is_active ()

    gboolean            bt_change_log_is_active             (BtChangeLog *self);

Checks if the changelog journalling is active. Should be checked before adding entries to avoid logging when e.g. loading a song.

`self` : | the changelog
Returns : | `TRUE` if the log is active

### bt_change_log_add ()

    void                bt_change_log_add                   (BtChangeLog *self,
                                                             BtChangeLogger *owner,
                                                             gchar *undo_data,
                                                             gchar *redo_data);

Add a new change to the change log. Changes are passed as serialized strings. The change-log takes ownership of `undo_data` and `redo_data`.

`self` : | the change log
`owner` : | the owner of the change
`undo_data` : | how to undo the change
`redo_data` : | how to redo the change

### bt_change_log_redo ()

    void                bt_change_log_redo                  (BtChangeLog *self);

Redo the last action.

`self` : | the change log

### bt_change_log_undo ()

    void                bt_change_log_undo                  (BtChangeLog *self);

Undo the last action.

`self` : | the change log

### bt_change_log_start_group ()

    void                bt_change_log_start_group           (BtChangeLog *self);

Open a new group. All further `bt_change_log_add()` calls will add to the active group. The group needs to be closed using `bt_change_log_end_group()`. Groups can be nested.

A top-level group is undone or redone with a single `bt_change_log_undo()` or `bt_change_log_redo()` call.

One would start and finish such a group in the first signal handler that triggered the change.

`self` : | the change log

### bt_change_log_end_group ()

    void                bt_change_log_end_group             (BtChangeLog *self);

Closed the last group opened with `bt_change_log_start_group()`. Usually one a group would be closed in the same local scope where it was opened.

`self` : | the change log

### bt_change_log_recover ()

    gboolean            bt_change_log_recover               (BtChangeLog *self,
                                                             const gchar *log_name);

Recover the given song.

Return: `TRUE` for successful recovery.

`self` : | the changelog
`log_name` : | the log file to replay

### bt_change_log_register ()

    void                bt_change_log_register              (BtChangeLog *self,
                                                             BtChangeLogger *logger);

Register a change-logger for use in change log replay.

`self` : | the change log
`logger` : | a change logger

## Property Details

### The `"can-redo"` property

      "can-redo"                 gboolean              : Read

Where there are action to redo.

Default value: FALSE

### The `"can-undo"` property

      "can-undo"                 gboolean              : Read

Where there are action to undo.

Default value: FALSE

### The `"crash-logs"` property

      "crash-logs"               gpointer              : Read

A list of found crash logs.

## See Also

BtCrashRecoverDialog