1 /************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27 28 #ifndef EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX 29 #define EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX 30 31 #include "propertyhandler.hxx" 32 33 /** === begin UNO includes === **/ 34 #include <com/sun/star/inspection/XObjectInspectorUI.hpp> 35 /** === end UNO includes === **/ 36 37 #include <map> 38 #include <set> 39 #include <memory> 40 41 //........................................................................ 42 namespace pcr 43 { 44 //........................................................................ 45 46 //==================================================================== 47 //= some helper types 48 //==================================================================== 49 50 struct MapHandlerToUI; 51 52 /** callback for an ComposedPropertyUIUpdate checking a given property for existence 53 */ 54 class SAL_NO_VTABLE IPropertyExistenceCheck 55 { 56 public: 57 virtual ::sal_Bool SAL_CALL hasPropertyByName( const ::rtl::OUString& _rName ) throw (::com::sun::star::uno::RuntimeException) = 0; 58 }; 59 60 //==================================================================== 61 //= ComposedPropertyUIUpdate 62 //==================================================================== 63 /** helper class composing requests to a ->XObjectInspectorUI interface, coming 64 from multiple sources 65 66 Usually, a handler tells the browser UI to enable to disable, or show or hide, certain 67 elements. Now when multiple handlers do this, their instructions must be combined: 68 If one handler disables a certain element, but others enable it, it must in the 69 result still be disabled. Similar for showing/hiding elements. 70 71 ->ComposedPropertyUIUpdate implements this combination. It does so by providing a dedicated 72 ->XObjectInspectorUI instance for every participating handler, and remembering the UI 73 state on a per-handler basis. Upon request (->fire), the combined UI state is 74 forwarded to another ->XObjectInspectorUI instance, the so-called delegator UI. 75 */ 76 class ComposedPropertyUIUpdate 77 { 78 private: 79 ::std::auto_ptr< MapHandlerToUI > m_pCollectedUIs; 80 ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI > 81 m_xDelegatorUI; 82 oslInterlockedCount m_nSuspendCounter; 83 IPropertyExistenceCheck* m_pPropertyCheck; 84 85 public: 86 /** constructs a ->ComposedPropertyUIUpdate instance 87 @param _rxDelegatorUI 88 a ->XObjectInspectorUI instance to which composed UI requests should be forwarded. Must 89 not be <NULL/>. 90 @param _pPropertyCheck 91 an instance checking properties for existence. If this is not <NULL/>, it will be invoked 92 whenever one of the ->XObjectInspectorUI methods is called, to check the passed property 93 name.<br/> 94 Beware of lifetime issues. The instance pointed to by <arg>_pPropertyCheck</arg> must 95 live at least as long as the ->ComposedPropertyUIUpdate instance you're going to create. 96 @throws ::com::sun::star::lang::NullPointerException 97 if ->_rxDelegatorUI is <NULL/> 98 */ 99 ComposedPropertyUIUpdate( 100 const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI >& _rxDelegatorUI, 101 IPropertyExistenceCheck* _pPropertyCheck ); 102 ~ComposedPropertyUIUpdate(); 103 104 /** returns the delegator UI 105 @throw ::com::sun::star::lang::DisposedException 106 */ 107 ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI > getDelegatorUI() const; 108 109 /** returns a ->XObjectInspectorUI instance belonging to a given property handler 110 111 In every call to an ->XPropertyHandler method which requires a ->XObjectInspectorUI, 112 the same UI instance should be used. The instance here will cache all requests passed 113 to it, and ->ComposedPropertyUIUpdate::fire will use the combination of all 114 cached UI states of all handlers to update the delegator UI. 115 */ 116 ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI > 117 getUIForPropertyHandler( const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XPropertyHandler >& _rxHandler ); 118 119 /** Suspends automatic firing of UI changes 120 121 normally, as soon as any of the property handlers does a request for an 122 arbitrary UI change, the set of collected UI changes is evaluated, and the combined 123 UI state is fired to the delegator UI. 124 125 You can disable this automatic firing by calling ->suspendAutoFire. As longs as auto 126 firing is suspended, only explicit ->fire calls trigger the notification to the 127 delegator UI. 128 129 Note that calls to ->suspendAutoFire are culmulative, that is, if you make multiple calls 130 they must be accompanied by an equal number of calls to ->resumeAutoFire, to enable 131 auto-firing again. 132 133 @seealso resumeAutoFire 134 */ 135 void SAL_CALL suspendAutoFire(); 136 137 /** Suspends automatic firing of UI changes 138 139 @seealso suspendAutoFire 140 */ 141 void SAL_CALL resumeAutoFire(); 142 143 /** disposes the instance, so it becomes non-functional. 144 145 All cached handlers and cached ->XObjectInspectorUI instances will be released, 146 the latter will also be disposed, so that if anybody still holds a reference to them 147 and tries to operate them will get a DisposedException. 148 */ 149 void SAL_CALL dispose(); 150 151 /** invokes m_pPropertyCheck to check whether a given property should be handled 152 */ 153 bool shouldContinuePropertyHandling( const ::rtl::OUString& _rName ) const; 154 155 private: 156 /// determines whether the instance is already disposed 157 inline bool impl_isDisposed() const { return m_pCollectedUIs.get() == NULL; } 158 159 /// throws an exception if the component is already disposed 160 void impl_checkDisposed() const; 161 162 /** fires the collected UI changes to our delegator UI 163 164 All operations for any elements are forwarded: 165 <ul><li>If an element has been hidden at least once, it's also hidden at the delegator UI.</li> 166 <li>If an element has been shown at least once, and never been hidden, it's also 167 shown at the delegator UI.</li> 168 <li>If an element has never been shown or hidden, it's also not touched at the delegator UI.</li> 169 <li>The same holds if you replace "hidden" in the last three items with "disabled", 170 and "shown" with "enabled".</li> 171 <li>If an element should have been rebuilt (->XObjectInspectorUI::rebuiltPropertyUI) 172 at least once, it's rebuilt at the delegator UI, too.<br/> 173 After that, the request to rebuild the UI for this property is cleared, so subsequent 174 calls to ->fire will not trigger an new rebuilt request. 175 </ul> 176 177 @precond 178 instance is not disposed 179 */ 180 void impl_fireAll_throw(); 181 182 /// fires the combination of ->XObjectInspectorUI::enablePropertyUI calls 183 void impl_fireEnablePropertyUI_throw(); 184 185 /// fires the combination of ->XObjectInspectorUI::enablePropertyUIElements calls 186 void impl_fireEnablePropertyUIElements_throw(); 187 188 /// fires the combination of ->XObjectInspectorUI::rebuildPropertyUI calls 189 void impl_fireRebuildPropertyUI_throw(); 190 191 /// fires the combination of ->XObjectInspectorUI::showPropertyUI and ->XObjectInspectorUI::hidePropertyUI calls 192 void impl_fireShowHidePropertyUI_throw(); 193 194 /// fires the combination of ->XObjectInspectorUI::showCategory calls 195 void impl_fireShowCategory_throw(); 196 197 /** callback for when a single property handler requested any change in the inspector UI 198 */ 199 void callback_inspectorUIChanged_throw(); 200 201 private: 202 ComposedPropertyUIUpdate(); // never implemented 203 ComposedPropertyUIUpdate( const ComposedPropertyUIUpdate& ); // never implemented 204 ComposedPropertyUIUpdate& operator=( const ComposedPropertyUIUpdate& ); // never implemented 205 }; 206 207 //==================================================================== 208 //= ComposedUIAutoFireGuard 209 //==================================================================== 210 class ComposedUIAutoFireGuard 211 { 212 private: 213 ComposedPropertyUIUpdate& m_rUIUpdate; 214 public: 215 ComposedUIAutoFireGuard( ComposedPropertyUIUpdate& _rUIUpdate ) 216 :m_rUIUpdate( _rUIUpdate ) 217 { 218 m_rUIUpdate.suspendAutoFire(); 219 } 220 ~ComposedUIAutoFireGuard() 221 { 222 m_rUIUpdate.resumeAutoFire(); 223 } 224 }; 225 226 //........................................................................ 227 } // namespace pcr 228 //........................................................................ 229 230 #endif // EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX 231 232