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 267 // @see com::sun::star::beans::XPropertySet::getPropertySetInfo 268 virtual 269 com::sun::star::uno::Reference< com::sun::star::beans::XPropertySetInfo > 270 SAL_CALL getPropertySetInfo(); 271 272 // @see com::sun::star::beans::XPropertySet::setPropertyValue 273 virtual void SAL_CALL setPropertyValue( 274 rtl::OUString const & propertyName, 275 com::sun::star::uno::Any const & value); 276 277 // @see com::sun::star::beans::XPropertySet::getPropertyValue 278 virtual com::sun::star::uno::Any SAL_CALL getPropertyValue( 279 rtl::OUString const & propertyName); 280 281 /** 282 @short Adds a 283 <code>com::sun::star::beans::XPropertyChangeListener</code>. 284 285 @descr If a listener is added more than once, it will receive all 286 relevant notifications multiple times. 287 288 @see com::sun::star::beans::XPropertySet::addPropertyChangeListener 289 */ 290 virtual void SAL_CALL addPropertyChangeListener( 291 rtl::OUString const & propertyName, 292 com::sun::star::uno::Reference< 293 com::sun::star::beans::XPropertyChangeListener > const & listener); 294 295 // @see com::sun::star::beans::XPropertySet::removePropertyChangeListener 296 virtual void SAL_CALL removePropertyChangeListener( 297 rtl::OUString const & propertyName, 298 com::sun::star::uno::Reference< 299 com::sun::star::beans::XPropertyChangeListener > const & listener); 300 301 /** 302 @short Adds a 303 <code>com::sun::star::beans::XVetoableChangeListener</code>. 304 305 @descr If a listener is added more than once, it will receive all 306 relevant notifications multiple times. 307 308 @see com::sun::star::beans::XPropertySet::addVetoableChangeListener 309 */ 310 virtual void SAL_CALL addVetoableChangeListener( 311 rtl::OUString const & propertyName, 312 com::sun::star::uno::Reference< 313 com::sun::star::beans::XVetoableChangeListener > const & listener); 314 315 // @see com::sun::star::beans::XPropertySet::removeVetoableChangeListener 316 virtual void SAL_CALL removeVetoableChangeListener( 317 rtl::OUString const & propertyName, 318 com::sun::star::uno::Reference< 319 com::sun::star::beans::XVetoableChangeListener > const & listener); 320 321 // @see com::sun::star::beans::XFastPropertySet::setFastPropertyValue 322 virtual void SAL_CALL setFastPropertyValue( 323 sal_Int32 handle, com::sun::star::uno::Any const & value); 324 325 // @see com::sun::star::beans::XFastPropertySet::getFastPropertyValue 326 virtual com::sun::star::uno::Any SAL_CALL getFastPropertyValue( 327 sal_Int32 handle); 328 329 // @see com::sun::star::beans::XPropertyAccess::getPropertyValues 330 virtual 331 com::sun::star::uno::Sequence< com::sun::star::beans::PropertyValue > 332 SAL_CALL getPropertyValues(); 333 334 // @see com::sun::star::beans::XPropertyAccess::setPropertyValues 335 virtual void SAL_CALL setPropertyValues( 336 com::sun::star::uno::Sequence< com::sun::star::beans::PropertyValue > 337 const & props); 338 339 private: 340 PropertySetMixinImpl( const PropertySetMixinImpl&); // not defined 341 void operator=( const PropertySetMixinImpl&); // not defined 342 343 PropertySetMixinImpl( 344 com::sun::star::uno::Reference< com::sun::star::uno::XComponentContext > 345 const & context, 346 Implements implements, 347 com::sun::star::uno::Sequence< rtl::OUString > const & absentOptional, 348 com::sun::star::uno::Type const & type); 349 350 class Impl; 351 Impl * m_impl; 352 353 friend class Impl; 354 template< typename T > friend class PropertySetMixin; 355 356 ~PropertySetMixinImpl(); 357 358 void checkUnknown(rtl::OUString const & propertyName); 359 }; 360 361 /** 362 @short A helper mixin to implement certain UNO interfaces related to property 363 set handling on top of the attributes of a given UNO interface type. 364 365 @descr The UNO interface type is specified by the type parameter 366 <code>T</code> (which must correspond to a UNO interface type). 367 368 @descr No specializations of this class template should be added by client 369 code. 370 371 @since UDK 3.2.1 372 */ 373 template< typename T > class PropertySetMixin: public PropertySetMixinImpl { 374 protected: 375 /** 376 @short The constructor. 377 378 @descr May throw <code>com::sun::star::uno::RuntimeException</code> and 379 <code>std::bad_alloc</code>. 380 381 @param context the component context used by this class template; must 382 not be null, and must supply the service 383 <code>com.sun.star.reflection.CoreReflection</code> and the singleton 384 <code>com.sun.star.reflection.theTypeDescriptionManager</code> 385 386 @param implements a combination of zero or more flags specifying what 387 UNO interface types shall be supported 388 389 @param absentOptional a list of optional properties that are not 390 present, and should thus not be visible via 391 <code>com::sun::star::beans::XPropertySet::getPropertySetInfo</code>, 392 <code>com::sun::star::beans::XPropertySet::addPropertyChangeListener<!-- 393 --></code>, <code>com::sun::star::beans::XPropertySet::<!-- 394 -->removePropertyChangeListener</code>, 395 <code>com::sun::star::beans::XPropertySet::addVetoableChangeListener<!-- 396 --></code>, and <code>com::sun::star::beans::XPropertySet::<!-- 397 -->removeVetoableChangeListener</code>. For consistency reasons, the 398 given <code>absentOptional</code> should only contain the names of 399 attributes that represent optional properties that are not present (that 400 is, the attribute getters and setters always throw a 401 <code>com::sun::star::beans::UnknownPropertyException</code>), and should 402 contain each such name only once. If an optional property is not present 403 (that is, the corresponding attribute getter and setter always throw a 404 <code>com::sun::star::beans::UnknownPropertyException</code>) but is not 405 contained in the given <code>absentOptional</code>, then it will be 406 visible via 407 <code>com::sun::star::beans::XPropertySet::getPropertySetInfo</code> as a 408 <code>com::sun::star::beans::Property</code> with a set 409 <code>com::sun::star::beans::PropertyAttribute::OPTIONAL</code>. If the 410 given <code>implements</code> specifies that 411 <code>com::sun::star::beans::XPropertySet</code> is not supported, then 412 the given <code>absentOptional</code> is effectively ignored and can be 413 empty. 414 */ PropertySetMixin(com::sun::star::uno::Reference<com::sun::star::uno::XComponentContext> const & context,Implements implements,com::sun::star::uno::Sequence<rtl::OUString> const & absentOptional)415 PropertySetMixin( 416 com::sun::star::uno::Reference< com::sun::star::uno::XComponentContext > 417 const & context, 418 Implements implements, 419 com::sun::star::uno::Sequence< rtl::OUString > const & absentOptional): 420 PropertySetMixinImpl( 421 context, implements, absentOptional, T::static_type()) 422 {} 423 424 /** 425 @short The destructor. 426 427 @descr Does not throw. 428 */ ~PropertySetMixin()429 ~PropertySetMixin() {} 430 431 private: 432 PropertySetMixin( const PropertySetMixin&); // not defined 433 void operator=( const PropertySetMixin&); // not defined 434 }; 435 436 #if defined _MSC_VER 437 #pragma warning(pop) 438 #endif 439 440 } 441 442 #endif 443