BtChangeLog: Buzztrax Bt-Edit Reference Manual

## BtChangeLog BtChangeLog — class for the editor action journaling |

## Functions

BtChangeLog * | bt_change_log_new ()
gboolean | bt_change_log_is_active ()
void | bt_change_log_add ()
void | bt_change_log_redo ()
void | bt_change_log_undo ()
void | bt_change_log_start_group ()
void | bt_change_log_end_group ()
gboolean | bt_change_log_recover ()
void | bt_change_log_register ()

## Properties

gboolean | can-redo | Read
gboolean | can-undo | Read
gpointer | crash-logs | Read

## Types and Values

struct | BtChangeLog

## Object Hierarchy

        GObject
        ╰── BtChangeLog

## Includes

    #include "bt-edit.h"

## 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 under the users-cache directory 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.

When running the application with BT_DEBUG_CHANGE_LOG=1 and if debugging is enabled, one will get extra comments in the edit journal.

## Functions

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

#### Parameters

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

#### Parameters

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.

#### Parameters

self | the change log |

### bt_change_log_undo ()

    void
    bt_change_log_undo (BtChangeLog *self);

Undo the last action.

#### Parameters

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.

#### Parameters

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 a group would be closed in the same local scope where it was opened.

#### Parameters

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.

#### Parameters

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.

#### Parameters

self | the change log |
logger | a change logger |

## Types and Values

### struct BtChangeLog

    struct BtChangeLog;

Editor action journal.

## Property Details

### The `“can-redo”` property

      “can-redo”                 gboolean

Where there are action to redo.

Flags: Read

Default value: FALSE

### The `“can-undo”` property

      “can-undo”                 gboolean

Where there are action to undo.

Flags: Read

Default value: FALSE

### The `“crash-logs”` property

      “crash-logs”               gpointer

A list of found crash logs.

Flags: Read

## See Also

BtCrashRecoverDialog