include/comphelper/propagg.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 INCLUDED_COMPHELPER_PROPAGG_HXX
  21 #define INCLUDED_COMPHELPER_PROPAGG_HXX
  22
  23 #include <com/sun/star/uno/XAggregation.hpp>
  24 #include <comphelper/propstate.hxx>
  25 #include <comphelper/comphelperdllapi.h>
  26
  27 #include <map>
  28
  29
  30 //= property helper classes
  31
  32
  33
  34 namespace comphelper
  35 {
  36
  37
  38
  39 //= OPropertyAccessor
  40 //= internal helper class for OPropertyArrayAggregationHelper
  41
  42 namespace internal
  43 {
  44     struct OPropertyAccessor
  45     {
  46         sal_Int32   nOriginalHandle;
  47         sal_Int32   nPos;
  48         bool        bAggregate;
  49
  50         OPropertyAccessor(sal_Int32 _nOriginalHandle, sal_Int32 _nPos, bool _bAggregate)
  51             :nOriginalHandle(_nOriginalHandle) ,nPos(_nPos) ,bAggregate(_bAggregate) { }
  52         OPropertyAccessor()
  53             :nOriginalHandle(-1) ,nPos(-1) ,bAggregate(false) { }
  54
  55         bool operator==(const OPropertyAccessor& rOb) const { return nPos == rOb.nPos; }
  56         bool operator <(const OPropertyAccessor& rOb) const { return nPos < rOb.nPos; }
  57     };
  58
  59     typedef std::map< sal_Int32, OPropertyAccessor, ::std::less< sal_Int32 > >  PropertyAccessorMap;
  60     typedef PropertyAccessorMap::iterator           PropertyAccessorMapIterator;
  61     typedef PropertyAccessorMap::const_iterator     ConstPropertyAccessorMapIterator;
  62 }
  63
  64
  65 /**
  66  * used as callback for a OPropertyArrayAggregationHelper
  67  */
  68 class IPropertyInfoService
  69 {
  70 public:
  71     /** get the preferred handle for the given property
  72         @param      _rName      the property name
  73         @return                 the handle the property should be referred by, or -1 if there are no
  74                                 preferences for the given property
  75     */
  76     virtual sal_Int32           getPreferredPropertyId(const OUString& _rName) = 0;
  77
  78 protected:
  79     ~IPropertyInfoService() {}
  80 };
  81
  82 /**
  83  * used for implementing an cppu::IPropertyArrayHelper for classes
  84  * aggregating property sets
  85  */
  86
  87 #define DEFAULT_AGGREGATE_PROPERTY_ID   10000
  88
  89 class COMPHELPER_DLLPUBLIC OPropertyArrayAggregationHelper: public ::cppu::IPropertyArrayHelper
  90 {
  91     friend class OPropertySetAggregationHelper;
  92 protected:
  93
  94     ::com::sun::star::uno::Sequence< ::com::sun::star::beans::Property> m_aProperties;
  95     internal::PropertyAccessorMap           m_aPropertyAccessors;
  96
  97 public:
  98     /** construct the object.
  99         @param  _rProperties    the properties of the object doing the aggregation. These properties
 100                                 are used without any checks, so the caller has to ensure that the names and
 101                                 handles are valid.
 102         @param  _rAggProperties the properties of the aggregate, usually got via an call to getProperties on the
 103                                 XPropertySetInfo of the aggregate.
 104                                 The names of the properties are used without any checks, so the caller has to ensure
 105                                 that there are no doubles.
 106                                 The handles are stored for later quick access, but the outside-handles the
 107                                 aggregate properties get depend from the following two parameters.
 108         @param  _pInfoService
 109                                 If not NULL, the object pointed to is used to calc handles which should be used
 110                                 for referring the aggregate's properties from outside.
 111                                 If one of the properties returned from the info service conflict with other handles
 112                                 alread present (e.g. through _rProperties), the property is handled as if -1 was returned.
 113                                 If NULL (or, for a special property, a call to getPreferredPropertyId returns -1),
 114                                 the aggregate property(ies) get a new handle which they can be referred by from outside.
 115         @param  _nFirstAggregateId
 116                                 if the object is about to create new handles for the aggregate properties, it uses
 117                                 id's ascending from this given id.
 118                                 No checks are made if the handle range determined by _nFirstAggregateId conflicts with other
 119                                 handles within _rProperties.
 120     */
 121     OPropertyArrayAggregationHelper(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::Property>& _rProperties,
 122                                     const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::Property>& _rAggProperties,
 123                                     IPropertyInfoService* _pInfoService = NULL,
 124                                     sal_Int32 _nFirstAggregateId = DEFAULT_AGGREGATE_PROPERTY_ID);
 125
 126
 127     /// inherited from IPropertyArrayHelper
 128     virtual sal_Bool SAL_CALL fillPropertyMembersByHandle( OUString* _pPropName, sal_Int16* _pAttributes,
 129                                             sal_Int32 _nHandle) SAL_OVERRIDE ;
 130
 131     /// inherited from IPropertyArrayHelper
 132     virtual ::com::sun::star::uno::Sequence< ::com::sun::star::beans::Property> SAL_CALL getProperties() SAL_OVERRIDE;
 133     /// inherited from IPropertyArrayHelper
 134     virtual ::com::sun::star::beans::Property SAL_CALL getPropertyByName(const OUString& _rPropertyName)
 135                                 throw(::com::sun::star::beans::UnknownPropertyException) SAL_OVERRIDE;
 136
 137     /// inherited from IPropertyArrayHelper
 138     virtual sal_Bool  SAL_CALL hasPropertyByName(const OUString& _rPropertyName) SAL_OVERRIDE ;
 139     /// inherited from IPropertyArrayHelper
 140     virtual sal_Int32 SAL_CALL getHandleByName(const OUString & _rPropertyName) SAL_OVERRIDE;
 141     /// inherited from IPropertyArrayHelper
 142     virtual sal_Int32 SAL_CALL fillHandles( /*out*/sal_Int32* _pHandles, const ::com::sun::star::uno::Sequence< OUString >& _rPropNames ) SAL_OVERRIDE;
 143
 144     /** returns information about a property of the aggregate.
 145         @param  _pPropName          points to a string to receive the property name. No name is returned if this is NULL.
 146         @param  _pOriginalHandle    points to a sal_Int32 to receive the original property handle. No original handle is returned
 147                                     if this is NULL.
 148         @param  _nHandle            the handle of the property as got by, for instance, fillHandles
 149
 150         @return sal_True, if _nHandle marks an aggregate property, otherwise sal_False
 151     */
 152     bool fillAggregatePropertyInfoByHandle(OUString* _pPropName, sal_Int32* _pOriginalHandle,
 153                                                    sal_Int32 _nHandle) const;
 154
 155     /** returns information about a property given by handle
 156     */
 157     bool getPropertyByHandle( sal_Int32 _nHandle, ::com::sun::star::beans::Property& _rProperty ) const;
 158
 159
 160     enum PropertyOrigin
 161     {
 162         AGGREGATE_PROPERTY,
 163         DELEGATOR_PROPERTY,
 164         UNKNOWN_PROPERTY
 165     };
 166     /** prefer this one over the XPropertySetInfo of the aggregate!
 167
 168         <p>The reason is that OPropertyArrayAggregationHelper is the only instance which really knows
 169         which properties of the aggregate are to be exposed. <br/>
 170
 171         For instance, some derivee of OPropertySetAggregationHelper may decide to create an
 172         OPropertyArrayAggregationHelper which contains only a subset of the aggregate properties. This way,
 173         some of the aggregate properties may be hidded to the public.<br/>
 174
 175         When using the XPropertySetInfo of the aggregate set to determine the existence of a property, then this
 176         would return false positives.</p>
 177     */
 178     PropertyOrigin  classifyProperty( const OUString& _rName );
 179
 180 protected:
 181     const ::com::sun::star::beans::Property* findPropertyByName(const OUString& _rName) const;
 182 };
 183
 184
 185 namespace internal
 186 {
 187     class PropertyForwarder;
 188 }
 189
 190 /**
 191  * helper class for implementing the property-set-related interfaces
 192  * for an object doin' aggregation
 193  * supports at least XPropertySet and XMultiPropertySet
 194  *
 195  */
 196 class COMPHELPER_DLLPUBLIC OPropertySetAggregationHelper    :public OPropertyStateHelper
 197                                     ,public ::com::sun::star::beans::XPropertiesChangeListener
 198                                     ,public ::com::sun::star::beans::XVetoableChangeListener
 199 {
 200     friend class internal::PropertyForwarder;
 201
 202 protected:
 203     ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertyState>      m_xAggregateState;
 204     ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet>        m_xAggregateSet;
 205     ::com::sun::star::uno::Reference< ::com::sun::star::beans::XMultiPropertySet>   m_xAggregateMultiSet;
 206     ::com::sun::star::uno::Reference< ::com::sun::star::beans::XFastPropertySet>    m_xAggregateFastSet;
 207
 208     internal::PropertyForwarder*    m_pForwarder;
 209     bool                        m_bListening : 1;
 210
 211 public:
 212     OPropertySetAggregationHelper( ::cppu::OBroadcastHelper& rBHelper );
 213
 214     virtual ::com::sun::star::uno::Any SAL_CALL queryInterface(const ::com::sun::star::uno::Type& aType) throw(::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 215
 216 // XEventListener
 217     virtual void SAL_CALL disposing(const ::com::sun::star::lang::EventObject& Source) throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 218
 219 // XFastPropertySet
 220     virtual void SAL_CALL setFastPropertyValue(sal_Int32 nHandle, const ::com::sun::star::uno::Any& aValue) throw(::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::beans::PropertyVetoException, ::com::sun::star::lang::IllegalArgumentException, ::com::sun::star::lang::WrappedTargetException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 221     virtual ::com::sun::star::uno::Any SAL_CALL getFastPropertyValue(sal_Int32 nHandle) throw(::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::WrappedTargetException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 222
 223 // XPropertySet
 224     virtual void SAL_CALL           addPropertyChangeListener(const OUString& aPropertyName, const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertyChangeListener >& xListener) throw(::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::WrappedTargetException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 225     virtual void SAL_CALL           addVetoableChangeListener(const OUString& PropertyName, const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XVetoableChangeListener >& aListener) throw(::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::WrappedTargetException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 226
 227 // XPropertiesChangeListener
 228     virtual void SAL_CALL propertiesChange(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyChangeEvent >& evt) throw(::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 229
 230 // XVetoableChangeListener
 231     virtual void SAL_CALL vetoableChange(const ::com::sun::star::beans::PropertyChangeEvent& aEvent) throw(::com::sun::star::beans::PropertyVetoException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 232
 233 // XMultiPropertySet
 234     virtual void SAL_CALL   setPropertyValues(const ::com::sun::star::uno::Sequence< OUString >& PropertyNames, const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& Values) throw(::com::sun::star::beans::PropertyVetoException, ::com::sun::star::lang::IllegalArgumentException, ::com::sun::star::lang::WrappedTargetException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 235     virtual void SAL_CALL   addPropertiesChangeListener(const ::com::sun::star::uno::Sequence< OUString >& aPropertyNames, const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertiesChangeListener >& xListener) throw(::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 236
 237 // XPropertyState
 238     virtual ::com::sun::star::beans::PropertyState SAL_CALL getPropertyState(const OUString& PropertyName) throw(::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 239     virtual void SAL_CALL                                   setPropertyToDefault(const OUString& PropertyName) throw(::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 240     virtual ::com::sun::star::uno::Any SAL_CALL             getPropertyDefault(const OUString& aPropertyName) throw(::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::WrappedTargetException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 241
 242 // OPropertySetHelper
 243     /** still waiting to be overwritten ...
 244         you <B>must<B/> use an OPropertyArrayAggregationHelper here, as the implementation strongly relies on this.
 245     */
 246     virtual ::cppu::IPropertyArrayHelper& SAL_CALL getInfoHelper() SAL_OVERRIDE = 0;
 247
 248     /** only implemented for "forwarded" properties, every other property must be handled
 249         in the derivee, and will assert if passed herein
 250     */
 251     virtual sal_Bool SAL_CALL convertFastPropertyValue( ::com::sun::star::uno::Any& _rConvertedValue, ::com::sun::star::uno::Any& _rOldValue, sal_Int32 _nHandle, const ::com::sun::star::uno::Any& _rValue ) throw(::com::sun::star::lang::IllegalArgumentException) SAL_OVERRIDE;
 252
 253     /** only implemented for "forwarded" properties, every other property must be handled
 254         in the derivee, and will assert if passed herein
 255     */
 256     virtual void SAL_CALL setFastPropertyValue_NoBroadcast( sal_Int32 _nHandle, const ::com::sun::star::uno::Any& _rValue ) throw ( ::com::sun::star::uno::Exception, std::exception ) SAL_OVERRIDE;
 257
 258 protected:
 259     virtual ~OPropertySetAggregationHelper();
 260
 261     virtual void SAL_CALL getFastPropertyValue(::com::sun::star::uno::Any& rValue, sal_Int32 nHandle) const SAL_OVERRIDE;
 262     void disposing();
 263
 264     sal_Int32       getOriginalHandle( sal_Int32 _nHandle ) const;
 265     OUString getPropertyName( sal_Int32 _nHandle ) const;
 266
 267     /** declares the property with the given (public) handle as one to be forwarded to the aggregate
 268
 269         Sometimes, you might want to <em>overwrite</em> properties at the aggregate. That is,
 270         though the aggregate implements this property, and still is to hold the property value,
 271         you want to do additional handling upon setting the property, but then forward the value
 272         to the aggregate.
 273
 274         Use this method to declare such properties.
 275
 276         When a "forwarded property" is set from outside, the class first calls
 277         <member>forwardingPropertyValue</member> for any preprocessing, then forwards the property
 278         value to the aggregate, and then calls <member>forwardedPropertyValue</member>.
 279
 280         When you declare a property as "forwarded", the class takes care for some multi-threading
 281         issues, for instance, it won't fire any property change notifications which result from
 282         forwarding a property value, unless it's safe to do so (i.e. unless our mutex is
 283         released).
 284
 285         @see forwardingPropertyValue
 286         @see forwardedPropertyValue
 287     */
 288     void declareForwardedProperty( sal_Int32 _nHandle );
 289
 290     /** checks whether we're actually forwarding a property value to our aggregate
 291
 292         @see declareForwardedProperty
 293         @see forwardingPropertyValue
 294         @see forwardedPropertyValue
 295     */
 296     bool    isCurrentlyForwardingProperty( sal_Int32 _nHandle ) const;
 297
 298     /** called immediately before a property value which is overwritten in this instance
 299         is forwarded to the aggregate
 300
 301         @see declareForwardedProperty
 302         @see forwardedPropertyValue
 303     */
 304     virtual void forwardingPropertyValue( sal_Int32 _nHandle );
 305
 306     /** called immediately after a property value which is overwritten in this instance
 307         has been forwarded to the aggregate
 308
 309         @see declareForwardedProperty
 310         @see forwardingPropertyValue
 311     */
 312     virtual void forwardedPropertyValue( sal_Int32 _nHandle );
 313
 314     /// must be called before aggregation, if aggregation is used
 315     void setAggregation(const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >&) throw( ::com::sun::star::lang::IllegalArgumentException );
 316     void startListening();
 317 };
 318
 319
 320 }   // namespace comphelper
 321
 322
 323 #endif // INCLUDED_COMPHELPER_PROPAGG_HXX
 324
 325 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */