include/comphelper/propshlp.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 #pragma once
  20
  21 #include <comphelper/multiinterfacecontainer4.hxx>
  22
  23 #include <com/sun/star/beans/XPropertySet.hpp>
  24 #include <com/sun/star/beans/XPropertySetOption.hpp>
  25 #include <com/sun/star/beans/XMultiPropertySet.hpp>
  26 #include <com/sun/star/beans/XFastPropertySet.hpp>
  27
  28 #include <comphelper/comphelperdllapi.h>
  29 #include <comphelper/unoimplbase.hxx>
  30 #include <cppuhelper/propshlp.hxx>
  31
  32 namespace comphelper
  33 {
  34 /*************************************************************************
  35 *************************************************************************/
  36
  37 /**
  38    This abstract class maps the methods of the interfaces XMultiPropertySet, XFastPropertySet
  39    and XPropertySet to the methods getInfoHelper, convertFastPropertyValue,
  40    setFastPropertyValue_NoBroadcast and getFastPropertyValue. You must derive from
  41    this class and override the methods.
  42    It provides a standard implementation of the XPropertySetInfo.
  43
  44    This is a modified copy of the cppuhelper::OPropertySetHelper class, except
  45    that is uses std::mutex instead of osl::Mutex.
  46  */
  47 class COMPHELPER_DLLPUBLIC OPropertySetHelper : public virtual comphelper::UnoImplBase,
  48                                                 public css::beans::XMultiPropertySet,
  49                                                 public css::beans::XFastPropertySet,
  50                                                 public css::beans::XPropertySet
  51 {
  52 public:
  53     OPropertySetHelper();
  54
  55     /** Constructor.
  56
  57         @param bIgnoreRuntimeExceptionsWhileFiring
  58                         indicates whether occurring RuntimeExceptions will be
  59                         ignored when firing notifications
  60                         (vetoableChange(), propertyChange())
  61                         to listeners.
  62                         PropertyVetoExceptions may still be thrown.
  63                         This flag is useful in an inter-process scenario when
  64                         remote bridges may break down
  65                         (firing DisposedExceptions).
  66     */
  67     OPropertySetHelper(bool bIgnoreRuntimeExceptionsWhileFiring);
  68
  69     /**
  70        Only returns a reference to XMultiPropertySet, XFastPropertySet, XPropertySet and
  71        XEventListener.
  72      */
  73     virtual css::uno::Any SAL_CALL queryInterface(const css::uno::Type& rType) override;
  74
  75     /** eases implementing XTypeProvider::getTypes, returns the types of XMultiPropertySet, XFastPropertySet, XPropertySet
  76
  77         @throws css::uno::RuntimeException
  78      */
  79     static css::uno::Sequence<css::uno::Type> getTypes();
  80
  81     /**
  82        Send a disposing notification to the listeners
  83
  84        @see OComponentHelper
  85      */
  86     void disposing(std::unique_lock<std::mutex>& rGuard);
  87
  88     /**
  89        Throw UnknownPropertyException or PropertyVetoException if the property with the name
  90        rPropertyName does not exist or is readonly. Otherwise rPropertyName is changed to its handle
  91        value and setFastPropertyValue is called.
  92      */
  93     virtual void SAL_CALL setPropertyValue(const ::rtl::OUString& rPropertyName,
  94                                            const css::uno::Any& aValue) override final;
  95     /**
  96        Throw UnknownPropertyException if the property with the name
  97        rPropertyName does not exist.
  98      */
  99     virtual css::uno::Any SAL_CALL
 100     getPropertyValue(const ::rtl::OUString& aPropertyName) override final;
 101
 102     /** Ignored if the property is not bound. */
 103     virtual void SAL_CALL addPropertyChangeListener(
 104         const ::rtl::OUString& aPropertyName,
 105         const css::uno::Reference<css::beans::XPropertyChangeListener>& aListener) override final;
 106
 107     /** Ignored if the property is not bound. */
 108     virtual void SAL_CALL removePropertyChangeListener(
 109         const ::rtl::OUString& aPropertyName,
 110         const css::uno::Reference<css::beans::XPropertyChangeListener>& aListener) override final;
 111
 112     /** Ignored if the property is not constrained. */
 113     virtual void SAL_CALL addVetoableChangeListener(
 114         const ::rtl::OUString& aPropertyName,
 115         const css::uno::Reference<css::beans::XVetoableChangeListener>& aListener) override final;
 116
 117     /** Ignored if the property is not constrained. */
 118     virtual void SAL_CALL removeVetoableChangeListener(
 119         const ::rtl::OUString& aPropertyName,
 120         const css::uno::Reference<css::beans::XVetoableChangeListener>& aListener) override final;
 121
 122     /**
 123        Throw UnknownPropertyException or PropertyVetoException if the property with the name
 124        rPropertyName does not exist or is readonly. Otherwise the method convertFastPropertyValue
 125        is called, then the vetoable listeners are notified. After this the value of the property
 126        is changed with the setFastPropertyValue_NoBroadcast method and the bound listeners are
 127        notified.
 128       */
 129     virtual void SAL_CALL setFastPropertyValue(sal_Int32 nHandle,
 130                                                const css::uno::Any& rValue) override final;
 131
 132     /**
 133        @exception css::beans::UnknownPropertyException
 134          if the property with the handle nHandle does not exist.
 135      */
 136     virtual css::uno::Any SAL_CALL getFastPropertyValue(sal_Int32 nHandle) override final;
 137
 138     // XMultiPropertySet
 139     virtual void SAL_CALL
 140     setPropertyValues(const css::uno::Sequence<::rtl::OUString>& PropertyNames,
 141                       const css::uno::Sequence<css::uno::Any>& Values) override;
 142
 143     virtual css::uno::Sequence<css::uno::Any> SAL_CALL
 144     getPropertyValues(const css::uno::Sequence<::rtl::OUString>& PropertyNames) override final;
 145
 146     virtual void SAL_CALL addPropertiesChangeListener(
 147         const css::uno::Sequence<::rtl::OUString>& PropertyNames,
 148         const css::uno::Reference<css::beans::XPropertiesChangeListener>& Listener) override final;
 149
 150     virtual void SAL_CALL removePropertiesChangeListener(
 151         const css::uno::Reference<css::beans::XPropertiesChangeListener>& Listener) override final;
 152
 153     virtual void SAL_CALL firePropertiesChangeEvent(
 154         const css::uno::Sequence<::rtl::OUString>& PropertyNames,
 155         const css::uno::Reference<css::beans::XPropertiesChangeListener>& Listener) override final;
 156
 157     /**
 158        The property sequence is created in the call. The interface isn't used after the call.
 159      */
 160     static css::uno::Reference<css::beans::XPropertySetInfo>
 161     createPropertySetInfo(cppu::IPropertyArrayHelper& rProperties);
 162
 163 protected:
 164     /**
 165        You must call disposing() before destruction.
 166      */
 167     ~OPropertySetHelper();
 168
 169     /** Override this if you need to do something special during setFastPropertyValue */
 170     virtual void setFastPropertyValueImpl(std::unique_lock<std::mutex>& rGuard, sal_Int32 nHandle,
 171                                           const css::uno::Any& rValue);
 172     /** Override this if you need to do something special during getPropertyValue */
 173     virtual css::uno::Any getPropertyValueImpl(std::unique_lock<std::mutex>& rGuard,
 174                                                const ::rtl::OUString& aPropertyName);
 175
 176     /**
 177        This method fire events to all registered property listeners.
 178        @param pnHandles     the id's of the properties that changed.
 179        @param pNewValues    the new values of the properties.
 180        @param pOldValues    the old values of the properties.
 181        @param nCount        the number of elements in the arrays pnHandles, pNewValues and pOldValues.
 182        @param bVetoable true means fire to VetoableChangeListener, false means fire to
 183                   XPropertyChangedListener and XMultiPropertyChangedListener.
 184      */
 185     void fire(std::unique_lock<std::mutex>& rGuard, sal_Int32* pnHandles,
 186               const css::uno::Any* pNewValues, const css::uno::Any* pOldValues, sal_Int32 nCount,
 187               bool bVetoable);
 188
 189     /**
 190        Set multiple properties with the handles.
 191        @param nSeqLen   the length of the arrays pHandles and Values.
 192        @param pHandles the handles of the properties. The number of elements
 193               in the Values sequence is the length of the handle array. A value of -1
 194               of a handle means invalid property. These are ignored.
 195        @param pValues the values of the properties.
 196        @param nHitCount the number of valid entries in the handle array.
 197      */
 198     void setFastPropertyValues(std::unique_lock<std::mutex>& rGuard, sal_Int32 nSeqLen,
 199                                sal_Int32* pHandles, const css::uno::Any* pValues,
 200                                sal_Int32 nHitCount);
 201
 202     /**
 203        This abstract method must return the name to index table. This table contains all property
 204        names and types of this object. The method is not implemented in this class.
 205      */
 206     virtual cppu::IPropertyArrayHelper& getInfoHelper() = 0;
 207
 208     /**
 209        Converted the value rValue and return the result in rConvertedValue and the
 210        old value in rOldValue. An IllegalArgumentException is thrown.
 211        The method is not implemented in this class. After this call the vetoable
 212        listeners are notified.
 213
 214        @param rConvertedValue the converted value. Only set if return is true.
 215        @param rOldValue the old value. Only set if return is true.
 216        @param nHandle the handle of the property.
 217        @param rValue the value to be converted
 218        @return true if the value converted.
 219        @throws css::lang::IllegalArgumentException
 220        @throws css::beans::UnknownPropertyException
 221        @throws css::uno::RuntimeException
 222      */
 223     virtual bool convertFastPropertyValue(std::unique_lock<std::mutex>& rGuard,
 224                                           css::uno::Any& rConvertedValue, css::uno::Any& rOldValue,
 225                                           sal_Int32 nHandle, const css::uno::Any& rValue)
 226         = 0;
 227
 228     /** The same as setFastPropertyValue; nHandle is always valid.
 229         The changes must not be broadcasted in this method.
 230         The method is implemented in a derived class.
 231
 232         @attention
 233         Although you are permitted to throw any UNO exception, only the following
 234         are valid for usage:
 235         -- css::beans::UnknownPropertyException
 236         -- css::beans::PropertyVetoException
 237         -- css::lang::IllegalArgumentException
 238         -- css::lang::WrappedTargetException
 239         -- css::uno::RuntimeException
 240
 241         @param nHandle
 242                handle
 243         @param rValue
 244                value
 245         @throws css::uno::Exception
 246     */
 247     virtual void setFastPropertyValue_NoBroadcast(std::unique_lock<std::mutex>& rGuard,
 248                                                   sal_Int32 nHandle, const css::uno::Any& rValue)
 249         = 0;
 250     /**
 251        The same as getFastPropertyValue, but return the value through rValue and nHandle
 252        is always valid.
 253        The method is not implemented in this class.
 254      */
 255     virtual void getFastPropertyValue(std::unique_lock<std::mutex>& rGuard, css::uno::Any& rValue,
 256                                       sal_Int32 nHandle) const = 0;
 257
 258     /** sets an dependent property's value
 259
 260         <p>Sometimes setting a given property needs to implicitly modify another property's value. Calling |setPropertyValue|
 261         from within |setFastPropertyValue_NoBroadcast| is not an option here, as it would notify the property listeners
 262         while our mutex is still locked. Setting the dependent property's value directly (e.g. by calling |setFastPropertyValue_NoBroadcast|
 263         recursively) is not an option, too, since it would miss firing the property change event.</p>
 264
 265         <p>So, in such cases, you use |setDependentFastPropertyValue| from within |setFastPropertyValue_NoBroadcast|.
 266         It will convert and actually set the property value (invoking |convertFastPropertyValue| and |setFastPropertyValue_NoBroadcast|
 267         for the given handle and value), and add the property change event to the list of events to be notified
 268         when the bottom-most |setFastPropertyValue_NoBroadcast| on the stack returns.</p>
 269
 270         <p><strong>Note</strong>: The method will <em>not</em> invoke veto listeners for the property.</p>
 271
 272         <p><strong>Note</strong>: It's the caller's responsibility to ensure that our mutex is locked. This is
 273         canonically given when the method is invoked from within |setFastPropertyValue_NoBroadcast|, in other
 274         contexts, you might need to take own measures.</p>
 275     */
 276     void setDependentFastPropertyValue(std::unique_lock<std::mutex>& rGuard, sal_Int32 i_handle,
 277                                        const css::uno::Any& i_value);
 278
 279 private:
 280     /**
 281        Container for the XPropertyChangedListener. The listeners are inserted by handle.
 282      */
 283     OMultiTypeInterfaceContainerHelperVar4<sal_Int32, css::beans::XPropertyChangeListener> aBoundLC;
 284     /**
 285        Container for the XPropertyVetoableListener. The listeners are inserted by handle.
 286      */
 287     OMultiTypeInterfaceContainerHelperVar4<sal_Int32, css::beans::XVetoableChangeListener>
 288         aVetoableLC;
 289     /**
 290        Container for the XPropertyChangedListener where the listeners want to listen to all properties.
 291      */
 292     comphelper::OInterfaceContainerHelper4<css::beans::XPropertyChangeListener>
 293         maPropertyChangeListeners;
 294     comphelper::OInterfaceContainerHelper4<css::beans::XPropertiesChangeListener>
 295         maPropertiesChangeListeners;
 296     /**
 297        Container for the XVetoableChangeListener where the listeners want to listen to all properties.
 298      */
 299     comphelper::OInterfaceContainerHelper4<css::beans::XVetoableChangeListener>
 300         maVetoableChangeListeners;
 301     std::vector<sal_Int32> m_handles;
 302     std::vector<css::uno::Any> m_newValues;
 303     std::vector<css::uno::Any> m_oldValues;
 304     bool m_bIgnoreRuntimeExceptionsWhileFiring = false;
 305     bool m_bFireEvents = true;
 306
 307     /** notifies the given changes in property's values, <em>plus</em> all property changes collected during recent
 308         |setDependentFastPropertyValue| calls.
 309     */
 310     void impl_fireAll(std::unique_lock<std::mutex>& rGuard, sal_Int32* i_handles,
 311                       const css::uno::Any* i_newValues, const css::uno::Any* i_oldValues,
 312                       sal_Int32 i_count);
 313
 314     void fireVetoableChangeListeners(
 315         std::unique_lock<std::mutex>& rGuard,
 316         comphelper::OInterfaceContainerHelper4<css::beans::XVetoableChangeListener>* pListeners,
 317         const css::beans::PropertyChangeEvent& rChangeEvent);
 318     void firePropertyChangeListeners(
 319         std::unique_lock<std::mutex>& rGuard,
 320         comphelper::OInterfaceContainerHelper4<css::beans::XPropertyChangeListener>* pListeners,
 321         const css::beans::PropertyChangeEvent& rChangeEvent);
 322 };
 323
 324 } // end namespace comphelper
 325
 326 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */