merged tag ooo/OOO330_m14
[LibreOffice.git] / extensions / source / propctrlr / composeduiupdate.hxx
blobd9ae3e0aa76e0ec2edae7e6e9f74c2a7ece4394a
1 /*************************************************************************
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
7 * OpenOffice.org - a multi-platform office productivity suite
9 * This file is part of OpenOffice.org.
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.
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).
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.
26 ************************************************************************/
28 #ifndef EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
29 #define EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
31 #include "propertyhandler.hxx"
33 /** === begin UNO includes === **/
34 #include <com/sun/star/inspection/XObjectInspectorUI.hpp>
35 /** === end UNO includes === **/
37 #include <map>
38 #include <set>
39 #include <memory>
41 //........................................................................
42 namespace pcr
44 //........................................................................
46 //====================================================================
47 //= some helper types
48 //====================================================================
50 struct MapHandlerToUI;
52 /** callback for an ComposedPropertyUIUpdate checking a given property for existence
54 class SAL_NO_VTABLE IPropertyExistenceCheck
56 public:
57 virtual ::sal_Bool SAL_CALL hasPropertyByName( const ::rtl::OUString& _rName ) throw (::com::sun::star::uno::RuntimeException) = 0;
60 //====================================================================
61 //= ComposedPropertyUIUpdate
62 //====================================================================
63 /** helper class composing requests to a ->XObjectInspectorUI interface, coming
64 from multiple sources
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.
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.
76 class ComposedPropertyUIUpdate
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;
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/>
99 ComposedPropertyUIUpdate(
100 const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI >& _rxDelegatorUI,
101 IPropertyExistenceCheck* _pPropertyCheck );
102 ~ComposedPropertyUIUpdate();
104 /** returns the delegator UI
105 @throw ::com::sun::star::lang::DisposedException
107 ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI > getDelegatorUI() const;
109 /** returns a ->XObjectInspectorUI instance belonging to a given property handler
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.
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 );
119 /** Suspends automatic firing of UI changes
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.
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.
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.
133 @seealso resumeAutoFire
135 void SAL_CALL suspendAutoFire();
137 /** Suspends automatic firing of UI changes
139 @seealso suspendAutoFire
141 void SAL_CALL resumeAutoFire();
143 /** disposes the instance, so it becomes non-functional.
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.
149 void SAL_CALL dispose();
151 /** invokes m_pPropertyCheck to check whether a given property should be handled
153 bool shouldContinuePropertyHandling( const ::rtl::OUString& _rName ) const;
155 private:
156 /// determines whether the instance is already disposed
157 inline bool impl_isDisposed() const { return m_pCollectedUIs.get() == NULL; }
159 /// throws an exception if the component is already disposed
160 void impl_checkDisposed() const;
162 /** fires the collected UI changes to our delegator UI
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>
177 @precond
178 instance is not disposed
180 void impl_fireAll_throw();
182 /// fires the combination of ->XObjectInspectorUI::enablePropertyUI calls
183 void impl_fireEnablePropertyUI_throw();
185 /// fires the combination of ->XObjectInspectorUI::enablePropertyUIElements calls
186 void impl_fireEnablePropertyUIElements_throw();
188 /// fires the combination of ->XObjectInspectorUI::rebuildPropertyUI calls
189 void impl_fireRebuildPropertyUI_throw();
191 /// fires the combination of ->XObjectInspectorUI::showPropertyUI and ->XObjectInspectorUI::hidePropertyUI calls
192 void impl_fireShowHidePropertyUI_throw();
194 /// fires the combination of ->XObjectInspectorUI::showCategory calls
195 void impl_fireShowCategory_throw();
197 /** callback for when a single property handler requested any change in the inspector UI
199 void callback_inspectorUIChanged_throw();
201 private:
202 ComposedPropertyUIUpdate(); // never implemented
203 ComposedPropertyUIUpdate( const ComposedPropertyUIUpdate& ); // never implemented
204 ComposedPropertyUIUpdate& operator=( const ComposedPropertyUIUpdate& ); // never implemented
207 //====================================================================
208 //= ComposedUIAutoFireGuard
209 //====================================================================
210 class ComposedUIAutoFireGuard
212 private:
213 ComposedPropertyUIUpdate& m_rUIUpdate;
214 public:
215 ComposedUIAutoFireGuard( ComposedPropertyUIUpdate& _rUIUpdate )
216 :m_rUIUpdate( _rUIUpdate )
218 m_rUIUpdate.suspendAutoFire();
220 ~ComposedUIAutoFireGuard()
222 m_rUIUpdate.resumeAutoFire();
226 //........................................................................
227 } // namespace pcr
228 //........................................................................
230 #endif // EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX