API Docs

Class: UndoObject

PD. UndoObject

Defines an object with multiple properties that can detect changes and manage its own PD.GlobalUndo entries.

This class creates a structured clone of the given properties and stores that as a reference for comparing values to detect changes. This means that it can store ArrayBuffers, DataViews, Dates, Maps, RegExps and Sets.

However, it cannot store functions or methods, so the object sent to its constructor must be a plain old JavaScript object (POJO) without methods.

NOTE: Another important caveat is to not use either _OLD or _NEW as property names for any objects or data that you store. These are generated by the DIFF utilities and used to identify end-of-line values.

new UndoObject(properties)

Creates a new undoable object.

Parameters:
Name Type Description
properties object

A simple POJO containing the properties to monitor.
Author:
  • drajmarsh

Members

:object

properties

Store the properties being monitored.

Type
  • object
:object

references

Store a reference copy of the given properties.

Type
  • object

Methods

addProperty(propName, value)

Adds a new property with the given value to both the properties and references store.

Parameters:
Name Type Description
propName string

The name of the new property to set the value of.
value any

The value to set the new property to.
Returns:

Returns this instance to support method chaining.

Type
PD.UndoObject

commitChange(propName, newValue)

Sets the value of a property and immediately commits the change.

Parameters:
Name Type Description
propName string

The name of the property to set the value of.
newValue any

The value to set the property to.
Returns:

Returns this instance to support method chaining.

Type
PD.UndoObject

commitChanges()

Compares and updates the monitored properties with their reference values.

This method first compares the properties to their reference values and generates an object containing any differences. If there are any differences, it updates the reference values and then creates an new undo/redo entry containing any differences.

Returns:

Returns this instance to support method chaining.

Type
PD.UndoObject

redo(changes)

Copies new values in the change list to both the references and properties store.

This method is typically called by PD.GlobalUno as it stores the change lists corresponding to a particular undo/redo step.

Parameters:
Name Type Description
changes object

The results of PD.GlobalUndo.shallowDiff or PD.GlobalUndo.deepDiff.

setProperty(path, value)

Sets the value of a property without committing the change.

To access the properties of child objects, you can use a nested path. A nested path may contain one or more period ('.') characters that separate it into a hierarchy of parent/child objects. If the path does not contain a period, then the whole string is treated as the field name.

As objects and arrays in JavaScript behave in some ways similar, you can use nested properties to access array entries by simply using a number as the field name to represent the ordinal index you want.

Once you have made all the changes you want to one or more properties, call the PD.UndoObject#commitChanges method to store your changes as a single undo/redo entry.

Parameters:
Name Type Description
path string

The path/name of the property to set the value of.
value any

The value to set the property to.
Returns:

Returns this instance to support method chaining.

Type
PD.UndoObject

undo(changes)

Copies new values in the change list to both the references and properties store.

This method is typically called by PD.GlobalUno as it stores the change lists corresponding to a particular undo/redo step.

Parameters:
Name Type Description
changes object

The results of PD.GlobalUndo.shallowDiff or PD.GlobalUndo.deepDiff.

copyNewValues(changes, refObj [, newObj]) <static>

Recursively copies new diff changes to a reference object.

Parameters:
Name Type Argument Description
changes object

The results of PD.GlobalUndo.shallowDiff or PD.GlobalUndo.deepDiff.
refObj object

The references object to copy old diff change values to.
newObj object <optional>

An optional properties object to copy new diff change values to.

copyOldValues(changes, refObj [, newObj]) <static>

Recursively copies previous diff changes to a reference object.

Parameters:
Name Type Argument Description
changes object

The results of PD.GlobalUndo.shallowDiff or PD.GlobalUndo.deepDiff.
refObj object

The references object to copy old diff change values to.
newObj object <optional>

An optional properties object to copy old diff change values to.