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 of `Commands`. 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
`protected java.util.List` `listeners` Deprecated. This field should not be referenced, use `notifyListeners()`
`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 and Description
`CommandStack()` Constructs a new command stack.

### Method Summary

Methods
`void` `addCommandStackEventListener(CommandStackEventListener listener)` Appends the listener to the list of command stack listeners.
`void` `addCommandStackListener(CommandStackListener listener)` Deprecated. Use `addCommandStackEventListener(CommandStackEventListener)` instead.
`boolean` `canRedo()`
`boolean` `canUndo()`
`void` `dispose()` This will `dispose()` 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. Use `notifyListeners(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. Use `CommandStackEventListener` instead.
`void` `setUndoLimit(int undoLimit)` Sets the undo limit.
`void` `undo()` Undoes the most recently executed (or redone) Command.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### 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, use `notifyListeners()`
The list of `CommandStackListener`s.

### Constructor Detail

#### CommandStack

    public CommandStack()

Constructs a new command stack. By default, there is no undo limit, and isDirty() will return `false`.

### 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. Use `addCommandStackEventListener(CommandStackEventListener)` instead.
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 call `redo()`.

#### canUndo

    public boolean canUndo()

Returns:
  `true` if `undo()` can be called

#### dispose

    public void dispose()

This will `dispose()` 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 for `PRE_EXECUTE` will be fired to event listeners. Similarly, after attempting to execute the command, an event for `POST_EXECUTE` will be fired. If the execution of the command completely normally, stack listeners will receive `stackChanged` 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 returned `Command` 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 returned `Command` 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 when `markSaveLocation()` 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 of `isDirty()` will be based on this checkpoint.

#### notifyListeners

    protected void notifyListeners()

Deprecated. Use `notifyListeners(Command, int)` instead.
Sends notification to all `CommandStackListener`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 command
  `state` - 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 when `canUndo()` returns `true`.

#### 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. Use `CommandStackEventListener` 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 when `canUndo()` returns `true`.