bump product version to 6.3.0.0.beta1
[LibreOffice.git] / extensions / source / propctrlr / composeduiupdate.hxx
blob7e3f9f128be62bcedf9e3284aaa45f2adb54c911
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
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/.
9 * This file incorporates work covered by the following license notice:
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 .
20 #ifndef INCLUDED_EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
21 #define INCLUDED_EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
23 #include "propertyhandler.hxx"
25 #include <com/sun/star/inspection/XObjectInspectorUI.hpp>
27 #include <map>
28 #include <set>
29 #include <memory>
32 namespace pcr
35 struct MapHandlerToUI;
37 /** callback for a ComposedPropertyUIUpdate checking a given property for existence
39 class SAL_NO_VTABLE IPropertyExistenceCheck
41 public:
42 /// @throws css::uno::RuntimeException
43 virtual bool hasPropertyByName( const OUString& _rName ) = 0;
45 protected:
46 ~IPropertyExistenceCheck() {}
49 /** helper class composing requests to a ->XObjectInspectorUI interface, coming
50 from multiple sources
52 Usually, a handler tells the browser UI to enable to disable, or show or hide, certain
53 elements. Now when multiple handlers do this, their instructions must be combined:
54 If one handler disables a certain element, but others enable it, it must in the
55 result still be disabled. Similar for showing/hiding elements.
57 ->ComposedPropertyUIUpdate implements this combination. It does so by providing a dedicated
58 ->XObjectInspectorUI instance for every participating handler, and remembering the UI
59 state on a per-handler basis. Upon request (->fire), the combined UI state is
60 forwarded to another ->XObjectInspectorUI instance, the so-called delegator UI.
62 class ComposedPropertyUIUpdate
64 private:
65 std::unique_ptr< MapHandlerToUI > m_pCollectedUIs;
66 css::uno::Reference< css::inspection::XObjectInspectorUI >
67 m_xDelegatorUI;
68 oslInterlockedCount m_nSuspendCounter;
69 IPropertyExistenceCheck* m_pPropertyCheck;
71 public:
72 /** constructs a ->ComposedPropertyUIUpdate instance
73 @param _rxDelegatorUI
74 a ->XObjectInspectorUI instance to which composed UI requests should be forwarded. Must
75 not be <NULL/>.
76 @param _pPropertyCheck
77 an instance checking properties for existence. If this is not <NULL/>, it will be invoked
78 whenever one of the ->XObjectInspectorUI methods is called, to check the passed property
79 name.<br/>
80 Beware of lifetime issues. The instance pointed to by <arg>_pPropertyCheck</arg> must
81 live at least as long as the ->ComposedPropertyUIUpdate instance you're going to create.
82 @throws css::lang::NullPointerException
83 if ->_rxDelegatorUI is <NULL/>
85 ComposedPropertyUIUpdate(
86 const css::uno::Reference< css::inspection::XObjectInspectorUI >& _rxDelegatorUI,
87 IPropertyExistenceCheck* _pPropertyCheck );
88 ~ComposedPropertyUIUpdate();
90 /** returns the delegator UI
91 @throw css::lang::DisposedException
93 css::uno::Reference< css::inspection::XObjectInspectorUI > const & getDelegatorUI() const;
95 /** returns a ->XObjectInspectorUI instance belonging to a given property handler
97 In every call to an ->XPropertyHandler method which requires a ->XObjectInspectorUI,
98 the same UI instance should be used. The instance here will cache all requests passed
99 to it, and ->ComposedPropertyUIUpdate::fire will use the combination of all
100 cached UI states of all handlers to update the delegator UI.
102 css::uno::Reference< css::inspection::XObjectInspectorUI >
103 getUIForPropertyHandler( const css::uno::Reference< css::inspection::XPropertyHandler >& _rxHandler );
105 /** Suspends automatic firing of UI changes
107 normally, as soon as any of the property handlers does a request for an
108 arbitrary UI change, the set of collected UI changes is evaluated, and the combined
109 UI state is fired to the delegator UI.
111 You can disable this automatic firing by calling ->suspendAutoFire. As longs as auto
112 firing is suspended, only explicit ->fire calls trigger the notification to the
113 delegator UI.
115 Note that calls to ->suspendAutoFire are cumulative, that is, if you make multiple calls
116 they must be accompanied by an equal number of calls to ->resumeAutoFire, to enable
117 auto-firing again.
119 @seealso resumeAutoFire
121 void suspendAutoFire();
123 /** Suspends automatic firing of UI changes
125 @seealso suspendAutoFire
127 void resumeAutoFire();
129 /** disposes the instance, so it becomes non-functional.
131 All cached handlers and cached ->XObjectInspectorUI instances will be released,
132 the latter will also be disposed, so that if anybody still holds a reference to them
133 and tries to operate them will get a DisposedException.
135 void dispose();
137 /** invokes m_pPropertyCheck to check whether a given property should be handled
139 bool shouldContinuePropertyHandling( const OUString& _rName ) const;
141 private:
142 /// determines whether the instance is already disposed
143 bool impl_isDisposed() const { return m_pCollectedUIs.get() == nullptr; }
145 /// throws an exception if the component is already disposed
146 void impl_checkDisposed() const;
148 /** fires the collected UI changes to our delegator UI
150 All operations for any elements are forwarded:
151 <ul><li>If an element has been hidden at least once, it's also hidden at the delegator UI.</li>
152 <li>If an element has been shown at least once, and never been hidden, it's also
153 shown at the delegator UI.</li>
154 <li>If an element has never been shown or hidden, it's also not touched at the delegator UI.</li>
155 <li>The same holds if you replace "hidden" in the last three items with "disabled",
156 and "shown" with "enabled".</li>
157 <li>If an element should have been rebuilt (->XObjectInspectorUI::rebuiltPropertyUI)
158 at least once, it's rebuilt at the delegator UI, too.<br/>
159 After that, the request to rebuild the UI for this property is cleared, so subsequent
160 calls to ->fire will not trigger a new rebuilt request.
161 </ul>
163 @precond
164 instance is not disposed
166 void impl_fireAll_throw();
168 /// fires the combination of ->XObjectInspectorUI::enablePropertyUI calls
169 void impl_fireEnablePropertyUI_throw();
171 /// fires the combination of ->XObjectInspectorUI::enablePropertyUIElements calls
172 void impl_fireEnablePropertyUIElements_throw();
174 /// fires the combination of ->XObjectInspectorUI::rebuildPropertyUI calls
175 void impl_fireRebuildPropertyUI_throw();
177 /// fires the combination of ->XObjectInspectorUI::showPropertyUI and ->XObjectInspectorUI::hidePropertyUI calls
178 void impl_fireShowHidePropertyUI_throw();
180 /// fires the combination of ->XObjectInspectorUI::showCategory calls
181 void impl_fireShowCategory_throw();
183 /** callback for when a single property handler requested any change in the inspector UI
185 void callback_inspectorUIChanged_throw();
187 private:
188 ComposedPropertyUIUpdate( const ComposedPropertyUIUpdate& ) = delete;
189 ComposedPropertyUIUpdate& operator=( const ComposedPropertyUIUpdate& ) = delete;
192 class ComposedUIAutoFireGuard
194 private:
195 ComposedPropertyUIUpdate& m_rUIUpdate;
196 public:
197 explicit ComposedUIAutoFireGuard( ComposedPropertyUIUpdate& _rUIUpdate )
198 :m_rUIUpdate( _rUIUpdate )
200 m_rUIUpdate.suspendAutoFire();
202 ~ComposedUIAutoFireGuard() COVERITY_NOEXCEPT_FALSE
204 m_rUIUpdate.resumeAutoFire();
209 } // namespace pcr
212 #endif // INCLUDED_EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
214 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */