extensions/source/propctrlr/composeduiupdate.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: composeduiupdate.hxx,v $
  10  * $Revision: 1.3 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
  32 #define EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
  33
  34 #include "propertyhandler.hxx"
  35
  36 /** === begin UNO includes === **/
  37 #include <com/sun/star/inspection/XObjectInspectorUI.hpp>
  38 /** === end UNO includes === **/
  39
  40 #include <map>
  41 #include <set>
  42 #include <memory>
  43
  44 //........................................................................
  45 namespace pcr
  46 {
  47 //........................................................................
  48
  49     //====================================================================
  50     //= some helper types
  51     //====================================================================
  52
  53     struct MapHandlerToUI;
  54
  55     /** callback for an ComposedPropertyUIUpdate checking a given property for existence
  56     */
  57     class SAL_NO_VTABLE IPropertyExistenceCheck
  58     {
  59     public:
  60         virtual ::sal_Bool SAL_CALL hasPropertyByName( const ::rtl::OUString& _rName ) throw (::com::sun::star::uno::RuntimeException) = 0;
  61     };
  62
  63     //====================================================================
  64     //= ComposedPropertyUIUpdate
  65     //====================================================================
  66     /** helper class composing requests to a ->XObjectInspectorUI interface, coming
  67         from multiple sources
  68
  69         Usually, a handler tells the browser UI to enable to disable, or show or hide, certain
  70         elements. Now when multiple handlers do this, their instructions must be combined:
  71         If one handler disables a certain element, but others enable it, it must in the
  72         result still be disabled. Similar for showing/hiding elements.
  73
  74         ->ComposedPropertyUIUpdate implements this combination. It does so by providing a dedicated
  75         ->XObjectInspectorUI instance for every participating handler, and remembering the UI
  76         state on a per-handler basis. Upon request (->fire), the combined UI state is
  77         forwarded to another ->XObjectInspectorUI instance, the so-called delegator UI.
  78     */
  79     class ComposedPropertyUIUpdate
  80     {
  81     private:
  82         ::std::auto_ptr< MapHandlerToUI >       m_pCollectedUIs;
  83         ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI >
  84                                                 m_xDelegatorUI;
  85         oslInterlockedCount                     m_nSuspendCounter;
  86         IPropertyExistenceCheck*                m_pPropertyCheck;
  87
  88     public:
  89         /** constructs a ->ComposedPropertyUIUpdate instance
  90             @param _rxDelegatorUI
  91                 a ->XObjectInspectorUI instance to which composed UI requests should be forwarded. Must
  92                 not be <NULL/>.
  93             @param _pPropertyCheck
  94                 an instance checking properties for existence. If this is not <NULL/>, it will be invoked
  95                 whenever one of the ->XObjectInspectorUI methods is called, to check the passed property
  96                 name.<br/>
  97                 Beware of lifetime issues. The instance pointed to by <arg>_pPropertyCheck</arg> must
  98                 live at least as long as the ->ComposedPropertyUIUpdate instance you're going to create.
  99             @throws ::com::sun::star::lang::NullPointerException
 100                 if ->_rxDelegatorUI is <NULL/>
 101         */
 102         ComposedPropertyUIUpdate(
 103             const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI >& _rxDelegatorUI,
 104             IPropertyExistenceCheck* _pPropertyCheck );
 105         ~ComposedPropertyUIUpdate();
 106
 107         /** returns the delegator UI
 108             @throw ::com::sun::star::lang::DisposedException
 109         */
 110         ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI > getDelegatorUI() const;
 111
 112         /** returns a ->XObjectInspectorUI instance belonging to a given property handler
 113
 114             In every call to an ->XPropertyHandler method which requires a ->XObjectInspectorUI,
 115             the same UI instance should be used. The instance here will cache all requests passed
 116             to it, and ->ComposedPropertyUIUpdate::fire will use the combination of all
 117             cached UI states of all handlers to update the delegator UI.
 118         */
 119         ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI >
 120             getUIForPropertyHandler( const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XPropertyHandler >& _rxHandler );
 121
 122         /** fires the collected UI changes to our delegator UI
 123
 124             All operations for any elements are forwarded:
 125             <ul><li>If an element has been hidden at least once, it's also hidden at the delegator UI.</li>
 126                 <li>If an element has been shown at least once, and never been hidden, it's also
 127                     shown at the delegator UI.</li>
 128                 <li>If an element has never been shown or hidden, it's also not touched at the delegator UI.</li>
 129                 <li>The same holds if you replace "hidden" in the last three items with "disabled",
 130                     and "shown" with "enabled".</li>
 131                 <li>If an element should have been rebuilt (->XObjectInspectorUI::rebuiltPropertyUI)
 132                     at least once, it's rebuilt at the delegator UI, too.<br/>
 133                     After that, the request to rebuild the UI for this property is cleared, so subsequent
 134                     calls to ->fire will not trigger an new rebuilt request.
 135             </ul>
 136
 137             @throws ::com::sun::star::lang::DisposedException
 138                 if ->dispose has been called previously
 139         */
 140         void SAL_CALL fire();
 141
 142         /** Suspends automatic firing of UI changes
 143
 144             normally, as soon as any of the property handlers does a request for an
 145             arbitrary UI change, the set of collected UI changes is evaluated, and the combined
 146             UI state is fired to the delegator UI.
 147
 148             You can disable this automatic firing by calling ->suspendAutoFire. As longs as auto
 149             firing is suspended, only explicit ->fire calls trigger the notification to the
 150             delegator UI.
 151
 152             Note that calls to ->suspendAutoFire are culmulative, that is, if you make multiple calls
 153             they must be accompanied by an equal number of calls to ->resumeAutoFire, to enable
 154             auto-firing again.
 155
 156             @seealso resumeAutoFire
 157         */
 158         void SAL_CALL suspendAutoFire();
 159
 160         /** Suspends automatic firing of UI changes
 161
 162             @seealso suspendAutoFire
 163         */
 164         void SAL_CALL resumeAutoFire();
 165
 166         /** disposes the instance, so it becomes non-functional.
 167
 168             All cached handlers and cached ->XObjectInspectorUI instances will be released,
 169             the latter will also be disposed, so that if anybody still holds a reference to them
 170             and tries to operate them will get a DisposedException.
 171         */
 172         void SAL_CALL dispose();
 173
 174         /** invokes m_pPropertyCheck to check whether a given property should be handled
 175         */
 176         bool shouldContinuePropertyHandling( const ::rtl::OUString& _rName ) const;
 177
 178     private:
 179         /// determines whether the instance is already disposed
 180         inline  bool impl_isDisposed() const { return m_pCollectedUIs.get() == NULL; }
 181
 182         /// throws an exception if the component is already disposed
 183                 void impl_checkDisposed() const;
 184
 185         /** fires all accumulated changes
 186             @precond
 187                 instance is not disposed
 188         */
 189         void    impl_fireAll_throw();
 190
 191         /// fires the combination of ->XObjectInspectorUI::enablePropertyUI calls
 192         void    impl_fireEnablePropertyUI_throw();
 193
 194         /// fires the combination of ->XObjectInspectorUI::enablePropertyUIElements calls
 195         void    impl_fireEnablePropertyUIElements_throw();
 196
 197         /// fires the combination of ->XObjectInspectorUI::rebuildPropertyUI calls
 198         void    impl_fireRebuildPropertyUI_throw();
 199
 200         /// fires the combination of ->XObjectInspectorUI::showPropertyUI and ->XObjectInspectorUI::hidePropertyUI calls
 201         void    impl_fireShowHidePropertyUI_throw();
 202
 203         /// fires the combination of ->XObjectInspectorUI::showCategory calls
 204         void    impl_fireShowCategory_throw();
 205
 206         /** callback for when a single property handler requested any change in the inspector UI
 207         */
 208         void    callback_inspectorUIChanged_throw();
 209
 210     private:
 211         ComposedPropertyUIUpdate();                                             // never implemented
 212         ComposedPropertyUIUpdate( const ComposedPropertyUIUpdate& );            // never implemented
 213         ComposedPropertyUIUpdate& operator=( const ComposedPropertyUIUpdate& ); // never implemented
 214     };
 215
 216     //====================================================================
 217     //= ComposedUIAutoFireGuard
 218     //====================================================================
 219     class ComposedUIAutoFireGuard
 220     {
 221     private:
 222         ComposedPropertyUIUpdate&   m_rUIUpdate;
 223     public:
 224         ComposedUIAutoFireGuard( ComposedPropertyUIUpdate& _rUIUpdate )
 225             :m_rUIUpdate( _rUIUpdate )
 226         {
 227             m_rUIUpdate.suspendAutoFire();
 228         }
 229         ~ComposedUIAutoFireGuard()
 230         {
 231             m_rUIUpdate.resumeAutoFire();
 232         }
 233     };
 234
 235 //........................................................................
 236 } // namespace pcr
 237 //........................................................................
 238
 239 #endif // EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
 240