1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/textandloc/textrendering/textformatting/inc/UndoSystem.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,353 @@
1.4 +/*
1.5 +* Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef UNDOSYSTEM_H_
1.23 +#define UNDOSYSTEM_H_
1.24 +
1.25 +#include <e32base.h>
1.26 +
1.27 +namespace UndoSystem
1.28 +{
1.29 +class CCommand;
1.30 +class CSingleCommand;
1.31 +class CBatchCommand;
1.32 +class CCommandManager;
1.33 +class CCommandHistory;
1.34 +class CCommandStack;
1.35 +class CSingleCommandStack;
1.36 +class CDefaultGatekeeper;
1.37 +
1.38 +/**
1.39 +Base class for gatekeepers. A Gatekeeper is responsible for finding more
1.40 +memory during certain out of memory conditions, and for deciding whether
1.41 +an operation that cannot be undone should be allowed to be excuted.
1.42 +
1.43 +@since App-frameworks6.1
1.44 +@internalAll
1.45 +*/
1.46 +class MNotUndoableGatekeeper
1.47 +
1.48 + {
1.49 +public:
1.50 + /**
1.51 + * Tries to find more memory. aNumRetries will be 0 on the first call to
1.52 + * this function for the processing of a given command. It will increase
1.53 + * by 1 each time it is called for the same command. The calls will stop
1.54 + * when either the processing for the command completes successfully, when
1.55 + * processing for the command fails for some other reason, or when this
1.56 + * function returns EFalse or leaves.
1.57 + *
1.58 + * Default behaviour is to return EFalse always.
1.59 + */
1.60 + IMPORT_C virtual TBool RetryOutOfMemoryL(TInt aNumRetries);
1.61 + /**
1.62 + * Decides whether to allow an operation that is undoable.
1.63 + *
1.64 + * aReason is the code that the attempt to create an inverse command
1.65 + * left with.
1.66 + *
1.67 + * A return value of EFalse indicates that the command should not be
1.68 + * executed, and all stored operations should be retained. KErrAbort will
1.69 + * be returned to the caller of CCommandManager. A return value of ETure
1.70 + * indicates that the command should be executed, and all stored
1.71 + * operations deleted. The function may also leave. Any leave will pass
1.72 + * back to the caller of CCommandManager, leaving the command unexecuted
1.73 + * and the stored operations intact.
1.74 + *
1.75 + * Default behaviour is to return ETrue if aReason is KErrNotSupported,
1.76 + * and leave with aReason otherwise.
1.77 + */
1.78 + IMPORT_C virtual TBool AllowNotUndoableL(TInt aReason);
1.79 + };
1.80 +
1.81 +/**
1.82 +General undo system. Together with CSingleCommand and CBatchCommand, this
1.83 +class provides a framework for building undo systems. A bookmark is
1.84 +maintained so that we can determine if the undo system has returned the
1.85 +target to a previously bookmarked state. This is useful for determining if
1.86 +saving is necessary on exit.
1.87 +
1.88 +@see CSingleCommand, CBatchCommand
1.89 +@since App-frameworks6.1
1.90 +@internalAll
1.91 +*/
1.92 +class CCommandManager : public CBase
1.93 +
1.94 + {
1.95 +public:
1.96 + /**
1.97 + * Allows a new owner to share this CCommandManager. Release() will need
1.98 + * to be called one extra time per call to NewReference().
1.99 + */
1.100 + IMPORT_C void NewReference();
1.101 + /**
1.102 + * Allows the caller to finish with this CCommandManager. The caller must
1.103 + * not access this object after calling Release().
1.104 + */
1.105 + IMPORT_C void Release();
1.106 +
1.107 + /**
1.108 + * Creates a new CCommandManager. One call to Release() will be required
1.109 + * to dispose of this object, unless NewReference() is called, in which case
1.110 + * one additional call to Release() is required per call to NewReference().
1.111 + */
1.112 + IMPORT_C static CCommandManager* NewL();
1.113 +
1.114 + /**
1.115 + * Begins a batch. Commands entered into the batch will be undone and redone
1.116 + * in one go. If undo is cancelled for one command in the batch, it will be
1.117 + * considered cancelled for the entire batch.
1.118 + * End the batch with CleanupStack::PopAndDestroy();
1.119 + */
1.120 + IMPORT_C void BeginBatchLC();
1.121 + /**
1.122 + * Returns ETrue iff UndoL() will have an effect.
1.123 + */
1.124 + IMPORT_C TBool CanUndo() const;
1.125 + /**
1.126 + * Returns ETrue iff RedoL() will have an effect.
1.127 + */
1.128 + IMPORT_C TBool CanRedo() const;
1.129 + /**
1.130 + * Executes a single command, allowing it to be undone later, if
1.131 + * appropriate.
1.132 + */
1.133 + IMPORT_C TInt ExecuteL(const CSingleCommand&);
1.134 + /**
1.135 + * Sets a gatekeper for the undo system. This will be called whenever an
1.136 + * operation is attempted that cannot be undone for any reason.
1.137 + * The gatekeeper therefore has an oportunity to suppress execution and
1.138 + * keep the current undo operations stored.
1.139 + * NULL may be passed to restore default behaviour.
1.140 + * Returns previous gatekeeper.
1.141 + */
1.142 + IMPORT_C MNotUndoableGatekeeper* SetGatekeeper(MNotUndoableGatekeeper*);
1.143 + /**
1.144 + * Sets limits on the 'undo depth'. This is the number of times that
1.145 + * successive calls to UndoL() have an effect.
1.146 + */
1.147 + IMPORT_C void SetMaxItems(TInt aMaxItems);
1.148 + /**
1.149 + * Undoes one operation or batch of operations. If one operation in the
1.150 + * middle of a batch leaves, this function will leave, but the underlying
1.151 + * editor will not necessarily be in the same state as it was in before
1.152 + * the call. However, all operations will still be stored, and so the
1.153 + * previous state is still recoverable with a further call to UndoL().
1.154 + */
1.155 + IMPORT_C void UndoL();
1.156 + /**
1.157 + * Redoes one operation or batch of operations. If one operation in the
1.158 + * middle of a batch leaves, this function will leave, but the underlying
1.159 + * editor will not necessarily be in the same state as it was in before
1.160 + * the call. However, all operations will still be stored, and so the
1.161 + * previous state is still recoverable with a further call to RedoL().
1.162 + */
1.163 + IMPORT_C void RedoL();
1.164 + /**
1.165 + * Deletes all stored operations. Deletes the bookmark.
1.166 + */
1.167 + IMPORT_C void ResetUndo();
1.168 + /**
1.169 + * Sets the bookmark to the current position in the history.
1.170 + */
1.171 + IMPORT_C void SetBookmark();
1.172 + /**
1.173 + * Returns true iff we are currently at the bookmarked position.
1.174 + */
1.175 + IMPORT_C TBool IsAtBookmark() const;
1.176 +
1.177 +private:
1.178 +
1.179 + TInt ExecuteSingleCommandL(const CSingleCommand& aCommand, CCommandHistory& aUndo);
1.180 + TInt ExecuteBatchCommandL(CBatchCommand& aCommand, CCommandHistory& aUndo);
1.181 + void MoveHistoryL(CCommandHistory& aFrom, CCommandHistory& aTo);
1.182 + TBool CreateAndPrepareToAddInverseL(const CSingleCommand& aCommand,
1.183 + CCommandHistory& aUndo, CCommand*& aInverse);
1.184 +
1.185 + CCommandManager();
1.186 + void ConstructL();
1.187 + ~CCommandManager();
1.188 +
1.189 + CCommandHistory* iFuture;
1.190 + CCommandHistory* iPast;
1.191 + MNotUndoableGatekeeper* iCurrentGatekeeper;
1.192 + CDefaultGatekeeper* iDefaultGatekeeper;
1.193 + TInt iRefCount;
1.194 + };
1.195 +
1.196 +/**
1.197 +Abstract base class for all commands that can be stored in the undo system
1.198 +
1.199 +@since App-frameworks6.1
1.200 +@internalComponent
1.201 +*/
1.202 +class CCommand : public CBase
1.203 +
1.204 + {
1.205 +public:
1.206 + /**
1.207 + * Casts this CCommand to CSingleCommand* if possible
1.208 + */
1.209 + virtual CSingleCommand* Single() = 0;
1.210 + /**
1.211 + * Casts this CCommand to CBatchCommand* if possible
1.212 + */
1.213 + virtual CBatchCommand* Batch() = 0;
1.214 + };
1.215 +
1.216 +/**
1.217 +Abstract base class for all commands. A CSingleCommand is able to be
1.218 +completed atomically, that is, leave their target unchanged if its
1.219 +execution leaves.
1.220 +
1.221 +@since App-frameworks6.1
1.222 +@internalAll
1.223 +*/
1.224 +class CSingleCommand : public CCommand
1.225 +
1.226 + {
1.227 +public:
1.228 + /**
1.229 + * Executes this command. This function may leave or return an error code.
1.230 + * in either case, there must have been no effect on its target(s).
1.231 + */
1.232 + virtual TInt ExecuteL() const = 0;
1.233 + /**
1.234 + * Prepares to add the inverse of this command to aLastCommand.
1.235 + * Returns ETrue iff this was possible. Returning ETrue implies that
1.236 + * a future call to AddInverseToLast with the same parameter will
1.237 + * succeed without leaving.
1.238 + * The defualt implementation is to return EFalse.
1.239 + */
1.240 + IMPORT_C virtual TBool PrepareToAddInverseToLastL(CSingleCommand& aLastCommand) const;
1.241 +
1.242 + /**
1.243 + * Adds this command's inverse to aLastCommand. This function will
1.244 + * only be called after PrepareToAddInverseToLastL has been called
1.245 + * with the same argument, ETrue having been returned.
1.246 + * Default implementation is to panic.
1.247 + */
1.248 + IMPORT_C virtual void AddInverseToLast(CSingleCommand& aLastCommand) const;
1.249 +
1.250 + /**
1.251 + * Creates an inverse of this command.
1.252 + * A return value of 0 indicates that this command has no effect, and so a
1.253 + * return is not needed. To indicate that an inverse command cannot be
1.254 + * created, this function should leave with KErrNotSupported.
1.255 + * Default implementation is to leave with KErrNotSupported.
1.256 + */
1.257 + IMPORT_C virtual CCommand* CreateInverseL() const;
1.258 +
1.259 + /**
1.260 + * Returns a UID for the family of CSingleCommands that this belongs to.
1.261 + * This would usually be the DLL UID or KNullUid. It can be used to
1.262 + * determine whether a downcast is safe.
1.263 + */
1.264 + IMPORT_C virtual TUid FamilyUid() const;
1.265 + /**
1.266 + * Returns this. Not to be overridden further.
1.267 + */
1.268 + IMPORT_C CSingleCommand* Single();
1.269 + /**
1.270 + * Returns 0. Not to be overridden further.
1.271 + */
1.272 + IMPORT_C CBatchCommand* Batch();
1.273 + };
1.274 +
1.275 +/**
1.276 +Batch of commands.
1.277 +
1.278 +@since App-frameworks6.1
1.279 +@internalComponent
1.280 +*/
1.281 +class CBatchCommand : public CCommand
1.282 +
1.283 + {
1.284 +public:
1.285 + IMPORT_C ~CBatchCommand();
1.286 +
1.287 + /**
1.288 + * Creates an empty batch.
1.289 + */
1.290 + IMPORT_C static CBatchCommand* NewL();
1.291 + /**
1.292 + * Creates an empty batch on the cleanup stack.
1.293 + */
1.294 + IMPORT_C static CBatchCommand* NewLC();
1.295 +
1.296 + /**
1.297 + * Returns 0.
1.298 + */
1.299 + IMPORT_C CSingleCommand* Single();
1.300 + /**
1.301 + * Returns this.
1.302 + */
1.303 + IMPORT_C CBatchCommand* Batch();
1.304 + /**
1.305 + * Returns the single command that is at the top of the stack. If a batch
1.306 + * is at the top, then it will be the top of that.
1.307 + * A return value of 0 indicates that the batch is empty. Some empty
1.308 + * batches within the batch may be deleted.
1.309 + */
1.310 + IMPORT_C CSingleCommand* Top() const;
1.311 + /**
1.312 + * Returns the single command that is at the top of the stack as for Top().
1.313 + * The ownership of the object is passed to the caller. This method must
1.314 + * not be called on an empty batch.
1.315 + */
1.316 + IMPORT_C CSingleCommand* Pop();
1.317 + /**
1.318 + * Ensures that enough resources to perform a Push(CCommand* aCommand)
1.319 + * without leaving are allocated. The contents of the batch are unaltered.
1.320 + */
1.321 + IMPORT_C void PrepareToPushL(CCommand* aCommand);
1.322 + /**
1.323 + * Pushes the command onto the batch. This command will be executed before
1.324 + * the commands currently in the batch. This function must only be called
1.325 + * if PrepareToPushL() has been called successfully since the last call to
1.326 + * Push() or NewL().
1.327 + *
1.328 + * aCommand may not be accessed after this call has completed.
1.329 + */
1.330 + IMPORT_C void Push(CCommand* aCommand);
1.331 + /**
1.332 + * Performs PrepareToPushL(aCommand) then Push(aCommand). If it leaves,
1.333 + * aCommand is destroyed.
1.334 + *
1.335 + * @see PrepareToPushL, Push
1.336 + */
1.337 + IMPORT_C void PushL(CCommand* aCommand);
1.338 + /**
1.339 + * Returns ETrue iff the batch is empty.
1.340 + */
1.341 + TBool IsEmpty() const
1.342 + {
1.343 + if (Top())
1.344 + return EFalse;
1.345 + else
1.346 + return ETrue;
1.347 + }
1.348 +
1.349 +private:
1.350 + CSingleCommandStack* iStack;
1.351 + CBatchCommand();
1.352 + void ConstructL();
1.353 + };
1.354 +}
1.355 +
1.356 +#endif // UNDOSYSTEM_H_