The following example shows how to use this class.
* *
* Foo foo; // class Foo implements {@link StateEditable}
* StateEdit edit;
*
* edit = new StateEdit(foo, "Name Change");
* foo.setName("Jane Doe");
* edit.end();
* undoManager.addEdit(edit);
*
*
* If Foo’s implementation of {@link
* StateEditable} considers the name as part of the editable state,
* the user can now choose “Undo Name Change” or
* “Redo Name Change” from the respective menu. No
* further undo support is needed from the application.
The following explains what happens in the example.
* *StateEdit is created, the associated
* {@link StateEditable} gets asked to store its state into a hash
* table, {@link #preState}.StateEdit. The end() method
* does two things.
*
* StateEdit now removes
* any entries from {@link #preState} and {@link #postState} that have
* the same key, and whose values are equal. Equality is determined
* by invoking the equals method inherited from
* {@link java.lang.Object}.StateEdit,
* the edited object is asked to {@linkplain StateEditable#restoreState
* restore its state} from the {@link #preState} table. Similarly,
* when the user chooses to redo the StateEdit,
* the edited object gets asked to restore its state from the {@link
* #postState}.StateEdit.
*/
protected StateEditable object;
/**
* The state of object at the time of constructing
* this StateEdit.
*/
protected Hashtable preState;
/**
* The state of object at the time when {@link #end()}
* was called.
*/
protected Hashtable postState;
/**
* A human-readable name for this edit action.
*/
protected String undoRedoName;
/**
* Constructs a StateEdit, specifying the object whose
* state is being edited.
*
* @param obj the object whose state is being edited by this
* StateEdit.
*/
public StateEdit(StateEditable obj)
{
init(obj, null);
}
/**
* Constructs a StateEdit, specifying the object whose
* state is being edited.
*
* @param obj the object whose state is being edited by this
* StateEdit.
*
* @param name the human-readable name of the editing action.
*/
public StateEdit(StateEditable obj, String name)
{
init(obj, name);
}
/**
* Initializes this StateEdit. The edited object will
* be asked to store its current state into {@link #preState}.
*
* @param obj the object being edited.
*
* @param name the human-readable name of the editing action.
*/
protected void init(StateEditable obj, String name)
{
object = obj;
undoRedoName = name;
preState = new Hashtable();
postState = new Hashtable();
obj.storeState(preState);
}
/**
* Informs this StateEdit that all edits are finished.
* The edited object will be asked to store its state into {@link
* #postState}, and any redundant entries will get removed from
* {@link #preState} and {@link #postState}.
*/
public void end()
{
object.storeState(postState);
removeRedundantState();
}
/**
* Undoes this edit operation. The edited object will be asked to
* {@linkplain StateEditable#restoreState restore its state} from
* {@link #preState}.
*
* @throws CannotUndoException if {@link #canUndo()} returns
* false, for example because this action has already
* been undone.
*/
public void undo()
{
super.undo();
object.restoreState(preState);
}
/**
* Redoes this edit operation. The edited object will be asked to
* {@linkplain StateEditable#restoreState restore its state} from
* {@link #postState}.
*
* @throws CannotRedoException if {@link #canRedo()} returns
* false, for example because this action has not yet
* been undone.
*/
public void redo()
{
super.redo();
object.restoreState(postState);
}
/**
* Returns a human-readable, localized name that describes this
* editing action and can be displayed to the user.
*
* @return the name, or null if no presentation
* name is available.
*/
public String getPresentationName()
{
return undoRedoName;
}
/**
* Removes all redundant entries from the pre- and post-edit state
* hash tables. An entry is considered redundant if it is present
* both before and after the edit, and if the two values are equal.
*/
protected void removeRedundantState()
{
Iterator i = preState.keySet().iterator();
while (i.hasNext())
{
Object key = i.next();
if (postState.containsKey(key))
{
if (preState.get(key).equals(postState.get(key)))
{
i.remove();
postState.remove(key);
}
}
}
}
}