include/framework/undomanagerhelper.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
  20 #ifndef INCLUDED_FRAMEWORK_UNDOMANAGERHELPER_HXX
  21 #define INCLUDED_FRAMEWORK_UNDOMANAGERHELPER_HXX
  22
  23 #include <framework/fwedllapi.h>
  24 #include <framework/iguard.hxx>
  25 #include <framework/imutex.hxx>
  26
  27 #include <com/sun/star/document/XUndoManager.hpp>
  28 #include <com/sun/star/util/XModifyListener.hpp>
  29
  30 #include <boost/scoped_ptr.hpp>
  31
  32 namespace svl
  33 {
  34     class IUndoManager;
  35 }
  36
  37 //......................................................................................................................
  38 namespace framework
  39 {
  40 //......................................................................................................................
  41
  42     //==================================================================================================================
  43     //= IMutexGuard
  44     //==================================================================================================================
  45     class SAL_NO_VTABLE IMutexGuard : public IGuard
  46     {
  47     public:
  48         /** returns the mutex guarded by the instance.
  49
  50             Even if the guard currently has not a lock on the mutex, this method must succeed.
  51         */
  52         virtual IMutex& getGuardedMutex() = 0;
  53
  54     protected:
  55         ~IMutexGuard() {}
  56     };
  57
  58     //==================================================================================================================
  59     //= IUndoManagerImplementation
  60     //==================================================================================================================
  61     class SAL_NO_VTABLE IUndoManagerImplementation
  62     {
  63     public:
  64         /** returns the IUndoManager interface to the actual Undo stack
  65
  66             @throws com::sun::star::lang::DisposedException
  67                 when the instance is already disposed, and no IUndoManager can be provided
  68
  69             @throws com::sun::star::lang::NotInitializedException
  70                 when the instance is not initialized, yet, and no IUndoManager can be provided
  71         */
  72         virtual ::svl::IUndoManager&    getImplUndoManager() = 0;
  73
  74         /** provides access to an UNO interface for the XUndoManager implementation. Used when throwing exceptions.
  75         */
  76         virtual ::com::sun::star::uno::Reference< ::com::sun::star::document::XUndoManager >
  77                                         getThis() = 0;
  78
  79     protected:
  80         ~IUndoManagerImplementation() {}
  81     };
  82
  83     //==================================================================================================================
  84     //= UndoManagerHelper
  85     //==================================================================================================================
  86     class UndoManagerHelper_Impl;
  87     /** helper class for implementing an XUndoManager
  88
  89         Several of the methods of the class take an IMutexGuard instance. It is assumed that this guard has a lock on
  90         its mutext at the moment the method is entered. The lock will be released before any notifications to the
  91         registered XUndoManagerListeners happen.
  92
  93         The following locking strategy is used for this mutex:
  94         <ul><li>Any notifications to the registered XUndoManagerListeners are after the guard has been cleared. i.e.
  95                 without the mutex being locked.</p>
  96             <li>Any calls into the <code>IUndoManager</code> implementation is made without the mutex being locked.
  97                 Note that this implies that the <code>IUndoManager</code> implementation must be thread-safe in itself
  98                 (which is true for the default implementation, SfxUndoManager).</li>
  99             <li>An exception to the previous item are the <member>IUndoManager::Undo</member> and
 100                 <member>IUndoManager::Redo</member> methods: They're called with the given external mutex being
 101                 locked.</li>
 102         </ul>
 103
 104         The reason for the exception for IUndoManager::Undo and IUndoManager::Redo is that those are expected to
 105         modify the actual document which the UndoManager works for. And as long as our documents are not thread-safe,
 106         and as long as we do not re-fit <strong>all</strong> existing SfxUndoImplementations to <em>not</em> expect
 107         the dreaded SolarMutex being locked when they're called, the above behavior is a compromise between "how it should
 108         be" and "how it can realistically be".
 109     */
 110     class FWE_DLLPUBLIC UndoManagerHelper
 111     {
 112     public:
 113         UndoManagerHelper( IUndoManagerImplementation& i_undoManagerImpl );
 114         ~UndoManagerHelper();
 115
 116         // life time control
 117         void disposing();
 118
 119         // XUndoManager equivalents
 120         void            enterUndoContext( const OUString& i_title, IMutexGuard& i_instanceLock );
 121         void            enterHiddenUndoContext( IMutexGuard& i_instanceLock );
 122         void            leaveUndoContext( IMutexGuard& i_instanceLock );
 123         void            addUndoAction( const ::com::sun::star::uno::Reference< ::com::sun::star::document::XUndoAction >& i_action, IMutexGuard& i_instanceLock );
 124         void            undo( IMutexGuard& i_instanceLock );
 125         void            redo( IMutexGuard& i_instanceLock );
 126         ::sal_Bool      isUndoPossible() const;
 127         ::sal_Bool      isRedoPossible() const;
 128         OUString getCurrentUndoActionTitle() const;
 129         OUString getCurrentRedoActionTitle() const;
 130         ::com::sun::star::uno::Sequence< OUString >
 131                         getAllUndoActionTitles() const;
 132         ::com::sun::star::uno::Sequence< OUString >
 133                         getAllRedoActionTitles() const;
 134         void            clear( IMutexGuard& i_instanceLock );
 135         void            clearRedo( IMutexGuard& i_instanceLock );
 136         void            reset( IMutexGuard& i_instanceLock );
 137         void            addUndoManagerListener( const ::com::sun::star::uno::Reference< ::com::sun::star::document::XUndoManagerListener >& i_listener );
 138         void            removeUndoManagerListener( const ::com::sun::star::uno::Reference< ::com::sun::star::document::XUndoManagerListener >& i_listener );
 139
 140         // XLockable, base of XUndoManager, equivalents
 141         void            lock();
 142         void            unlock();
 143         ::sal_Bool      isLocked();
 144
 145         // XModifyBroadcaster equivalents
 146         void            addModifyListener( const ::com::sun::star::uno::Reference< ::com::sun::star::util::XModifyListener >& i_listener );
 147         void            removeModifyListener( const ::com::sun::star::uno::Reference< ::com::sun::star::util::XModifyListener >& i_listener );
 148
 149     private:
 150         ::boost::scoped_ptr< UndoManagerHelper_Impl >   m_pImpl;
 151     };
 152
 153 //......................................................................................................................
 154 } // namespace framework
 155 //......................................................................................................................
 156
 157 #endif // INCLUDED_FRAMEWORK_UNDOMANAGERHELPER_HXX
 158
 159 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */