INTEGRATION: CWS eforms4 (1.2.6); FILE MERGED

2004/12/29 10:52:48 fs 1.2.6.3: #i39451# support for property change notifications
2004/12/29 10:17:35 fs 1.2.6.2: #i10000# unxsols4 didn't like the throw specifications in function declarations being template arguments
2004/12/28 09:38:05 fs 1.2.6.1: #i39451# derive from another PropertySet helper class, which also allows listener handling

forms/source/xforms/propertysetbase.hxx

@@ -2,9 +2,9 @@
  *
  *  $RCSfile: propertysetbase.hxx,v $
  *
- *  $Revision: 1.2 $
+ *  $Revision: 1.3 $
  *
- *  last change: $Author: obo $ $Date: 2004-11-16 10:55:54 $
+ *  last change: $Author: vg $ $Date: 2005-03-23 11:38:25 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -65,10 +65,16 @@
 // include for parent class
 #include <cppuhelper/weak.hxx>
 #include <com/sun/star/lang/XTypeProvider.hpp>
-#include <comphelper/propertysethelper.hxx>
+#include <comphelper/propstate.hxx>
+#include <comphelper/propertysetinfo.hxx>
+#include <comphelper/proparrhlp.hxx>
+#include <rtl/ref.hxx>
 
 // include for inlined helper function below
 #include <com/sun/star/lang/IllegalArgumentException.hpp>
+#include <com/sun/star/beans/PropertyAttribute.hpp>
+
+#include <map>
 
 // forward declarations for method arguments
 namespace com { namespace sun { namespace star { namespace uno {
@@ -78,99 +84,320 @@ namespace com { namespace sun { namespace star { namespace uno {
         template<class T> class Sequence;
 } } } }
 
+/** base class which encapsulates accessing (reading/writing) concrete property values
+*/
+class PropertyAccessorBase : public ::rtl::IReference
+{
+private:
+    oslInterlockedCount m_refCount;
 
+protected:
+    PropertyAccessorBase() : m_refCount( 0 ) { }
 
-/** turn PropertySetHelper into a full UNO object.
- * PropertySetBase can be used with ImplInheritanceHelper classes.
- */
-class PropertySetBase : public cppu::OWeakObject,
-                        public com::sun::star::lang::XTypeProvider,
-                        public comphelper::PropertySetHelper
+public:
+    virtual oslInterlockedCount SAL_CALL acquire();
+    virtual oslInterlockedCount SAL_CALL release();
+
+    virtual bool    approveValue( const com::sun::star::uno::Any& rValue ) const = 0;
+    virtual void    setValue( const com::sun::star::uno::Any& rValue ) = 0;
+    virtual void    getValue( com::sun::star::uno::Any& rValue ) const = 0;
+    virtual bool    isWriteable() const = 0;
+};
+
+
+/** helper class for implementing property accessors through public member functions
+*/
+template< typename CLASS, typename VALUE, class WRITER, class READER >
+class GenericPropertyAccessor : public PropertyAccessorBase
 {
 public:
-    PropertySetBase();
-    PropertySetBase( comphelper::PropertySetInfo* pInfo ) throw();
-    virtual ~PropertySetBase() throw();
+    typedef WRITER  Writer;
+    typedef READER  Reader;
+
+private:
+    CLASS*      m_pInstance;
+    Writer      m_pWriter;
+    Reader      m_pReader;
 
-    virtual void SAL_CALL acquire() throw();
-    virtual void SAL_CALL release() throw();
+public:
+    GenericPropertyAccessor( CLASS* pInstance, Writer pWriter, Reader pReader )
+        :m_pInstance( pInstance )
+        ,m_pWriter( pWriter )
+        ,m_pReader( pReader )
+    {
+    }
 
-    virtual com::sun::star::uno::Any SAL_CALL queryInterface(
-        com::sun::star::uno::Type const & rType )
-        throw( com::sun::star::uno::RuntimeException);
+    virtual bool    approveValue( const com::sun::star::uno::Any& rValue ) const
+    {
+        VALUE aVal;
+        return ( rValue >>= aVal );
+    }
 
-    virtual com::sun::star::uno::Sequence<com::sun::star::uno::Type> SAL_CALL getTypes() throw( com::sun::star::uno::RuntimeException );
+    virtual void    setValue( const com::sun::star::uno::Any& rValue )
+    {
+        VALUE aTypedVal;
+        OSL_VERIFY( rValue >>= aTypedVal );
+        (m_pInstance->*m_pWriter)( aTypedVal );
+    }
 
-    virtual com::sun::star::uno::Sequence<sal_Int8> SAL_CALL getImplementationId() throw( com::sun::star::uno::RuntimeException );
+    virtual void getValue( com::sun::star::uno::Any& rValue ) const
+    {
+        rValue = com::sun::star::uno::makeAny( (m_pInstance->*m_pReader)() );
+    }
 
+    virtual bool isWriteable() const
+    {
+        return m_pWriter != NULL;
+    }
 };
 
-/** helper function template; set a property value through a member function */
-template<typename CLASS, typename VALUE>
-void setAny( CLASS* pObject,
-             void (CLASS::*pMethod)(const VALUE&),
-             const com::sun::star::uno::Any& rAny )
+/** helper class for implementing property accessors via non-UNO methods
+*/
+template< typename CLASS, typename VALUE >
+class DirectPropertyAccessor
+    :public GenericPropertyAccessor < CLASS
+                                , VALUE
+                                , void (CLASS::*)( const VALUE& )
+                                , VALUE (CLASS::*)() const
+                                >
 {
-    VALUE aVal;
-    if( rAny >>= aVal )
-        (pObject->*pMethod)( aVal );
-    else
-        throw com::sun::star::lang::IllegalArgumentException();
-}
-
-template<typename CLASS>
-void setAny( CLASS* pObject,
-             void (CLASS::*pMethod)(bool),
-             const com::sun::star::uno::Any& rAny )
+protected:
+    typedef void (CLASS::*Writer)( const VALUE& );
+    typedef VALUE (CLASS::*Reader)() const;
+public:
+    DirectPropertyAccessor( CLASS* pInstance, Writer pWriter, Reader pReader )
+        :GenericPropertyAccessor< CLASS, VALUE, Writer, Reader >( pInstance, pWriter, pReader )
+    {
+    }
+};
+
+/** helper class for implementing non-UNO accessors to a boolean property
+*/
+template< typename CLASS, typename DUMMY >
+class BooleanPropertyAccessor
+    :public GenericPropertyAccessor < CLASS
+                                , bool
+                                , void (CLASS::*)( bool )
+                                , bool (CLASS::*)() const
+                                >
 {
-    bool bVal;
-    if( rAny >>= bVal )
-        (pObject->*pMethod)( bVal );
-    else
-        throw com::sun::star::lang::IllegalArgumentException();
-}
-
-/** helper function template; get a property value through a member function */
-template<typename CLASS, typename VALUE>
-void getAny( const CLASS* pObject,
-             VALUE (CLASS::*pMethod)() const,
-             com::sun::star::uno::Any& rAny )
+protected:
+    typedef void (CLASS::*Writer)( bool );
+    typedef bool (CLASS::*Reader)() const;
+public:
+    BooleanPropertyAccessor( CLASS* pInstance, Writer pWriter, Reader pReader )
+        :GenericPropertyAccessor< CLASS, bool, Writer, Reader >( pInstance, pWriter, pReader )
+    {
+    }
+};
+
+/** helper class for implementing property accessors via UNO methods
+*/
+template< typename CLASS, typename VALUE >
+class APIPropertyAccessor
+    :public GenericPropertyAccessor < CLASS
+                                    , VALUE
+                                    , void (SAL_CALL CLASS::*)( const VALUE& )
+                                    , VALUE (SAL_CALL CLASS::*)()
+                                    >
 {
-    rAny <<= (pObject->*pMethod)();
-}
+protected:
+    typedef void (SAL_CALL CLASS::*Writer)( const VALUE& );
+    typedef VALUE (SAL_CALL CLASS::*Reader)();
+public:
+    APIPropertyAccessor( CLASS* pInstance, Writer pWriter, Reader pReader )
+        :GenericPropertyAccessor< CLASS, VALUE, Writer, Reader >( pInstance, pWriter, pReader )
+    {
+    }
+};
 
+/** bridges two XPropertySet helper implementations
 
-#ifdef _MSC_VER
+    The <type scope="comphelper">OStatefulPropertySet</type> (basically, the
+    <type scope="cppu">OPropertySetHelper</type>) implements a comprehensive framework
+    for property sets, including property change notifications.
+    However, it lacks some easy possibilities to declare the supported properties.
+    Other helper structs and classes allow for this, but are lacking needed features
+    such as property change notifications.
 
-/* With the MS Windows compiler, we make use of the SAL_CALL macro for
- * different calling conventions for normal and API methods. To
- * support these, the following templates are copies of the templates
- * above, except with SAL_CALL.
- *
- * To porters: This applies to any platform that uses SAL_CALL. If you
- * have such a platform, add it to the ifdef above.
+    The <type>PropertySetBase</type> bridges various implementations,
+    so you have the best of both worlds.
  */
-
-template<typename CLASS, typename VALUE>
-void setAny( CLASS* pObject,
-             void (SAL_CALL CLASS::*pMethod)(const VALUE&),
-             const com::sun::star::uno::Any& rAny )
+class PropertySetBase : public comphelper::OStatefulPropertySet
 {
-    VALUE aVal;
-    if( rAny >>= aVal )
-        (pObject->*pMethod)( aVal );
-    else
-        throw com::sun::star::lang::IllegalArgumentException();
-}
-#endif // _MSC_VER
-
-template<typename CLASS, typename VALUE>
-void getAny( CLASS* pObject,
-             VALUE (SAL_CALL CLASS::*pMethod)(),
-             com::sun::star::uno::Any& rAny )
+private:
+    typedef com::sun::star::uno::Any    Any_t;
+
+    typedef ::std::map< const sal_Int32, ::rtl::Reference< PropertyAccessorBase > >     PropertyAccessors;
+    typedef ::std::vector< ::com::sun::star::beans::Property >                          PropertyArray;
+    typedef ::std::map< const sal_Int32, Any_t >                                        PropertyValueCache;
+
+    PropertyArray                   m_aProperties;
+    cppu::IPropertyArrayHelper*     m_pProperties;
+    PropertyAccessors               m_aAccessors;
+    PropertyValueCache              m_aCache;
+
+protected:
+    PropertySetBase();
+    virtual ~PropertySetBase();
+
+    /** registers a new property to be supported by this instance
+        @param rProperty
+            the descriptor for the to-be-supported property
+        @param rAccessor
+            an instance which is able to provide read and possibly write access to
+            the property.
+        @precond
+            Must not be called after any of the property set related UNO interfaces
+            has been used. Usually, you will do a number of <member>registerProperty</member>
+            calls in the constructor of your class.
+    */
+    void registerProperty(
+        const com::sun::star::beans::Property& rProperty,
+        const ::rtl::Reference< PropertyAccessorBase >& rAccessor
+    );
+
+    /** notifies a change in a given property value, if necessary
+
+        The necessity of the notification is determined by a cached value for the given
+        property. Caching happens after notification.
+
+        That is, when you call <member>notifyAndCachePropertyValue</member> for the first time,
+        a value for the given property is default constructed, and considered to be the "old value".
+        If this value differs from the current value, then this change is notified to all interested
+        listeners. Finally, the current value is remembered.
+
+        Subsequent calls to <member>notifyAndCachePropertyValue</member> use the remembered value as
+        "old value", and from then on behave as the first call.
+
+        @param nHandle
+            the handle of the property. Must denote a property supported by this instance, i.e.
+            one previously registered via <member>registerProperty</member>.
+
+        @precond
+            our ref count must not be 0. The reason is that during this method's execution,
+            the instance might be acquired and released, which would immediately destroy
+            the instance if it has a ref count of 0.
+
+        @seealso initializePropertyValueCache
+    */
+    void notifyAndCachePropertyValue( sal_Int32 nHandle );
+
+    /** initializes the property value cache for the given property, with its current value
+
+        Usually used to initialize the cache with values which are different from default
+        constructed values. Say you have a boolean property whose initial state
+        is <TRUE/>. Say you call <member>notifyAndCachePropertyValue</member> the first time: it will
+        default construct the "old value" for this property as <FALSE/>, and thus <b>not</b> do
+        any notifications if the "current value" is also <FALSE/> - which might be wrong, since
+        the guessing of the "old value" differed from the real initial value which was <TRUE/>.
+
+        Too confusing? Okay, than just call this method for every property you have.
+
+        @param nHandle
+            the handle of the property. Must denote a property supported by this instance, i.e.
+            one previously registered via <member>registerProperty</member>.
+        @param rValue
+            the value to cache
+        @seealso notifyAndCachePropertyValue
+    */
+    void initializePropertyValueCache( sal_Int32 nHandle );
+
+    /// OPropertysetHelper methods
+    virtual sal_Bool SAL_CALL convertFastPropertyValue( Any_t& rConvertedValue, Any_t& rOldValue, sal_Int32 nHandle, const Any_t& rValue )
+        throw (::com::sun::star::lang::IllegalArgumentException);
+    virtual void SAL_CALL setFastPropertyValue_NoBroadcast( sal_Int32 nHandle, const Any_t& rValue )
+        throw (::com::sun::star::uno::Exception);
+    virtual void SAL_CALL getFastPropertyValue( Any_t& rValue, sal_Int32 nHandle ) const;
+
+    virtual cppu::IPropertyArrayHelper& SAL_CALL getInfoHelper();
+    virtual ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySetInfo > SAL_CALL getPropertySetInfo(  ) throw(::com::sun::star::uno::RuntimeException);
+
+public:
+    /// helper struct for granting selective access to some notification-related methods
+    struct NotifierAccess { friend struct PropertyChangeNotifier; private: NotifierAccess() { } };
+    /** retrieves the current property value for the given handle
+        @param nHandle
+            the handle of the property. Must denote a property supported by this instance, i.e.
+            one previously registered via <member>registerProperty</member>.
+        @see registerProperty
+    */
+    inline void getCurrentPropertyValueByHandle( sal_Int32 nHandle, Any_t& /* [out] */ rValue, const NotifierAccess& ) const
+    {
+        getFastPropertyValue( rValue, nHandle );
+    }
+
+    /** notifies a change in a given property to all interested listeners
+    */
+    inline void notifyPropertyChange( sal_Int32 nHandle, const Any_t& rOldValue, const Any_t& rNewValue, const NotifierAccess& ) const
+    {
+        const_cast< PropertySetBase* >( this )->firePropertyChange( nHandle, rNewValue, rOldValue );
+    }
+
+private:
+    /** locates a property given by handle
+        @param nHandle
+            the handle of the property. Must denote a property supported by this instance, i.e.
+            one previously registered via <member>registerProperty</member>.
+        @see registerProperty
+    */
+    PropertyAccessorBase& locatePropertyHandler( sal_Int32 nHandle ) const;
+};
+
+/** a helper class for notifying property changes in a <type>PropertySetBase</type> instance.
+
+    You can create an instance of this class on the stack of a method which is to programmatically
+    change the value of a property. In its constructor, the instance will acquire the current property
+    value, and in its destructor, it will notify the change of this property's value (if necessary).
+
+    You do not need this class if you are modifying property values by using the X(Fast|Multi)PropertSet
+    methods, since those already care for property notifications. You only need it if you're changing
+    the internal representation of your property directly.
+
+    Also note that usually, notifications in the UNO world should be done without a locked mutex. So
+    if you use this class in conjunction with a <type>MutexGuard</type>, ensure that you <b>first</b>
+    instantiate the <type>PropertyChangeNotifier</type>, and <b>then</b> the <type>MutexGuard</type>,
+    so your mutex is released before the notification happens.
+*/
+struct PropertyChangeNotifier
 {
-    rAny <<= (pObject->*pMethod)();
-}
+private:
+    const PropertySetBase&      m_rPropertySet;
+    sal_Int32                   m_nHandle;
+    com::sun::star::uno::Any    m_aOldValue;
+
+public:
+    /** constructs a PropertyChangeNotifier
+        @param rPropertySet
+            the property set implementation whose property is going to be changed. Note
+            that this property set implementation must live at least as long as the
+            PropertyChangeNotifier instance does.
+        @param nHandle
+            the handle of the property which is going to be changed. Must be a valid property
+            handle for the given <arg>rPropertySet</arg>
+    */
+    inline PropertyChangeNotifier( const PropertySetBase& rPropertySet, sal_Int32 nHandle )
+        :m_rPropertySet( rPropertySet )
+        ,m_nHandle( nHandle )
+    {
+        m_rPropertySet.getCurrentPropertyValueByHandle( m_nHandle, m_aOldValue, PropertySetBase::NotifierAccess() );
+    }
+    inline ~PropertyChangeNotifier()
+    {
+        com::sun::star::uno::Any aNewValue;
+        m_rPropertySet.getCurrentPropertyValueByHandle( m_nHandle, aNewValue, PropertySetBase::NotifierAccess() );
+        if ( aNewValue != m_aOldValue )
+        {
+            m_rPropertySet.notifyPropertyChange( m_nHandle, m_aOldValue, aNewValue, PropertySetBase::NotifierAccess() );
+        }
+    }
+};
+
 
+#define PROPERTY_FLAGS( NAME, TYPE, FLAG ) com::sun::star::beans::Property( \
+    ::rtl::OUString( #NAME, sizeof( #NAME ) - 1, RTL_TEXTENCODING_ASCII_US ), \
+    HANDLE_##NAME, getCppuType( static_cast< TYPE* >( NULL ) ), FLAG )
+#define PROPERTY( NAME, TYPE )      PROPERTY_FLAGS( NAME, TYPE, com::sun::star::beans::PropertyAttribute::BOUND )
+#define PROPERTY_RO( NAME, TYPE )   PROPERTY_FLAGS( NAME, TYPE, com::sun::star::beans::PropertyAttribute::BOUND | com::sun::star::beans::PropertyAttribute::READONLY )
 
 #endif