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