LCOV - code coverage report
Current view: top level - extensions/source/propctrlr - composeduiupdate.hxx (source / functions) Hit Total Coverage
Test: commit e02a6cb2c3e2b23b203b422e4e0680877f232636 Lines: 0 10 0.0 %
Date: 2014-04-14 Functions: 0 5 0.0 %
Legend: Lines: hit not hit

          Line data    Source code
       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           0 :     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           0 :         ~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           0 :         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           0 :         ComposedUIAutoFireGuard( ComposedPropertyUIUpdate& _rUIUpdate )
     209           0 :             :m_rUIUpdate( _rUIUpdate )
     210             :         {
     211           0 :             m_rUIUpdate.suspendAutoFire();
     212           0 :         }
     213           0 :         ~ComposedUIAutoFireGuard()
     214             :         {
     215           0 :             m_rUIUpdate.resumeAutoFire();
     216           0 :         }
     217             :     };
     218             : 
     219             : 
     220             : } // namespace pcr
     221             : 
     222             : 
     223             : #endif // EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
     224             : 
     225             : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */

Generated by: LCOV version 1.10