1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 #ifndef UNDOSYSTEM_H_

    20 #define UNDOSYSTEM_H_

    21 

    22 #include <e32base.h>

    23 

    24 namespace UndoSystem

    25 {

    26 class CCommand;

    27 class CSingleCommand;

    28 class CBatchCommand;

    29 class CCommandManager;

    30 class CCommandHistory;

    31 class CCommandStack;

    32 class CSingleCommandStack;

    33 class CDefaultGatekeeper;

    34 

    35 /**

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

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

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

    39 

    40 @since App-frameworks6.1

    41 @internalAll

    42 */

    43 class MNotUndoableGatekeeper

    44 

    45 	{

    46 public:

    47 	/**

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

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

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

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

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

    53 	 * function returns EFalse or leaves.

    54 	 *

    55 	 * Default behaviour is to return EFalse always.

    56 	 */

    57 	IMPORT_C virtual TBool RetryOutOfMemoryL(TInt aNumRetries);

    58 	/**

    59 	 * Decides whether to allow an operation that is undoable.

    60 	 *

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

    62 	 * left with.

    63 	 *

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

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

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

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

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

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

    70 	 * and the stored operations intact.

    71 	 *

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

    73 	 * and leave with aReason otherwise.

    74 	 */

    75 	IMPORT_C virtual TBool AllowNotUndoableL(TInt aReason);

    76 	};

    77 

    78 /**

    79 General undo system. Together with CSingleCommand and CBatchCommand, this

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

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

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

    83 saving is necessary on exit.

    84 

    85 @see CSingleCommand, CBatchCommand

    86 @since App-frameworks6.1

    87 @internalAll

    88 */

    89 class CCommandManager : public CBase

    90 

    91 	{

    92 public:

    93 	/**

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

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

    96 	 */

    97 	IMPORT_C void NewReference();

    98 	/**

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

   100 	 * not access this object after calling Release().

   101 	 */

   102 	IMPORT_C void Release();

   103 

   104 	/**

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

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

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

   108 	 */

   109 	IMPORT_C static CCommandManager* NewL();

   110 

   111 	/**

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

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

   114 	 * considered cancelled for the entire batch.

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

   116 	 */

   117 	IMPORT_C void BeginBatchLC();

   118 	/**

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

   120 	 */

   121 	IMPORT_C TBool CanUndo() const;

   122 	/**

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

   124 	 */

   125 	IMPORT_C TBool CanRedo() const;

   126 	/**

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

   128 	 * appropriate.

   129 	 */

   130 	IMPORT_C TInt ExecuteL(const CSingleCommand&);

   131 	/**

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

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

   134 	 * The gatekeeper therefore has an oportunity to suppress execution and

   135 	 * keep the current undo operations stored.

   136 	 * NULL may be passed to restore default behaviour.

   137 	 * Returns previous gatekeeper.

   138 	 */

   139 	IMPORT_C MNotUndoableGatekeeper* SetGatekeeper(MNotUndoableGatekeeper*);

   140 	/**

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

   142 	 * successive calls to UndoL() have an effect.

   143 	 */

   144 	IMPORT_C void SetMaxItems(TInt aMaxItems);

   145 	/**

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

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

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

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

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

   151 	 */

   152 	IMPORT_C void UndoL();

   153 	/**

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

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

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

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

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

   159 	 */

   160 	IMPORT_C void RedoL();

   161 	/**

   162 	 * Deletes all stored operations. Deletes the bookmark.

   163 	 */

   164 	IMPORT_C void ResetUndo();

   165 	/**

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

   167 	 */

   168 	IMPORT_C void SetBookmark();

   169 	/**

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

   171 	 */

   172 	IMPORT_C TBool IsAtBookmark() const;

   173 

   174 private:

   175 

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

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

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

   179 	TBool CreateAndPrepareToAddInverseL(const CSingleCommand& aCommand,

   180 		CCommandHistory& aUndo, CCommand*& aInverse);

   181 

   182 	CCommandManager();

   183 	void ConstructL();

   184 	~CCommandManager();

   185 

   186 	CCommandHistory*		iFuture;

   187 	CCommandHistory*		iPast;

   188 	MNotUndoableGatekeeper*	iCurrentGatekeeper;

   189 	CDefaultGatekeeper*		iDefaultGatekeeper;

   190 	TInt					iRefCount;

   191 	};

   192 

   193 /**

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

   195 

   196 @since App-frameworks6.1

   197 @internalComponent

   198 */

   199 class CCommand : public CBase

   200 

   201 	{

   202 public:

   203 	/**

   204 	 * Casts this CCommand to CSingleCommand* if possible

   205 	 */

   206 	virtual CSingleCommand*	Single() = 0;

   207 	/**

   208 	 * Casts this CCommand to CBatchCommand* if possible

   209 	 */

   210 	virtual CBatchCommand*	Batch() = 0;

   211 	};

   212 

   213 /**

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

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

   216 execution leaves.

   217 

   218 @since App-frameworks6.1

   219 @internalAll

   220 */

   221 class CSingleCommand : public CCommand

   222 

   223 	{

   224 public:

   225 	/**

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

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

   228 	 */

   229 	virtual TInt ExecuteL() const = 0;

   230 	/**

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

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

   233 	 * a future call to AddInverseToLast with the same parameter will

   234 	 * succeed without leaving.

   235 	 * The defualt implementation is to return EFalse.

   236 	 */

   237 	IMPORT_C virtual TBool PrepareToAddInverseToLastL(CSingleCommand& aLastCommand) const;

   238 

   239 	/**

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

   241 	 * only be called after PrepareToAddInverseToLastL has been called

   242 	 * with the same argument, ETrue having been returned.

   243 	 * Default implementation is to panic.

   244 	 */

   245 	IMPORT_C virtual void AddInverseToLast(CSingleCommand& aLastCommand) const;

   246 

   247 	/**

   248 	 * Creates an inverse of this command.

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

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

   251 	 * created, this function should leave with KErrNotSupported.

   252 	 * Default implementation is to leave with KErrNotSupported.

   253 	 */

   254 	IMPORT_C virtual CCommand* CreateInverseL() const;

   255 

   256 	/**

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

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

   259 	 * determine whether a downcast is safe.

   260 	 */

   261 	IMPORT_C virtual TUid FamilyUid() const;

   262 	/**

   263 	 * Returns this. Not to be overridden further.

   264 	 */

   265 	IMPORT_C CSingleCommand* Single();

   266 	/**

   267 	 * Returns 0. Not to be overridden further.

   268 	 */

   269 	IMPORT_C CBatchCommand* Batch();

   270 	};

   271 

   272 /**

   273 Batch of commands.

   274 

   275 @since App-frameworks6.1

   276 @internalComponent

   277 */

   278 class CBatchCommand : public CCommand

   279 

   280 	{

   281 public:

   282 	IMPORT_C ~CBatchCommand();

   283 

   284 	/**

   285 	 * Creates an empty batch.

   286 	 */

   287 	IMPORT_C static CBatchCommand* NewL();

   288 	/**

   289 	 * Creates an empty batch on the cleanup stack.

   290 	 */

   291 	IMPORT_C static CBatchCommand* NewLC();

   292 

   293 	/**

   294 	 * Returns 0.

   295 	 */

   296 	IMPORT_C CSingleCommand*	Single();

   297 	/**

   298 	 * Returns this.

   299 	 */

   300 	IMPORT_C CBatchCommand*		Batch();

   301 	/**

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

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

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

   305 	 * batches within the batch may be deleted.

   306 	 */

   307 	IMPORT_C CSingleCommand*	Top() const;

   308 	/**

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

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

   311 	 * not be called on an empty batch.

   312 	 */

   313 	IMPORT_C CSingleCommand*	Pop();

   314 	/**

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

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

   317 	 */

   318 	IMPORT_C void				PrepareToPushL(CCommand* aCommand);

   319 	/**

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

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

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

   323 	 * Push() or NewL().

   324 	 *

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

   326 	 */

   327 	IMPORT_C void				Push(CCommand* aCommand);

   328 	/**

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

   330 	 * aCommand is destroyed.

   331 	 *

   332 	 * @see PrepareToPushL, Push

   333 	 */

   334 	IMPORT_C void				PushL(CCommand* aCommand);

   335 	/**

   336 	 * Returns ETrue iff the batch is empty.

   337 	 */

   338 	TBool IsEmpty() const 

   339 		{

   340 		if (Top())

   341 			return EFalse;

   342 		else

   343 			return ETrue;

   344 		}

   345 

   346 private:

   347 	CSingleCommandStack* iStack;

   348 	CBatchCommand();

   349 	void ConstructL();

   350 	};

   351 }

   352 

   353 #endif	// UNDOSYSTEM_H_