1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 #ifndef INCLUDED_CPPUHELPER_PROPERTYSETMIXIN_HXX 25 #define INCLUDED_CPPUHELPER_PROPERTYSETMIXIN_HXX \ 26 INCLUDED_CPPUHELPER_PROPERTYSETMIXIN_HXX 27 28 #include "sal/config.h" 29 #include "com/sun/star/beans/PropertyVetoException.hpp" 30 #include "com/sun/star/beans/UnknownPropertyException.hpp" 31 #include "com/sun/star/beans/XFastPropertySet.hpp" 32 #include "com/sun/star/beans/XPropertyAccess.hpp" 33 #include "com/sun/star/beans/XPropertySet.hpp" 34 #include "com/sun/star/lang/IllegalArgumentException.hpp" 35 #include "com/sun/star/lang/WrappedTargetException.hpp" 36 #include "com/sun/star/uno/Reference.hxx" 37 #include "com/sun/star/uno/RuntimeException.hpp" 38 #include "com/sun/star/uno/Sequence.hxx" 39 #include "sal/types.h" 40 #include "cppuhelper/cppuhelperdllapi.h" 41 42 /// @HTML 43 44 namespace com { namespace sun { namespace star { 45 namespace beans { 46 class XPropertyChangeListener; 47 class XPropertySetInfo; 48 class XVetoableChangeListener; 49 struct PropertyValue; 50 } 51 namespace uno { 52 class Any; 53 class Type; 54 class XComponentContext; 55 } 56 } } } 57 namespace rtl { class OUString; } 58 59 namespace cppu { 60 61 template< typename T > class PropertySetMixin; 62 63 // Suppress warnings about virtual functions but non-virtual destructor: 64 #if defined _MSC_VER 65 #pragma warning(push) 66 #pragma warning(disable: 4265) 67 #endif 68 69 /** 70 @short A helper base class for <code>cppu::PropertySetMixin</code>. 71 72 @descr See the documentation of <code>cppu::PropertySetMixin</code> for 73 further details. 74 75 @descr That <code>cppu::PropertySetMixin</code> is derived from this 76 base class should be considered an implementation detail. The functionality 77 of <code>cppu::PropertySetMixin</code> that is inherited from this base 78 class and is visible to subclasses of 79 <code>cppu::PropertySetMixin</code> should be treated by such 80 subclasses as being provided by <code>cppu::PropertySetMixin</code> 81 directly (e.g., in such subclasses, use 82 “<code>PropertySetMixin::Implements</code>” instead of 83 “<code>PropertySetMixinImpl::Implements</code>”). 84 85 @since UDK 3.2.1 86 */ 87 class CPPUHELPER_DLLPUBLIC PropertySetMixinImpl: 88 public com::sun::star::beans::XPropertySet, 89 public com::sun::star::beans::XFastPropertySet, 90 public com::sun::star::beans::XPropertyAccess 91 { 92 protected: 93 /** 94 @short Flags used by subclasses of 95 <code>cppu::PropertySetMixin</code> to specify what UNO interface 96 types shall be supported. 97 */ 98 enum Implements { 99 /** 100 @short Flag specifying that the UNO interface type 101 <code>com::sun::star::beans::XPropertySet</code> shall be supported. 102 */ 103 IMPLEMENTS_PROPERTY_SET = 1, 104 105 /** 106 @short Flag specifying that the UNO interface type 107 <code>com::sun::star::beans::XFastPropertySet</code> shall be 108 supported. 109 */ 110 IMPLEMENTS_FAST_PROPERTY_SET = 2, 111 112 /** 113 @short Flag specifying that the UNO interface type 114 <code>com::sun::star::beans::XPropertyAccess</code> shall be 115 supported. 116 */ 117 IMPLEMENTS_PROPERTY_ACCESS = 4 118 }; 119 120 /** 121 @short A class used by subclasses of 122 <code>cppu::PropertySetMixin</code> when implementing UNO interface 123 type attribute setter functions. 124 125 @descr This class is not thread safe; that is, the constructor, 126 <code>notify</code>, and the destructor must be called from the same 127 thread. 128 129 @descr See <code>cppu::PropertySetMixinImpl::prepareSet</code> for 130 further details. 131 */ 132 class CPPUHELPER_DLLPUBLIC BoundListeners { 133 public: 134 /** 135 @short The constructor. 136 137 @descr May throw <code>std::bad_alloc</code>. 138 */ 139 BoundListeners(); 140 141 /** 142 @short The destructor. 143 144 @descr Does not throw. 145 */ 146 ~BoundListeners(); 147 148 /** 149 @short Notifies any 150 <code>com::sun::star::beans::XPropertyChangeListener</code>s. 151 152 @descr May throw <code>com::sun::star::uno::RuntimeException</code> 153 and <code>std::bad_alloc</code>. 154 155 @descr See <code>cppu::PropertySetMixinImpl::prepareSet</code> 156 for further details. 157 */ 158 void notify() const; 159 160 private: 161 BoundListeners( const BoundListeners&); // not defined 162 void operator=( const BoundListeners&); // not defined 163 164 class Impl; 165 Impl * m_impl; 166 167 friend class PropertySetMixinImpl; 168 }; 169 170 /** 171 @short A function used by subclasses of 172 <code>cppu::PropertySetMixin</code> when implementing UNO interface 173 type attribute setter functions. 174 175 @descr First, this function checks whether this instance has already been 176 disposed (see <code>cppu::PropertySetMixinImpl::dispose</code>), 177 and throws a <code>com::sun::star::lang::DisposedException</code> if 178 applicable. For a constrained attribute (whose setter can explicitly 179 raise <code>com::sun::star::beans::PropertyVetoException</code>), this 180 function notifies any 181 <code>com::sun::star::beans::XVetoableChangeListener</code>s. For a 182 bound attribute, this function modifies the passed-in 183 <code>boundListeners</code> so that it can afterwards be used to notify 184 any <code>com::sun::star::beans::XPropertyChangeListener</code>s. This 185 function should be called before storing the new attribute value, and 186 <code>boundListeners->notify()</code> should be called exactly once after 187 storing the new attribute value (in case the attribute is bound; 188 otherwise, calling <code>boundListeners->notify()</code> is ignored). 189 Furthermore, <code>boundListeners->notify()</code> and this function have 190 to be called from the same thread. 191 192 @descr May throw 193 <code>com::sun::star::beans::PropertyVetoException</code>, 194 <code>com::sun::star::uno::RuntimeException</code> (and 195 <code>com::sun::star::lang::DisposedException</code> in particular), and 196 <code>std::bad_alloc</code>. 197 198 @param propertyName the name of the property (which is the same as the 199 name of the attribute that is going to be set) 200 201 @param oldValue the property value corresponding to the old attribute 202 value. This is only used as 203 <code>com::sun::star::beans::PropertyChangeEvent::OldValue</code>, which 204 is rather useless, anyway (see “Using the Observer Pattern” 205 in <a href="http://tools.openoffice.org/CodingGuidelines.sxw"> 206 <cite>OpenOffice.org Coding Guidelines</cite></a>). If the attribute 207 that is going to be set is neither bound nor constrained, or if 208 <code>com::sun::star::beans::PropertyChangeEvent::OldValue</code> should 209 not be set, a <code>VOID</code> <code>Any</code> can be used instead. 210 211 @param newValue the property value corresponding to the new 212 attribute value. This is only used as 213 <code>com::sun::star::beans::PropertyChangeEvent::NewValue</code>, which 214 is rather useless, anyway (see “Using the Observer Pattern” 215 in <a href="http://tools.openoffice.org/CodingGuidelines.sxw"> 216 <cite>OpenOffice.org Coding Guidelines</cite></a>), <em>unless</em> the 217 attribute that is going to be set is constrained. If the attribute 218 that is going to be set is neither bound nor constrained, or if it is 219 only bound but 220 <code>com::sun::star::beans::PropertyChangeEvent::NewValue</code> should 221 not be set, a <code>VOID</code> <code>Any</code> can be used instead. 222 223 @param boundListeners a pointer to a fresh 224 <code>cppu::PropertySetMixinImpl::BoundListeners</code> instance 225 (which has not been passed to this function before, and on which 226 <code>notify</code> has not yet been called); may only be null if the 227 attribute that is going to be set is not bound 228 */ 229 void prepareSet( 230 rtl::OUString const & propertyName, 231 com::sun::star::uno::Any const & oldValue, 232 com::sun::star::uno::Any const & newValue, 233 BoundListeners * boundListeners); 234 235 /** 236 @short Mark this instance as being disposed. 237 238 @descr See <code>com::sun::star::lang::XComponent</code> for the general 239 concept of disposing UNO objects. On the first call to this function, 240 all registered listeners 241 (<code>com::sun::star::beans::XPropertyChangeListener</code>s and 242 <code>com::sun::star::beans::XVetoableChangeListener</code>s) are 243 notified of the disposing source. Any subsequent calls to this function 244 are ignored. 245 246 @descr May throw <code>com::sun::star::uno::RuntimeException</code> and 247 <code>std::bad_alloc</code>. 248 */ 249 void dispose(); 250 251 /** 252 @short A function used by subclasses of 253 <code>cppu::PropertySetMixin</code> when implementing 254 <code>com::sun::star::uno::XInterface::queryInterface</code>. 255 256 @descr This function checks for support of any of the UNO interface types 257 specified in the call of the <code>cppu::PropertySetMixin</code> 258 constructor. It does not check for any other UNO interface types (not 259 even for <code>com::sun::star::uno::XInterface</code>), and should not 260 be used directly as the implementation of 261 <code>com::sun::star::uno::XInterface::queryInterface</code> of this UNO 262 object. 263 */ 264 virtual com::sun::star::uno::Any SAL_CALL queryInterface( 265 com::sun::star::uno::Type const & type) 266 throw (com::sun::star::uno::RuntimeException); 267 268 // @see com::sun::star::beans::XPropertySet::getPropertySetInfo 269 virtual 270 com::sun::star::uno::Reference< com::sun::star::beans::XPropertySetInfo > 271 SAL_CALL getPropertySetInfo() throw (com::sun::star::uno::RuntimeException); 272 273 // @see com::sun::star::beans::XPropertySet::setPropertyValue 274 virtual void SAL_CALL setPropertyValue( 275 rtl::OUString const & propertyName, 276 com::sun::star::uno::Any const & value) 277 throw ( 278 com::sun::star::beans::UnknownPropertyException, 279 com::sun::star::beans::PropertyVetoException, 280 com::sun::star::lang::IllegalArgumentException, 281 com::sun::star::lang::WrappedTargetException, 282 com::sun::star::uno::RuntimeException); 283 284 // @see com::sun::star::beans::XPropertySet::getPropertyValue 285 virtual com::sun::star::uno::Any SAL_CALL getPropertyValue( 286 rtl::OUString const & propertyName) 287 throw ( 288 com::sun::star::beans::UnknownPropertyException, 289 com::sun::star::lang::WrappedTargetException, 290 com::sun::star::uno::RuntimeException); 291 292 /** 293 @short Adds a 294 <code>com::sun::star::beans::XPropertyChangeListener</code>. 295 296 @descr If a listener is added more than once, it will receive all 297 relevant notifications multiple times. 298 299 @see com::sun::star::beans::XPropertySet::addPropertyChangeListener 300 */ 301 virtual void SAL_CALL addPropertyChangeListener( 302 rtl::OUString const & propertyName, 303 com::sun::star::uno::Reference< 304 com::sun::star::beans::XPropertyChangeListener > const & listener) 305 throw ( 306 com::sun::star::beans::UnknownPropertyException, 307 com::sun::star::lang::WrappedTargetException, 308 com::sun::star::uno::RuntimeException); 309 310 // @see com::sun::star::beans::XPropertySet::removePropertyChangeListener 311 virtual void SAL_CALL removePropertyChangeListener( 312 rtl::OUString const & propertyName, 313 com::sun::star::uno::Reference< 314 com::sun::star::beans::XPropertyChangeListener > const & listener) 315 throw ( 316 com::sun::star::beans::UnknownPropertyException, 317 com::sun::star::lang::WrappedTargetException, 318 com::sun::star::uno::RuntimeException); 319 320 /** 321 @short Adds a 322 <code>com::sun::star::beans::XVetoableChangeListener</code>. 323 324 @descr If a listener is added more than once, it will receive all 325 relevant notifications multiple times. 326 327 @see com::sun::star::beans::XPropertySet::addVetoableChangeListener 328 */ 329 virtual void SAL_CALL addVetoableChangeListener( 330 rtl::OUString const & propertyName, 331 com::sun::star::uno::Reference< 332 com::sun::star::beans::XVetoableChangeListener > const & listener) 333 throw ( 334 com::sun::star::beans::UnknownPropertyException, 335 com::sun::star::lang::WrappedTargetException, 336 com::sun::star::uno::RuntimeException); 337 338 // @see com::sun::star::beans::XPropertySet::removeVetoableChangeListener 339 virtual void SAL_CALL removeVetoableChangeListener( 340 rtl::OUString const & propertyName, 341 com::sun::star::uno::Reference< 342 com::sun::star::beans::XVetoableChangeListener > const & listener) 343 throw ( 344 com::sun::star::beans::UnknownPropertyException, 345 com::sun::star::lang::WrappedTargetException, 346 com::sun::star::uno::RuntimeException); 347 348 // @see com::sun::star::beans::XFastPropertySet::setFastPropertyValue 349 virtual void SAL_CALL setFastPropertyValue( 350 sal_Int32 handle, com::sun::star::uno::Any const & value) 351 throw ( 352 com::sun::star::beans::UnknownPropertyException, 353 com::sun::star::beans::PropertyVetoException, 354 com::sun::star::lang::IllegalArgumentException, 355 com::sun::star::lang::WrappedTargetException, 356 com::sun::star::uno::RuntimeException); 357 358 // @see com::sun::star::beans::XFastPropertySet::getFastPropertyValue 359 virtual com::sun::star::uno::Any SAL_CALL getFastPropertyValue( 360 sal_Int32 handle) 361 throw ( 362 com::sun::star::beans::UnknownPropertyException, 363 com::sun::star::lang::WrappedTargetException, 364 com::sun::star::uno::RuntimeException); 365 366 // @see com::sun::star::beans::XPropertyAccess::getPropertyValues 367 virtual 368 com::sun::star::uno::Sequence< com::sun::star::beans::PropertyValue > 369 SAL_CALL getPropertyValues() throw (com::sun::star::uno::RuntimeException); 370 371 // @see com::sun::star::beans::XPropertyAccess::setPropertyValues 372 virtual void SAL_CALL setPropertyValues( 373 com::sun::star::uno::Sequence< com::sun::star::beans::PropertyValue > 374 const & props) 375 throw ( 376 com::sun::star::beans::UnknownPropertyException, 377 com::sun::star::beans::PropertyVetoException, 378 com::sun::star::lang::IllegalArgumentException, 379 com::sun::star::lang::WrappedTargetException, 380 com::sun::star::uno::RuntimeException); 381 382 private: 383 PropertySetMixinImpl( const PropertySetMixinImpl&); // not defined 384 void operator=( const PropertySetMixinImpl&); // not defined 385 386 PropertySetMixinImpl( 387 com::sun::star::uno::Reference< com::sun::star::uno::XComponentContext > 388 const & context, 389 Implements implements, 390 com::sun::star::uno::Sequence< rtl::OUString > const & absentOptional, 391 com::sun::star::uno::Type const & type); 392 393 class Impl; 394 Impl * m_impl; 395 396 friend class Impl; 397 template< typename T > friend class PropertySetMixin; 398 399 ~PropertySetMixinImpl(); 400 401 void checkUnknown(rtl::OUString const & propertyName); 402 }; 403 404 /** 405 @short A helper mixin to implement certain UNO interfaces related to property 406 set handling on top of the attributes of a given UNO interface type. 407 408 @descr The UNO interface type is specified by the type parameter 409 <code>T</code> (which must correspond to a UNO interface type). 410 411 @descr No specializations of this class template should be added by client 412 code. 413 414 @since UDK 3.2.1 415 */ 416 template< typename T > class PropertySetMixin: public PropertySetMixinImpl { 417 protected: 418 /** 419 @short The constructor. 420 421 @descr May throw <code>com::sun::star::uno::RuntimeException</code> and 422 <code>std::bad_alloc</code>. 423 424 @param context the component context used by this class template; must 425 not be null, and must supply the service 426 <code>com.sun.star.reflection.CoreReflection</code> and the singleton 427 <code>com.sun.star.reflection.theTypeDescriptionManager</code> 428 429 @param implements a combination of zero or more flags specifying what 430 UNO interface types shall be supported 431 432 @param absentOptional a list of optional properties that are not 433 present, and should thus not be visible via 434 <code>com::sun::star::beans::XPropertySet::getPropertySetInfo</code>, 435 <code>com::sun::star::beans::XPropertySet::addPropertyChangeListener<!-- 436 --></code>, <code>com::sun::star::beans::XPropertySet::<!-- 437 -->removePropertyChangeListener</code>, 438 <code>com::sun::star::beans::XPropertySet::addVetoableChangeListener<!-- 439 --></code>, and <code>com::sun::star::beans::XPropertySet::<!-- 440 -->removeVetoableChangeListener</code>. For consistency reasons, the 441 given <code>absentOptional</code> should only contain the names of 442 attributes that represent optional properties that are not present (that 443 is, the attribute getters and setters always throw a 444 <code>com::sun::star::beans::UnknownPropertyException</code>), and should 445 contain each such name only once. If an optional property is not present 446 (that is, the corresponding attribute getter and setter always throw a 447 <code>com::sun::star::beans::UnknownPropertyException</code>) but is not 448 contained in the given <code>absentOptional</code>, then it will be 449 visible via 450 <code>com::sun::star::beans::XPropertySet::getPropertySetInfo</code> as a 451 <code>com::sun::star::beans::Property</code> with a set 452 <code>com::sun::star::beans::PropertyAttribute::OPTIONAL</code>. If the 453 given <code>implements</code> specifies that 454 <code>com::sun::star::beans::XPropertySet</code> is not supported, then 455 the given <code>absentOptional</code> is effectively ignored and can be 456 empty. 457 */ PropertySetMixin(com::sun::star::uno::Reference<com::sun::star::uno::XComponentContext> const & context,Implements implements,com::sun::star::uno::Sequence<rtl::OUString> const & absentOptional)458 PropertySetMixin( 459 com::sun::star::uno::Reference< com::sun::star::uno::XComponentContext > 460 const & context, 461 Implements implements, 462 com::sun::star::uno::Sequence< rtl::OUString > const & absentOptional): 463 PropertySetMixinImpl( 464 context, implements, absentOptional, T::static_type()) 465 {} 466 467 /** 468 @short The destructor. 469 470 @descr Does not throw. 471 */ ~PropertySetMixin()472 ~PropertySetMixin() {} 473 474 private: 475 PropertySetMixin( const PropertySetMixin&); // not defined 476 void operator=( const PropertySetMixin&); // not defined 477 }; 478 479 #if defined _MSC_VER 480 #pragma warning(pop) 481 #endif 482 483 } 484 485 #endif 486