ptolemy.kernel.undo
Class UndoStackAttribute

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.kernel.util.SingletonAttribute
              ptolemy.kernel.undo.UndoStackAttribute

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable, Singleton

Direct Known Subclasses:

GTFrameTools.DelegatedUndoStackAttribute

public class UndoStackAttribute
extends SingletonAttribute

This attribute holds the undo/redo information for a model. This attribute is not persistent, so undo/redo information disappears when the model is closed. It is also a singleton, meaning that it will replace any previous attribute that has the same name and is an instance of the same base class, SingletonAttribute.

Two stacks of information are maintained - one for undo information and one for redo information. Normally, a push onto this stack puts the undo information in the undo stack. However, if the push occurs during the execution of an undo, then the information is put on the redo stack. The entries on the stack implement the UndoAction interface.

NOTE: the information in the redo stack is emptied when a new undo action is pushed onto the undo stack that was not the result of a redo being requested. This situation arises when a user requests a series of undo and redo operations, and then performs some normal undoable action. At this point the information in the redo stack is not relevant to the state of the model and so must be cleared.

Since:

Ptolemy II 3.1

Version:

$Id: UndoStackAttribute.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Neil Smyth and Edward A. Lee

See Also:

UndoAction, Serialized Form

Accepted Rating:

Red (cxh)

Proposed Rating:

Yellow (eal)

Nested Class Summary

private static class

UndoStackAttribute.MergeUndoActions An undo or redo action on the stack.

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

private int	_inRedo
private int	_inUndo
private java.util.Stack	_redoEntries
private java.util.Stack	_undoEntries

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Constructor Summary

UndoStackAttribute(NamedObj container, java.lang.String name)
Construct an attribute with the given name contained by the specified container.

Method Summary

static UndoStackAttribute	getUndoInfo(NamedObj object) Get the UndoStackAttribute associated with the given object.
void	mergeTopTwo() Merge the top two undo entries into a single action, unless we are in either a redo or an undo, in which case the merge happens automatically and need not be explicitly requested by the client.
void	push(UndoAction action) Push an action to the undo stack, or if we are executing an undo, onto the redo stack.
void	redo() Remove the top redo action and execute it.
void	undo() Remove the top undo action and execute it.

Methods inherited from class ptolemy.kernel.util.SingletonAttribute

setContainer

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, clone, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _description, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_inRedo

private int _inRedo

_inUndo

private int _inUndo

_redoEntries

private java.util.Stack _redoEntries

_undoEntries

private java.util.Stack _undoEntries

Constructor Detail

UndoStackAttribute

public UndoStackAttribute(NamedObj container,
                          java.lang.String name)
                   throws IllegalActionException,
                          NameDuplicationException

Construct an attribute with the given name contained by the specified container. The container argument must not be null, or a NullPointerException will be thrown. This attribute will use the workspace of the container for synchronization and version counts. If the name argument is null, then the name is set to the empty string. The object is added to the directory of the workspace if the container is null. Increment the version of the workspace.

Parameters:

container - The container.

name - The name of this attribute.

Throws:

IllegalActionException - If the attribute is not of an acceptable class for the container, or if the name contains a period.

NameDuplicationException - If the name coincides with an attribute already in the container.

Method Detail

getUndoInfo

public static UndoStackAttribute getUndoInfo(NamedObj object)

Get the UndoStackAttribute associated with the given object. This is done by searching up the containment hierarchy until such an attribute is found. If no such attribute is found, then create and attach a new one to the top level. This method gets read access on the workspace associated with the specified object.

Parameters:

object - The model for which an undo stack is required (must not be null or a NullPointerException will the thrown).

Returns:

The current undo stack attribute if there is one, or a new one.

mergeTopTwo

public void mergeTopTwo()

Merge the top two undo entries into a single action, unless we are in either a redo or an undo, in which case the merge happens automatically and need not be explicitly requested by the client. If there are fewer than two entries on the stack, do nothing. Note that when two entries are merged, the one on the top of the stack becomes the first one executed and the one below that on the stack becomes the second one executed. This method gets write access on the workspace.

push

public void push(UndoAction action)

Push an action to the undo stack, or if we are executing an undo, onto the redo stack. This method gets write access on the workspace.

Parameters:

action - The undo action.

redo

public void redo()
          throws java.lang.Exception

Remove the top redo action and execute it. If there are no redo entries, do nothing. This method gets write access on the workspace.

Throws:

java.lang.Exception - If something goes wrong.

undo

public void undo()
          throws java.lang.Exception

Remove the top undo action and execute it. If there are no undo entries, do nothing. This method gets write access on the workspace.

Throws:

java.lang.Exception - If something goes wrong.