diff -r 000000000000 -r bde4ae8d615e os/textandloc/textrendering/textformatting/inc/UndoSystem.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/os/textandloc/textrendering/textformatting/inc/UndoSystem.h Fri Jun 15 03:10:57 2012 +0200 @@ -0,0 +1,353 @@ +/* +* 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 + +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_