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