Class CommandStack

java.lang.Object
org.eclipse.gef.commands.CommandStack

public class CommandStack extends 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 Details

    • POST_EXECUTE

      public static final int POST_EXECUTE
      Constant indicating notification after a command has been executed.
      See Also:
    • POST_REDO

      public static final int POST_REDO
      Constant indicating notification after a command has been redone.
      See Also:
    • POST_UNDO

      public static final int POST_UNDO
      Constant indicating notification after a command has been undone.
      See Also:
    • POST_FLUSH

      public static final int POST_FLUSH
      Constant indicating notification after flushing the stack.
      Since:
      3.11
      See Also:
    • 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:
    • 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();
       }
       
      See Also:
    • PRE_EXECUTE

      public static final int PRE_EXECUTE
      Constant indicating notification prior to executing a command.
      See Also:
    • PRE_REDO

      public static final int PRE_REDO
      Constant indicating notification prior to redoing a command.
      See Also:
    • PRE_UNDO

      public static final int PRE_UNDO
      Constant indicating notification prior to undoing a command.
      See Also:
    • PRE_FLUSH

      public static final int PRE_FLUSH
      Constant indicating notification prior to flushing the stack.
      Since:
      3.11
      See Also:
    • 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:
    • 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.
      See Also:
    • listeners

      @Deprecated protected List<CommandStackListener> listeners
      Deprecated.
      This field should not be referenced, use notifyListeners()
      The list of CommandStackListeners.
  • Constructor Details

    • CommandStack

      public CommandStack()
      Constructs a new command stack. By default, there is no undo limit, and isDirty() will return false.
  • Method Details

    • 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

      @Deprecated public void addCommandStackListener(CommandStackListener listener)
      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:
    • 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 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

      @Deprecated protected void notifyListeners()
      Deprecated.
      Sends notification to all CommandStackListeners.
    • 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

      @Deprecated public void removeCommandStackListener(CommandStackListener listener)
      Deprecated.
      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.