ChangeHistoryService

Completes a recording that was started with TryBeginRecording(). Pass the identifier returned by that call along with an FinishRecordingOperation describing what to do with the recorded changes:

• FinishRecordingOperation.Commit adds the changes to the undo/redo history as a new waypoint.
• FinishRecordingOperation.Cancel discards the recording and reverts the changes it captured. The identifier is ignored for this operation, so a plugin can cancel its own in-progress recording without knowing the identifier.
• FinishRecordingOperation.Append merges the recording into the waypoint that immediately precedes it rather than creating a new one.

When the recording finishes, this method fires OnRecordingFinished, forwarding the finalOptions table. It raises an error if the calling plugin has no recording in progress, or if operation is not FinishRecordingOperation.Cancel and identifier does not match the active recording. It has no effect when the service is disabled or while an undo or redo is in progress.

Reports whether Redo() currently has an action available to replay. It returns a boolean that is true when a redoable waypoint exists ahead of the current position in the undo/redo history; when that boolean is true, it also returns the name of the waypoint that the next redo would replay.

The boolean is false, with no name returned, when the redo stack is empty because the newest waypoint is already the current one, or when the service is disabled (which is always the case at runtime).

Reports whether Undo() currently has an action available to revert. It returns a boolean that is true when an undoable waypoint exists at the current position in the undo/redo history; when that boolean is true, it also returns the name of the waypoint that the next undo would revert.

The boolean is false, with no name returned, when the undo stack is empty because the position is already at the base waypoint, or when the service is disabled (which is always the case at runtime).

Reports whether the calling plugin has a recording in progress that was started with TryBeginRecording().

When called without an identifier, it returns true if any recording is active for the plugin. When an identifier is supplied, it returns true only if the active recording's identifier matches that value. It returns false when the service is disabled or when the plugin has no active recording.

Replays the waypoint immediately ahead of the current position in the undo/redo history, redoing the action that a matching Undo() had reverted, and advances the redo pointer forward by one waypoint. After the waypoint is replayed, it fires OnRedo with the name of the redone waypoint.

This method raises an error if a play is already in progress, if the service is disabled (which is always the case at runtime), or if there is nothing left to redo. Call GetCanRedo() first to confirm a redo is available.

Records the current state as a waypoint named base and then merges every existing waypoint into that single waypoint, leaving no actions to undo or redo. Use this to establish a clean starting point so that later Undo() calls cannot revert past the current state.

This method has no effect when the service is disabled (which is always the case at runtime).

Sets whether or not the ChangeHistoryService is enabled. When set to false, the undo/redo list is cleared, and does not repopulate. When set to true again, the original list is not restored, but further operations append to the list once more

This method will be deprecated soon in favor of TryBeginRecording().

ChangeHistoryService tracks plugin history as a stream of property changes. SetWaypoint() creates a cut in that stream of property changes so that the undo and redo actions know where to stop.

By convention, user-invoked actions in Studio must call SetWaypoint() after completing their set of changes to the experience. Calling it before a set of changes may clean up another misbehaving plugin which failed to set a waypoint, but it's a poor reason to justify such usage in your own plugin.

This method begins a recording to track changes to the data model. You must call it prior to making changes to avoid future warnings or errors.

When the recording is completed, you call FinishRecording() with the returned recording identifier to complete the recording and update the undo/redo stack.

This method will return nil if it fails to begin a recording. Recordings fail if the plugin already has a recording in progress, or if the user is in a solo playtest.

You may use IsRecordingInProgress() to check the recording status of the plugin.

Unplays the waypoint at the current position in the undo/redo history, reverting the most recent recorded action, and steps the undo pointer back by one waypoint. After the waypoint is reverted, it fires OnUndo with the name of the undone waypoint.

This method raises an error if a play is already in progress, if the service is disabled (which is always the case at runtime), or if there is nothing left to undo. Call GetCanUndo() first to confirm an undo is available.

Fires when a recording started with TryBeginRecording() is completed through FinishRecording(). The operation argument reports how the recording was finished (Commit, Cancel, or Append), and finalOptions is the optional table that was passed to FinishRecording().

Fires when a plugin begins a recording with TryBeginRecording(), carrying the same name and displayName values that were passed to that call.

Fires immediately after Redo() replays a waypoint, whether the redo was triggered by the user through Studio or invoked programmatically. The waypoint argument is the name of the action that was redone, matching the name that was recorded for that waypoint.

Fires immediately after Undo() reverts a waypoint, whether the undo was triggered by the user through Studio or invoked programmatically. The waypoint argument is the name of the action that was undone, matching the name that was recorded for that waypoint.