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 #ifndef INCLUDED_EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
  21 #define INCLUDED_EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
  22
  23 #include "propertyhandler.hxx"
  24
  25 #include <com/sun/star/inspection/XObjectInspectorUI.hpp>
  26
  27 #include <map>
  28 #include <set>
  29 #include <memory>
  30
  31
  32 namespace pcr
  33 {
  34
  35     struct MapHandlerToUI;
  36
  37     /** callback for a ComposedPropertyUIUpdate checking a given property for existence
  38     */
  39     class SAL_NO_VTABLE IPropertyExistenceCheck
  40     {
  41     public:
  42         /// @throws css::uno::RuntimeException
  43         virtual bool hasPropertyByName( const OUString& _rName ) = 0;
  44
  45     protected:
  46         ~IPropertyExistenceCheck() {}
  47     };
  48
  49     /** helper class composing requests to a ->XObjectInspectorUI interface, coming
  50         from multiple sources
  51
  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.
  56
  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.
  61     */
  62     class ComposedPropertyUIUpdate
  63     {
  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;
  70
  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/>
  84         */
  85         ComposedPropertyUIUpdate(
  86             const css::uno::Reference< css::inspection::XObjectInspectorUI >& _rxDelegatorUI,
  87             IPropertyExistenceCheck* _pPropertyCheck );
  88         ~ComposedPropertyUIUpdate();
  89
  90         /** returns the delegator UI
  91             @throw css::lang::DisposedException
  92         */
  93         css::uno::Reference< css::inspection::XObjectInspectorUI > const & getDelegatorUI() const;
  94
  95         /** returns a ->XObjectInspectorUI instance belonging to a given property handler
  96
  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.
 101         */
 102         css::uno::Reference< css::inspection::XObjectInspectorUI >
 103             getUIForPropertyHandler( const css::uno::Reference< css::inspection::XPropertyHandler >& _rxHandler );
 104
 105         /** Suspends automatic firing of UI changes
 106
 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.
 110
 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.
 114
 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.
 118
 119             @seealso resumeAutoFire
 120         */
 121         void suspendAutoFire();
 122
 123         /** Suspends automatic firing of UI changes
 124
 125             @seealso suspendAutoFire
 126         */
 127         void resumeAutoFire();
 128
 129         /** disposes the instance, so it becomes non-functional.
 130
 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.
 134         */
 135         void dispose();
 136
 137         /** invokes m_pPropertyCheck to check whether a given property should be handled
 138         */
 139         bool shouldContinuePropertyHandling( const OUString& _rName ) const;
 140
 141     private:
 142         /// determines whether the instance is already disposed
 143         bool impl_isDisposed() const { return m_pCollectedUIs.get() == nullptr; }
 144
 145         /// throws an exception if the component is already disposed
 146                 void impl_checkDisposed() const;
 147
 148         /** fires the collected UI changes to our delegator UI
 149
 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>
 162
 163             @precond
 164                 instance is not disposed
 165         */
 166         void    impl_fireAll_throw();
 167
 168         /// fires the combination of ->XObjectInspectorUI::enablePropertyUI calls
 169         void    impl_fireEnablePropertyUI_throw();
 170
 171         /// fires the combination of ->XObjectInspectorUI::enablePropertyUIElements calls
 172         void    impl_fireEnablePropertyUIElements_throw();
 173
 174         /// fires the combination of ->XObjectInspectorUI::rebuildPropertyUI calls
 175         void    impl_fireRebuildPropertyUI_throw();
 176
 177         /// fires the combination of ->XObjectInspectorUI::showPropertyUI and ->XObjectInspectorUI::hidePropertyUI calls
 178         void    impl_fireShowHidePropertyUI_throw();
 179
 180         /// fires the combination of ->XObjectInspectorUI::showCategory calls
 181         void    impl_fireShowCategory_throw();
 182
 183         /** callback for when a single property handler requested any change in the inspector UI
 184         */
 185         void    callback_inspectorUIChanged_throw();
 186
 187     private:
 188         ComposedPropertyUIUpdate( const ComposedPropertyUIUpdate& ) = delete;
 189         ComposedPropertyUIUpdate& operator=( const ComposedPropertyUIUpdate& ) = delete;
 190     };
 191
 192     class ComposedUIAutoFireGuard
 193     {
 194     private:
 195         ComposedPropertyUIUpdate&   m_rUIUpdate;
 196     public:
 197         explicit ComposedUIAutoFireGuard( ComposedPropertyUIUpdate& _rUIUpdate )
 198             :m_rUIUpdate( _rUIUpdate )
 199         {
 200             m_rUIUpdate.suspendAutoFire();
 201         }
 202         ~ComposedUIAutoFireGuard() COVERITY_NOEXCEPT_FALSE
 203         {
 204             m_rUIUpdate.resumeAutoFire();
 205         }
 206     };
 207
 208
 209 } // namespace pcr
 210
 211
 212 #endif // INCLUDED_EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
 213
 214 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */