1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 #ifndef FRAMEWORK_UNDOMANAGERHELPER_HXX 23 #define FRAMEWORK_UNDOMANAGERHELPER_HXX 24 25 #include "framework/fwedllapi.h" 26 #include "framework/iguard.hxx" 27 #include "framework/imutex.hxx" 28 29 /** === begin UNO includes === **/ 30 #include <com/sun/star/document/XUndoManager.hpp> 31 #include <com/sun/star/util/XModifyListener.hpp> 32 /** === end UNO includes === **/ 33 34 #include <boost/scoped_ptr.hpp> 35 36 namespace svl 37 { 38 class IUndoManager; 39 } 40 41 //...................................................................................................................... 42 namespace framework 43 { 44 //...................................................................................................................... 45 46 //================================================================================================================== 47 //= IMutexGuard 48 //================================================================================================================== 49 class SAL_NO_VTABLE IMutexGuard : public IGuard 50 { 51 public: 52 /** returns the mutex guarded by the instance. 53 54 Even if the guard currently has not a lock on the mutex, this method must succeed. 55 */ 56 virtual IMutex& getGuardedMutex() = 0; 57 }; 58 59 //================================================================================================================== 60 //= IUndoManagerImplementation 61 //================================================================================================================== 62 class SAL_NO_VTABLE IUndoManagerImplementation 63 { 64 public: 65 /** returns the IUndoManager interface to the actual Undo stack 66 67 @throws com::sun::star::lang::DisposedException 68 when the instance is already disposed, and no IUndoManager can be provided 69 70 @throws com::sun::star::lang::NotInitializedException 71 when the instance is not initialized, yet, and no IUndoManager can be provided 72 */ 73 virtual ::svl::IUndoManager& getImplUndoManager() = 0; 74 75 /** provides access to an UNO interface for the XUndoManager implementation. Used when throwing exceptions. 76 */ 77 virtual ::com::sun::star::uno::Reference< ::com::sun::star::document::XUndoManager > 78 getThis() = 0; 79 }; 80 81 //================================================================================================================== 82 //= UndoManagerHelper 83 //================================================================================================================== 84 class UndoManagerHelper_Impl; 85 /** helper class for implementing an XUndoManager 86 87 Several of the methods of the class take an IMutexGuard instance. It is assumed that this guard has a lock on 88 its mutex at the moment the method is entered. The lock will be released before any notifications to the 89 registered XUndoManagerListeners happen. 90 91 The following locking strategy is used for this mutex: 92 <ul><li>Any notifications to the registered XUndoManagerListeners are after the guard has been cleared. i.e. 93 without the mutex being locked.</p> 94 <li>Any calls into the <code>IUndoManager</code> implementation is made without the mutex being locked. 95 Note that this implies that the <code>IUndoManager</code> implementation must be thread-safe in itself 96 (which is true for the default implementation, SfxUndoManager).</li> 97 <li>An exception to the previous item are the <member>IUndoManager::Undo</member> and 98 <member>IUndoManager::Redo</member> methods: They're called with the given external mutex being 99 locked.</li> 100 </ul> 101 102 The reason for the exception for IUndoManager::Undo and IUndoManager::Redo is that those are expected to 103 modify the actual document which the UndoManager works for. And as long as our documents are not thread-safe, 104 and as long as we do not re-fit <strong>all</strong> existing SfxUndoImplementations to <em>not</em> expect 105 the dreaded SolarMutex being locked when they're called, the above behavior is a compromise between "how it should 106 be" and "how it can realistically be". 107 */ 108 class FWE_DLLPUBLIC UndoManagerHelper 109 { 110 public: 111 UndoManagerHelper( IUndoManagerImplementation& i_undoManagerImpl ); 112 ~UndoManagerHelper(); 113 114 // life time control 115 void disposing(); 116 117 // XUndoManager equivalents 118 void enterUndoContext( const ::rtl::OUString& i_title, IMutexGuard& i_instanceLock ); 119 void enterHiddenUndoContext( IMutexGuard& i_instanceLock ); 120 void leaveUndoContext( IMutexGuard& i_instanceLock ); 121 void addUndoAction( const ::com::sun::star::uno::Reference< ::com::sun::star::document::XUndoAction >& i_action, IMutexGuard& i_instanceLock ); 122 void undo( IMutexGuard& i_instanceLock ); 123 void redo( IMutexGuard& i_instanceLock ); 124 ::sal_Bool isUndoPossible() const; 125 ::sal_Bool isRedoPossible() const; 126 ::rtl::OUString getCurrentUndoActionTitle() const; 127 ::rtl::OUString getCurrentRedoActionTitle() const; 128 ::com::sun::star::uno::Sequence< ::rtl::OUString > 129 getAllUndoActionTitles() const; 130 ::com::sun::star::uno::Sequence< ::rtl::OUString > 131 getAllRedoActionTitles() const; 132 void clear( IMutexGuard& i_instanceLock ); 133 void clearRedo( IMutexGuard& i_instanceLock ); 134 void reset( IMutexGuard& i_instanceLock ); 135 void addUndoManagerListener( const ::com::sun::star::uno::Reference< ::com::sun::star::document::XUndoManagerListener >& i_listener ); 136 void removeUndoManagerListener( const ::com::sun::star::uno::Reference< ::com::sun::star::document::XUndoManagerListener >& i_listener ); 137 138 // XLockable, base of XUndoManager, equivalents 139 void lock(); 140 void unlock(); 141 ::sal_Bool isLocked(); 142 143 // XModifyBroadcaster equivalents 144 void addModifyListener( const ::com::sun::star::uno::Reference< ::com::sun::star::util::XModifyListener >& i_listener ); 145 void removeModifyListener( const ::com::sun::star::uno::Reference< ::com::sun::star::util::XModifyListener >& i_listener ); 146 147 private: 148 ::boost::scoped_ptr< UndoManagerHelper_Impl > m_pImpl; 149 }; 150 151 //...................................................................................................................... 152 } // namespace framework 153 //...................................................................................................................... 154 155 #endif // FRAMEWORK_UNDOMANAGERHELPER_HXX 156 157 /* vim: set noet sw=4 ts=4: */ 158