API Docs Class: GlobalUndo

new GlobalUndo()

Manages global undo and redo for framework applications and their models.

This class provides a global undo/redo manager that interfaces with a range of PD.UndoAction subclasses that handle the actual processes of undoing and redoing themselves. The manager simply maintains the required lists, updates global state whenever necessary and provides methods for recording various model actions.

Author:

drajmarsh

Members

debouncedInProgressReset <static>

Sets the undoRedoInProgress flag to false after allowing some time for async undo/redo actions to complete.

:boolean isActive <static>

Whether or not to record undo actions when state changes.

Use this property to pause or resume undo and redo activity within the application. When not active, new entries are not added to the queue.

Type

boolean

:Array redoQueue <static>

Stores a list of redoable actions that have been undone in the model.

Type

Array

:number timeLimit <static>

The time period within which multiple sequential instances of the same undo action may be merged together rather than being created as multiple separate entries.

This value is given in milliseconds and defaults to 4000 (4 secs). Acceptable values are in the range 0 (no merging) to 60000 (1 min). Whether or not an undo action can be updated as well as created is determined by the undo action class itself.

Type

number

:Array undoQueue <static>

Stores a list of undoable actions that have been applied to the model.

Type

Array

Methods

addActionToUndoQueue(action) <static>

Adds an action to the undo queue.

This method adds the given action and does some housekeeping such as clearing the redo queue and checking the maximum size to avoid memory issues.

Parameters:

Name	Type	Description
`action`	PD.UndoAction	The action to add.

canRedo() <static>

Whether or not there are items in the redo queue.

canUndo() <static>

Whether or not there are items in the undo queue.

changeGlobalState(property, newValue) <static>

Sets the value of the given PD.GlobalState property after recording its current value and creating/updating an undo record.

Use this method instead of PD.GlobalUndo.recordGlobalStateChange if you do not want to manage the recording of the existing value before setting the new value and recording the change.

NOTE: In order to efficiently record the change in value, you must rely on this method to actually set the new value. If you change the global state property value before calling this method, its current value will be the same as the new value, so there will effectively be no value change to record.

This method can be called multiple times during an interactive action. If the previous entry in the undo queue is a global state change of the same property within the current time limit, then that entry will be updated with the new value instead of creating and adding a new entry.

Parameters:

Name	Type	Description
`property`	string	The global state property changing.
`newValue`	any	The new value to set.

checkElementPath(element) <static>

Check for a valid path, then update and recompute plane equation if needed.

If a path is planar, this will ensure that all its vertices are projected onto its plane each time it is updated. Rather than store the plane equation, we can simply recompute it from the path vertices whenever we undo/redo as they will have already been made coplanar.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element whose path moved.

checkElementPath(element) <static>

Check for a valid path, then update and recompute plane equation if needed.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element whose path moved.

checkTypeAndTime(item, type [, timeout]) <static>

Check if action item is of the given type and within the time limit.

Parameters:

Name	Type	Argument	Description
`item`	PD.UndoAction		The undo action item to check.
`type`	any		The `PD.UndoAction` subclass to check.
`timeout`	number	<optional>	The number of milliseconds back, defaults to `PD.GlobalUndo.timeLimit`.

Returns:

Returns true if item is same type and within the time limit.

Type: boolean

getLastUndoAction() <static>

Retrieves the last action item in the undo queue, if available.

Returns:

Returns the last undo action item.

Type: PD.UndoAction | undefined

getLastUndoActionOfTypeWithinTime(type [, timeout]) <static>

Retrieves the last action in the undo queue if it is the given type and within time limit.

This method is used when there is likely to be multiple changes in quick succession to the same property or parameter that you actually want merged into a single undo point. Simply pass the PD.UndoAction subclass you want to test for, as well as an optional timeout value in milliseconds and, if the last item in the undo queue matches those values, it is returned. If not, then a null value is returned.

If you do not provide the optional timeout value, the PD.GlobalUndo.timeLimit value will be used (which defaults to 4000ms (4 secs)). To ignore the timeout limit, simply set the timeout value to zero.

Parameters:

Name	Type	Argument	Description
`type`	any		The subclass of `PD.UndoAction` to check.
`timeout`	number	<optional>	The number of milliseconds since updated, defaults to `PD.GlobalUndo.timeLimit`.

Returns:

Returns the last undo action item if matching, else null.

Type: PD.UndoAction | null

Example

MyClass.prototype.storeUndoPoint = function(property, oldValue, newValue) {

     if (PD.GlobalUndo.isActiveAndNotBusy()) {

         const last_item = PD.GlobalUndo.getLastUndoActionOfTypeWithinTime(MyClass.UndoAction);
         if (last_item && (last_item.property == property)) {
             last_item.timestamp = Date.now();
             last_item.newValue = newValue;
         }

         /// Create new undo record.
         else PD.GlobalUndo.addActionToUndoQueue(
             new MyClass.UndoAction(this, property, oldValue, newValue)
         );

     }

};

isActiveAndNotBusy() <static>

Determines if the undo or redo action receptive to storing changes.

The result of this method depends on the PD.GlobalUndo.isActive property and and the PD.GlobalUndo.isUndoRedoInProgress method. Whilst an undo or redo command is in progress, the ability to add to or update items in the undo/redo queue is temporarily suspended to ensure that any changes that occur during an undo/redo don't generate any more undo/redo actions.

isUndoRedoInProgress() <static>

Retrieves whether or not an undo or redo action being processed.

Whilst an undo or redo command is in progress, the ability to add to or update items in the undo/redo queue is temporarily suspended. As Undo and redo commands are atomic in nature, this should not otherwise affect your application, but ensures that any changes that occur during an undo/redo don't generate more undo/redo actions.

rebuildModel() <static>

Rebuilds the current model, checks for space overlaps, updates selection and generates a redraw.

Call this method after your undo/redo action makes any significant changes that affect the geometry of any element(s) in the model.

rebuildModel() <static>

A placeholder that the host application can reassign or override in order to update its internal model when an entity's parameters are changed.

Call this method after your undo/redo action makes any significant changes that affect the host application's internal model.

rebuildModelAndClearSelection() <static>

Rebuilds the model, clears the selection and generates a redraw.

Call this method if your undo/redo action creates a new element or changes the level, thus invalidating the current selection set.

rebuildModelAndClearSelection() <static>

Rebuilds the model, clears the selection and generates a redraw.

Call this method if your undo/redo action creates a new element or changes the level, thus invalidating the current selection set.

recordAddElements(elements) <static>

Records the addition of multiple element to the model.

Parameters:

Name	Type	Description
`elements`	BIM.Element	The list of elements that were just added.

recordAddElements(elements) <static>

Records the addition of multiple element to the model.

Parameters:

Name	Type	Description
`elements`	BIM.Element	The list of elements that were just added.

recordAndApplyCurveTypeChange(selection, curveType, id) <static>

Sets a new curve type for items in the selection set and records undo/redo info.

NOTE: Do not set the curve type of any junction in the selection set prior to calling this method. This method has the logic required to iterate over the given selection set and properly change each selected junction's curve type, prior to adding or updating the undoable action in the undo queue.

This method can be called multiple times, such as when a user is choosing different curve types in quick succession. If the last item in the undo queue is of the same type and the selection set identifier has not changed, then the last undo action will be updated to reflect the new changes. If the last item is a different type or has a different id value, a new undo entry of this type will be added.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`curveType`	PD.CURVE	The new curve type to set for junctions.
`id`	number	The numeric id of the move sequence.

Returns:

Returns true if any curve in the selection changed, otherwise false.

Type: boolean

recordAndApplyCurveTypeChange(selection, curveType, id) <static>

Sets a new curve type for items in the selection set and records undo/redo info.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`curveType`	PD.CURVE	The new curve type to set for junctions.
`id`	number	The numeric id of the move sequence.

Returns:

Returns true if any curve in the selection changed, otherwise false.

Type: boolean

recordAndApplyElementRename(element, name) <static>

Records the renaming of an element.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element being renamed.
`name`	string	The new name for the element.

recordAndApplyJunctionOrientationChange(selection, rotation, id) <static>

Sets a new junction orientation for items in the selection set and records undo/redo info.

NOTE: Do not set the orientation of any junction in the selection set prior to calling this method. This method has the logic required to iterate over the given selection set and update each selected junction's orientation based on the given rotation angle, prior to adding or updating the undoable action in the undo queue.

This method can be called multiple times during an ongoing operation. If the last item in the undo queue is of the same type, the selection set identifier has not changed and it is within 4sec of the last undo action, then the last undo action itself will be updated to reflect the new changes. If the last undo action is of a different type, has a different id value or occurred more than 4sec ago, a new undo entry of this type will be added.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`rotation`	number	The relative rotation to apply to selected junctions.
`id`	number	The numeric id of the move sequence.

recordAndApplyJunctionOrientationChange(selection, rotation, id) <static>

Sets a new junction orientation for items in the selection set and records undo/redo info.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`rotation`	number	The relative rotation to apply to selected junctions.
`id`	number	The numeric id of the move sequence.

recordAndApplySelectionNudge(selection, vector, id) <static>

Records the keyboard-based nudging of a selection set, updating previous if id is the same.

This method is called when the user is in nudge mode, where pressing the X, Y or Z keys moves the current selection in increments equal to the current snap grid. If the last item in the undo queue is of the same type, the selection set identifier has not changed and it is within 4sec of the last undo action, then the last undo action itself will be updated to reflect the new changes. If the last undo action is of a different type, has a different id value or occurred more than 4sec ago, a new undo entry of this type will be added.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`vector`	THREE.Vector3	The relative vector to move the selection by.
`id`	number	The numeric id of the move sequence.

recordApertureAdd(element, junction, aperture [, contourIndex] [, junctionIndex] [, apertureIndex]) <static>

Records the addition of an aperture to a junction.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element being added to.
`junction`	BIM.Junction		The junction being added to.
`aperture`	BIM.Aperture		The aperture that was just added.
`contourIndex`	number	<optional>	The ordinal index of the element path contour.
`junctionIndex`	number	<optional>	The ordinal index of the junction in the contour.
`apertureIndex`	number	<optional>	The ordinal index of the aperture in the junction.

recordApertureAdd(element, junction, aperture [, contour_index] [, junction_index] [, aperture_index]) <static>

Records the addition of an aperture to a junction.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element being added to.
`junction`	BIM.Junction		The junction being added to.
`aperture`	BIM.Aperture		The aperture that was just added.
`contour_index`	number	<optional>	The ordinal index of the element path contour.
`junction_index`	number	<optional>	The ordinal index of the junction in the contour.
`aperture_index`	number	<optional>	The ordinal index of the aperture in the junction.

recordApertureChange(element, junction, aperture [, contourIndex] [, junctionIndex] [, apertureIndex]) <static>

Records the interactive editing of an aperture size and/or position.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element the aperture belongs to.
`junction`	BIM.Junction		The junction the aperture belongs to.
`aperture`	BIM.Aperture		The aperture that was just edited.
`contourIndex`	number	<optional>	The ordinal index of the element path contour.
`junctionIndex`	number	<optional>	The ordinal index of the junction in the contour.
`apertureIndex`	number	<optional>	The ordinal index of the aperture in the junction.

recordApertureChange(element, junction, aperture [, contour_index] [, junction_index] [, aperture_index]) <static>

Records the interactive editing of an aperture size and/or position.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element the aperture belongs to.
`junction`	BIM.Junction		The junction the aperture belongs to.
`aperture`	BIM.Aperture		The aperture that was just edited.
`contour_index`	number	<optional>	The ordinal index of the element path contour.
`junction_index`	number	<optional>	The ordinal index of the junction in the contour.
`aperture_index`	number	<optional>	The ordinal index of the aperture in the junction.

recordApertureChangeIfSelectionChanged(element, junction, aperture) <static>

Records the manual editing of an aperture size and/or position.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element the aperture belongs to.
`junction`	BIM.Junction	The junction the aperture belongs to.
`aperture`	BIM.Aperture	The aperture that was edited.

recordApertureChangeIfSelectionChanged(element, junction, aperture) <static>

Records the manual editing of an aperture size and/or position.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element the aperture belongs to.
`junction`	BIM.Junction	The junction the aperture belongs to.
`aperture`	BIM.Aperture	The aperture that was edited.

recordApertureRemove(element, junction, aperture [, contourIndex] [, junctionIndex] [, apertureIndex]) <static>

Records the removal of an aperture from a junction.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element being deleted from.
`junction`	BIM.Junction		The junction being deleted from.
`aperture`	BIM.Aperture		The aperture that is about to be removed.
`contourIndex`	number	<optional>	The ordinal index of the element path contour.
`junctionIndex`	number	<optional>	The ordinal index of the junction in the contour.
`apertureIndex`	number	<optional>	The ordinal index of the aperture in the junction.

recordApertureRemove(element, junction, aperture [, contour_index] [, junction_index] [, aperture_index]) <static>

Records the removal of an aperture from a junction.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element being deleted from.
`junction`	BIM.Junction		The junction being deleted from.
`aperture`	BIM.Aperture		The aperture that is about to be removed.
`contour_index`	number	<optional>	The ordinal index of the element path contour.
`junction_index`	number	<optional>	The ordinal index of the junction in the contour.
`aperture_index`	number	<optional>	The ordinal index of the aperture in the junction.

recordApertureSelectionEdit(selection) <static>

Records the manual editing of selected apertures.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.

recordApertureSelectionEdit(selection) <static>

Records the manual editing of selected apertures.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.

recordApertureSelectionEditIfChanged(selection, id) <static>

Records the interactive movement of a selection, updating previous if id is the same.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`id`	number	The numeric id of the move sequence.

recordApertureSelectionEditIfChanged(selection, id) <static>

Records the interactive movement of a selection, updating previous if id is the same.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`id`	number	The numeric id of the move sequence.

recordContourAdd(element, contourIndex) <static>

Records the addition of a new contour into an element path.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element being added to.
`contourIndex`	number	The ordinal index of the contour in the element path.

recordContourAdd(element, contour_index) <static>

Records the addition of a new contour into an element path.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element being added to.
`contour_index`	number	The ordinal index of the contour in the element path.

recordContourOffset(element, contourIndex) <static>

Records the offset of an existing contour in an element path.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element whose path contour is being offset.
`contourIndex`	number	The ordinal index of the contour in the element path.

recordContourRemove(element, contourIndex) <static>

Records the removal of an existing contour from an element path.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element being deleted from.
`contourIndex`	number	The ordinal index of the contour in the element path.

recordContourRemove(element, contour_index) <static>

Records the removal of an existing contour from an element path.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element being deleted from.
`contour_index`	number	The ordinal index of the contour in the element path.

recordContourReverse(element, contourIndex) <static>

Records the reversal of an existing contour in an element path.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element whose path contour is being reversed.
`contourIndex`	number	The ordinal index of the contour in the element path.

recordContourReverse(element, contour_index) <static>

Records the reversal of an existing contour in an element path.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element whose path contour is being reversed.
`contour_index`	number	The ordinal index of the contour in the element path.

recordControlNodeMoved(element, junction, nodeIndex, id) <static>

Records the interactive movement of a control node, updating previous if id is the same.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element the junction belongs to.
`junction`	BIM.Junction	The junction the control node belongs to.
`nodeIndex`	number	The index of the control node that moved.
`id`	number	The numeric id of the move sequence.

recordControlNodeMoved(element, junction, node_index, id) <static>

Records the interactive movement of a control node, updating previous if id is the same.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element the junction belongs to.
`junction`	BIM.Junction	The junction the control node belongs to.
`node_index`	number	The index of the control node that moved.
`id`	number	The numeric id of the move sequence.

recordCutElements(selection) <static>

Records the removal of a selection set from the model.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.

recordCutElements(selection) <static>

Records the removal of a selection set from the model.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.

recordDeleteAnimations(element) <static>

Records a deletion of the given element's animations, if it has any.

Parameters:

Name	Type	Description
`element`	BIM.Element.Three	The element whose animations are to be deleted.

recordElementAdd(parent, element [, index]) <static>

Records the addition of a new element to a level or space.

Parameters:

Name	Type	Argument	Description
`parent`	BIM.Level \| BIM.Space		The level or space being added to.
`element`	BIM.Element		The element that was just added.
`index`	number	<optional>	The ordinal index of the new element in its host.

recordElementAdd(parent, element [, index]) <static>

Records the addition of a new element to a level or space.

Parameters:

Name	Type	Argument	Description
`parent`	BIM.Level \| BIM.Space		The level or space being added to.
`element`	BIM.Element		The element that was just added.
`index`	number	<optional>	The ordinal index of the new element in its host.

recordElementCreation(element) <static>

Records the progressive interactive addition of a new element.

This is different from adding a new element as it records the steps a user is going through as they draw the path of a new element. The element isn't actually added to the model until the user indicates that they are done.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element being created/added to the model.

recordElementCreation(element) <static>

Records the progressive interactive addition of a new element.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element being created/added to the model.

recordElementRemove(parent, element [, index]) <static>

Records the removal of an existing element from a level or space.

Parameters:

Name	Type	Argument	Description
`parent`	BIM.Level \| BIM.Space		The level or space being deleted from.
`element`	BIM.Element		The element that is about to be removed.
`index`	number	<optional>	The ordinal index of the deleted element in its host.

recordElementRemove(parent, element [, index]) <static>

Records the removal of an existing element from a level or space.

Parameters:

Name	Type	Argument	Description
`parent`	BIM.Level \| BIM.Space		The level or space being deleted from.
`element`	BIM.Element		The element that is about to be removed.
`index`	number	<optional>	The ordinal index of the deleted element in its host.

recordGlobalLocationChange(new_latitude, new_longitude [, new_timezone]) <static>

Sets the global location after recording its current values and creating/updating an undo record.

NOTE: In order to efficiently record the change in value, you must use this method to actually set the new location. If you change the global location value before calling this method, its current values will be the same as the new values, so there will effectively be no change to record.

This method can be called multiple times during an interactive action. If the previous entry in the undo queue is a global location change within the current time limit, then that entry will be updated with the new location instead of creating and adding a new entry.

Parameters:

Name	Type	Argument	Description
`new_latitude`	number		The new latitude angle in degrees (-90 to 90).
`new_longitude`	number		The new longitude angle in degrees (-180 to 180).
`new_timezone`	number	<optional>	The new timezone in decimal hours (-12 to +13), will be computed if not given.

recordGlobalStateChange(property, oldValue, newValue) <static>

Records a change in the value of the given PD.GlobalState property.

Parameters:

Name	Type	Description
`property`	string	The `PD.GlobalState` property that changed.
`oldValue`	any	The previous value before the change.
`newValue`	any	The current value after the change.

recordJunctionAdd(element, junction [, contourIndex] [, junctionIndex]) <static>

Records the addition of a new junction to an element path.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element being added to.
`junction`	BIM.Junction		The junction that was just added.
`contourIndex`	number	<optional>	The ordinal index of the element path contour.
`junctionIndex`	number	<optional>	The ordinal index of the junction in the contour.

recordJunctionAdd(element, junction [, contour_index] [, junction_index]) <static>

Records the addition of a new junction to an element path.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element being added to.
`junction`	BIM.Junction		The junction that was just added.
`contour_index`	number	<optional>	The ordinal index of the element path contour.
`junction_index`	number	<optional>	The ordinal index of the junction in the contour.

recordJunctionFlagsChange(selection, id) <static>

Stores junction flag value changes in the selection set.

__NOTE: __ This action is slightly different from other undo actions in that, to work, it requires you to call it at least twice with the same selection id number. The first call should occur before changes are made and creates the undo action with each junction's old flag values. The second call should occur after changes are made to store each junction's new flag values.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`id`	number	The numeric id of the selection.

recordJunctionFlagsChange(selection, id) <static>

Stores junction flag value changes in the selection set.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`id`	number	The numeric id of the selection.

recordJunctionRemove(element, junction [, contourIndex] [, junctionIndex]) <static>

Records the removal of an existing junction from an element path.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element being deleted from.
`junction`	BIM.Junction		The junction that is about to be deleted.
`contourIndex`	number	<optional>	The ordinal index of the element path contour.
`junctionIndex`	number	<optional>	The ordinal index of the junction in the contour.

recordJunctionRemove(element, junction [, contour_index] [, junction_index]) <static>

Records the removal of an existing junction from an element path.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element being deleted from.
`junction`	BIM.Junction		The junction that is about to be deleted.
`contour_index`	number	<optional>	The ordinal index of the element path contour.
`junction_index`	number	<optional>	The ordinal index of the junction in the contour.

recordLevelAdd(structure, level [, index]) <static>

Records the addition of a new level to a structure.

Parameters:

Name	Type	Argument	Description
`structure`	BIM.Structure		The structure being added to.
`level`	BIM.Level		The level that was just added.
`index`	number	<optional>	The ordinal index of the added level in the structure.

recordLevelAdd(structure, level [, index]) <static>

Records the addition of a new level to a structure.

Parameters:

Name	Type	Argument	Description
`structure`	BIM.Element		The structure being added to.
`level`	BIM.Level		The level that was just added.
`index`	number	<optional>	The ordinal index of the added level in the structure.

recordLevelHeights(structure) <static>

Records the order and heights of each level in the given structure.

Parameters:

Name	Type	Description
`structure`	BIM.Structure	The structure to record level data for.

recordLevelHeights(structure) <static>

Records the order and heights of each level in the given structure.

Parameters:

Name	Type	Description
`structure`	BIM.Structure	The structure to record level data for.

recordLevelRemove(structure, level [, index]) <static>

Records the removal of a level from a structure.

Parameters:

Name	Type	Argument	Description
`structure`	BIM.Structure		The structure being removed from.
`level`	BIM.Level		The level that is about to be removed.
`index`	number	<optional>	The ordinal index of the level in the structure.

recordLevelRemove(structure, level [, index]) <static>

Records the removal of a level from a structure.

Parameters:

Name	Type	Argument	Description
`structure`	BIM.Element		The structure being removed from.
`level`	BIM.Level		The level that is about to be removed.
`index`	number	<optional>	The ordinal index of the level in the structure.

recordMergeToCompositeElement(parent, children, level) <static>

Records the merging of child roof elements into a parent composite roof element.

Parameters:

Name	Type	Description
`parent`	BIM.Roof.Composite	The parent composite roof.
`children`	Array.<BIM.Roof>	The list of child roofs merged into the parent.
`level`	BIM.Level	The level the children came from.

recordMergeToCompositeElement(parent, children, level) <static>

Records the merging of child roof elements into a parent composite roof element.

Parameters:

Name	Type	Description
`parent`	BIM.Roof.Composite	The parent composite roof.
`children`	Array.<BIM.Roof>	The list of child roofs merged into the parent.
`level`	BIM.Level	The level the children came from.

recordNewProject(oldProject, newProject) <static>

Records the creation of a new model project.

Parameters:

Name	Type	Description
`oldProject`	BIM.Project	The old project.
`newProject`	BIM.Project	The new project.

recordNewProject(old_project, new_project) <static>

Records the creation of a new model project.

Parameters:

Name	Type	Description
`old_project`	BIM.Project	The old project.
`new_project`	BIM.Project	The new project.

recordParameterChange(host, param, group, oldValue, newValue) <static>

Records changes to a dynamic parameter of a host object.

This method can be called multiple times during an interactive action. If the previous entry in the undo queue is a change of the same parameter on the same host, within the current time limit, then that entry will be updated with the new value instead of creating and adding a new entry.

NOTE: Dynamic parameters do not have a 'setAndRecord' method as undo/redo is handled internally by the parameters themselves. You must therefore use the PD.Parameter#setValueOnHost or PD.Parameter#setValueOnHostIfDifferent methods on the parameter itself.

Parameters:

Name	Type	Description
`host`	object	The element/object that hosts the dynamic parameter group.
`param`	PD.Parameter	The dynamic parameter that changed.
`group`	PD.ParamGroup	The parameter group that this dynamic parameter belongs to.
`oldValue`	any	The previous value before the change.
`newValue`	any	The current value after the change.

recordPasteParameters(element, component, new_params) <static>

Records multiple parameter changes, typically due to copy/pasting parameter data.

This method can be called multiple times during an interactive action. If the previous entry in the undo queue is a change of the same parameters on the same element and component, within the current time limit, then that entry will be updated with the new parameter values instead of creating and adding a new entry.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element that hosts the component or parameters.
`component`	BIM.Component	The component that hosts the parameters, if any.
`new_params`	object	Typically a JSON data object.

recordPathColorChange(element, oldColor) <static>

Records changes to the path fill color value of an element.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element whose path color changed.
`oldColor`	any	The previous color value before the change.

recordPathColorChange(element, old_color) <static>

Records changes to the path fill color value of an element.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element whose path color changed.
`old_color`	any	The previous color value before the change.

recordPathFlagsChange(path, oldFlags) <static>

Records the current flags in an element path.

Parameters:

Name	Type	Description
`path`	BIM.Path	The path to record the current flags of.
`oldFlags`	number	The previous flags value.

recordPathMove(element [, all]) <static>

Records the interactive movement of point(s) within an element path.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element whose path point(s) moved.
`all`	boolean	<optional>	Whether or not the whole path was moved.

recordPathMove(element [, all]) <static>

Records the interactive movement of point(s) within an element path.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element whose path point(s) moved.
`all`	boolean	<optional>	Whether or not the whole path was moved.

recordPathMoveIfSelectionChanged(element [, all]) <static>

Records the manual movement of point(s) within an element path, only if selection changed.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element whose path moved.
`all`	boolean	<optional>	Whether or not the whole path was moved.

recordPathMoveIfSelectionChanged(element [, all]) <static>

Records the manual movement of point(s) within an element path, only if selection changed.

Parameters:

Name	Type	Argument	Description
`element`	BIM.Element		The element whose path moved.
`all`	boolean	<optional>	Whether or not the whole path was moved.

recordPathState(path [, actionName]) <static>

Records the current state of an element path.

Parameters:

Name	Type	Argument	Description
`path`	BIM.Path		The path to record the current state of.
`actionName`	string	<optional>	The an optional name for the undo record, defaults to 'Modify Path'.

recordProjectDataAddItem(map, item, type) <static>

Records the addition of a new shared project data item.

Parameters:

Name	Type	Description
`map`	Map	The map the data item was added to.
`item`	object	The item that was added.
`type`	string	The type of data item.

recordProjectDataAddItem(map, item, type) <static>

Records the addition of a new shared project data item.

Parameters:

Name	Type	Description
`map`	Map	The map the data item was added to.
`item`	object	The item that was added.
`type`	string	The type of data item.

recordProjectDataDeleteItem(map, item, type) <static>

Records the deletion of a new shared project data item.

Parameters:

Name	Type	Description
`map`	Map	The map the data item was deleted from.
`item`	object	The item that was deleted.
`type`	string	The type of data item.

recordProjectDataDeleteItem(map, item, type) <static>

Records the deletion of a new shared project data item.

Parameters:

Name	Type	Description
`map`	Map	The map the data item was deleted from.
`item`	object	The item that was deleted.
`type`	string	The type of data item.

recordPropertyChange(host, property, oldValue, newValue [, callback]) <static>

Records a change to the given property of a host object.

This method can be called multiple times during an ongoing operation. If the last entry in the undo queue is of the same type and for the same host and property, within the current time limit, then the last undo action itself will be updated to reflect the new changes. If the last undo action is of a different type, for a different host or property, or occurred prior to the time limit, a new undo entry of this type will be added.

Parameters:

Name	Type	Argument	Description
`host`	object		The element/object with the property.
`property`	string		The name of the property that changed.
`oldValue`	any		The previous value before the change.
`newValue`	any		The current value after the change.
`callback`	function \| string	<optional>	An optional callback function or method name to invoke on each change.

recordRectMeshEditIfSelectionChanged(mesh, originalExtents) <static>

Records the manual editing of a rectangular mesh, only if selection changed.

This method can be called multiple times during an ongoing operation. If the last item in the undo queue is of the same type, modified the same mesh and it is within 4sec of the last undo action, then the last undo action itself will be updated to reflect the new changes. If the last undo action is of a different type, has a different id value or occurred more than 4sec ago, a new undo entry of this type will be added.

Parameters:

Name	Type	Description
`mesh`	PD.RectMesh	The rectangular mesh being edited.
`originalExtents`	THREE.Box3	The original bounding box extents before edit.

recordRectMeshEditIfSelectionChanged(mesh, original_extents) <static>

Records the manual editing of a rectangular mesh, only if selection changed.

Parameters:

Name	Type	Description
`mesh`	PD.RectMesh	The rectangular mesh being edited.
`original_extents`	THREE.Box3	The original bounding box extents before edit.

recordSelectionMove(selection, vector) <static>

Records the manual movement of a selection set.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`vector`	THREE.Vector3	The vector to move the selection by.

recordSelectionMove(selection, vector) <static>

Records the manual movement of a selection set.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`vector`	THREE.Vector3	The vector to move the selection by.

recordSelectionMoveIfChanged(selection, vector, id) <static>

Records the interactive movement of a selection set, updating previous if id is the same.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`vector`	THREE.Vector3	The relative vector to move the selection by.
`id`	number	The numeric id of the move sequence.

recordSelectionMoveIfChanged(selection, vector, id) <static>

Records the interactive movement of a selection set, updating previous if id is the same.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`vector`	THREE.Vector3	The relative vector to move the selection by.
`id`	number	The numeric id of the move sequence.

recordSelectionRotateIfChanged(selection, quaternion, refPoint, id) <static>

Records the interactive rotation of a selection set, updating previous if id is the same.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`quaternion`	THREE.Quaternion	The rotation quaternion.
`refPoint`	THREE.Vector3	The rotation about point.
`id`	number	The numerical id of the sequence.

recordSelectionRotateIfChanged(selection, quaternion, refPoint, id) <static>

Records the interactive rotation of a selection set, updating previous if id is the same.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`quaternion`	THREE.Quaternion	The rotation quaternion.
`refPoint`	THREE.Vector3	The rotation about point.
`id`	number	The numerical id of the sequence.

recordSelectionTransformIfChanged(selection, matrix, refPoint, id) <static>

Records the interactive transformation of a selection set, updating previous if id is the same.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`matrix`	THREE.Matrix4	The transformation matrix.
`refPoint`	THREE.Vector3	The rotation about point.
`id`	number	The numerical id of the sequence.

recordSelectionTransformIfChanged(selection, matrix, refPoint, id) <static>

Records the interactive transformation of a selection set, updating previous if id is the same.

Parameters:

Name	Type	Description
`selection`	PD.SelectionSet	The extended selection set, if any.
`matrix`	THREE.Matrix4	The transformation matrix.
`refPoint`	THREE.Vector3	The rotation about point.
`id`	number	The numerical id of the sequence.

recordSeparateCompositeElement(parent, level) <static>

Records the separation of child roof elements from a parent composite roof element.

Parameters:

Name	Type	Description
`parent`	BIM.Roof.Composite	The parent composite roof.
`level`	BIM.Level	The level the children came from.

recordSeparateCompositeElement(parent, level) <static>

Records the separation of child roof elements from a parent composite roof element.

Parameters:

Name	Type	Description
`parent`	BIM.Roof.Composite	The parent composite roof.
`level`	BIM.Level	The level the children came from.

recordStructureRemove(project, structure [, index]) <static>

Records the removal of a structure from a project.

Parameters:

Name	Type	Argument	Description
`project`	BIM.Project		The project the structure belongs to.
`structure`	BIM.Structure		The structure being removed from.
`index`	number	<optional>	The ordinal index of the level in the structure.

recordTransformOriginChange(origin, id) <static>

Stores changes to the position of the transform origin.

Parameters:

Name	Type	Description
`origin`	PD.Point	The transform origin to store.
`id`	number	The numeric id of the selection.

recordTransformOriginChange(origin, id) <static>

Stores changes to the position of the transform origin.

Parameters:

Name	Type	Description
`origin`	PD.Point	The transform origin to store.
`id`	number	The numeric id of the selection.

recordTypeComponentChange(element, new_type) <static>

Records an element type component change.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element who's type changed.
`new_type`	BIM.Component	The new type being changed to.

recordTypeComponentChange(element, new_type) <static>

Records an element type component change.

Parameters:

Name	Type	Description
`element`	BIM.Element	The element who's type changed.
`new_type`	BIM.Component	The new type being changed to.

recordViewAdd(project, view) <static>

Records the adding of a new stored view to the project.

Parameters:

Name	Type	Description
`project`	BIM.Project	The project the view was added to.
`view`	BIM.DrawingView	The view that was just added.

recordViewAdd(project, view) <static>

Records the adding of a new stored view to the project.

Parameters:

Name	Type	Description
`project`	BIM.Project	The project the view was added to.
`view`	BIM.DrawingView	The view that was just added.

recordViewData(view) <static>

Records a stored view name and type prior to it being edited/changed.

Parameters:

Name	Type	Description
`view`	BIM.DrawingView	The view that is about to be edited.

recordViewData(view) <static>

Records a stored view name and type prior to it being edited/changed.

Parameters:

Name	Type	Description
`view`	BIM.DrawingView	The view that is about to be edited.

recordViewUpdate(view) <static>

Records a stored view update record prior to it being updated.

Parameters:

Name	Type	Description
`view`	BIM.DrawingView	The view that is about to be updated.

recordViewUpdate(view) <static>

Records a stored view update record prior to it being updated.

Parameters:

Name	Type	Description
`view`	BIM.DrawingView	The view that is about to be updated.

recordViewsList(project) <static>

Records a new stored view list record.

Parameters:

Name	Type	Description
`project`	BIM.Project	The project whose view list is recorded.

recordViewsList(project) <static>

Records a new stored view list record.

Parameters:

Name	Type	Description
`project`	BIM.Project	The project whose view list is recorded.

redo() <static>

Redoes the last undo action, if available.

setAndRecordGlobalLocationChange(new_latitude, new_longitude [, new_timezone]) <static>

Sets the global location after recording its current values and creating/updating an undo record.

Parameters:

Name	Type	Argument	Description
`new_latitude`	number		The new latitude angle in degrees (-90 to 90).
`new_longitude`	number		The new longitude angle in degrees (-180 to 180).
`new_timezone`	number	<optional>	The new timezone in decimal hours (-12 to +13), will be computed if not given.

setAndRecordPropertyChange(host, property, newValue [, callback]) <static>

Sets the value of the given property on a host object after recording its current value and creating/updating an undo record.

Use this method instead of PD.GlobalUndo.recordPropertyChange if you do not want to manage the recording of the existing value before setting the new value and recording the change.

NOTE: In order to efficiently record the change in value, you must use this method to actually set the new value. If you change the host property value before calling this method, its current value will be the same as the new value, so there will effectively be no value change to record.

Parameters:

Name	Type	Argument	Description
`host`	object		The element/object with the property.
`property`	string		The name of the property that changed.
`newValue`	any		The current value after the change.
`callback`	function \| string	<optional>	An optional callback function or method name to invoke on each change.

setDateTime(day, time) <static>

Sets the global date/time and creates and undo/redo record.

NOTE: In order to efficiently record the change in value, you must rely on this method to actually set the new date/time. If you change the global date and/or time before calling this method, their current values will be the same as the new values, so there will effectively be no change to record.

This method can be called multiple times during an interactive action. If the previous entry in the undo queue is a global date/time change within the current time limit, then that entry will be updated with the new date/time instead of creating and adding a new entry.

You can alternatively us the PD.GlobalActions.setDateTime method to set the date/time without adding an undo/redo entry.

Parameters:

Name	Type	Description
`day`	number	The ordinal day of the year (0 to 365).
`time`	number	The time of day in decimal hours (0 to 24).

Returns:

Returns true if the date or time changed, otherwise false.

Type: boolean

setDayOfYear(day) <static>

Sets the current day of the year.

This method first checks if the new day of the year is at least 1 day from the current day of the year before applying the change. Any less than this is no meaningful difference in the time of day.

You can alternatively use the PD.GlobalActions.setDayOfYear method to set the day without adding an undo/redo entry.

Parameters:

Name	Type	Description
`day`	number	The ordinal day of the year (0 to 365).

Returns:

Returns true if the day changed, otherwise false.

Type: boolean

setLatitude(latitude) <static>

Sets the location latitude angle and creates an undo/redo entry.

This method first checks if the new latitude is at least 1e-6 degrees from the current latitude before applying the change. This represents a threshold distance of around 100mm (4") on the Earth's surface, below which there is no meaningful difference in location.

You can alternatively use the PD.GlobalActions.setLatitude method to set the location without adding an undo/redo entry.

Parameters:

Name	Type	Description
`latitude`	number	The new geographic latitude above the equator, in decimal degrees (-90 to 90).

Returns:

Returns true if the location changed, otherwise false.

Type: boolean

setLocation(latitude, longitude [, timezone]) <static>

Sets the global site location and creates and undo/redo record.

NOTE: In order to efficiently record the change in value, you must rely on this method to actually set the new location. If you change the global location value before calling this method, its current values will be the same as the new values, so there will effectively be no change to record.

You can alternatively us the PD.GlobalActions.setLocation method to set the location without adding an undo/redo entry.

Parameters:

Name	Type	Argument	Description
`latitude`	number		The new geographic latitude above the equator, in decimal degrees (-90 to 90).
`longitude`	number		The new geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
`timezone`	number	<optional>	The new timezone in decimal hours (-12 to +13), will be computed if not given.

Returns:

Returns true if the location changed, otherwise false.

Type: boolean

setLongitude(longitude) <static>

Sets the location longitude angle and creates an undo/redo entry.

This method first checks if the new longitude is at least 1e-6 degrees from the current longitude before applying the change. This represents a threshold distance of around 100mm (4") on the Earth's surface, below which there is no meaningful difference in location.

You can alternatively use the PD.GlobalActions.setLongitude method to set the location without adding an undo/redo entry.

Parameters:

Name	Type	Description
`longitude`	number	The new geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).

Returns:

Returns true if the location changed, otherwise false.

Type: boolean

setTimeOfDay(time) <static>

Sets the current hour of the day and creates an undo/redo entry.

This method first checks if the new time is at least 1 second from the current time before applying the change. Any less than this is no meaningful difference in the time of day.

You can alternatively use the PD.GlobalActions.setTimeOfDay method to set the time without adding an undo/redo entry.

Parameters:

Name	Type	Description
`time`	number	The time of day in decimal hours (0 to 24).

Returns:

Returns true if the time of day changed, otherwise false.

Type: boolean

setTimeZone(timezone) <static>

Sets the location timezone offset and creates an undo/redo entry.

This method first checks if the new timezone is at least 1 minute from the current timezone before applying the change. Any less than this is no meaningful difference in location.

You can alternatively use the PD.GlobalActions.setTimeZone method to set the location without adding an undo/redo entry.

Parameters:

Name	Type	Description
`timezone`	number	The new timezone in decimal hours (-12 to +13).

Returns:

Returns true if the location changed, otherwise false.

Type: boolean

shallowDiff(refObj, newObj) <static>

Compares two objects and returns the differences, or null if the same.

This method considers the reference object to be the source of truth, so only check the properties that it contains. This means that the new object can contain any number of other properties and/or methods which will not be checked.

If there are changes, the returned data object will contain the keys for each changed property with the stored value being an {_OLD,_NEW} object.

Parameters:

Name	Type	Description
`refObj`	object	The reference object with the original data.
`newObj`	object	The new object with updated or changed data.

Returns:

Returns an object with changed fields, or null if no changes.

Type: object | null

undo() <static>

Undoes the last action, if available.

updateGlobalState() <static>

Updates the canUndo and canRedo properties in global state.

It also updates the undo and redo lists to support the UI displaying the actual undo/redo stack.

This allows a front-end framework to update the state of undo/redo buttons or menu items within the UI as state changes occur.

updateModel() <static>

A placeholder that the host application can reassign or override in order to update its internal model when an entity's parameters are changed.

Call this method after your undo/redo action makes any significant changes that affect the host application's internal model.

updateSelectionAndView() <static>

Updates the current selection set and generates a redraw.

Call this method if your undo/redo action affects only what is selected and does not change any geometry within the model.

updateSelectionAndView() <static>

Updates the current selection set and generates a redraw.

Call this method if your undo/redo action affects only what is selected and does not change any geometry within the model.