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