UndoRedo V1.2
by Matthew Ford
2005/06/27

Package au.com.forward.undoRedo

The UndoRedoManager class is the main class for this package, TestUndoRedo is a test application.
Run the jar file to start the test application.

See:
          Description

Interface Summary
ICanBeRolledBack This interface marks an UndoableEdit as being able to roll back the undo/redo tree in the event that it fails or is cancelled.
IDisplayText This interface marks a class as being able to display text using setText(str).
IHaveDescription This interface indicates that the UndoableEdit has a long description that gives more information then the getPresentationName()
 

Class Summary
BranchDefaultMutableTreeNode A mutable tree node to hold Redo branches.
BranchUndoRedo An UndoRedo node that starts a Redo Branch.
BranchUndoRedo.BranchUndoableEdit A dummy UndoableEdit for the BranchUndoRedo node to wrap.
UndoRedo Wrapps an UndoableEdit for adding to the UndoRedoManager tree.
UndoRedoEdit  
UndoRedoManager This is the main class, it handles a tree of undo/redos.
UndoRedoTreeNode  
 

Package au.com.forward.undoRedo Description

The UndoRedoManager class is the main class for this package, TestUndoRedo is a test application.
Run the jar file to start the test application. See below for the Licence Agreement.

The UndoRedoManager provides a complete history of all the user's actions, undos and redos (provided those the users actions notify the UndoRedoManager). Unlike the standard UndoManager, the UndoRedoManager does not truncate the undo history, nor does it throw away the redo history once the user performs another action.

Undo and Redo work in just the same way as the previous Java UndoManager. The Undo actions are available to be undone by calling undo() which undoes one action at a time until you reach the initial point of the application. Calling redo() redoes the last series of undos in the same way the previous Java UndoManager did.

As well as these traditional functions, the UndoReoManager maintains a tree structure which can be displayed to allow the user to select any previous state and undo/redo to that point by selecting that node in the tree and calling processUndoRedoCommand() By default the pressing the Enter key on the selected node performs this action. Use UndoRedoManager.getTree() to get the JTree component to add to your layout.

The UndoRedoManager tree keeps a main trunk of all the actions the user has done or redone and which have not been undone, in the order they were performed, most recent at the top.

As actions are undone they are transferred to a Redo branch from which they can be redone. As actions are redone they add a new undo leaf to the top of the tree. As they are undone a Redo branch is created. Each time a user performs a series of Undo actions, a new Redo branch is created, even if the user has previously retraced this same route. This faithfully records the time order of all the user's actions. As well as the usual undo/redo usage, this tree structure could also be directly applied to recording as user's web browsing history.

To assist in navigation, the UndoRedoManager's tree display shows, for each Redo branch, the deepest level redo on that branch. If the branch is displayed with >> it means some its sub-nodes have been redone. That is the user has retraced some way down that that branch.

A strikethrough node means that die() had been called on the node's UndoableEdit. UndoRedoManager never calls die() but will not undo or redo past a dead node. A dead node effectively isolates the main trunk below that point. If the user tries to undo/redo past a dead node then the unreachable nodes are shown as grey strikethrough. These nodes are not dead, but they cannot be redone/undone because of a dead node higher up.

Insignificant nodes (isSignificant()==false) are displayed in grey but otherwise not handled differently from other nodes. If you want to omit processing insignificant nodes, either extend UnodRedoManager to ignore then in UndoRedoManager.undoableEditHappened() or write you undoableEdit class to do nothing on undo/redo for insignificant edits.

TODO: The UndoRedo class does not implement addEdit() and replaceEdit(), so compound edits need to be collected before calling UndoRedoManager.undoableEditHappened().

Other features

A well as the tree enhancements to undo/redo, the UndoRedoManager supports two other optional features:-
i) Extended descriptions with lazy creation
ii) Type ahead of actions with the ability to rollback the undo/redo tree if they fail or are cancelled.

The optional features are enabled by implement interfaces in your undoableEdit class. The ICanBeRolledBack interface causes the UndoRedoManager to create a framemarker which can be used to roll back the undo/redo tree. The IHaveDescription interface provides access to an extended description of the action. It uses a callback so you can defer creating the description until it is requested. To display the descriptions just add the UndoRedoManager to your layout. The UndoRedoManager extends JSplitPane and displays the tree on the left and the description on the right. You can also get the display text component separately or supply your own.

Licence Agreement

UndoRedo Package
Copyright (c)2005 Forward Computing and Control Pty. Ltd.
NSW. Australia,  www.forward.com.au
All rights reserved.

Redistribution of the source of this package, with or without
modification, is NOT permitted.

Redistribution of the compiled java .class files of this package, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions in compiled java .class form must reproduce the above
   copyright notice, this list of conditions and the following disclaimer
   in the documentation and/or other materials provided with the distribution.

2. If the software is modified, the compiled java .class distribution must
   include, in the documentation and/or other materials provided with the 
   distribution, a statement that the software has been modified and
   identify the person who was responsable for the modifications.  

3. Neither the name of the author nor Forward Computing and Control may be 
   used to endorse or promote products derived from this software
   without specific prior written permission.

4.  All advertising materials mentioning features or use of this
    software must display the following acknowledgment: 
    "This product includes software developed by Matthew Ford
     and Forward Computing and Control Pty. Ltd. 
    (http://www.forward.com.au)."


THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


©2005, Forward Computing and Control Pty. Ltd
ACN 003 669 994   NSW Australia
All Rights Reserved.