extensions/source/propctrlr/composeduiupdate.hxx

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