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