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 #include <memory>
  29 #include <vector>
  30
  31
  32 //= property helper classes
  33
  34
  35 namespace comphelper
  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 >  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     std::vector<css::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                                 already 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 css::uno::Sequence< css::beans::Property>& _rProperties,
 122                                     const css::uno::Sequence< css::beans::Property>& _rAggProperties,
 123                                     IPropertyInfoService* _pInfoService = nullptr,
 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) override ;
 130
 131     /// inherited from IPropertyArrayHelper
 132     virtual css::uno::Sequence< css::beans::Property> SAL_CALL getProperties() override;
 133     /// inherited from IPropertyArrayHelper
 134     virtual css::beans::Property SAL_CALL getPropertyByName(const OUString& _rPropertyName) override;
 135
 136     /// inherited from IPropertyArrayHelper
 137     virtual sal_Bool  SAL_CALL hasPropertyByName(const OUString& _rPropertyName) override ;
 138     /// inherited from IPropertyArrayHelper
 139     virtual sal_Int32 SAL_CALL getHandleByName(const OUString & _rPropertyName) override;
 140     /// inherited from IPropertyArrayHelper
 141     virtual sal_Int32 SAL_CALL fillHandles( /*out*/sal_Int32* _pHandles, const css::uno::Sequence< OUString >& _rPropNames ) override;
 142
 143     /** returns information about a property of the aggregate.
 144         @param  _pPropName          points to a string to receive the property name. No name is returned if this is NULL.
 145         @param  _pOriginalHandle    points to a sal_Int32 to receive the original property handle. No original handle is returned
 146                                     if this is NULL.
 147         @param  _nHandle            the handle of the property as got by, for instance, fillHandles
 148
 149         @return sal_True, if _nHandle marks an aggregate property, otherwise sal_False
 150     */
 151     bool fillAggregatePropertyInfoByHandle(OUString* _pPropName, sal_Int32* _pOriginalHandle,
 152                                                    sal_Int32 _nHandle) const;
 153
 154     /** returns information about a property given by handle
 155     */
 156     bool getPropertyByHandle( sal_Int32 _nHandle, css::beans::Property& _rProperty ) const;
 157
 158
 159     enum class PropertyOrigin
 160     {
 161         Aggregate,
 162         Delegator,
 163         Unknown
 164     };
 165     /** prefer this one over the XPropertySetInfo of the aggregate!
 166
 167         <p>The reason is that OPropertyArrayAggregationHelper is the only instance which really knows
 168         which properties of the aggregate are to be exposed. <br/>
 169
 170         For instance, some derivee of OPropertySetAggregationHelper may decide to create an
 171         OPropertyArrayAggregationHelper which contains only a subset of the aggregate properties. This way,
 172         some of the aggregate properties may be hidden to the public.<br/>
 173
 174         When using the XPropertySetInfo of the aggregate set to determine the existence of a property, then this
 175         would return false positives.</p>
 176     */
 177     PropertyOrigin  classifyProperty( const OUString& _rName );
 178
 179 protected:
 180     const css::beans::Property* findPropertyByName(const OUString& _rName) const;
 181 };
 182
 183
 184 namespace internal
 185 {
 186     class PropertyForwarder;
 187 }
 188
 189 /**
 190  * helper class for implementing the property-set-related interfaces
 191  * for an object doin' aggregation
 192  * supports at least XPropertySet and XMultiPropertySet
 193  *
 194  */
 195 class COMPHELPER_DLLPUBLIC OPropertySetAggregationHelper    :public OPropertyStateHelper
 196                                     ,public css::beans::XPropertiesChangeListener
 197                                     ,public css::beans::XVetoableChangeListener
 198 {
 199     friend class internal::PropertyForwarder;
 200
 201 protected:
 202     css::uno::Reference< css::beans::XPropertyState>      m_xAggregateState;
 203     css::uno::Reference< css::beans::XPropertySet>        m_xAggregateSet;
 204     css::uno::Reference< css::beans::XMultiPropertySet>   m_xAggregateMultiSet;
 205     css::uno::Reference< css::beans::XFastPropertySet>    m_xAggregateFastSet;
 206
 207     std::unique_ptr<internal::PropertyForwarder>          m_pForwarder;
 208     bool                            m_bListening : 1;
 209
 210 public:
 211     OPropertySetAggregationHelper( ::cppu::OBroadcastHelper& rBHelper );
 212
 213     virtual css::uno::Any SAL_CALL queryInterface(const css::uno::Type& aType) override;
 214
 215 // XEventListener
 216     virtual void SAL_CALL disposing(const css::lang::EventObject& Source) override;
 217
 218 // XFastPropertySet
 219     virtual void SAL_CALL setFastPropertyValue(sal_Int32 nHandle, const css::uno::Any& aValue) override;
 220     virtual css::uno::Any SAL_CALL getFastPropertyValue(sal_Int32 nHandle) override;
 221
 222 // XPropertySet
 223     virtual void SAL_CALL           addPropertyChangeListener(const OUString& aPropertyName, const css::uno::Reference< css::beans::XPropertyChangeListener >& xListener) override;
 224     virtual void SAL_CALL           addVetoableChangeListener(const OUString& PropertyName, const css::uno::Reference< css::beans::XVetoableChangeListener >& aListener) override;
 225
 226 // XPropertiesChangeListener
 227     virtual void SAL_CALL propertiesChange(const css::uno::Sequence< css::beans::PropertyChangeEvent >& evt) override;
 228
 229 // XVetoableChangeListener
 230     virtual void SAL_CALL vetoableChange(const css::beans::PropertyChangeEvent& aEvent) override;
 231
 232 // XMultiPropertySet
 233     virtual void SAL_CALL   setPropertyValues(const css::uno::Sequence< OUString >& PropertyNames, const css::uno::Sequence< css::uno::Any >& Values) override;
 234     virtual void SAL_CALL   addPropertiesChangeListener(const css::uno::Sequence< OUString >& aPropertyNames, const css::uno::Reference< css::beans::XPropertiesChangeListener >& xListener) override;
 235
 236 // XPropertyState
 237     virtual css::beans::PropertyState SAL_CALL getPropertyState(const OUString& PropertyName) override;
 238     virtual void SAL_CALL                                   setPropertyToDefault(const OUString& PropertyName) override;
 239     virtual css::uno::Any SAL_CALL             getPropertyDefault(const OUString& aPropertyName) override;
 240
 241 // OPropertySetHelper
 242     /** still waiting to be overwritten ...
 243         you <B>must<B/> use an OPropertyArrayAggregationHelper here, as the implementation strongly relies on this.
 244     */
 245     virtual ::cppu::IPropertyArrayHelper& SAL_CALL getInfoHelper() override = 0;
 246
 247     /** only implemented for "forwarded" properties, every other property must be handled
 248         in the derivee, and will assert if passed herein
 249     */
 250     virtual sal_Bool SAL_CALL convertFastPropertyValue( css::uno::Any& _rConvertedValue, css::uno::Any& _rOldValue, sal_Int32 _nHandle, const css::uno::Any& _rValue ) override;
 251
 252     /** only implemented for "forwarded" properties, every other property must be handled
 253         in the derivee, and will assert if passed herein
 254     */
 255     virtual void SAL_CALL setFastPropertyValue_NoBroadcast( sal_Int32 _nHandle, const css::uno::Any& _rValue ) override;
 256
 257 protected:
 258     virtual ~OPropertySetAggregationHelper() override;
 259
 260     virtual void SAL_CALL getFastPropertyValue(css::uno::Any& rValue, sal_Int32 nHandle) const override;
 261     void disposing();
 262
 263     sal_Int32       getOriginalHandle( sal_Int32 _nHandle ) const;
 264     OUString getPropertyName( sal_Int32 _nHandle ) const;
 265
 266     /** declares the property with the given (public) handle as one to be forwarded to the aggregate
 267
 268         Sometimes, you might want to <em>overwrite</em> properties at the aggregate. That is,
 269         though the aggregate implements this property, and still is to hold the property value,
 270         you want to do additional handling upon setting the property, but then forward the value
 271         to the aggregate.
 272
 273         Use this method to declare such properties.
 274
 275         When a "forwarded property" is set from outside, the class first calls
 276         <member>forwardingPropertyValue</member> for any preprocessing, then forwards the property
 277         value to the aggregate, and then calls <member>forwardedPropertyValue</member>.
 278
 279         When you declare a property as "forwarded", the class takes care for some multi-threading
 280         issues, for instance, it won't fire any property change notifications which result from
 281         forwarding a property value, unless it's safe to do so (i.e. unless our mutex is
 282         released).
 283
 284         @see forwardingPropertyValue
 285         @see forwardedPropertyValue
 286     */
 287     void declareForwardedProperty( sal_Int32 _nHandle );
 288
 289     /** checks whether we're actually forwarding a property value to our aggregate
 290
 291         @see declareForwardedProperty
 292         @see forwardingPropertyValue
 293         @see forwardedPropertyValue
 294     */
 295     bool    isCurrentlyForwardingProperty( sal_Int32 _nHandle ) const;
 296
 297     /** called immediately before a property value which is overwritten in this instance
 298         is forwarded to the aggregate
 299
 300         @see declareForwardedProperty
 301         @see forwardedPropertyValue
 302     */
 303     virtual void forwardingPropertyValue( sal_Int32 _nHandle );
 304
 305     /** called immediately after a property value which is overwritten in this instance
 306         has been forwarded to the aggregate
 307
 308         @see declareForwardedProperty
 309         @see forwardingPropertyValue
 310     */
 311     virtual void forwardedPropertyValue( sal_Int32 _nHandle );
 312
 313     /// must be called before aggregation, if aggregation is used
 314     ///
 315     /// @throws css::lang::IllegalArgumentException
 316     void setAggregation(const css::uno::Reference< css::uno::XInterface >&);
 317     void startListening();
 318 };
 319
 320
 321 }   // namespace comphelper
 322
 323
 324 #endif // INCLUDED_COMPHELPER_PROPAGG_HXX
 325
 326 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */