Line data Source code
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_PROPERTYSETMIXIN_HXX
21 : #define INCLUDED_CPPUHELPER_PROPERTYSETMIXIN_HXX
22 :
23 : #include <sal/config.h>
24 :
25 : #include <exception>
26 :
27 : #include <com/sun/star/beans/PropertyVetoException.hpp>
28 : #include <com/sun/star/beans/UnknownPropertyException.hpp>
29 : #include <com/sun/star/beans/XFastPropertySet.hpp>
30 : #include <com/sun/star/beans/XPropertyAccess.hpp>
31 : #include <com/sun/star/beans/XPropertySet.hpp>
32 : #include <com/sun/star/lang/IllegalArgumentException.hpp>
33 : #include <com/sun/star/lang/WrappedTargetException.hpp>
34 : #include <com/sun/star/uno/Reference.hxx>
35 : #include <com/sun/star/uno/RuntimeException.hpp>
36 : #include <com/sun/star/uno/Sequence.hxx>
37 : #include <sal/types.h>
38 : #include <cppuhelper/cppuhelperdllapi.h>
39 :
40 : namespace com { namespace sun { namespace star {
41 : namespace beans {
42 : class XPropertyChangeListener;
43 : class XPropertySetInfo;
44 : class XVetoableChangeListener;
45 : struct PropertyValue;
46 : }
47 : namespace uno {
48 : class Any;
49 : class Type;
50 : class XComponentContext;
51 : }
52 : } } }
53 : namespace rtl { class OUString; }
54 :
55 : namespace cppu {
56 :
57 : template< typename T > class PropertySetMixin;
58 :
59 : // Suppress warnings about virtual functions but non-virtual destructor:
60 : #if defined _MSC_VER
61 : #pragma warning(push)
62 : #pragma warning(disable: 4265)
63 : #endif
64 :
65 : /**
66 : @short A helper base class for <code>cppu::PropertySetMixin</code>.
67 :
68 : See the documentation of <code>cppu::PropertySetMixin</code> for
69 : further details.
70 :
71 : That <code>cppu::PropertySetMixin</code> is derived from this
72 : base class should be considered an implementation detail. The functionality
73 : of <code>cppu::PropertySetMixin</code> that is inherited from this base
74 : class and is visible to subclasses of
75 : <code>cppu::PropertySetMixin</code> should be treated by such
76 : subclasses as being provided by <code>cppu::PropertySetMixin</code>
77 : directly (e.g., in such subclasses, use
78 : “<code>PropertySetMixin::Implements</code>” instead of
79 : “<code>PropertySetMixinImpl::Implements</code>”).
80 :
81 : @since UDK 3.2.1
82 : */
83 : #if defined __GNUC__ && !defined __clang__
84 : #pragma GCC diagnostic push
85 : #pragma GCC diagnostic ignored "-Wnon-virtual-dtor"
86 : #endif
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 : 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 : 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 : May throw <code>std::bad_alloc</code>.
138 : */
139 : BoundListeners();
140 :
141 : /**
142 : @short The destructor.
143 :
144 : Does not throw.
145 : */
146 : ~BoundListeners();
147 :
148 : /**
149 : @short Notifies any
150 : <code>com::sun::star::beans::XPropertyChangeListener</code>s.
151 :
152 : May throw <code>com::sun::star::uno::RuntimeException</code>
153 : and <code>std::bad_alloc</code>.
154 :
155 : See <code>cppu::PropertySetMixinImpl::prepareSet</code>
156 : for further details.
157 : */
158 : void notify() const;
159 :
160 : private:
161 : BoundListeners( const BoundListeners&) SAL_DELETED_FUNCTION;
162 : void operator=( const BoundListeners&) SAL_DELETED_FUNCTION;
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 : 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 : 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 : OpenOffice.org Coding Guidelines</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 : OpenOffice.org Coding Guidelines</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 : 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 : 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 : 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, std::exception) SAL_OVERRIDE;
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()
272 : throw (com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
273 :
274 : // @see com::sun::star::beans::XPropertySet::setPropertyValue
275 : virtual void SAL_CALL setPropertyValue(
276 : rtl::OUString const & propertyName,
277 : com::sun::star::uno::Any const & value)
278 : throw (
279 : com::sun::star::beans::UnknownPropertyException,
280 : com::sun::star::beans::PropertyVetoException,
281 : com::sun::star::lang::IllegalArgumentException,
282 : com::sun::star::lang::WrappedTargetException,
283 : com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
284 :
285 : // @see com::sun::star::beans::XPropertySet::getPropertyValue
286 : virtual com::sun::star::uno::Any SAL_CALL getPropertyValue(
287 : rtl::OUString const & propertyName)
288 : throw (
289 : com::sun::star::beans::UnknownPropertyException,
290 : com::sun::star::lang::WrappedTargetException,
291 : com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
292 :
293 : /**
294 : @short Adds a
295 : <code>com::sun::star::beans::XPropertyChangeListener</code>.
296 :
297 : If a listener is added more than once, it will receive all
298 : relevant notifications multiple times.
299 :
300 : @see com::sun::star::beans::XPropertySet::addPropertyChangeListener
301 : */
302 : virtual void SAL_CALL addPropertyChangeListener(
303 : rtl::OUString const & propertyName,
304 : com::sun::star::uno::Reference<
305 : com::sun::star::beans::XPropertyChangeListener > const & listener)
306 : throw (
307 : com::sun::star::beans::UnknownPropertyException,
308 : com::sun::star::lang::WrappedTargetException,
309 : com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
310 :
311 : // @see com::sun::star::beans::XPropertySet::removePropertyChangeListener
312 : virtual void SAL_CALL removePropertyChangeListener(
313 : rtl::OUString const & propertyName,
314 : com::sun::star::uno::Reference<
315 : com::sun::star::beans::XPropertyChangeListener > const & listener)
316 : throw (
317 : com::sun::star::beans::UnknownPropertyException,
318 : com::sun::star::lang::WrappedTargetException,
319 : com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
320 :
321 : /**
322 : @short Adds a
323 : <code>com::sun::star::beans::XVetoableChangeListener</code>.
324 :
325 : If a listener is added more than once, it will receive all
326 : relevant notifications multiple times.
327 :
328 : @see com::sun::star::beans::XPropertySet::addVetoableChangeListener
329 : */
330 : virtual void SAL_CALL addVetoableChangeListener(
331 : rtl::OUString const & propertyName,
332 : com::sun::star::uno::Reference<
333 : com::sun::star::beans::XVetoableChangeListener > const & listener)
334 : throw (
335 : com::sun::star::beans::UnknownPropertyException,
336 : com::sun::star::lang::WrappedTargetException,
337 : com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
338 :
339 : // @see com::sun::star::beans::XPropertySet::removeVetoableChangeListener
340 : virtual void SAL_CALL removeVetoableChangeListener(
341 : rtl::OUString const & propertyName,
342 : com::sun::star::uno::Reference<
343 : com::sun::star::beans::XVetoableChangeListener > const & listener)
344 : throw (
345 : com::sun::star::beans::UnknownPropertyException,
346 : com::sun::star::lang::WrappedTargetException,
347 : com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
348 :
349 : // @see com::sun::star::beans::XFastPropertySet::setFastPropertyValue
350 : virtual void SAL_CALL setFastPropertyValue(
351 : sal_Int32 handle, com::sun::star::uno::Any const & value)
352 : throw (
353 : com::sun::star::beans::UnknownPropertyException,
354 : com::sun::star::beans::PropertyVetoException,
355 : com::sun::star::lang::IllegalArgumentException,
356 : com::sun::star::lang::WrappedTargetException,
357 : com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
358 :
359 : // @see com::sun::star::beans::XFastPropertySet::getFastPropertyValue
360 : virtual com::sun::star::uno::Any SAL_CALL getFastPropertyValue(
361 : sal_Int32 handle)
362 : throw (
363 : com::sun::star::beans::UnknownPropertyException,
364 : com::sun::star::lang::WrappedTargetException,
365 : com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
366 :
367 : // @see com::sun::star::beans::XPropertyAccess::getPropertyValues
368 : virtual
369 : com::sun::star::uno::Sequence< com::sun::star::beans::PropertyValue >
370 : SAL_CALL getPropertyValues()
371 : throw (com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
372 :
373 : // @see com::sun::star::beans::XPropertyAccess::setPropertyValues
374 : virtual void SAL_CALL setPropertyValues(
375 : com::sun::star::uno::Sequence< com::sun::star::beans::PropertyValue >
376 : const & props)
377 : throw (
378 : com::sun::star::beans::UnknownPropertyException,
379 : com::sun::star::beans::PropertyVetoException,
380 : com::sun::star::lang::IllegalArgumentException,
381 : com::sun::star::lang::WrappedTargetException,
382 : com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
383 :
384 : private:
385 : PropertySetMixinImpl( const PropertySetMixinImpl&) SAL_DELETED_FUNCTION;
386 : void operator=( const PropertySetMixinImpl&) SAL_DELETED_FUNCTION;
387 :
388 : PropertySetMixinImpl(
389 : com::sun::star::uno::Reference< com::sun::star::uno::XComponentContext >
390 : const & context,
391 : Implements implements,
392 : com::sun::star::uno::Sequence< rtl::OUString > const & absentOptional,
393 : com::sun::star::uno::Type const & type);
394 :
395 : class Impl;
396 : Impl * m_impl;
397 :
398 : friend class Impl;
399 : template< typename T > friend class PropertySetMixin;
400 :
401 : ~PropertySetMixinImpl();
402 :
403 : void checkUnknown(rtl::OUString const & propertyName);
404 : };
405 :
406 : /**
407 : @short A helper mixin to implement certain UNO interfaces related to property
408 : set handling on top of the attributes of a given UNO interface type.
409 :
410 : The UNO interface type is specified by the type parameter
411 : <code>T</code> (which must correspond to a UNO interface type).
412 :
413 : No specializations of this class template should be added by client
414 : code.
415 :
416 : @since UDK 3.2.1
417 : */
418 : template< typename T > class PropertySetMixin: public PropertySetMixinImpl {
419 : protected:
420 : /**
421 : @short The constructor.
422 :
423 : May throw <code>com::sun::star::uno::RuntimeException</code> and
424 : <code>std::bad_alloc</code>.
425 :
426 : @param context the component context used by this class template; must
427 : not be null, and must supply the
428 : <code>com.sun.star.reflection.theCoreReflection</code> and
429 : <code>com.sun.star.reflection.theTypeDescriptionManager</code> singletons
430 :
431 : @param implements a combination of zero or more flags specifying what
432 : UNO interface types shall be supported
433 :
434 : @param absentOptional a list of optional properties that are not
435 : present, and should thus not be visible via
436 : <code>com::sun::star::beans::XPropertySet::getPropertySetInfo</code>,
437 : <code>com::sun::star::beans::XPropertySet::addPropertyChangeListener<!--
438 : --></code>, <code>com::sun::star::beans::XPropertySet::<!--
439 : -->removePropertyChangeListener</code>,
440 : <code>com::sun::star::beans::XPropertySet::addVetoableChangeListener<!--
441 : --></code>, and <code>com::sun::star::beans::XPropertySet::<!--
442 : -->removeVetoableChangeListener</code>. For consistency reasons, the
443 : given <code>absentOptional</code> should only contain the names of
444 : attributes that represent optional properties that are not present (that
445 : is, the attribute getters and setters always throw a
446 : <code>com::sun::star::beans::UnknownPropertyException</code>), and should
447 : contain each such name only once. If an optional property is not present
448 : (that is, the corresponding attribute getter and setter always throw a
449 : <code>com::sun::star::beans::UnknownPropertyException</code>) but is not
450 : contained in the given <code>absentOptional</code>, then it will be
451 : visible via
452 : <code>com::sun::star::beans::XPropertySet::getPropertySetInfo</code> as a
453 : <code>com::sun::star::beans::Property</code> with a set
454 : <code>com::sun::star::beans::PropertyAttribute::OPTIONAL</code>. If the
455 : given <code>implements</code> specifies that
456 : <code>com::sun::star::beans::XPropertySet</code> is not supported, then
457 : the given <code>absentOptional</code> is effectively ignored and can be
458 : empty.
459 : */
460 9987 : PropertySetMixin(
461 : com::sun::star::uno::Reference< com::sun::star::uno::XComponentContext >
462 : const & context,
463 : Implements implements,
464 : com::sun::star::uno::Sequence< rtl::OUString > const & absentOptional):
465 : PropertySetMixinImpl(
466 9987 : context, implements, absentOptional, T::static_type())
467 9987 : {}
468 :
469 : /**
470 : @short The destructor.
471 :
472 : Does not throw.
473 : */
474 9975 : ~PropertySetMixin() {}
475 :
476 : private:
477 : PropertySetMixin( const PropertySetMixin&) SAL_DELETED_FUNCTION;
478 : void operator=( const PropertySetMixin&) SAL_DELETED_FUNCTION;
479 : };
480 : #if defined __GNUC__ && !defined __clang__
481 : #pragma GCC diagnostic pop
482 : #endif
483 :
484 : #if defined _MSC_VER
485 : #pragma warning(pop)
486 : #endif
487 :
488 : }
489 :
490 : #endif
491 :
492 : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
