include/svl/undo.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef INCLUDED_SVL_UNDO_HXX
  20 #define INCLUDED_SVL_UNDO_HXX
  21
  22 #include <svl/svldllapi.h>
  23 #include <rtl/ustring.hxx>
  24
  25 #include <limits>
  26 #include <memory>
  27
  28 struct MarkedUndoAction;
  29
  30 class SVL_DLLPUBLIC SfxRepeatTarget
  31 {
  32 public:
  33     virtual             ~SfxRepeatTarget() = 0;
  34 };
  35
  36
  37 class SVL_DLLPUBLIC SfxUndoContext
  38 {
  39 public:
  40     virtual             ~SfxUndoContext() = 0;
  41 };
  42
  43
  44 class SfxLinkUndoAction;
  45
  46 class SVL_DLLPUBLIC SfxUndoAction
  47 {
  48 private:
  49     SfxLinkUndoAction*      mpSfxLinkUndoAction;
  50
  51 public:
  52                             SfxUndoAction();
  53     virtual                 ~SfxUndoAction();
  54
  55     virtual void SetLinkToSfxLinkUndoAction(SfxLinkUndoAction* pSfxLinkUndoAction);
  56
  57     virtual void            Undo();
  58     virtual void            UndoWithContext( SfxUndoContext& i_context );
  59     virtual void            Redo();
  60     virtual void            RedoWithContext( SfxUndoContext& i_context );
  61     virtual void            Repeat(SfxRepeatTarget&);
  62     virtual bool            CanRepeat(SfxRepeatTarget&) const;
  63
  64     virtual bool            Merge( SfxUndoAction *pNextAction );
  65
  66     virtual OUString    GetComment() const;
  67     virtual OUString    GetRepeatComment(SfxRepeatTarget&) const;
  68     virtual sal_uInt16  GetId() const;
  69     virtual void dumpAsXml(struct _xmlTextWriter* pWriter) const;
  70
  71 private:
  72     SfxUndoAction( const SfxUndoAction& ) = delete;
  73     SfxUndoAction& operator=( const SfxUndoAction& ) = delete;
  74 };
  75
  76
  77 /// is a mark on the Undo stack
  78 typedef sal_Int32 UndoStackMark;
  79 #define MARK_INVALID    ::std::numeric_limits< UndoStackMark >::max()
  80
  81 class SVL_DLLPUBLIC SfxUndoActions
  82 {
  83     struct Impl;
  84     std::unique_ptr<Impl> mpImpl;
  85
  86 public:
  87     SfxUndoActions();
  88     SfxUndoActions( const SfxUndoActions& r );
  89     ~SfxUndoActions();
  90
  91     bool empty() const;
  92     size_t size() const;
  93
  94     const MarkedUndoAction& operator[]( size_t i ) const;
  95     MarkedUndoAction& operator[]( size_t i );
  96
  97     const SfxUndoAction* GetUndoAction( size_t i ) const;
  98     SfxUndoAction* GetUndoAction( size_t i );
  99
 100     void Remove( size_t i_pos );
 101     void Remove( size_t i_pos, size_t i_count );
 102     void Insert( SfxUndoAction* i_action, size_t i_pos );
 103 };
 104
 105 /** do not make use of these implementation details, unless you
 106     really really have to! */
 107 struct SVL_DLLPUBLIC SfxUndoArray
 108 {
 109     SfxUndoActions          aUndoActions;
 110     size_t                  nMaxUndoActions;
 111     size_t                  nCurUndoAction;
 112     SfxUndoArray            *pFatherUndoArray;
 113                             SfxUndoArray(size_t nMax=0):
 114                                 nMaxUndoActions(nMax), nCurUndoAction(0),
 115                                 pFatherUndoArray(nullptr) {}
 116     virtual ~SfxUndoArray();
 117 };
 118
 119
 120 /** do not make use of these implementation details, unless you
 121     really really have to! */
 122 class SVL_DLLPUBLIC SfxListUndoAction : public SfxUndoAction, public SfxUndoArray
 123
 124 /*  [Explanation]
 125
 126     UndoAction to composite multiple Undos in one UndoAction.
 127     These actions are used by SfxUndomanager. With < SfxUndoManager::EnterListAction >
 128     you can go one composite level down and with < SfxUndoManager::LeaveListAction > up again.
 129     Redo and Undo work element wise on SfxListUndoActions.
 130 */
 131 {
 132     struct Impl;
 133     std::unique_ptr<Impl> mpImpl;
 134
 135 public:
 136
 137     SfxListUndoAction(
 138         const OUString &rComment, const OUString& rRepeatComment, sal_uInt16 nId, SfxUndoArray *pFather );
 139     virtual ~SfxListUndoAction();
 140
 141     virtual void            Undo() override;
 142     virtual void            UndoWithContext( SfxUndoContext& i_context ) override;
 143     virtual void            Redo() override;
 144     virtual void            RedoWithContext( SfxUndoContext& i_context ) override;
 145     virtual void            Repeat(SfxRepeatTarget&) override;
 146     virtual bool            CanRepeat(SfxRepeatTarget&) const override;
 147
 148     virtual bool            Merge( SfxUndoAction *pNextAction ) override;
 149
 150     virtual OUString        GetComment() const override;
 151     virtual OUString        GetRepeatComment(SfxRepeatTarget&) const override;
 152     virtual sal_uInt16      GetId() const override;
 153
 154     void SetComment(const OUString& rComment);
 155     void dumpAsXml(struct _xmlTextWriter* pWriter) const override;
 156 };
 157
 158
 159 /**  is a callback interface for notifications about state changes of an SfxUndoManager
 160 */
 161 class SAL_NO_VTABLE SfxUndoListener
 162 {
 163 public:
 164     virtual void actionUndone( const OUString& i_actionComment ) = 0;
 165     virtual void actionRedone( const OUString& i_actionComment ) = 0;
 166     virtual void undoActionAdded( const OUString& i_actionComment ) = 0;
 167     virtual void cleared() = 0;
 168     virtual void clearedRedo() = 0;
 169     virtual void resetAll() = 0;
 170     virtual void listActionEntered( const OUString& i_comment ) = 0;
 171     virtual void listActionLeft( const OUString& i_comment ) = 0;
 172     virtual void listActionCancelled() = 0;
 173     virtual void undoManagerDying() = 0;
 174
 175 protected:
 176     ~SfxUndoListener() {}
 177 };
 178
 179
 180 namespace svl
 181 {
 182     class SAL_NO_VTABLE SAL_DLLPUBLIC_RTTI IUndoManager
 183     {
 184     public:
 185         static bool const CurrentLevel = true;
 186         static bool const TopLevel = false;
 187
 188         virtual                 ~IUndoManager() { };
 189
 190         virtual void            SetMaxUndoActionCount( size_t nMaxUndoActionCount ) = 0;
 191         virtual size_t          GetMaxUndoActionCount() const = 0;
 192
 193         virtual void            AddUndoAction( SfxUndoAction *pAction, bool bTryMerg=false ) = 0;
 194
 195         virtual size_t          GetUndoActionCount( bool const i_currentLevel = CurrentLevel ) const = 0;
 196         virtual sal_uInt16      GetUndoActionId() const = 0;
 197         virtual OUString        GetUndoActionComment( size_t nNo=0, bool const i_currentLevel = CurrentLevel ) const = 0;
 198         virtual SfxUndoAction*  GetUndoAction( size_t nNo=0 ) const = 0;
 199
 200         virtual size_t          GetRedoActionCount( bool const i_currentLevel = CurrentLevel ) const = 0;
 201         virtual OUString        GetRedoActionComment( size_t nNo=0, bool const i_currentLevel = CurrentLevel ) const = 0;
 202         virtual SfxUndoAction*  GetRedoAction() const = 0;
 203
 204         virtual bool            Undo() = 0;
 205         virtual bool            Redo() = 0;
 206
 207         /** clears both the Redo and the Undo stack.
 208
 209             Will assert and bail out when called while within a list action (<member>IsInListAction</member>).
 210         */
 211         virtual void            Clear() = 0;
 212
 213         /** clears the Redo stack.
 214
 215             Will assert and bail out when called while within a list action (<member>IsInListAction</member>).
 216         */
 217         virtual void            ClearRedo() = 0;
 218
 219         /** leaves any possible open list action (<member>IsInListAction</member>), and clears both the Undo and the
 220             Redo stack.
 221
 222             Effectively, calling this method is equivalent to <code>while ( IsInListAction() ) LeaveListAction();</code>,
 223             followed by <code>Clear()</code>. The only difference to this calling sequence is that Reset is an
 224             atomic operation, also resulting in only one notification.
 225         */
 226         virtual void            Reset() = 0;
 227
 228         /** determines whether an Undo or Redo is currently running
 229         */
 230         virtual bool            IsDoing() const = 0;
 231
 232         virtual size_t          GetRepeatActionCount() const = 0;
 233         virtual OUString        GetRepeatActionComment( SfxRepeatTarget &rTarget) const = 0;
 234         virtual bool            Repeat( SfxRepeatTarget &rTarget ) = 0;
 235         virtual bool            CanRepeat( SfxRepeatTarget &rTarget ) const = 0;
 236
 237         virtual void            EnterListAction(const OUString &rComment, const OUString& rRepeatComment, sal_uInt16 nId=0) = 0;
 238
 239         /** leaves the list action entered with EnterListAction
 240             @return the number of the sub actions in the list which has just been left. Note that in case no such
 241                 actions exist, the list action does not contribute to the Undo stack, but is silently removed.
 242         */
 243         virtual size_t          LeaveListAction() = 0;
 244
 245         /** leaves the list action entered with EnterListAction, and forcefully merges the previous
 246             action on the stack into the newly created list action.
 247
 248             Say you have an Undo action A on the stack, then call EnterListAction, followed by one or more calls to
 249             AddUndoAction, followed by a call to LeaveAndMergeListAction. In opposite to LeaveListAction, your Undo
 250             stack will now still contain one undo action: the newly created list action, whose first child is the
 251             original A, whose other children are those you added via AddUndoAction, and whose comment is the same as
 252             the comment of A.
 253
 254             Effectively, this means that all actions added between EnterListAction and LeaveAndMergeListAction are
 255             hidden from the user.
 256
 257             @return the number of the sub actions in the list which has just been left. Note that in case no such
 258                 actions exist, the list action does not contribute to the Undo stack, but is silently removed.
 259         */
 260         virtual size_t          LeaveAndMergeListAction() = 0;
 261
 262         /// determines whether we're within a ListAction context, i.e. a LeaveListAction/LeaveAndMergeListAction call is pending
 263         virtual bool            IsInListAction() const = 0;
 264
 265         /// determines how many nested list actions are currently open
 266         virtual size_t          GetListActionDepth() const = 0;
 267
 268         /** clears the redo stack and removes the top undo action */
 269         virtual void            RemoveLastUndoAction() = 0;
 270
 271         /** enables (true) or disables (false) recording of undo actions
 272
 273             If undo actions are added while undo is disabled, they are deleted.
 274             Disabling undo does not clear the current undo buffer!
 275
 276             Multiple calls to <code>EnableUndo</code> are not cumulative. That is, calling <code>EnableUndo( false )</code>
 277             twice, and then calling <code>EnableUndo( true )</code> means that Undo is enable afterwards.
 278         */
 279         virtual void            EnableUndo( bool bEnable ) = 0;
 280
 281         // returns true if undo is currently enabled
 282         // This returns false if undo was disabled using EnableUndo( false ) and
 283         // also during the runtime of the Undo() and Redo() methods.
 284         virtual bool            IsUndoEnabled() const = 0;
 285
 286         /// adds a new listener to be notified about changes in the UndoManager's state
 287         virtual void            AddUndoListener( SfxUndoListener& i_listener ) = 0;
 288         virtual void            RemoveUndoListener( SfxUndoListener& i_listener ) = 0;
 289    };
 290 }
 291
 292
 293 namespace svl { namespace undo { namespace impl
 294 {
 295     class UndoManagerGuard;
 296     class LockGuard;
 297 } } }
 298
 299 struct SfxUndoManager_Data;
 300 class SVL_DLLPUBLIC SfxUndoManager : public ::svl::IUndoManager
 301 {
 302     friend class SfxLinkUndoAction;
 303
 304     std::unique_ptr< SfxUndoManager_Data >
 305                             m_xData;
 306 public:
 307                             SfxUndoManager( size_t nMaxUndoActionCount = 20 );
 308     virtual                 ~SfxUndoManager();
 309
 310     // IUndoManager overridables
 311     virtual void            SetMaxUndoActionCount( size_t nMaxUndoActionCount ) override;
 312     virtual size_t          GetMaxUndoActionCount() const override;
 313     virtual void            AddUndoAction( SfxUndoAction *pAction, bool bTryMerg=false ) override;
 314     virtual size_t          GetUndoActionCount( bool const i_currentLevel = CurrentLevel ) const override;
 315     virtual sal_uInt16      GetUndoActionId() const override;
 316     virtual OUString        GetUndoActionComment( size_t nNo=0, bool const i_currentLevel = CurrentLevel ) const override;
 317     virtual SfxUndoAction*  GetUndoAction( size_t nNo=0 ) const override;
 318     virtual size_t          GetRedoActionCount( bool const i_currentLevel = CurrentLevel ) const override;
 319     virtual OUString        GetRedoActionComment( size_t nNo=0, bool const i_currentLevel = CurrentLevel ) const override;
 320     virtual SfxUndoAction*  GetRedoAction() const override;
 321     virtual bool            Undo() override;
 322     virtual bool            Redo() override;
 323     virtual void            Clear() override;
 324     virtual void            ClearRedo() override;
 325     virtual void            Reset() override;
 326     virtual bool            IsDoing() const override;
 327     virtual size_t          GetRepeatActionCount() const override;
 328     virtual OUString        GetRepeatActionComment( SfxRepeatTarget &rTarget) const override;
 329     virtual bool            Repeat( SfxRepeatTarget &rTarget ) override;
 330     virtual bool            CanRepeat( SfxRepeatTarget &rTarget ) const override;
 331     virtual void            EnterListAction(const OUString &rComment, const OUString& rRepeatComment, sal_uInt16 nId=0) override;
 332     virtual size_t          LeaveListAction() override;
 333     virtual size_t          LeaveAndMergeListAction() override;
 334     virtual bool            IsInListAction() const override;
 335     virtual size_t          GetListActionDepth() const override;
 336     virtual void            RemoveLastUndoAction() override;
 337     virtual void            EnableUndo( bool bEnable ) override;
 338     virtual bool            IsUndoEnabled() const override;
 339     virtual void            AddUndoListener( SfxUndoListener& i_listener ) override;
 340     virtual void            RemoveUndoListener( SfxUndoListener& i_listener ) override;
 341
 342     /** marks the current top-level element of the Undo stack, and returns a unique ID for it
 343     */
 344     UndoStackMark   MarkTopUndoAction();
 345
 346     /** removes a mark given by its ID.
 347         After the call, the mark ID is invalid.
 348     */
 349     void            RemoveMark( UndoStackMark const i_mark );
 350
 351     /** determines whether the top action on the Undo stack has a given mark
 352     */
 353     bool            HasTopUndoActionMark( UndoStackMark const i_mark );
 354
 355     /** removes the oldest Undo actions from the stack
 356     */
 357     void            RemoveOldestUndoAction();
 358
 359     void dumpAsXml(struct _xmlTextWriter* pWriter) const;
 360
 361 protected:
 362     bool    UndoWithContext( SfxUndoContext& i_context );
 363     bool    RedoWithContext( SfxUndoContext& i_context );
 364
 365     void    ImplClearRedo_NoLock( bool const i_currentLevel );
 366
 367     /** clears all undo actions on the current level, plus all undo actions on superordinate levels,
 368         as soon as those levels are reached.
 369
 370         If no list action is active currently, i.e. we're on the top level already, this method is equivalent to
 371         ->Clear.
 372
 373         Otherwise, the Undo actions on the current level are removed. Upon leaving the current list action, all
 374         undo actions on the then-current level are removed, too. This is continued until the top level is reached.
 375     */
 376     void    ClearAllLevels();
 377
 378 private:
 379     size_t  ImplLeaveListAction( const bool i_merge, ::svl::undo::impl::UndoManagerGuard& i_guard );
 380     bool    ImplAddUndoAction_NoNotify( SfxUndoAction* pAction, bool bTryMerge, bool bClearRedo, ::svl::undo::impl::UndoManagerGuard& i_guard );
 381     void    ImplClearRedo( ::svl::undo::impl::UndoManagerGuard& i_guard, bool const i_currentLevel );
 382     void    ImplClearUndo( ::svl::undo::impl::UndoManagerGuard& i_guard );
 383     void    ImplClearCurrentLevel_NoNotify( ::svl::undo::impl::UndoManagerGuard& i_guard );
 384     size_t  ImplGetRedoActionCount_Lock( bool const i_currentLevel = CurrentLevel ) const;
 385     bool    ImplIsUndoEnabled_Lock() const;
 386     bool    ImplIsInListAction_Lock() const;
 387     void    ImplEnableUndo_Lock( bool const i_enable );
 388
 389     bool ImplUndo( SfxUndoContext* i_contextOrNull );
 390     bool ImplRedo( SfxUndoContext* i_contextOrNull );
 391
 392     friend class ::svl::undo::impl::LockGuard;
 393 };
 394
 395
 396 class SVL_DLLPUBLIC SfxLinkUndoAction : public SfxUndoAction
 397
 398 /*  [Explanation]
 399
 400     SfxLinkUndoAction is used to link two SfxUndoManager. The Undo/Redos inserted
 401     in the first SfxUndoManager redirect their Undo/Redo to the second. With this it
 402     does not matter, if the undo/redo initially was on the first or the second.
 403
 404     After inserting SfxLinkUndoAction on the first SfxUndoManager, you have to
 405     insert it on the second as well. While the second SfxUndoManager is steered
 406     from the first, you must not insert neither Actions nor issue a  undo/redo
 407     command to the second, while it is steered by the first.
 408 */
 409
 410 {
 411 private:
 412     friend class SfxUndoAction;
 413     void LinkedSfxUndoActionDestructed(const SfxUndoAction& rCandidate);
 414
 415 public:
 416                             SfxLinkUndoAction(::svl::IUndoManager *pManager);
 417                             virtual ~SfxLinkUndoAction();
 418
 419     virtual void            Undo() override;
 420     virtual void            Redo() override;
 421     virtual bool            CanRepeat(SfxRepeatTarget& r) const override;
 422
 423     virtual void            Repeat(SfxRepeatTarget&r) override;
 424
 425     virtual OUString        GetComment() const override;
 426     virtual OUString        GetRepeatComment(SfxRepeatTarget&r) const override;
 427     virtual sal_uInt16      GetId() const override;
 428
 429     SfxUndoAction*          GetAction() const { return pAction; }
 430
 431 protected:
 432     ::svl::IUndoManager*    pUndoManager;
 433     SfxUndoAction*          pAction;
 434
 435 };
 436
 437 #endif
 438
 439 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */