diff options
Diffstat (limited to 'include/comphelper/propagg.hxx')
| -rw-r--r-- | include/comphelper/propagg.hxx | 325 |
1 files changed, 325 insertions, 0 deletions
diff --git a/include/comphelper/propagg.hxx b/include/comphelper/propagg.hxx new file mode 100644 index 000000000..949251892 --- /dev/null +++ b/include/comphelper/propagg.hxx @@ -0,0 +1,325 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ + +#ifndef INCLUDED_COMPHELPER_PROPAGG_HXX +#define INCLUDED_COMPHELPER_PROPAGG_HXX + +#include <config_options.h> +#include <com/sun/star/beans/Property.hpp> +#include <com/sun/star/beans/PropertyState.hpp> +#include <com/sun/star/beans/XPropertiesChangeListener.hpp> +#include <com/sun/star/beans/XVetoableChangeListener.hpp> +#include <com/sun/star/lang/EventObject.hpp> +#include <comphelper/propstate.hxx> +#include <comphelper/comphelperdllapi.h> + +#include <cstddef> +#include <map> +#include <memory> +#include <vector> + + +//= property helper classes + + +namespace comphelper +{ + + +//= OPropertyAccessor +//= internal helper class for OPropertyArrayAggregationHelper + +namespace internal +{ + struct OPropertyAccessor + { + sal_Int32 nOriginalHandle; + std::size_t nPos; + bool bAggregate; + + OPropertyAccessor(sal_Int32 _nOriginalHandle, std::size_t _nPos, bool _bAggregate) + :nOriginalHandle(_nOriginalHandle) ,nPos(_nPos) ,bAggregate(_bAggregate) { } + + bool operator==(const OPropertyAccessor& rOb) const { return nPos == rOb.nPos; } + bool operator <(const OPropertyAccessor& rOb) const { return nPos < rOb.nPos; } + }; +} + + +/** + * used as callback for an OPropertyArrayAggregationHelper + */ +class IPropertyInfoService +{ +public: + /** get the preferred handle for the given property + @param _rName the property name + @return the handle the property should be referred by, or -1 if there are no + preferences for the given property + */ + virtual sal_Int32 getPreferredPropertyId(const OUString& _rName) = 0; + +protected: + ~IPropertyInfoService() {} +}; + +/** + * used for implementing a cppu::IPropertyArrayHelper for classes + * aggregating property sets + */ + +#define DEFAULT_AGGREGATE_PROPERTY_ID 10000 + +class COMPHELPER_DLLPUBLIC OPropertyArrayAggregationHelper final : public ::cppu::IPropertyArrayHelper +{ + friend class OPropertySetAggregationHelper; + + std::vector<css::beans::Property> m_aProperties; + std::map< sal_Int32, internal::OPropertyAccessor > m_aPropertyAccessors; + +public: + /** construct the object. + @param _rProperties the properties of the object doing the aggregation. These properties + are used without any checks, so the caller has to ensure that the names and + handles are valid. + @param _rAggProperties the properties of the aggregate, usually got via a call to getProperties on the + XPropertySetInfo of the aggregate. + The names of the properties are used without any checks, so the caller has to ensure + that there are no doubles. + The handles are stored for later quick access, but the outside-handles the + aggregate properties get depend from the following two parameters. + @param _pInfoService + If not NULL, the object pointed to is used to calc handles which should be used + for referring the aggregate's properties from outside. + If one of the properties returned from the info service conflict with other handles + already present (e.g. through _rProperties), the property is handled as if -1 was returned. + If NULL (or, for a special property, a call to getPreferredPropertyId returns -1), + the aggregate property(ies) get a new handle which they can be referred by from outside. + @param _nFirstAggregateId + if the object is about to create new handles for the aggregate properties, it uses + id's ascending from this given id. + No checks are made if the handle range determined by _nFirstAggregateId conflicts with other + handles within _rProperties. + */ + OPropertyArrayAggregationHelper(const css::uno::Sequence< css::beans::Property>& _rProperties, + const css::uno::Sequence< css::beans::Property>& _rAggProperties, + IPropertyInfoService* _pInfoService = nullptr, + sal_Int32 _nFirstAggregateId = DEFAULT_AGGREGATE_PROPERTY_ID); + + + /// inherited from IPropertyArrayHelper + virtual sal_Bool SAL_CALL fillPropertyMembersByHandle( OUString* _pPropName, sal_Int16* _pAttributes, + sal_Int32 _nHandle) override ; + + /// inherited from IPropertyArrayHelper + virtual css::uno::Sequence< css::beans::Property> SAL_CALL getProperties() override; + /// inherited from IPropertyArrayHelper + virtual css::beans::Property SAL_CALL getPropertyByName(const OUString& _rPropertyName) override; + + /// inherited from IPropertyArrayHelper + virtual sal_Bool SAL_CALL hasPropertyByName(const OUString& _rPropertyName) override ; + /// inherited from IPropertyArrayHelper + virtual sal_Int32 SAL_CALL getHandleByName(const OUString & _rPropertyName) override; + /// inherited from IPropertyArrayHelper + virtual sal_Int32 SAL_CALL fillHandles( /*out*/sal_Int32* _pHandles, const css::uno::Sequence< OUString >& _rPropNames ) override; + + /** returns information about a property of the aggregate. + @param _pPropName points to a string to receive the property name. No name is returned if this is NULL. + @param _pOriginalHandle points to a sal_Int32 to receive the original property handle. No original handle is returned + if this is NULL. + @param _nHandle the handle of the property as got by, for instance, fillHandles + + @return sal_True, if _nHandle marks an aggregate property, otherwise sal_False + */ + bool fillAggregatePropertyInfoByHandle(OUString* _pPropName, sal_Int32* _pOriginalHandle, + sal_Int32 _nHandle) const; + + /** returns information about a property given by handle + */ + bool getPropertyByHandle( sal_Int32 _nHandle, css::beans::Property& _rProperty ) const; + + + enum class PropertyOrigin + { + Aggregate, + Delegator, + Unknown + }; + /** prefer this one over the XPropertySetInfo of the aggregate! + + <p>The reason is that OPropertyArrayAggregationHelper is the only instance which really knows + which properties of the aggregate are to be exposed. <br/> + + For instance, some derivee of OPropertySetAggregationHelper may decide to create an + OPropertyArrayAggregationHelper which contains only a subset of the aggregate properties. This way, + some of the aggregate properties may be hidden to the public.<br/> + + When using the XPropertySetInfo of the aggregate set to determine the existence of a property, then this + would return false positives.</p> + */ + PropertyOrigin classifyProperty( const OUString& _rName ); + +private: + const css::beans::Property* findPropertyByName(const OUString& _rName) const; +}; + + +namespace internal +{ + class PropertyForwarder; +} + +/** + * helper class for implementing the property-set-related interfaces + * for an object doin' aggregation + * supports at least XPropertySet and XMultiPropertySet + * + */ +class UNLESS_MERGELIBS(COMPHELPER_DLLPUBLIC) OPropertySetAggregationHelper :public OPropertyStateHelper + ,public css::beans::XPropertiesChangeListener + ,public css::beans::XVetoableChangeListener +{ + friend class internal::PropertyForwarder; + +protected: + css::uno::Reference< css::beans::XPropertyState> m_xAggregateState; + css::uno::Reference< css::beans::XPropertySet> m_xAggregateSet; + css::uno::Reference< css::beans::XMultiPropertySet> m_xAggregateMultiSet; + css::uno::Reference< css::beans::XFastPropertySet> m_xAggregateFastSet; + + std::unique_ptr<internal::PropertyForwarder> m_pForwarder; + bool m_bListening : 1; + +public: + OPropertySetAggregationHelper( ::cppu::OBroadcastHelper& rBHelper ); + + virtual css::uno::Any SAL_CALL queryInterface(const css::uno::Type& aType) override; + +// XEventListener + virtual void SAL_CALL disposing(const css::lang::EventObject& Source) override; + +// XFastPropertySet + virtual void SAL_CALL setFastPropertyValue(sal_Int32 nHandle, const css::uno::Any& aValue) override; + virtual css::uno::Any SAL_CALL getFastPropertyValue(sal_Int32 nHandle) override; + +// XPropertySet + virtual void SAL_CALL addPropertyChangeListener(const OUString& aPropertyName, const css::uno::Reference< css::beans::XPropertyChangeListener >& xListener) override; + virtual void SAL_CALL addVetoableChangeListener(const OUString& PropertyName, const css::uno::Reference< css::beans::XVetoableChangeListener >& aListener) override; + +// XPropertiesChangeListener + virtual void SAL_CALL propertiesChange(const css::uno::Sequence< css::beans::PropertyChangeEvent >& evt) override; + +// XVetoableChangeListener + virtual void SAL_CALL vetoableChange(const css::beans::PropertyChangeEvent& aEvent) override; + +// XMultiPropertySet + virtual void SAL_CALL setPropertyValues(const css::uno::Sequence< OUString >& PropertyNames, const css::uno::Sequence< css::uno::Any >& Values) override; + virtual void SAL_CALL addPropertiesChangeListener(const css::uno::Sequence< OUString >& aPropertyNames, const css::uno::Reference< css::beans::XPropertiesChangeListener >& xListener) override; + +// XPropertyState + virtual css::beans::PropertyState SAL_CALL getPropertyState(const OUString& PropertyName) override; + virtual void SAL_CALL setPropertyToDefault(const OUString& PropertyName) override; + virtual css::uno::Any SAL_CALL getPropertyDefault(const OUString& aPropertyName) override; + +// OPropertySetHelper + /** still waiting to be overwritten ... + you <B>must<B/> use an OPropertyArrayAggregationHelper here, as the implementation strongly relies on this. + */ + virtual ::cppu::IPropertyArrayHelper& SAL_CALL getInfoHelper() override = 0; + + /** only implemented for "forwarded" properties, every other property must be handled + in the derivee, and will assert if passed herein + */ + virtual sal_Bool SAL_CALL convertFastPropertyValue( css::uno::Any& _rConvertedValue, css::uno::Any& _rOldValue, sal_Int32 _nHandle, const css::uno::Any& _rValue ) override; + + /** only implemented for "forwarded" properties, every other property must be handled + in the derivee, and will assert if passed herein + */ + virtual void SAL_CALL setFastPropertyValue_NoBroadcast( sal_Int32 _nHandle, const css::uno::Any& _rValue ) override; + +protected: + virtual ~OPropertySetAggregationHelper() override; + + virtual void SAL_CALL getFastPropertyValue(css::uno::Any& rValue, sal_Int32 nHandle) const override; + void disposing(); + + sal_Int32 getOriginalHandle( sal_Int32 _nHandle ) const; + OUString getPropertyName( sal_Int32 _nHandle ) const; + + /** declares the property with the given (public) handle as one to be forwarded to the aggregate + + Sometimes, you might want to <em>overwrite</em> properties at the aggregate. That is, + though the aggregate implements this property, and still is to hold the property value, + you want to do additional handling upon setting the property, but then forward the value + to the aggregate. + + Use this method to declare such properties. + + When a "forwarded property" is set from outside, the class first calls + <member>forwardingPropertyValue</member> for any preprocessing, then forwards the property + value to the aggregate, and then calls <member>forwardedPropertyValue</member>. + + When you declare a property as "forwarded", the class takes care for some multi-threading + issues, for instance, it won't fire any property change notifications which result from + forwarding a property value, unless it's safe to do so (i.e. unless our mutex is + released). + + @see forwardingPropertyValue + @see forwardedPropertyValue + */ + void declareForwardedProperty( sal_Int32 _nHandle ); + + /** checks whether we're actually forwarding a property value to our aggregate + + @see declareForwardedProperty + @see forwardingPropertyValue + @see forwardedPropertyValue + */ + bool isCurrentlyForwardingProperty( sal_Int32 _nHandle ) const; + + /** called immediately before a property value which is overwritten in this instance + is forwarded to the aggregate + + @see declareForwardedProperty + @see forwardedPropertyValue + */ + virtual void forwardingPropertyValue( sal_Int32 _nHandle ); + + /** called immediately after a property value which is overwritten in this instance + has been forwarded to the aggregate + + @see declareForwardedProperty + @see forwardingPropertyValue + */ + virtual void forwardedPropertyValue( sal_Int32 _nHandle ); + + /// must be called before aggregation, if aggregation is used + /// + /// @throws css::lang::IllegalArgumentException + void setAggregation(const css::uno::Reference< css::uno::XInterface >&); + void startListening(); +}; + + +} // namespace comphelper + + +#endif // INCLUDED_COMPHELPER_PROPAGG_HXX + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |