include/cppuhelper/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
  20 #ifndef INCLUDED_CPPUHELPER_PROPSHLP_HXX
  21 #define INCLUDED_CPPUHELPER_PROPSHLP_HXX
  22
  23 #include <rtl/alloc.h>
  24
  25 #include <cppuhelper/interfacecontainer.h>
  26
  27 #include <com/sun/star/beans/XPropertySet.hpp>
  28 #include <com/sun/star/beans/XPropertySetOption.hpp>
  29 #include <com/sun/star/beans/XMultiPropertySet.hpp>
  30 #include <com/sun/star/beans/XFastPropertySet.hpp>
  31
  32 #include <cppuhelper/cppuhelperdllapi.h>
  33
  34
  35 namespace cppu
  36 {
  37
  38
  39 /*************************************************************************
  40 *************************************************************************/
  41
  42
  43 /**
  44    This interface is used by the OPropertyHelper, to access the property description.
  45  */
  46 class SAL_WARN_UNUSED CPPUHELPER_DLLPUBLIC IPropertyArrayHelper
  47 {
  48 public:
  49     // these are here to force memory de/allocation to sal lib.
  50     static void * SAL_CALL operator new( size_t nSize )
  51         { return ::rtl_allocateMemory( nSize ); }
  52     static void SAL_CALL operator delete( void * pMem )
  53         { ::rtl_freeMemory( pMem ); }
  54     static void * SAL_CALL operator new( size_t, void * pMem )
  55         { return pMem; }
  56     static void SAL_CALL operator delete( void *, void * )
  57         {}
  58
  59     /**
  60        Following the rule, the first virtual method implies a virtual destructor.
  61      */
  62     virtual ~IPropertyArrayHelper();
  63
  64     /**
  65        Return the property members Name and Attribute from the handle nHandle.
  66        @param nHandle   the handle of a property. If the values of the handles
  67                           are sorted in the same way as the names and the highest handle value
  68                           is getCount() -1, than it must be an indexed access to the property array.
  69        @param pPropName is an out parameter filled with property name of the property with the
  70                               handle nHandle. May be NULL.
  71        @param pAttributes is an out parameter filled with attributes of the property with the
  72                               handle nHandle. May be NULL.
  73        @return True, if the handle exist, otherwise false.
  74      */
  75     virtual sal_Bool SAL_CALL fillPropertyMembersByHandle(
  76         ::rtl::OUString * pPropName, sal_Int16 * pAttributes, sal_Int32 nHandle ) = 0;
  77     /**
  78        Return the sequence of properties. The sequence is sorted by name.
  79      */
  80     virtual css::uno::Sequence< css::beans::Property > SAL_CALL getProperties() = 0;
  81     /**
  82        Return the property with the name rPropertyName.
  83        @param rPropertyName the name of the property.
  84        @exception UnknownPropertyException  thrown if the property name is unknown.
  85      */
  86     virtual css::beans::Property SAL_CALL getPropertyByName(
  87         const ::rtl::OUString& rPropertyName ) = 0;
  88     /**
  89        Return true if the property with the name rPropertyName exist, otherwise false.
  90        @param rPropertyName the name of the property.
  91      */
  92     virtual sal_Bool SAL_CALL hasPropertyByName(const ::rtl::OUString& rPropertyName) = 0;
  93     /**
  94        Return the handle of the property with the name rPropertyName.
  95        If the property does not exist -1 is returned.
  96        @param rPropertyName the name of the property.
  97      */
  98     virtual sal_Int32 SAL_CALL getHandleByName( const ::rtl::OUString & rPropertyName ) = 0;
  99     /**
 100        Fill the array with the handles of the properties.
 101        @return the handles of the names from the pHandles array. -1
 102        indicates an unknown property name.
 103      */
 104     virtual sal_Int32 SAL_CALL fillHandles(
 105         /*out*/ sal_Int32 * pHandles, const css::uno::Sequence< ::rtl::OUString > & rPropNames ) = 0;
 106 };
 107
 108 /**
 109    You can use this helper class to map a XPropertySet-Interface to a XFast-
 110    or a XMultiPropertySet interface.
 111  */
 112 class SAL_WARN_UNUSED CPPUHELPER_DLLPUBLIC OPropertyArrayHelper : public IPropertyArrayHelper
 113 {
 114 public:
 115      /**
 116        Create an object which supports the common property interfaces.
 117
 118        @param pProps    array of properties
 119                           The array pProps should be sorted.
 120        @param nElements is the number of properties in the pProps structure.
 121        @param bSorted   indicates that the elements are sorted.
 122       *********/
 123     OPropertyArrayHelper(
 124         css::beans::Property *pProps,
 125         sal_Int32 nElements ,
 126         sal_Bool bSorted = true );
 127
 128      /**
 129        Create an object which supports the common property interfaces.
 130        @param aProps     sequence of properties which are supported by this helper.
 131                            The sequence aProps should be sorted.
 132        @param bSorted    indicates that the elements are sorted.
 133      */
 134     OPropertyArrayHelper(
 135         const css::uno::Sequence< css::beans::Property > & aProps,
 136         sal_Bool bSorted = true );
 137
 138     /**
 139        Return the number of properties.
 140      */
 141     sal_Int32 SAL_CALL getCount() const;
 142     /**
 143        Return the property members Name and Attribute from the handle nHandle.
 144        @param nHandle   the handle of a property. If the values of the handles
 145                           are sorted in the same way as the names and the highest handle value
 146                           is getCount() -1, than it is only an indexed access to the property array.
 147                           Otherwise it is a linear search through the array.
 148        @param pPropName is an out parameter filled with property name of the property with the
 149                               handle nHandle. May be NULL.
 150        @param pAttributes is an out parameter filled with attributes of the property with the
 151                               handle nHandle. May be NULL.
 152        @return True, if the handle exist, otherwise false.
 153      */
 154     virtual sal_Bool SAL_CALL fillPropertyMembersByHandle(
 155         ::rtl::OUString * pPropName, sal_Int16 * pAttributes, sal_Int32 nHandle ) SAL_OVERRIDE;
 156     /**
 157        Return the sequence of properties. The sequence is sorted by name.
 158      */
 159     virtual css::uno::Sequence< css::beans::Property > SAL_CALL getProperties() SAL_OVERRIDE;
 160     /**
 161        Return the property with the name rPropertyName.
 162        @param rPropertyName the name of the property.
 163        @exception UnknownPropertyException  thrown if the property name is unknown.
 164      */
 165     virtual css::beans::Property SAL_CALL getPropertyByName(
 166         const ::rtl::OUString& rPropertyName ) SAL_OVERRIDE;
 167     /**
 168        Return true if the property with the name rPropertyName exist, otherwise false.
 169        @param rPropertyName the name of the property.
 170      */
 171     virtual sal_Bool SAL_CALL hasPropertyByName(const ::rtl::OUString& rPropertyName) SAL_OVERRIDE;
 172     /**
 173        Return the handle of the property with the name rPropertyName.
 174        If the property does not exist -1 is returned.
 175        @param rPropertyName the name of the property.
 176      */
 177     virtual sal_Int32 SAL_CALL getHandleByName( const ::rtl::OUString & rPropertyName ) SAL_OVERRIDE;
 178     /**
 179        Fill the array with the handles of the properties.
 180        @return the handles of the names from the pHandles array. -1
 181        indicates an unknown property name.
 182      */
 183     virtual sal_Int32 SAL_CALL fillHandles(
 184         /*out*/sal_Int32 * pHandles, const css::uno::Sequence< ::rtl::OUString > & rPropNames ) SAL_OVERRIDE;
 185
 186 protected:
 187     /** reserved for future use. do not use.
 188      */
 189     void * m_pReserved;
 190
 191 private:
 192     void init( sal_Bool bSorted );
 193
 194     /** The sequence generated from the pProperties array. */
 195     css::uno::Sequence< css::beans::Property > aInfos;
 196
 197     /**
 198        True, If the values of the handles are sorted in the same way as the names
 199        and the highest handle value is getCount() -1, otherwise false.
 200      */
 201     sal_Bool                    bRightOrdered;
 202 };
 203
 204
 205 // helper defines needed for an interface container with a 32 bit key values
 206
 207 struct equalInt32_Impl
 208 {
 209     bool operator()(const sal_Int32 & i1 , const sal_Int32 & i2) const
 210         { return i1 == i2; }
 211 };
 212
 213 struct hashInt32_Impl
 214 {
 215     size_t operator()(const sal_Int32 & i) const
 216         { return i; }
 217 };
 218
 219 /** Specialized class for key type sal_Int32,
 220     without explicit usage of STL symbols.
 221 */
 222 class SAL_WARN_UNUSED CPPUHELPER_DLLPUBLIC OMultiTypeInterfaceContainerHelperInt32
 223 {
 224 public:
 225     // these are here to force memory de/allocation to sal lib.
 226     static void * SAL_CALL operator new( size_t nSize )
 227         { return ::rtl_allocateMemory( nSize ); }
 228     static void SAL_CALL operator delete( void * pMem )
 229         { ::rtl_freeMemory( pMem ); }
 230     static void * SAL_CALL operator new( size_t, void * pMem )
 231         { return pMem; }
 232     static void SAL_CALL operator delete( void *, void * )
 233         {}
 234
 235     /**
 236       Create a container of interface containers.
 237
 238       @param rMutex the mutex to protect multi thread access.
 239                          The lifetime must be longer than the lifetime
 240                          of this object.
 241      */
 242     OMultiTypeInterfaceContainerHelperInt32( ::osl::Mutex & rMutex );
 243     /**
 244       Delete all containers.
 245      */
 246     ~OMultiTypeInterfaceContainerHelperInt32();
 247
 248     /**
 249       Return all id's under which at least one interface is added.
 250      */
 251     css::uno::Sequence< sal_Int32 > SAL_CALL getContainedTypes() const;
 252
 253     /**
 254       Return the container created under this key.
 255       @return the container created under this key. If the container
 256                  was not created, null was returned.
 257      */
 258     OInterfaceContainerHelper * SAL_CALL getContainer( const sal_Int32 & rKey ) const;
 259
 260     /**
 261       Insert an element in the container specified with the key. The position is not specified.
 262       @param rKey       the id of the container.
 263       @param r          the added interface. It is allowed to insert null or
 264                          the same pointer more than once.
 265       @return the new count of elements in the container.
 266      */
 267     sal_Int32 SAL_CALL addInterface(
 268         const sal_Int32 & rKey,
 269         const css::uno::Reference< css::uno::XInterface > & r );
 270
 271     /**
 272       Remove an element from the container specified with the key.
 273       It uses the equal definition of uno objects to remove the interfaces.
 274       @param rKey       the id of the container.
 275       @param rxIFace    the removed interface.
 276       @return the new count of elements in the container.
 277      */
 278     sal_Int32 SAL_CALL removeInterface(
 279         const sal_Int32 & rKey,
 280         const css::uno::Reference< css::uno::XInterface > & rxIFace );
 281
 282     /**
 283       Call disposing on all objects in the container that
 284       support XEventListener. Then clear the container.
 285      */
 286     void SAL_CALL disposeAndClear( const css::lang::EventObject & rEvt );
 287     /**
 288       Remove all elements of all containers. Does not delete the container.
 289      */
 290     void SAL_CALL clear();
 291
 292     typedef sal_Int32 keyType;
 293 private:
 294     void *          m_pMap;
 295     ::osl::Mutex &  rMutex;
 296
 297     OMultiTypeInterfaceContainerHelperInt32( const OMultiTypeInterfaceContainerHelperInt32 & ) SAL_DELETED_FUNCTION;
 298     OMultiTypeInterfaceContainerHelperInt32 & operator = ( const OMultiTypeInterfaceContainerHelperInt32 & )SAL_DELETED_FUNCTION;
 299 };
 300
 301
 302 /** An interface to extend event notification actions.
 303   */
 304 class IEventNotificationHook
 305 {
 306 public:
 307     /**
 308         Method to be called by OPropertySetHelper::fire.
 309
 310         @param bIgnoreRuntimeExceptionsWhileFiring
 311                         indicates whether occurring RuntimeExceptions shall be
 312                         ignored when firing notifications
 313        @param pnHandles     the id's of the properties that changed.
 314        @param nCount        the number of elements in the arrays pnHandles, pNewValues and pOldValues.
 315        @param bVetoable true means fire to VetoableChangeListener, false means fire to
 316                   XPropertyChangedListener and XMultiPropertyChangedListener.
 317        @param bIgnoreRuntimeExceptionsWhileFiring
 318                         indicates whether occurring RuntimeExceptions will be
 319                         ignored when firing notifications
 320                         (vetoableChange(), propertyChange())
 321                         to listeners.
 322                         PropertyVetoExceptions may still be thrown.
 323                         This flag is useful in an inter-process scenario when
 324                         remote bridges may break down
 325                         (firing DisposedExceptions).
 326
 327         @see OPropertySetHelper::fire
 328      */
 329     virtual void fireEvents(
 330         sal_Int32 * pnHandles,
 331         sal_Int32 nCount,
 332         sal_Bool bVetoable,
 333         bool bIgnoreRuntimeExceptionsWhileFiring) = 0;
 334
 335 #if !defined _MSC_VER // public -> protected changes mangled names there
 336 protected:
 337 #elif defined __clang__
 338 #pragma clang diagnostic push
 339 #pragma clang diagnostic ignored "-Wnon-virtual-dtor"
 340 #endif
 341     ~IEventNotificationHook() {}
 342         // avoid warnings about virtual members and non-virtual dtor
 343 #if defined _MSC_VER && defined __clang__
 344 #pragma clang diagnostic pop
 345 #endif
 346 };
 347
 348
 349 /**
 350    This abstract class maps the methods of the interfaces XMultiPropertySet, XFastPropertySet
 351    and XPropertySet to the methods getInfoHelper, convertFastPropertyValue,
 352    setFastPropertyValue_NoBroadcast and getFastPropertyValue. You must derive from
 353    this class and override the methods.
 354    It provides a standard implementation of the XPropertySetInfo.
 355    The XPropertiesChangeListener are inserted in the rBHelper.aLC structure.
 356    The XPropertyChangeListener and XVetoableChangeListener with no names are inserted
 357    in the rBHelper.aLC structure. So it is possible to advise property listeners with
 358    the connection point interfaces. But only listeners that listen to all property changes.
 359
 360  */
 361 class CPPUHELPER_DLLPUBLIC OPropertySetHelper :
 362                            public css::beans::XMultiPropertySet,
 363                            public css::beans::XFastPropertySet,
 364                            public css::beans::XPropertySet
 365 {
 366 public:
 367     /**
 368        @param rBHelper  this structure contains the basic members of
 369                           a broadcaster.
 370                           The lifetime must be longer than the lifetime
 371                           of this object. Stored in the variable rBHelper.
 372      */
 373     OPropertySetHelper( OBroadcastHelper & rBHelper );
 374
 375     /** Constructor.
 376
 377         @param rBHelper
 378                         this structure contains the basic members of
 379                         a broadcaster.
 380                           The lifetime must be longer than the lifetime
 381                           of this object. Stored in the variable rBHelper.
 382
 383         @param bIgnoreRuntimeExceptionsWhileFiring
 384                         indicates whether occurring RuntimeExceptions will be
 385                         ignored when firing notifications
 386                         (vetoableChange(), propertyChange())
 387                         to listeners.
 388                         PropertyVetoExceptions may still be thrown.
 389                         This flag is useful in an inter-process scenario when
 390                         remote bridges may break down
 391                         (firing DisposedExceptions).
 392     */
 393     OPropertySetHelper(
 394         OBroadcastHelper & rBHelper, bool bIgnoreRuntimeExceptionsWhileFiring );
 395
 396     /** Constructor.
 397
 398         @param rBHelper
 399                         this structure contains the basic members of
 400                         a broadcaster.
 401                         The lifetime must be longer than the lifetime
 402                         of this object. Stored in the variable rBHelper.
 403
 404         @param i_pFireEvents
 405                         additional event notifier
 406
 407         @param bIgnoreRuntimeExceptionsWhileFiring
 408                         indicates whether occurring RuntimeExceptions will be
 409                         ignored when firing notifications
 410                         (vetoableChange(), propertyChange())
 411                         to listeners.
 412                         PropertyVetoExceptions may still be thrown.
 413                         This flag is useful in an inter-process scenario when
 414                         remote bridges may break down
 415                         (firing DisposedExceptions).
 416     */
 417     OPropertySetHelper(
 418         OBroadcastHelper & rBHelper,
 419         IEventNotificationHook *i_pFireEvents,
 420         bool bIgnoreRuntimeExceptionsWhileFiring = false);
 421
 422     /**
 423        Only returns a reference to XMultiPropertySet, XFastPropertySet, XPropertySet and
 424        XEventListener.
 425      */
 426     virtual css::uno::Any SAL_CALL queryInterface( const css::uno::Type & rType ) SAL_OVERRIDE;
 427
 428     /** eases implementing XTypeProvider::getTypes, returns the types of XMultiPropertySet, XFastPropertySet, XPropertySet
 429
 430         @throws css::uno::RuntimeException
 431      */
 432     css::uno::Sequence< css::uno::Type > getTypes();
 433
 434     /**
 435        Send a disposing notification to the listeners in the containers aBoundLC
 436        and aVetoableLC.
 437
 438        @see OComponentHelper
 439      */
 440     void SAL_CALL disposing();
 441
 442     /**
 443        Throw UnknownPropertyException or PropertyVetoException if the property with the name
 444        rPropertyName does not exist or is readonly. Otherwise rPropertyName is changed to its handle
 445        value and setFastPropertyValue is called.
 446      */
 447     virtual void SAL_CALL setPropertyValue( const ::rtl::OUString& rPropertyName, const css::uno::Any& aValue ) SAL_OVERRIDE;
 448     /**
 449        Throw UnknownPropertyException if the property with the name
 450        rPropertyName does not exist.
 451      */
 452     virtual css::uno::Any SAL_CALL getPropertyValue(const ::rtl::OUString& aPropertyName) SAL_OVERRIDE;
 453     /** Ignored if the property is not bound. */
 454     virtual void SAL_CALL addPropertyChangeListener(
 455         const ::rtl::OUString& aPropertyName,
 456         const css::uno::Reference< css::beans::XPropertyChangeListener >& aListener) SAL_OVERRIDE;
 457
 458     /** Ignored if the property is not bound. */
 459     virtual void SAL_CALL removePropertyChangeListener(
 460         const ::rtl::OUString& aPropertyName,
 461         const css::uno::Reference < css::beans::XPropertyChangeListener >& aListener) SAL_OVERRIDE;
 462
 463     /** Ignored if the property is not constrained. */
 464     virtual void SAL_CALL addVetoableChangeListener(
 465         const ::rtl::OUString& aPropertyName,
 466         const css::uno::Reference< css::beans::XVetoableChangeListener >& aListener) SAL_OVERRIDE;
 467
 468     /** Ignored if the property is not constrained. */
 469     virtual void SAL_CALL removeVetoableChangeListener(
 470         const ::rtl::OUString& aPropertyName,
 471         const css::uno::Reference< css::beans::XVetoableChangeListener > & aListener ) SAL_OVERRIDE;
 472
 473     /**
 474        Throw UnknownPropertyException or PropertyVetoException if the property with the name
 475        rPropertyName does not exist or is readonly. Otherwise the method convertFastPropertyValue
 476        is called, then the vetoable listeners are notified. After this the value of the property
 477        is changed with the setFastPropertyValue_NoBroadcast method and the bound listeners are
 478        notified.
 479       */
 480     virtual void SAL_CALL setFastPropertyValue( sal_Int32 nHandle, const css::uno::Any& rValue ) SAL_OVERRIDE;
 481
 482     /**
 483        @exception css::beans::UnknownPropertyException
 484          if the property with the handle nHandle does not exist.
 485      */
 486     virtual css::uno::Any SAL_CALL getFastPropertyValue( sal_Int32 nHandle ) SAL_OVERRIDE;
 487
 488     // XMultiPropertySet
 489     virtual void SAL_CALL setPropertyValues(
 490         const css::uno::Sequence< ::rtl::OUString >& PropertyNames,
 491         const css::uno::Sequence< css::uno::Any >& Values ) SAL_OVERRIDE;
 492
 493     virtual css::uno::Sequence< css::uno::Any > SAL_CALL getPropertyValues(
 494         const css::uno::Sequence< ::rtl::OUString >& PropertyNames ) SAL_OVERRIDE;
 495
 496     virtual void SAL_CALL addPropertiesChangeListener(
 497         const css::uno::Sequence< ::rtl::OUString >& PropertyNames,
 498         const css::uno::Reference< css::beans::XPropertiesChangeListener >& Listener ) SAL_OVERRIDE;
 499
 500     virtual void SAL_CALL removePropertiesChangeListener(
 501         const css::uno::Reference< css::beans::XPropertiesChangeListener >& Listener ) SAL_OVERRIDE;
 502
 503     virtual void SAL_CALL firePropertiesChangeEvent(
 504         const css::uno::Sequence< ::rtl::OUString >& PropertyNames,
 505         const css::uno::Reference< css::beans::XPropertiesChangeListener > & Listener ) SAL_OVERRIDE;
 506
 507     /**
 508        The property sequence is created in the call. The interface isn't used after the call.
 509      */
 510     static css::uno::Reference < css::beans::XPropertySetInfo > SAL_CALL
 511         createPropertySetInfo( IPropertyArrayHelper & rProperties );
 512 protected:
 513     /**
 514        This method fire events to all registered property listeners.
 515        @param pnHandles     the id's of the properties that changed.
 516        @param pNewValues    the new values of the properties.
 517        @param pOldValues    the old values of the properties.
 518        @param nCount        the number of elements in the arrays pnHandles, pNewValues and pOldValues.
 519        @param bVetoable true means fire to VetoableChangeListener, false means fire to
 520                   XPropertyChangedListener and XMultiPropertyChangedListener.
 521      */
 522     void SAL_CALL fire(
 523         sal_Int32 * pnHandles,
 524         const css::uno::Any * pNewValues,
 525         const css::uno::Any * pOldValues,
 526         sal_Int32 nCount,
 527         sal_Bool bVetoable );
 528
 529     /**
 530        Set multiple properties with the handles.
 531        @param nSeqLen   the length of the arrays pHandles and Values.
 532        @param pHandles the handles of the properties. The number of elements
 533               in the Values sequence is the length of the handle array. A value of -1
 534               of a handle means invalid property. These are ignored.
 535        @param pValues the values of the properties.
 536        @param nHitCount the number of valid entries in the handle array.
 537      */
 538     void SAL_CALL setFastPropertyValues(
 539         sal_Int32 nSeqLen,
 540         sal_Int32 * pHandles,
 541         const css::uno::Any * pValues,
 542         sal_Int32 nHitCount );
 543
 544     /**
 545        This abstract method must return the name to index table. This table contains all property
 546        names and types of this object. The method is not implemented in this class.
 547      */
 548     virtual IPropertyArrayHelper & SAL_CALL getInfoHelper() = 0;
 549
 550     /**
 551        Converted the value rValue and return the result in rConvertedValue and the
 552        old value in rOldValue. A IllegalArgumentException is thrown.
 553        The method is not implemented in this class. After this call the vetoable
 554        listeners are notified.
 555
 556        @param rConvertedValue the converted value. Only set if return is true.
 557        @param rOldValue the old value. Only set if return is true.
 558        @param nHandle the handle of the proberty.
 559        @param rValue the value to be converted
 560        @return true if the value converted.
 561        @throws css::lang::IllegalArgumentException
 562        @throws css::beans::UnknownPropertyException
 563        @throws css::uno::RuntimeException
 564      */
 565     virtual sal_Bool SAL_CALL convertFastPropertyValue(
 566         css::uno::Any & rConvertedValue,
 567         css::uno::Any & rOldValue,
 568         sal_Int32 nHandle,
 569         const css::uno::Any& rValue ) = 0;
 570
 571     /** The same as setFastProperyValue; nHandle is always valid.
 572         The changes must not be broadcasted in this method.
 573         The method is implemented in a derived class.
 574
 575         @attention
 576         Although you are permitted to throw any UNO exception, only the following
 577         are valid for usage:
 578         -- css::beans::UnknownPropertyException
 579         -- css::beans::PropertyVetoException
 580         -- css::lang::IllegalArgumentException
 581         -- css::lang::WrappedTargetException
 582         -- css::uno::RuntimeException
 583
 584         @param nHandle
 585                handle
 586         @param rValue
 587                value
 588         @throws css::uno::Exception
 589     */
 590     virtual void SAL_CALL setFastPropertyValue_NoBroadcast(
 591         sal_Int32 nHandle,
 592         const css::uno::Any& rValue ) = 0;
 593     /**
 594        The same as getFastProperyValue, but return the value through rValue and nHandle
 595        is always valid.
 596        The method is not implemented in this class.
 597      */
 598     virtual void SAL_CALL getFastPropertyValue(
 599         css::uno::Any& rValue,
 600         sal_Int32 nHandle ) const = 0;
 601
 602     /** sets an dependent property's value
 603
 604         <p>Sometimes setting a given property needs to implicitly modify another property's value. Calling |setPropertyValue|
 605         from within |setFastPropertyValue_NoBroadcast| is not an option here, as it would notify the property listeners
 606         while our mutex is still locked. Setting the dependent property's value directly (e.g. by calling |setFastPropertyValue_NoBroadcast|
 607         recursively) is not an option, too, since it would miss firing the property change event.</p>
 608
 609         <p>So, in such cases, you use |setDependentFastPropertyValue| from within |setFastPropertyValue_NoBroadcast|.
 610         It will convert and actually set the property value (invoking |convertFastPropertyValue| and |setFastPropertyValue_NoBroadcast|
 611         for the given handle and value), and add the property change event to the list of events to be notified
 612         when the bottom-most |setFastPropertyValue_NoBroadcast| on the stack returns.</p>
 613
 614         <p><strong>Note</strong>: The method will <em>not</em> invoke veto listeners for the property.</p>
 615
 616         <p><strong>Note</strong>: It's the caller's responsibility to ensure that our mutex is locked. This is
 617         canonically given when the method is invoked from within |setFastPropertyValue_NoBroadcast|, in other
 618         contexts, you might need to take own measures.</p>
 619     */
 620     void    setDependentFastPropertyValue(
 621                 sal_Int32 i_handle,
 622                 const css::uno::Any& i_value
 623             );
 624
 625     /** The common data of a broadcaster. Use the mutex, disposing state and the listener container. */
 626     OBroadcastHelper    &rBHelper;
 627     /**
 628        Container for the XProperyChangedListener. The listeners are inserted by handle.
 629      */
 630     OMultiTypeInterfaceContainerHelperInt32  aBoundLC;
 631     /**
 632        Container for the XPropertyVetoableListener. The listeners are inserted by handle.
 633      */
 634     OMultiTypeInterfaceContainerHelperInt32 aVetoableLC;
 635
 636     class Impl;
 637
 638     /** reserved for future use. finally, the future has arrived...
 639      */
 640     Impl * const m_pReserved;
 641
 642 private:
 643     OPropertySetHelper( const OPropertySetHelper & ) SAL_DELETED_FUNCTION;
 644     OPropertySetHelper &    operator = ( const OPropertySetHelper & )
 645         SAL_DELETED_FUNCTION;
 646
 647     /** notifies the given changes in property's values, <em>plus</em> all property changes collected during recent
 648         |setDependentFastPropertyValue| calls.
 649     */
 650     void    impl_fireAll(
 651                 sal_Int32* i_handles,
 652                 const css::uno::Any * i_newValues,
 653                 const css::uno::Any * i_oldValues,
 654                 sal_Int32 i_count
 655             );
 656
 657 #if defined _MSC_VER // public -> protected changes mangled names there
 658 public:
 659 #else
 660 protected:
 661 #endif
 662 // Suppress warning about virtual functions but non-virtual destructor:
 663 #if defined _MSC_VER
 664 #pragma warning(push)
 665 #pragma warning(disable: 4265)
 666 #if defined __clang__
 667 #pragma clang diagnostic push
 668 #pragma clang diagnostic ignored "-Wnon-virtual-dtor"
 669 #endif
 670 #endif
 671     /**
 672        You must call disposing before destruction.
 673      */
 674     ~OPropertySetHelper();
 675 };
 676 #if defined _MSC_VER
 677 #if defined __clang__
 678 #pragma clang diagnostic pop
 679 #endif
 680 #pragma warning(pop)
 681 #endif
 682
 683 /**
 684    OPropertySetHelper plus XPropertySetOption
 685
 686    @attention
 687    The getTypes() inherited from OPropertysetHelper does not cover
 688    XPropertySetOption.
 689 */
 690 class CPPUHELPER_DLLPUBLIC OPropertySetHelper2 : public OPropertySetHelper,
 691                             public css::beans::XPropertySetOption
 692 {
 693 public:
 694     /** Constructor.
 695
 696         See OPropertySetHelper constructors documentation
 697     */
 698     explicit OPropertySetHelper2(
 699         OBroadcastHelper & rBHelper,
 700         IEventNotificationHook *i_pFireEvents = NULL,
 701         bool bIgnoreRuntimeExceptionsWhileFiring = false);
 702
 703     // XInterface
 704     virtual css::uno::Any SAL_CALL queryInterface( const css::uno::Type & rType ) SAL_OVERRIDE;
 705
 706     // XPropertySetOption
 707     virtual void SAL_CALL enableChangeListenerNotification( sal_Bool bEnable ) SAL_OVERRIDE;
 708
 709
 710 private:
 711     OPropertySetHelper2( const OPropertySetHelper2 & ) SAL_DELETED_FUNCTION;
 712     OPropertySetHelper2 &    operator = ( const OPropertySetHelper2 & )
 713         SAL_DELETED_FUNCTION;
 714
 715 #if defined _MSC_VER // public -> protected changes mangled names there
 716 public:
 717 #else
 718 protected:
 719 #endif
 720 // Suppress warning about virtual functions but non-virtual destructor:
 721     /**
 722        You must call disposing before destruction.
 723      */
 724     virtual ~OPropertySetHelper2();
 725 };
 726
 727 } // end namespace cppuhelper
 728 #endif
 729
 730
 731 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */