/*

* 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_