UndoManager.hh

Go to the documentation of this file.

/*
 *  Copyright 2007 Martin von Gagern
 *
 *
 *  This file is part of bande.
 *
 *  bande is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  bande is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */


/**
 * @file
 * Interface of class bande::UndoManager.
 */

namespace bande {



  /**
   * Abstract base class for any undoable modification.
   */
  class UndoBase {
  public:

    /**
     * Destructor.
     * This cirtual destructor allows clean destruction of derived
     * classes even in the presence of polymorphism.
     */
    virtual ~UndoBase() {}

    /**
     * Undo one operation.
     * This is a pure virtual function that must be overridden by any
     * concrete derived class.
     */
    virtual void undo() = 0;
  };



  class UndoManager;



  /**
   * Stack pointer for the UndoManager.
   * This encapsulates the current state of the UndoManager. It
   * represents a snapshot of its action stack and allows undoing all
   * actions that were added later in order to restore the state
   * corresponding to this snapshot.
   */
  class UndoState {
  public:

    /**
     * Undo all modifications added after this state was saved.
     */
    void restore();

  protected:

    /**
     * Constructor.
     * Access to this constructor is only allowed from within the
     * UndoManager. Other code must ask UndoManager::save() to get an
     * UndoState object.
     * @param um the undo manager associated with this state.
     * @param pos the current stack pointer of this undo manager.
     */
    UndoState(UndoManager& um, unsigned pos) : um(um), pos(pos) { }

    /**
     * The UndoManager may create objects of this class.
     */
    friend class UndoManager;

  private:

    /**
     * The associated undo manager.
     */
    UndoManager& um;

    /**
     * Stack pointer for the associated undo manager.
     */
    const unsigned pos;
  };



  /**
   * Stack of undoable modifications.
   *
   * Whenever a class performs some local modification that needs to
   * be unwound when the current branch is left, this modification can
   * be registered with the UndoManager. In this way, no class has to
   * care for properly cleaning up all modifications in all possible
   * cases. It registers the undo event when it performs the
   * modification in the first place, and after that it can forget
   * about it. The branching code will ask the undo manager to rewind
   * modifications in reverse order at appropriate times.
   */
  class UndoManager {
  public:

    virtual ~UndoManager();

    /**
     * Save current state.
     *
     * The returned object can be used to rewind all modifications
     * added after its creation.
     *
     * @return an object encapsulating the current state of the stack
     *         of modifications.
     */
    UndoState save() { return UndoState(*this, events.size()); }

    /**
     * Record a modification for later rewinding.
     * The undo manager will ensure the objects will get deleted
     * eventually.
     *
     * @param event an undoable object describing the modification.
     */
    void record(UndoBase* event) { events.push_back(event); }

  protected:

    void restore(unsigned pos);

    /**
     * The UndoState may initiate rewinding of modifications.
     */
    friend void UndoState::restore();

  private:

    /**
     * A stack of undoable events.
     */
    std::vector<UndoBase*> events;
  };



  inline void UndoState::restore() { um.restore(pos); }



  /**
   * Undo information for modification of one int variable.
   */
  class UndoInt : public UndoBase {
  public:

    /**
     * Record undo information given pointer and previous value.
     * @param p the pointer of the variable about to be modified.
     * @param v the old value of the variable to be restored upon
     *          undo.
     */
    UndoInt(int* p, int v) : ptr(p), val(v) { }

    /**
     * Record undo information using a reference to the variable.
     * The supplied reference will be used to record both the
     * variable's address and its current (old) value.
     * @param i the variable that is about to be modified.
     */
    UndoInt(int& i) : ptr(&i), val(i) { }

    /**
     * Undo the modification.
     * The recorded old value is written to the recoded address.
     */
    void undo() { *ptr = val; }

  protected:

    /**
     * Address of the modified variable.
     */
    int *ptr;

    /**
     * Old value of the modified variable.
     */
    int val;
  };

}

---