2
For general Scribus (>=1.3.2) copyright and licensing information please refer
3
to the COPYING file provided with the program. Following this notice may exist
4
a copyright and/or license notice that predates the release of Scribus 1.3.2
5
for which a new license (GPL+exception) is in place.
7
/***************************************************************************
8
* Copyright (C) 2005 by Riku Leino *
11
* This program is free software; you can redistribute it and/or modify *
12
* it under the terms of the GNU General Public License as published by *
13
* the Free Software Foundation; either version 2 of the License, or *
14
* (at your option) any later version. *
16
* This program is distributed in the hope that it will be useful, *
17
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
18
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
19
* GNU General Public License for more details. *
21
* You should have received a copy of the GNU General Public License *
22
* along with this program; if not, write to the *
23
* Free Software Foundation, Inc., *
24
* 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
25
***************************************************************************/
36
#include "scribusapi.h"
37
#include "undostate.h"
38
#include "undoobject.h"
43
typedef std::pair<UndoObject*, UndoState*> ActionPair;
44
typedef std::vector<ActionPair> ActionList;
45
typedef std::pair<ActionList::iterator, ActionList> StackPair;
46
typedef QMap<QString, StackPair> StackMap;
49
* @brief UndoManager handles the undo stack.
51
* UndoManager is the engine of the undo/redo handling. When ever an undoable
52
* action happens an UndoState object will be sent to the UndoManager which then
53
* stores the state in the undo stack. When an undo is requested the state is
54
* send back to it's creator which is then responsible for doing the actual undo or
57
* UndoManager also handles the UndoGuis by linking them together and reporting
58
* all undo/redo actions to the guis for them to update the visual representation.
59
* For this to work all UndoGuis need to be registered to the UndoManager with the
60
* registerGui() method.
62
* @author Riku Leino tsoots@gmail.com
65
class SCRIBUS_API UndoManager : public QObject
71
/*** UndoManager::TransactionState ***************************************************/
74
* @brief TransactionState provides a container where multiple actions can be stored
75
* @brief as a single action which then appears in the attached <code>UndoGui</code>s.
76
* @author Riku Leino tsoots@gmail.com
79
class TransactionState : public UndoState
82
/** @brief Number of undo states stored in this transaction */
84
/** @brief vector to keep the states in */
85
std::vector<ActionPair*> states;
87
/** @brief Creates a new TransactionState instance */
89
/** @brief Destroys the TransactionState instance */
92
* @brief Add a new <code>UndoState</code> object to the transaction.
93
* @param state state to be added to the transaction
95
void pushBack(UndoObject *target, UndoState *state);
97
* @brief Returns the count of the <code>UndoState</code> objects in this transaction.
98
* @return count of the <code>UndoState</code> objects in this transaction
101
/** @brief Use the name from last action added to this <code>TransactionState</code> */
102
void useActionName();
104
* @brief Returns an <code>UndoState</code> object at <code>index</code>.
105
* @param index index from where an <code>UndoState</code> object is returned.
106
* If <code>index</code> is out of scope <code>NULL</code> will be rerturned.
107
* @return <code>UndoState</code> object from <code>index</code> or <code>NULL</code>
108
* if <code>index</code> is out of scope.
110
ActionPair* at(int index);
112
* @brief Returns true if this transaction contains UndoObject with the id <code>uid</code>
113
* @brief otherwise returns false.
114
* @return true if this transaction contains UndoObject with the ide <code>uid</code>
115
* @return otherwise returns false.
117
bool contains(int uid);
119
* @brief Replace object with id uid with new UndoObject newUndoObject.
120
* @param uid id of the object that is wanted to be replaced
121
* @param newUndoObject object that is used for replacing
122
* @return UndoObject which was replaced
124
UndoObject* replace(ulong uid, UndoObject *newUndoObject);
127
/*** UndoManager::TransactionObject ***************************************************/
130
* @brief Dummy subclass of <code>UndoObject</code> which is used for holding the name
131
* @brief for the transaction's target object(group) (f.e "Selection", "Group", "Script"...).
132
* @author Riku Leino tsoots@gmail.com
135
class TransactionObject : public UndoObject
138
TransactionObject() {};
139
virtual ~TransactionObject() {};
140
void restore(UndoState*, bool) {};
143
/**************************************************************************************/
146
* @brief The only instance of UndoManager available.
148
* UndoManager is singleton and the instance can be queried with the method
151
static UndoManager* _instance;
153
/** @brief Should undo states be stored or ignored */
154
static bool _undoEnabled;
157
* @brief Tracks the state of _undoEnabled.
159
* This value is increased whenever setUndoEnabled(true) is called and decreased
160
* when setUndoEnabled(false) is called. This means _undoEnabled == true when this
161
* value is 0 and when its above zero _undoEnabled == false. Counting setUndoEnabled()
162
* calls this way guarantees that undo is not enabled accidentally calling
163
* setUndoEnabled(true) even it has been set false before this false-true pair touched it.
165
static int undoEnabledCounter;
169
/** @brief Doc to which the currently active stack belongs */
173
* @brief Id number of the object for what the object specific undo is shown
174
* @brief or -1 if global undo is used.
176
int currentUndoObjectId;
179
* @brief Stores the transactions which are currently started but not
180
* @brief canceled or commited.
182
std::vector<std::pair<TransactionObject*, TransactionState*> > transactions;
185
* @brief If in transaction mode this is the container for incoming <code>UndoState</code>
188
* It is also used to detect if we are in the transaction mode. When it is <code>NULL</code>
191
TransactionState *transaction;
193
/** @brief Dummy object for storing transaction target's name */
194
TransactionObject *transactionTarget;
197
* @brief UndoGuis attached to this UndoManager
202
std::vector<UndoGui*> undoGuis;
204
/** @brief Undo stacks for all open documents */
207
/** @brief Maximum length of the undo stack. 0 marks for infinite length. */
211
* @brief Initializes the UndoGui.
212
* @param gui UndoGui to be initialized
213
* @param uid UndoObject's id if in object specific mode or -1 to tell
214
* that global undo is used.
216
void setState(UndoGui* gui, int uid = -1);
219
* @brief Disconnect all attached UndoGui instances from signals provided by this
220
* @brief class and other UndoGui objects.
224
* @brief Connect all attached UndoGui instances to signals provided by this
225
* @brief class and other UndoGui objects.
227
void disconnectGuis();
229
* @brief Load icons needed for Action History window.
233
* @brief Checks the stack length against historyLength variable and removes
234
* @brief actions until it is of right length.
236
* This method is used when a user alters the history length option in preferences
237
* and whenever a new action is added to the stack.
239
void checkStackLength();
241
* @brief Extracts actions from TransactionState object and undos them.
242
* @param tstate TransactionState object from where the actions are going to be extracted.
244
void doTransactionUndo(TransactionState *tstate);
246
* @brief Extracts actions from TransactionState object and redos them.
247
* @param tstate TransactionState object from where the actions are going to be extracted.
249
void doTransactionRedo(TransactionState *tstate);
252
/** @brief Stores the current position in the undo stack while undoing/redoing */
253
ActionList::iterator currentAction;
256
* @brief Returns the next <code>ActionPair</code> to undo.
257
* @return next action to undo
259
ActionPair& getNextUndoPair();
262
* @brief Returns the next <code>ActionPair</code> to redo.
263
* @return next <code>ActionPair</code> to redo
265
ActionPair& getNextRedoPair();
268
* @brief Sorts the stack after undo.
269
* @param steps how many undo steps was taken
271
void reorderUndoStack(int steps);
274
* @brief Sorts the stack after redo.
275
* @param steps how many redo steps was taken
277
void reorderRedoStack(int steps);
280
/** @brief Marks for a global undo mode where ever UndoOjbect id is requested. */
281
static const int GLOBAL_UNDO_MODE = -1;
284
* @brief When object specific mode is requested but no suitable object is selected
285
* @brief this can be passed to showObject() to clear the undo stack representations.
287
static const int NO_UNDO_STACK = -2;
290
* @brief Returns a pointer to the UndoManager instance
291
* @return A pointer to the UndoManager instance
293
static UndoManager* instance();
296
* @brief Deletes the UndoManager Instance
298
* Must be called when UndoManager is no more needed.
300
static void deleteInstance();
303
* @brief Sets the undo action tracking enabled or disabled.
304
* @param isEnabled If true undo stack is updated with the states sent
305
* to the UndoManager else undo stack is not updated and attached UndoGuis
306
* are not informed of the actions.
308
void setUndoEnabled(bool isEnabled);
311
* @brief Returns true if undo actions are stored, if not will return false.
312
* @return true if undo actions are stored, if not will return false
314
static bool undoEnabled();
317
* @brief Start a transaction.
319
* After this method has been invoked <code>UndoManager</code> will switch to the
320
* transaction (silent) mode where it does not report actions to the attached
321
* <code>UndoGui</code> widgets but stores all incoming <code>UndoState</code> objects into
322
* the transaction container which after call to the method commit() will be sent
323
* to the guis as a single undo action. Transaction can be named when starting it or
324
* naming can be done when commiting it.
325
* @param targetName name for the target of this transaction (f.e. "Selection")
326
* @param targetPixmap Icon for the target on which this transaction works.
327
* this icon will be drawn first when the action is presented in Action History
328
* window and icon for the action will be drawn over this one.
329
* @param name name for the transaction (f.e. "Move" would make with the above
331
* @param description description for the transaction
332
* @param actionPixmap icon for the action performed by the transaction
335
void beginTransaction(const QString &targetName = "",
336
QPixmap *targetPixmap = 0,
337
const QString &actionName = "",
338
const QString &description = "",
339
QPixmap *actionPixmap = 0);
342
* @brief Cancels the current transaction and deletes groupped <code>UndoState</code>s.
343
* @brief Nothing from canceled transaction will be sent to the undo gui widgets.
345
void cancelTransaction();
348
* @brief Commit the current transaction.
350
* Current transaction will be commited and <code>UndoManager</code> will be switched
351
* to the normal mode. Commited transaction will be sent to the attached undo gui
352
* widgets and it will show up there as a single undo action. Details used as a parameter
353
* will be details shown in the gui widgets.
354
* @param targetName name for the target of this transaction (f.e. "Selection")
355
* @param targetPixmap Icon for the target on which this transaction works.
356
* this icon will be drawn first when the action is presented in Action History
357
* window and icon for the action will be drawn over this one.
358
* @param name name for the action
359
* @param description description for the action
360
* @param actionPixmap icon for the action performed by the transaction
361
* @sa beginTransaction()
363
void commit(const QString &targetName = "",
364
QPixmap *targetPixmap = 0,
365
const QString &name = "",
366
const QString &description = "",
367
QPixmap *actionPixmap = 0);
370
* @brief Returns true if in transaction mode if not will return false.
371
* @return true if in transaction mode if not will return false
373
bool isTransactionMode();
376
* @brief Register an UndoGui to the UndoManager.
378
* After registering a gui to the manager the gui will be updated with the
379
* undo action information received by the UndoManager. Actions done with the
380
* UndoGui to be registered are also handled after registering.
381
* @param gui A pointer to the UndoGui that is wanted to be registered.
383
void registerGui(UndoGui* gui);
386
* @brief Removes an UndoGui from UndoManager.
387
* @param gui UndoGui to be removed from the UndoManager.
389
void removeGui(UndoGui* gui);
392
* @brief Changes the active undo stack.
394
* Sets the stack connected to the name <code>stackName</code> active. Calling
395
* this method will send clear() signal to the attached <code>UndoGui</code>s and
396
* will update their undo stack representations.
397
* @param stackName Name of the stack to be used
399
void switchStack(const QString& stackName);
402
* @brief Rename the current stack
403
* @param newName New name for the current stack.
405
void renameStack(const QString& newName);
408
* @brief Remove the stack with the name <code>stackName</code>
409
* @param stackName Name of the stack that is wanted to be removed
411
void removeStack(const QString& stackName);
414
* @brief Returns true if there are actions that can be undone otherwise returns false.
416
* This is useful when undo/redo actions are handled with a gui that is not attached to
417
* the UndoManager (f.e. menu items) and when those gui items are wanted to set enabled
418
* or disabled depending on the status of the undo stack.
419
* @return true if there are actions that can be undone otherwise returns false
421
bool hasUndoActions(int uid = -1);
424
* @brief Returns true if there are actions that can be redone otherwise returns false.
425
* @return true if there are actions that can be redone otherwise returns false
426
* @sa UndoManager::hasUndoActions()
428
bool hasRedoActions(int uid = -1);
431
* @brief Replace an UndoObject with the id uid with a new UndoObject new.
432
* @param uid Id for the UndoObject that is wanted to be replaced.
433
* @param newUndoObject UndoObject which will replace an old UndoObject in the stack.
434
* @return UndoObject which was replaced
436
UndoObject* replaceObject(ulong uid, UndoObject *newUndoObject);
439
* @brief Returns the maximum length of the undostack.
440
* @return the maximum length of the undostack
442
int getHistoryLength();
445
* @brief Returns true if in global mode and false if in object specific mode.
446
* @return true if in global mode and false if in object specific mode
451
* @name Action strings
452
* Strings describing undo actions
455
static QString AddVGuide;
456
static QString AddHGuide;
457
static QString DelVGuide;
458
static QString DelHGuide;
459
static QString MoveVGuide;
460
static QString MoveHGuide;
461
static QString LockGuides;
462
static QString UnlockGuides;
464
static QString Resize;
465
static QString Rotate;
466
static QString MoveFromTo;
467
static QString ResizeFromTo;
468
static QString ImageOffset;
469
static QString ImageScale;
470
static QString ImageOffsetFromTo;
471
static QString ImageScaleFromTo;
472
static QString Selection;
473
static QString Group;
474
static QString SelectionGroup;
475
static QString Create;
476
static QString CreateTo;
477
static QString AlignDistribute;
478
static QString ItemsInvolved;
479
static QString Cancel;
480
static QString SetFill;
481
static QString ColorFromTo;
482
static QString SetShade;
483
static QString SetLineColor;
484
static QString SetLineShade;
485
static QString FlipH;
486
static QString FlipV;
488
static QString UnLock;
489
static QString SizeLock;
490
static QString SizeUnLock;
491
static QString EnablePrint;
492
static QString DisablePrint;
493
static QString Ungroup;
494
static QString Delete;
495
static QString Rename;
496
static QString FromTo;
497
static QString ApplyMasterPage;
498
static QString Paste;
500
static QString Transparency;
501
static QString LineTransparency;
502
static QString LineStyle;
503
static QString LineEnd;
504
static QString LineJoin;
505
static QString LineWidth;
506
static QString NoStyle;
507
static QString CustomLineStyle;
508
static QString NoLineStyle;
509
static QString StartArrow;
510
static QString EndArrow;
511
static QString CreateTable;
512
static QString RowsCols;
513
static QString SetFont;
514
static QString SetFontSize;
515
static QString SetFontWidth;
516
static QString SetFontHeight;
517
static QString SetFontFill;
518
static QString SetFontStroke;
519
static QString SetFontFillShade;
520
static QString SetFontStrokeShade;
521
static QString SetKerning;
522
static QString SetLineSpacing;
523
static QString SetStyle;
524
static QString SetLanguage;
525
static QString AlignText;
526
static QString SetFontEffect;
527
static QString ImageFrame;
528
static QString TextFrame;
529
static QString Polygon;
530
static QString BezierCurve;
531
static QString Polyline;
532
static QString PathText;
533
static QString ConvertTo;
534
static QString ImportSVG;
535
static QString ImportEPS;
536
static QString ImportOOoDraw;
537
static QString ScratchSpace;
538
static QString TextFlow;
539
static QString BoundingBox;
540
static QString ContourLine;
541
static QString NoTextFlow;
542
static QString NoBoundingBox;
543
static QString NoContourLine;
544
static QString PageNmbr;
545
static QString ImageScaling;
546
static QString FrameSize;
547
static QString FreeScaling;
548
static QString KeepRatio;
549
static QString BreakRatio;
550
static QString EditContourLine;
551
static QString EditShape;
552
static QString ResetContourLine;
553
static QString AddPage;
554
static QString AddPages;
555
static QString DeletePage;
556
static QString DeletePages;
557
static QString AddLayer;
558
static QString DeleteLayer;
559
static QString RenameLayer;
560
static QString RaiseLayer;
561
static QString LowerLayer;
562
static QString SendToLayer;
563
static QString PrintLayer;
564
static QString DoNotPrintLayer;
565
static QString SetLayerName;
566
static QString GetImage;
567
static QString MultipleDuplicate;
568
static QString EditContour;
569
static QString ResetControlPoint;
570
static QString ResetControlPoints;
571
static QString ImageEffects;
576
* Icons for undo actions
579
/*** Icons for UndoObjects *******************************************/
580
static QPixmap *IImageFrame;
581
static QPixmap *ITextFrame;
582
static QPixmap *ILine;
583
static QPixmap *IPolygon;
584
static QPixmap *IPolyline;
585
static QPixmap *IPathText;
586
static QPixmap *IGroup;
587
static QPixmap *ILayer;
588
/*** Icons for actions ***********************************************/
589
static QPixmap *IMove;
590
static QPixmap *IResize;
591
static QPixmap *IRotate;
592
static QPixmap *IGuides;
593
static QPixmap *ILockGuides;
594
static QPixmap *IAlignDistribute;
595
static QPixmap *IFill;
596
static QPixmap *IShade;
597
static QPixmap *IFlipH;
598
static QPixmap *IFlipV;
599
static QPixmap *ILock;
600
static QPixmap *IUnLock;
601
static QPixmap *IEnablePrint;
602
static QPixmap *IDisablePrint;
603
static QPixmap *IDelete;
604
static QPixmap *ICreate;
605
static QPixmap *IPaste;
606
static QPixmap *ICut;
607
static QPixmap *ITransparency;
608
static QPixmap *ILineStyle;
609
static QPixmap *IArrow;
610
static QPixmap *ITable;
611
static QPixmap *IFont;
612
static QPixmap *ISVG;
613
static QPixmap *IEPS;
614
static QPixmap *IImportOOoDraw;
615
static QPixmap *IImageScaling;
616
static QPixmap *IBorder;
617
static QPixmap *IDocument;
618
static QPixmap *ILayerAction;
620
static QPixmap *IDown;
621
static QPixmap *IPrint;
622
static QPixmap *IGetImage;
623
static QPixmap *IMultipleDuplicate;
627
/** @brief Creates a new UndoManager instance */
630
/** @brief Destroys the UndoManager instance */
635
* @brief Take undo steps the given amount
637
* When an UndoGui is registered to the UndoManager gui's undo() signal
638
* is connected to this slot. Emitting an undo() signal will make the
639
* UndoManager perform undo actions the given number of steps.
640
* @param steps Number of undo actions to make
642
void doUndo(int steps);
645
* @brief Take redo steps the given amount
646
* @param steps Number of redo actions to make
647
* @sa UndoManager::doUndo(int steps)
649
void doRedo(int steps);
653
* @brief Updates strings when the GUI language is changed.
655
void languageChange();
658
* @brief Adds a new action to the undo stack.
660
* If _unodEnabled is true the action will be stored otherwise it will
661
* be just ignored. When a new action is added redo items from the stack
662
* will be removed and the current action will be set to the one which was
664
* @param target Source of the action. When undoing/redoing this action
665
* restore() method of this UndoObject will be called.
666
* @param state UndoSate describing the state (action).
667
* @param targetPixmap Is used to override the default target icon in this action.
669
void action(UndoObject* target, UndoState* state, QPixmap *targetPixmap = 0);
672
* @brief Adds a new action to the undo stack.
674
* If _unodEnabled is true the action will be stored otherwise it will
675
* be just ignored. When a new action is added redo items from the stack
676
* will be removed and the current action will be set to the one which was
678
* @param target Source of the action. When undoing/redoing this action
679
* restore() method of this UndoObject will be called.
680
* @param state UndoSate describing the state (action).
681
* @param targetName Is used to override the default target name in this action.
682
* @param targetPixmap Is used to override the default target icon in this action.
684
void action(UndoObject* target, UndoState* state, const QString &targetName, QPixmap *targetPixmap = 0);
687
* @brief Informs UndoManager to perform undo
689
* If an undo is wanted and the caller is not registered UndoGui this method
690
* can be used. Useful for example with the menu entry for undo.
691
* @param steps Number of undo steps to take
693
void undo(int steps);
696
* @brief Informs UndoManager to perform redo
697
* @param steps Number of redo steps to take
698
* @sa UndoManager::undo(int steps)
700
void redo(int steps);
703
* @brief Switches the state of UndoManager (global/object specific undo).
705
* If parameter uid is less than 0 global undo is used else the undo state
706
* is object specific using the object whose uid is given as a parameter.
707
* @param uid UndoObject's id for what the object specific undo is wanted or
708
* -1 if global undo is wanted.
710
void showObject(int uid);
713
* @brief Sets the length of the undo stack.
715
* Tells how many UndoStates are stored.
716
* @param steps number of UndoStates to store in the undo stack
718
void setHistoryLength(int steps);
722
* @brief Emitted when a new undo action is stored to the undo stack.
724
* This signal is connected to the registered UndoGuis for them to update the
725
* visual representation of the undo stack.
726
* @param target Source of the action
727
* @param state UndoState describing the action
729
void newAction(UndoObject* target, UndoState* state);
732
* @brief Emitted when an undo action has been done.
734
* It is connected to attached guis to inform them to update the visual
735
* representation of the undo stack. This signal will be also sent to the
736
* <code>UndoGui</code> where it came from.
737
* @param steps Number of steps to take
739
void undoSignal(int steps);
742
* @brief Emitted when a redo action has been done.
743
* @param steps Number of steps to take
744
* @sa UndoManager::undoSignal(int steps)
746
void redoSignal(int steps);
749
* @brief Emitted when a new actions comes in and UndoManager is in object
750
* @brief specific mode and action does not belong to the currently selected
756
* @brief This signal is used to notify registered UndoGui instances that
757
* @brief history limit is reached and the last item from the stack
758
* @brief representation should be removed.
763
* @brief This signal is emitted when all requested undo/redo actions have been done.
765
* It could be used in the application as a signal when the view can be rendered
766
* again after undo/redo.
772
typedef UndoManager Um;
added
removed
scribus/undomanager.h
