Package org.eclipse.gef.commands
Class CommandStack
- java.lang.Object
-
- org.eclipse.gef.commands.CommandStack
-
public class CommandStack extends java.lang.Object
An implementation of a command stack. A stack manages the executing, undoing, and redoing ofCommands
. Executed commands are pushed onto a a stack for undoing later. Commands which are undone are pushed onto a redo stack. Whenever a new command is executed, the redo stack is flushed.A CommandStack contains a dirty property. This property can be used to determine when persisting changes is required. The stack is dirty whenever the last executed or redone command is different than the command that was at the top of the undo stack when
markSaveLocation()
was last called. Initially, the undo stack is empty, and not dirty.
-
-
Field Summary
Fields Modifier and Type Field Description protected java.util.List
listeners
Deprecated.This field should not be referenced, usenotifyListeners()
static int
POST_EXECUTE
Constant indicating notification after a command has been executed.static int
POST_FLUSH
Constant indicating notification after flushing the stack.static int
POST_MARK_SAVE
Constant indicating notification after marking the save location of the stack.static int
POST_MASK
A bit-mask indicating notification after the command stack has changed.static int
POST_REDO
Constant indicating notification after a command has been redone.static int
POST_UNDO
Constant indicating notification after a command has been undone.static int
PRE_EXECUTE
Constant indicating notification prior to executing a command.static int
PRE_FLUSH
Constant indicating notification prior to flushing the stack.static int
PRE_MARK_SAVE
Constant indicating notification prior to marking the save location of the stack.static int
PRE_MASK
A bit-mask indicating notification before the command stack is changed.static int
PRE_REDO
Constant indicating notification prior to redoing a command.static int
PRE_UNDO
Constant indicating notification prior to undoing a command.
-
Constructor Summary
Constructors Constructor Description CommandStack()
Constructs a new command stack.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addCommandStackEventListener(CommandStackEventListener listener)
Appends the listener to the list of command stack listeners.void
addCommandStackListener(CommandStackListener listener)
Deprecated.boolean
canRedo()
boolean
canUndo()
void
dispose()
This willdispose()
all the commands in both the undo and redo stack.void
execute(Command command)
Executes the specified Command if possible.void
flush()
Flushes the entire stack and resets the save location to zero.java.lang.Object[]
getCommands()
Command
getRedoCommand()
Peeks at the top of the redo stack.Command
getUndoCommand()
Peeks at the top of the undo stack.int
getUndoLimit()
Returns the undo limit.boolean
isDirty()
Returns true if the stack is dirty.void
markSaveLocation()
Marks the last executed or redone Command as the point at which the changes were saved.protected void
notifyListeners()
Deprecated.UsenotifyListeners(Command, int)
instead.protected void
notifyListeners(Command command, int state)
Notifies command stack event listeners that the command stack has changed to the specified state.void
redo()
Calls redo on the Command at the top of the redo stack, and pushes that Command onto the undo stack.void
removeCommandStackEventListener(CommandStackEventListener listener)
Removes the first occurrence of the specified listener.void
removeCommandStackListener(CommandStackListener listener)
Deprecated.UseCommandStackEventListener
instead.void
setUndoLimit(int undoLimit)
Sets the undo limit.void
undo()
Undoes the most recently executed (or redone) Command.
-
-
-
Field Detail
-
POST_EXECUTE
public static final int POST_EXECUTE
Constant indicating notification after a command has been executed.- See Also:
- Constant Field Values
-
POST_REDO
public static final int POST_REDO
Constant indicating notification after a command has been redone.- See Also:
- Constant Field Values
-
POST_UNDO
public static final int POST_UNDO
Constant indicating notification after a command has been undone.- See Also:
- Constant Field Values
-
POST_FLUSH
public static final int POST_FLUSH
Constant indicating notification after flushing the stack.- Since:
- 3.11
- See Also:
- Constant Field Values
-
POST_MARK_SAVE
public static final int POST_MARK_SAVE
Constant indicating notification after marking the save location of the stack.- Since:
- 3.11
- See Also:
- Constant Field Values
-
POST_MASK
public static final int POST_MASK
A bit-mask indicating notification after the command stack has changed. This includes after a command has been undone, redone, or executed, as well as after it has been flushed or the save location has been marked.Usage
if ((commandStackEvent.getDetail() & CommandStack.POST_MASK) != 0) { // Do something, like: stopBatchingChanges(); }
-
PRE_EXECUTE
public static final int PRE_EXECUTE
Constant indicating notification prior to executing a command.- See Also:
- Constant Field Values
-
PRE_REDO
public static final int PRE_REDO
Constant indicating notification prior to redoing a command.- See Also:
- Constant Field Values
-
PRE_UNDO
public static final int PRE_UNDO
Constant indicating notification prior to undoing a command.- See Also:
- Constant Field Values
-
PRE_FLUSH
public static final int PRE_FLUSH
Constant indicating notification prior to flushing the stack.- Since:
- 3.11
- See Also:
- Constant Field Values
-
PRE_MARK_SAVE
public static final int PRE_MARK_SAVE
Constant indicating notification prior to marking the save location of the stack.- Since:
- 3.11
- See Also:
- Constant Field Values
-
PRE_MASK
public static final int PRE_MASK
A bit-mask indicating notification before the command stack is changed. This includes before a command has been undone, redone, or executed, and before the stack is being flushed or the save location is marked.Usage
if ((commandStackEvent.getDetail() & CommandStack.PRE_MASK) != 0) { // Do something, like: startBatchingChanges(); }
- Since:
- 3.7 Had package visibility before.
-
listeners
protected java.util.List listeners
Deprecated.This field should not be referenced, usenotifyListeners()
The list ofCommandStackListener
s.
-
-
Method Detail
-
addCommandStackEventListener
public void addCommandStackEventListener(CommandStackEventListener listener)
Appends the listener to the list of command stack listeners. Multiple adds result in multiple notifications.- Parameters:
listener
- the event listener- Since:
- 3.1
-
addCommandStackListener
public void addCommandStackListener(CommandStackListener listener)
Deprecated.Appends the listener to the list of command stack listeners. Multiple adds will result in multiple notifications.- Parameters:
listener
- the listener
-
canRedo
public boolean canRedo()
- Returns:
true
if it is appropriate to callredo()
.
-
canUndo
public boolean canUndo()
- Returns:
true
ifundo()
can be called
-
dispose
public void dispose()
This willdispose()
all the commands in both the undo and redo stack. Both stacks will be empty afterwards.
-
execute
public void execute(Command command)
Executes the specified Command if possible. Prior to executing the command, a CommandStackEvent forPRE_EXECUTE
will be fired to event listeners. Similarly, after attempting to execute the command, an event forPOST_EXECUTE
will be fired. If the execution of the command completely normally, stack listeners will receivestackChanged
notification.If the command is
null
or cannot be executed, nothing happens.- Parameters:
command
- the Command to execute- See Also:
CommandStackEventListener
-
flush
public void flush()
Flushes the entire stack and resets the save location to zero. This method might be called when performing "revert to saved".
-
getCommands
public java.lang.Object[] getCommands()
- Returns:
- an array containing all commands in the order they were executed
-
getRedoCommand
public Command getRedoCommand()
Peeks at the top of the redo stack. This is useful for describing to the User what will be redone. The returnedCommand
has a label describing it.- Returns:
- the top of the redo stack, which may be
null
-
getUndoCommand
public Command getUndoCommand()
Peeks at the top of the undo stack. This is useful for describing to the User what will be undone. The returnedCommand
has a label describing it.- Returns:
- the top of the undo stack, which may be
null
-
getUndoLimit
public int getUndoLimit()
Returns the undo limit. The undo limit is the maximum number of atomic operations that the User can undo.-1
is used to indicate no limit.- Returns:
- the undo limit
-
isDirty
public boolean isDirty()
Returns true if the stack is dirty. The stack is dirty whenever the last executed or redone command is different than the command that was at the top of the undo stack whenmarkSaveLocation()
was last called.- Returns:
true
if the stack is dirty
-
markSaveLocation
public void markSaveLocation()
Marks the last executed or redone Command as the point at which the changes were saved. Calculation ofisDirty()
will be based on this checkpoint.
-
notifyListeners
protected void notifyListeners()
Deprecated.UsenotifyListeners(Command, int)
instead.Sends notification to allCommandStackListener
s.
-
notifyListeners
protected void notifyListeners(Command command, int state)
Notifies command stack event listeners that the command stack has changed to the specified state.- Parameters:
command
- the commandstate
- the current stack state- Since:
- 3.2
-
redo
public void redo()
Calls redo on the Command at the top of the redo stack, and pushes that Command onto the undo stack. This method should only be called whencanUndo()
returnstrue
.
-
removeCommandStackEventListener
public void removeCommandStackEventListener(CommandStackEventListener listener)
Removes the first occurrence of the specified listener.- Parameters:
listener
- the listener
-
removeCommandStackListener
public void removeCommandStackListener(CommandStackListener listener)
Deprecated.UseCommandStackEventListener
instead.Removes the first occurrence of the specified listener.- Parameters:
listener
- the listener
-
setUndoLimit
public void setUndoLimit(int undoLimit)
Sets the undo limit. The undo limit is the maximum number of atomic operations that the User can undo.-1
is used to indicate no limit.- Parameters:
undoLimit
- the undo limit
-
undo
public void undo()
Undoes the most recently executed (or redone) Command. The Command is popped from the undo stack to and pushed onto the redo stack. This method should only be called whencanUndo()
returnstrue
.
-
-