Jazz2::Editor::CommandHistory class

Undo and redo history of a level being edited.

Every change of the document goes through the history. A change is either executed by it, or — when it was already applied, as a stroke is shown while it's being drawn — just recorded. Changes made between BeginTransaction() and EndTransaction() are undone as one step.

Each state of the document has its own revision, so the document can tell whether it's back where it was saved. When the commands take more memory than allowed, the oldest ones are forgotten.

Constructors, destructors, conversion operators

CommandHistory(LevelDocument& document, std::size_t memoryBudget) explicit
Creates the history of a document.
~CommandHistory()
CommandHistory(const CommandHistory&) deleted

Public functions

auto operator=(const CommandHistory&) -> CommandHistory& deleted
auto GetDocument() -> LevelDocument&
Returns the document.
void Execute(std::unique_ptr<EditCommand> command, DocumentChanges& changes, bool allowMerge = false)
Applies a change and records it.
void Record(std::unique_ptr<EditCommand> command, bool allowMerge = false)
Records a change that was already applied to the document.
void BreakMerge()
Makes the next change a step of its own, even if it could be merged into the previous one.
void BeginTransaction(String name)
Starts a transaction, all changes until it ends are undone as one step, transactions can be nested.
void EndTransaction()
Ends a transaction.
void CancelTransaction(DocumentChanges& changes)
Ends a transaction and reverts all its changes.
auto IsInTransaction() const -> bool
Returns true if a transaction is in progress.
auto CanUndo() const -> bool
Returns true if there is a change to undo.
auto CanRedo() const -> bool
Returns true if there is a change to redo.
auto Undo(DocumentChanges& changes) -> bool
Undoes the last change.
auto Redo(DocumentChanges& changes) -> bool
Redoes the last undone change.
auto GetUndoName() const -> String
Returns the name of the change that would be undone.
auto GetRedoName() const -> String
Returns the name of the change that would be redone.
auto GetCount() const -> std::int32_t
Returns the number of recorded changes, done and undone.
auto GetDoneCount() const -> std::int32_t
Returns the number of changes that are done.
auto GetName(std::int32_t index) const -> String
Returns the name of a recorded change.
auto GetRevision() const -> std::uint32_t
Returns the revision of the current state of the document.
void MarkSaved()
Remembers the current state as saved.
void MarkDirty()
Makes the current state count as unsaved, as when it was restored from a recovery copy.
void NoteOutsideChange()
Counts a change made outside of the history that doesn't make the document unsaved.
auto IsDirty() const -> bool
Returns true if the document changed since it was saved.
auto GetOutsideChangeCount() const -> std::uint32_t
Returns how many times the document was marked as changed outside of the history.
void Clear()
Forgets all changes, the current state becomes the saved one.
auto GetMemoryUsage() const -> std::size_t
Returns the memory taken by all recorded changes.

Public variables

Function<void()> OnTransactionsEnded
Called when the outermost transaction ended or was cancelled.

Function documentation

void Jazz2::Editor::CommandHistory::Execute(std::unique_ptr<EditCommand> command, DocumentChanges& changes, bool allowMerge = false)

Applies a change and records it.

With allowMerge the change may be merged into the previous one (see EditCommand::TryMerge()), unless BreakMerge() was called since.

void Jazz2::Editor::CommandHistory::BreakMerge()

Makes the next change a step of its own, even if it could be merged into the previous one.

Called where a continuous change ends — a value is no longer dragged, a text is committed — or where a new one starts, so two separate changes of the same value aren't undone at once. Undo and redo break merging too.

void Jazz2::Editor::CommandHistory::NoteOutsideChange()

Counts a change made outside of the history that doesn't make the document unsaved.

Such as hiding a layer: it's saved with the level when it's saved, but alone it's no reason to save. Whoever keeps a copy of the document sees it by GetOutsideChangeCount().

std::uint32_t Jazz2::Editor::CommandHistory::GetOutsideChangeCount() const

Returns how many times the document was marked as changed outside of the history.

The revision doesn't change then, so whoever keeps a copy of the document compares this too.

Variable documentation

Function<void()> Jazz2::Editor::CommandHistory::OnTransactionsEnded

Called when the outermost transaction ended or was cancelled.

The editor shows the changes made in a transaction only then, all at once, see EditorSession::OnDocumentChanged().