Revert last code drop.
/*
* 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_