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