/*

 * Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of "Eclipse Public License v1.0"

 * which accompanies this distribution, and is available

 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description: 

 *

 */

 #ifndef UNDOSYSTEM_H_

 #define UNDOSYSTEM_H_

 #include <e32base.h>

 namespace UndoSystem

 {

 class CCommand;

 class CSingleCommand;

 class CBatchCommand;

 class CCommandManager;

 class CCommandHistory;

 class CCommandStack;

 class CSingleCommandStack;

 class CDefaultGatekeeper;

 /**

 Base class for gatekeepers. A Gatekeeper is responsible for finding more

 memory during certain out of memory conditions, and for deciding whether

 an operation that cannot be undone should be allowed to be excuted.

 @since App-frameworks6.1

 @internalAll

 */

 class MNotUndoableGatekeeper

 	{

 public:

 	/**

 	 * Tries to find more memory. aNumRetries will be 0 on the first call to

 	 * this function for the processing of a given command. It will increase

 	 * by 1 each time it is called for the same command. The calls will stop

 	 * when either the processing for the command completes successfully, when

 	 * processing for the command fails for some other reason, or when this

 	 * function returns EFalse or leaves.

 	 *

 	 * Default behaviour is to return EFalse always.

 	 */

 	IMPORT_C virtual TBool RetryOutOfMemoryL(TInt aNumRetries);

 	/**

 	 * Decides whether to allow an operation that is undoable.

 	 *

 	 * aReason is the code that the attempt to create an inverse command

 	 * left with.

 	 *

 	 * A return value of EFalse indicates that the command should not be

 	 * executed, and all stored operations should be retained. KErrAbort will

 	 * be returned to the caller of CCommandManager. A return value of ETure

 	 * indicates that the command should be executed, and all stored

 	 * operations deleted. The function may also leave. Any leave will pass

 	 * back to the caller of CCommandManager, leaving the command unexecuted

 	 * and the stored operations intact.

 	 *

 	 * Default behaviour is to return ETrue if aReason is KErrNotSupported,

 	 * and leave with aReason otherwise.

 	 */

 	IMPORT_C virtual TBool AllowNotUndoableL(TInt aReason);

 	};

 /**

 General undo system. Together with CSingleCommand and CBatchCommand, this

 class provides a framework for building undo systems. A bookmark is

 maintained so that we can determine if the undo system has returned the

 target to a previously bookmarked state. This is useful for determining if

 saving is necessary on exit.

 @see CSingleCommand, CBatchCommand

 @since App-frameworks6.1

 @internalAll

 */

 class CCommandManager : public CBase

 	{

 public:

 	/**

 	 * Allows a new owner to share this CCommandManager. Release() will need

 	 * to be called one extra time per call to NewReference().

 	 */

 	IMPORT_C void NewReference();

 	/**

 	 * Allows the caller to finish with this CCommandManager. The caller must

 	 * not access this object after calling Release().

 	 */

 	IMPORT_C void Release();

 	/**

 	 * Creates a new CCommandManager. One call to Release() will be required

 	 * to dispose of this object, unless NewReference() is called, in which case

 	 * one additional call to Release() is required per call to NewReference().

 	 */

 	IMPORT_C static CCommandManager* NewL();

 	/**

 	 * Begins a batch. Commands entered into the batch will be undone and redone

 	 * in one go. If undo is cancelled for one command in the batch, it will be

 	 * considered cancelled for the entire batch.

 	 * End the batch with CleanupStack::PopAndDestroy();

 	 */

 	IMPORT_C void BeginBatchLC();

 	/**

 	 * Returns ETrue iff UndoL() will have an effect.

 	 */

 	IMPORT_C TBool CanUndo() const;

 	/**

 	 * Returns ETrue iff RedoL() will have an effect.

 	 */

 	IMPORT_C TBool CanRedo() const;

 	/**

 	 * Executes a single command, allowing it to be undone later, if

 	 * appropriate.

 	 */

 	IMPORT_C TInt ExecuteL(const CSingleCommand&);

 	/**

 	 * Sets a gatekeper for the undo system. This will be called whenever an

 	 * operation is attempted that cannot be undone for any reason.

 	 * The gatekeeper therefore has an oportunity to suppress execution and

 	 * keep the current undo operations stored.

 	 * NULL may be passed to restore default behaviour.

 	 * Returns previous gatekeeper.

 	 */

 	IMPORT_C MNotUndoableGatekeeper* SetGatekeeper(MNotUndoableGatekeeper*);

 	/**

 	 * Sets limits on the 'undo depth'. This is the number of times that

 	 * successive calls to UndoL() have an effect.

 	 */

 	IMPORT_C void SetMaxItems(TInt aMaxItems);

 	/**

 	 * Undoes one operation or batch of operations. If one operation in the

 	 * middle of a batch leaves, this function will leave, but the underlying

 	 * editor will not necessarily be in the same state as it was in before

 	 * the call. However, all operations will still be stored, and so the

 	 * previous state is still recoverable with a further call to UndoL().

 	 */

 	IMPORT_C void UndoL();

 	/**

 	 * Redoes one operation or batch of operations. If one operation in the

 	 * middle of a batch leaves, this function will leave, but the underlying

 	 * editor will not necessarily be in the same state as it was in before

 	 * the call. However, all operations will still be stored, and so the

 	 * previous state is still recoverable with a further call to RedoL().

 	 */

 	IMPORT_C void RedoL();

 	/**

 	 * Deletes all stored operations. Deletes the bookmark.

 	 */

 	IMPORT_C void ResetUndo();

 	/**

 	 * Sets the bookmark to the current position in the history.

 	 */

 	IMPORT_C void SetBookmark();

 	/**

 	 * Returns true iff we are currently at the bookmarked position.

 	 */

 	IMPORT_C TBool IsAtBookmark() const;

 private:

 	TInt ExecuteSingleCommandL(const CSingleCommand& aCommand, CCommandHistory& aUndo);

 	TInt ExecuteBatchCommandL(CBatchCommand& aCommand, CCommandHistory& aUndo);

 	void MoveHistoryL(CCommandHistory& aFrom, CCommandHistory& aTo);

 	TBool CreateAndPrepareToAddInverseL(const CSingleCommand& aCommand,

 		CCommandHistory& aUndo, CCommand*& aInverse);

 	CCommandManager();

 	void ConstructL();

 	~CCommandManager();

 	CCommandHistory*		iFuture;

 	CCommandHistory*		iPast;

 	MNotUndoableGatekeeper*	iCurrentGatekeeper;

 	CDefaultGatekeeper*		iDefaultGatekeeper;

 	TInt					iRefCount;

 	};

 /**

 Abstract base class for all commands that can be stored in the undo system

 @since App-frameworks6.1

 @internalComponent

 */

 class CCommand : public CBase

 	{

 public:

 	/**

 	 * Casts this CCommand to CSingleCommand* if possible

 	 */

 	virtual CSingleCommand*	Single() = 0;

 	/**

 	 * Casts this CCommand to CBatchCommand* if possible

 	 */

 	virtual CBatchCommand*	Batch() = 0;

 	};

 /**

 Abstract base class for all commands. A CSingleCommand is able to be

 completed atomically, that is, leave their target unchanged if its

 execution leaves.

 @since App-frameworks6.1

 @internalAll

 */

 class CSingleCommand : public CCommand

 	{

 public:

 	/**

 	 * Executes this command. This function may leave or return an error code.

 	 * in either case, there must have been no effect on its target(s).

 	 */

 	virtual TInt ExecuteL() const = 0;

 	/**

 	 * Prepares to add the inverse of this command to aLastCommand.

 	 * Returns ETrue iff this was possible. Returning ETrue implies that

 	 * a future call to AddInverseToLast with the same parameter will

 	 * succeed without leaving.

 	 * The defualt implementation is to return EFalse.

 	 */

 	IMPORT_C virtual TBool PrepareToAddInverseToLastL(CSingleCommand& aLastCommand) const;

 	/**

 	 * Adds this command's inverse to aLastCommand. This function will

 	 * only be called after PrepareToAddInverseToLastL has been called

 	 * with the same argument, ETrue having been returned.

 	 * Default implementation is to panic.

 	 */

 	IMPORT_C virtual void AddInverseToLast(CSingleCommand& aLastCommand) const;

 	/**

 	 * Creates an inverse of this command.

 	 * A return value of 0 indicates that this command has no effect, and so a

 	 * return is not needed. To indicate that an inverse command cannot be

 	 * created, this function should leave with KErrNotSupported.

 	 * Default implementation is to leave with KErrNotSupported.

 	 */

 	IMPORT_C virtual CCommand* CreateInverseL() const;

 	/**

 	 * Returns a UID for the family of CSingleCommands that this belongs to.

 	 * This would usually be the DLL UID or KNullUid. It can be used to

 	 * determine whether a downcast is safe.

 	 */

 	IMPORT_C virtual TUid FamilyUid() const;

 	/**

 	 * Returns this. Not to be overridden further.

 	 */

 	IMPORT_C CSingleCommand* Single();

 	/**

 	 * Returns 0. Not to be overridden further.

 	 */

 	IMPORT_C CBatchCommand* Batch();

 	};

 /**

 Batch of commands.

 @since App-frameworks6.1

 @internalComponent

 */

 class CBatchCommand : public CCommand

 	{

 public:

 	IMPORT_C ~CBatchCommand();

 	/**

 	 * Creates an empty batch.

 	 */

 	IMPORT_C static CBatchCommand* NewL();

 	/**

 	 * Creates an empty batch on the cleanup stack.

 	 */

 	IMPORT_C static CBatchCommand* NewLC();

 	/**

 	 * Returns 0.

 	 */

 	IMPORT_C CSingleCommand*	Single();

 	/**

 	 * Returns this.

 	 */

 	IMPORT_C CBatchCommand*		Batch();

 	/**

 	 * Returns the single command that is at the top of the stack. If a batch

 	 * is at the top, then it will be the top of that.

 	 * A return value of 0 indicates that the batch is empty. Some empty

 	 * batches within the batch may be deleted.

 	 */

 	IMPORT_C CSingleCommand*	Top() const;

 	/**

 	 * Returns the single command that is at the top of the stack as for Top().

 	 * The ownership of the object is passed to the caller. This method must

 	 * not be called on an empty batch.

 	 */

 	IMPORT_C CSingleCommand*	Pop();

 	/**

 	 * Ensures that enough resources to perform a Push(CCommand* aCommand)

 	 * without leaving are allocated. The contents of the batch are unaltered.

 	 */

 	IMPORT_C void				PrepareToPushL(CCommand* aCommand);

 	/**

 	 * Pushes the command onto the batch. This command will be executed before

 	 * the commands currently in the batch. This function must only be called

 	 * if PrepareToPushL() has been called successfully since the last call to

 	 * Push() or NewL().

 	 *

 	 * aCommand may not be accessed after this call has completed.

 	 */

 	IMPORT_C void				Push(CCommand* aCommand);

 	/**

 	 * Performs PrepareToPushL(aCommand) then Push(aCommand). If it leaves,

 	 * aCommand is destroyed.

 	 *

 	 * @see PrepareToPushL, Push

 	 */

 	IMPORT_C void				PushL(CCommand* aCommand);

 	/**

 	 * Returns ETrue iff the batch is empty.

 	 */

 	TBool IsEmpty() const 

 		{

 		if (Top())

 			return EFalse;

 		else

 			return ETrue;

 		}

 private:

 	CSingleCommandStack* iStack;

 	CBatchCommand();

 	void ConstructL();

 	};

 }

 #endif	// UNDOSYSTEM_H_