INTEGRATION: CWS pbrwuno (1.1.2); FILE ADDED

2006/03/09 14:14:29 fs 1.1.2.6: #i62967# no UnknownPropertyExceptions at the XObjectInspectorUI anymore
2005/10/31 11:13:05 fs 1.1.2.5: teach the ComposedPropertyUIUpdate to handle missing properties
2005/10/17 08:38:37 fs 1.1.2.4: implement auto-firing for ComposedUIUpdate
2005/10/13 13:00:59 fs 1.1.2.3: #i53095# introduce an XObjectInspector/Model
2005/10/11 13:28:58 fs 1.1.2.2: #i53095# phase 3:
introduced XPropertyHandler and XObjectInspectorUI
same open issues as in previous phase
(plus probably some more, since not everything is tested, yet :-\)
2005/08/12 16:30:09 fs 1.1.2.1: - more fine-grained control in the IPropertyBrowserUI which elements
to enable or disable
- moved designing the SQL command into a dedicated handler
- some more reactions on actuating properties move to dedicated handlers
- *nearly* completed implementation of the "composed browser UI", which
collects and combines UI change requests (IPropertyBrowserUI)
(still missing: proper auto-firing)

1 files changed, 249 insertions, 0 deletions

diff --git a/extensions/source/propctrlr/composeduiupdate.hxx b/extensions/source/propctrlr/composeduiupdate.hxx
new file mode 100644
index 000000000000..a61cc2087fad
--- /dev/null
+++ b/extensions/source/propctrlr/composeduiupdate.hxx
@@ -0,0 +1,249 @@
+/*************************************************************************
+ *
+ *  OpenOffice.org - a multi-platform office productivity suite
+ *
+ *  $RCSfile: composeduiupdate.hxx,v $
+ *
+ *  $Revision: 1.2 $
+ *
+ *  last change: $Author: vg $ $Date: 2006-03-14 11:19:54 $
+ *
+ *  The Contents of this file are made available subject to
+ *  the terms of GNU Lesser General Public License Version 2.1.
+ *
+ *
+ *    GNU Lesser General Public License Version 2.1
+ *    =============================================
+ *    Copyright 2005 by Sun Microsystems, Inc.
+ *    901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *    This library is free software; you can redistribute it and/or
+ *    modify it under the terms of the GNU Lesser General Public
+ *    License version 2.1, as published by the Free Software Foundation.
+ *
+ *    This library is distributed in the hope that it will be useful,
+ *    but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *    Lesser General Public License for more details.
+ *
+ *    You should have received a copy of the GNU Lesser General Public
+ *    License along with this library; if not, write to the Free Software
+ *    Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *    MA  02111-1307  USA
+ *
+ ************************************************************************/
+
+#ifndef EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
+#define EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
+
+#ifndef EXTENSIONS_SOURCE_PROPCTRLR_PROPERTYHANDLER_HXX
+#include "propertyhandler.hxx"
+#endif
+
+/** === begin UNO includes === **/
+#ifndef _COM_SUN_STAR_INSPECTION_XOBJECTINSPECTORUI_HPP_
+#include <com/sun/star/inspection/XObjectInspectorUI.hpp>
+#endif
+/** === end UNO includes === **/
+
+#include <map>
+#include <set>
+#include <memory>
+
+//........................................................................
+namespace pcr
+{
+//........................................................................
+
+    //====================================================================
+    //= some helper types
+    //====================================================================
+
+    struct MapHandlerToUI;
+
+    /** callback for an ComposedPropertyUIUpdate checking a given property for existence
+    */
+    class SAL_NO_VTABLE IPropertyExistenceCheck
+    {
+    public:
+        virtual ::sal_Bool SAL_CALL hasPropertyByName( const ::rtl::OUString& _rName ) throw (::com::sun::star::uno::RuntimeException) = 0;
+    };
+
+    //====================================================================
+    //= ComposedPropertyUIUpdate
+    //====================================================================
+    /** helper class composing requests to a ->XObjectInspectorUI interface, coming
+        from multiple sources
+
+        Usually, a handler tells the browser UI to enable to disable, or show or hide, certain
+        elements. Now when multiple handlers do this, their instructions must be combined:
+        If one handler disables a certain element, but others enable it, it must in the
+        result still be disabled. Similar for showing/hiding elements.
+
+        ->ComposedPropertyUIUpdate implements this combination. It does so by providing a dedicated
+        ->XObjectInspectorUI instance for every participating handler, and remembering the UI
+        state on a per-handler basis. Upon request (->fire), the combined UI state is
+        forwarded to another ->XObjectInspectorUI instance, the so-called delegator UI.
+    */
+    class ComposedPropertyUIUpdate
+    {
+    private:
+        ::std::auto_ptr< MapHandlerToUI >       m_pCollectedUIs;
+        ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI >
+                                                m_xDelegatorUI;
+        oslInterlockedCount                     m_nSuspendCounter;
+        IPropertyExistenceCheck*                m_pPropertyCheck;
+
+    public:
+        /** constructs a ->ComposedPropertyUIUpdate instance
+            @param _rxDelegatorUI
+                a ->XObjectInspectorUI instance to which composed UI requests should be forwarded. Must
+                not be <NULL/>.
+            @param _pPropertyCheck
+                an instance checking properties for existence. If this is not <NULL/>, it will be invoked
+                whenever one of the ->XObjectInspectorUI methods is called, to check the passed property
+                name.<br/>
+                Beware of lifetime issues. The instance pointed to by <arg>_pPropertyCheck</arg> must
+                live at least as long as the ->ComposedPropertyUIUpdate instance you're going to create.
+            @throws ::com::sun::star::lang::NullPointerException
+                if ->_rxDelegatorUI is <NULL/>
+        */
+        ComposedPropertyUIUpdate(
+            const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI >& _rxDelegatorUI,
+            IPropertyExistenceCheck* _pPropertyCheck );
+        ~ComposedPropertyUIUpdate();
+
+        /** returns the delegator UI
+            @throw ::com::sun::star::lang::DisposedException
+        */
+        ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI > getDelegatorUI() const;
+
+        /** returns a ->XObjectInspectorUI instance belonging to a given property handler
+
+            In every call to an ->XPropertyHandler method which requires a ->XObjectInspectorUI,
+            the same UI instance should be used. The instance here will cache all requests passed
+            to it, and ->ComposedPropertyUIUpdate::fire will use the combination of all
+            cached UI states of all handlers to update the delegator UI.
+        */
+        ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI >
+            getUIForPropertyHandler( const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XPropertyHandler >& _rxHandler );
+
+        /** fires the collected UI changes to our delegator UI
+
+            All operations for any elements are forwarded:
+            <ul><li>If an element has been hidden at least once, it's also hidden at the delegator UI.</li>
+                <li>If an element has been shown at least once, and never been hidden, it's also
+                    shown at the delegator UI.</li>
+                <li>If an element has never been shown or hidden, it's also not touched at the delegator UI.</li>
+                <li>The same holds if you replace "hidden" in the last three items with "disabled",
+                    and "shown" with "enabled".</li>
+                <li>If an element should have been rebuilt (->XObjectInspectorUI::rebuiltPropertyUI)
+                    at least once, it's rebuilt at the delegator UI, too.<br/>
+                    After that, the request to rebuild the UI for this property is cleared, so subsequent
+                    calls to ->fire will not trigger an new rebuilt request.
+            </ul>
+
+            @throws ::com::sun::star::lang::DisposedException
+                if ->dispose has been called previously
+        */
+        void SAL_CALL fire();
+
+        /** Suspends automatic firing of UI changes
+
+            normally, as soon as any of the property handlers does a request for an
+            arbitrary UI change, the set of collected UI changes is evaluated, and the combined
+            UI state is fired to the delegator UI.
+
+            You can disable this automatic firing by calling ->suspendAutoFire. As longs as auto
+            firing is suspended, only explicit ->fire calls trigger the notification to the
+            delegator UI.
+
+            Note that calls to ->suspendAutoFire are culmulative, that is, if you make multiple calls
+            they must be accompanied by an equal number of calls to ->resumeAutoFire, to enable
+            auto-firing again.
+
+            @seealso resumeAutoFire
+        */
+        void SAL_CALL suspendAutoFire();
+
+        /** Suspends automatic firing of UI changes
+
+            @seealso suspendAutoFire
+        */
+        void SAL_CALL resumeAutoFire();
+
+        /** disposes the instance, so it becomes non-functional.
+
+            All cached handlers and cached ->XObjectInspectorUI instances will be released,
+            the latter will also be disposed, so that if anybody still holds a reference to them
+            and tries to operate them will get a DisposedException.
+        */
+        void SAL_CALL dispose();
+
+        /** invokes m_pPropertyCheck to check whether a given property should be handled
+        */
+        bool shouldContinuePropertyHandling( const ::rtl::OUString& _rName ) const;
+
+    private:
+        /// determines whether the instance is already disposed
+        inline  bool impl_isDisposed() const { return m_pCollectedUIs.get() == NULL; }
+
+        /// throws an exception if the component is already disposed
+                void impl_checkDisposed() const;
+
+        /** fires all accumulated changes
+            @precond
+                instance is not disposed
+        */
+        void    impl_fireAll_throw();
+
+        /// fires the combination of ->XObjectInspectorUI::enablePropertyUI calls
+        void    impl_fireEnablePropertyUI_throw();
+
+        /// fires the combination of ->XObjectInspectorUI::enablePropertyUIElements calls
+        void    impl_fireEnablePropertyUIElements_throw();
+
+        /// fires the combination of ->XObjectInspectorUI::rebuildPropertyUI calls
+        void    impl_fireRebuildPropertyUI_throw();
+
+        /// fires the combination of ->XObjectInspectorUI::showPropertyUI and ->XObjectInspectorUI::hidePropertyUI calls
+        void    impl_fireShowHidePropertyUI_throw();
+
+        /// fires the combination of ->XObjectInspectorUI::showCategory calls
+        void    impl_fireShowCategory_throw();
+
+        /** callback for when a single property handler requested any change in the inspector UI
+        */
+        void    callback_inspectorUIChanged_throw();
+
+    private:
+        ComposedPropertyUIUpdate();                                             // never implemented
+        ComposedPropertyUIUpdate( const ComposedPropertyUIUpdate& );            // never implemented
+        ComposedPropertyUIUpdate& operator=( const ComposedPropertyUIUpdate& ); // never implemented
+    };
+
+    //====================================================================
+    //= ComposedUIAutoFireGuard
+    //====================================================================
+    class ComposedUIAutoFireGuard
+    {
+    private:
+        ComposedPropertyUIUpdate&   m_rUIUpdate;
+    public:
+        ComposedUIAutoFireGuard( ComposedPropertyUIUpdate& _rUIUpdate )
+            :m_rUIUpdate( _rUIUpdate )
+        {
+            m_rUIUpdate.suspendAutoFire();
+        }
+        ~ComposedUIAutoFireGuard()
+        {
+            m_rUIUpdate.resumeAutoFire();
+        }
+    };
+
+//........................................................................
+} // namespace pcr
+//........................................................................
+
+#endif // EXTENSIONS_SOURCE_PROPCTRLR_COMPOSEDUIUPDATE_HXX
+