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 : #include "com/sun/star/beans/PropertyVetoException.hpp"
25 : #include "com/sun/star/beans/UnknownPropertyException.hpp"
26 : #include "com/sun/star/beans/XFastPropertySet.hpp"
27 : #include "com/sun/star/beans/XPropertyAccess.hpp"
28 : #include "com/sun/star/beans/XPropertySet.hpp"
29 : #include "com/sun/star/lang/IllegalArgumentException.hpp"
30 : #include "com/sun/star/lang/WrappedTargetException.hpp"
31 : #include "com/sun/star/uno/Reference.hxx"
32 : #include "com/sun/star/uno/RuntimeException.hpp"
33 : #include "com/sun/star/uno/Sequence.hxx"
34 : #include "sal/types.h"
35 : #include "cppuhelperdllapi.h"
36 :
37 : namespace com { namespace sun { namespace star {
38 : namespace beans {
39 : class XPropertyChangeListener;
40 : class XPropertySetInfo;
41 : class XVetoableChangeListener;
42 : struct PropertyValue;
43 : }
44 : namespace uno {
45 : class Any;
46 : class Type;
47 : class XComponentContext;
48 : }
49 : } } }
50 : namespace rtl { class OUString; }
51 :
52 : namespace cppu {
53 :
54 : template< typename T > class PropertySetMixin;
55 :
56 : // Suppress warnings about virtual functions but non-virtual destructor:
57 : #if defined _MSC_VER
58 : #pragma warning(push)
59 : #pragma warning(disable: 4265)
60 : #endif
61 :
62 : /**
63 : @short A helper base class for <code>cppu::PropertySetMixin</code>.
64 :
65 : See the documentation of <code>cppu::PropertySetMixin</code> for
66 : further details.
67 :
68 : That <code>cppu::PropertySetMixin</code> is derived from this
69 : base class should be considered an implementation detail. The functionality
70 : of <code>cppu::PropertySetMixin</code> that is inherited from this base
71 : class and is visible to subclasses of
72 : <code>cppu::PropertySetMixin</code> should be treated by such
73 : subclasses as being provided by <code>cppu::PropertySetMixin</code>
74 : directly (e.g., in such subclasses, use
75 : “<code>PropertySetMixin::Implements</code>” instead of
76 : “<code>PropertySetMixinImpl::Implements</code>”).
77 :
78 : @since UDK 3.2.1
79 : */
80 : #if HAVE_GCC_PRAGMA_DIAGNOSTIC_MODIFY && HAVE_GCC_PRAGMA_DIAGNOSTIC_SCOPE \
81 : && !defined __clang__
82 : #pragma GCC diagnostic push
83 : #pragma GCC diagnostic ignored "-Wnon-virtual-dtor"
84 : #endif
85 : class CPPUHELPER_DLLPUBLIC PropertySetMixinImpl:
86 : public com::sun::star::beans::XPropertySet,
87 : public com::sun::star::beans::XFastPropertySet,
88 : public com::sun::star::beans::XPropertyAccess
89 : {
90 : protected:
91 : /**
92 : @short Flags used by subclasses of
93 : <code>cppu::PropertySetMixin</code> to specify what UNO interface
94 : types shall be supported.
95 : */
96 : enum Implements {
97 : /**
98 : @short Flag specifying that the UNO interface type
99 : <code>com::sun::star::beans::XPropertySet</code> shall be supported.
100 : */
101 : IMPLEMENTS_PROPERTY_SET = 1,
102 :
103 : /**
104 : @short Flag specifying that the UNO interface type
105 : <code>com::sun::star::beans::XFastPropertySet</code> shall be
106 : supported.
107 : */
108 : IMPLEMENTS_FAST_PROPERTY_SET = 2,
109 :
110 : /**
111 : @short Flag specifying that the UNO interface type
112 : <code>com::sun::star::beans::XPropertyAccess</code> shall be
113 : supported.
114 : */
115 : IMPLEMENTS_PROPERTY_ACCESS = 4
116 : };
117 :
118 : /**
119 : @short A class used by subclasses of
120 : <code>cppu::PropertySetMixin</code> when implementing UNO interface
121 : type attribute setter functions.
122 :
123 : This class is not thread safe; that is, the constructor,
124 : <code>notify</code>, and the destructor must be called from the same
125 : thread.
126 :
127 : See <code>cppu::PropertySetMixinImpl::prepareSet</code> for
128 : further details.
129 : */
130 : class CPPUHELPER_DLLPUBLIC BoundListeners {
131 : public:
132 : /**
133 : @short The constructor.
134 :
135 : May throw <code>std::bad_alloc</code>.
136 : */
137 : BoundListeners();
138 :
139 : /**
140 : @short The destructor.
141 :
142 : Does not throw.
143 : */
144 : ~BoundListeners();
145 :
146 : /**
147 : @short Notifies any
148 : <code>com::sun::star::beans::XPropertyChangeListener</code>s.
149 :
150 : May throw <code>com::sun::star::uno::RuntimeException</code>
151 : and <code>std::bad_alloc</code>.
152 :
153 : See <code>cppu::PropertySetMixinImpl::prepareSet</code>
154 : for further details.
155 : */
156 : void notify() const;
157 :
158 : private:
159 : BoundListeners( const BoundListeners&); // not defined
160 : void operator=( const BoundListeners&); // not defined
161 :
162 : class Impl;
163 : Impl * m_impl;
164 :
165 : friend class PropertySetMixinImpl;
166 : };
167 :
168 : /**
169 : @short A function used by subclasses of
170 : <code>cppu::PropertySetMixin</code> when implementing UNO interface
171 : type attribute setter functions.
172 :
173 : First, this function checks whether this instance has already been
174 : disposed (see <code>cppu::PropertySetMixinImpl::dispose</code>),
175 : and throws a <code>com::sun::star::lang::DisposedException</code> if
176 : applicable. For a constrained attribute (whose setter can explicitly
177 : raise <code>com::sun::star::beans::PropertyVetoException</code>), this
178 : function notifies any
179 : <code>com::sun::star::beans::XVetoableChangeListener</code>s. For a
180 : bound attribute, this function modifies the passed-in
181 : <code>boundListeners</code> so that it can afterwards be used to notify
182 : any <code>com::sun::star::beans::XPropertyChangeListener</code>s. This
183 : function should be called before storing the new attribute value, and
184 : <code>boundListeners->notify()</code> should be called exactly once after
185 : storing the new attribute value (in case the attribute is bound;
186 : otherwise, calling <code>boundListeners->notify()</code> is ignored).
187 : Furthermore, <code>boundListeners->notify()</code> and this function have
188 : to be called from the same thread.
189 :
190 : May throw
191 : <code>com::sun::star::beans::PropertyVetoException</code>,
192 : <code>com::sun::star::uno::RuntimeException</code> (and
193 : <code>com::sun::star::lang::DisposedException</code> in particular), and
194 : <code>std::bad_alloc</code>.
195 :
196 : @param propertyName the name of the property (which is the same as the
197 : name of the attribute that is going to be set)
198 :
199 : @param oldValue the property value corresponding to the old attribute
200 : value. This is only used as
201 : <code>com::sun::star::beans::PropertyChangeEvent::OldValue</code>, which
202 : is rather useless, anyway (see “Using the Observer Pattern”
203 : in <a href="http://tools.openoffice.org/CodingGuidelines.sxw">
204 : OpenOffice.org Coding Guidelines</a>). If the attribute
205 : that is going to be set is neither bound nor constrained, or if
206 : <code>com::sun::star::beans::PropertyChangeEvent::OldValue</code> should
207 : not be set, a <code>VOID</code> <code>Any</code> can be used instead.
208 :
209 : @param newValue the property value corresponding to the new
210 : attribute value. This is only used as
211 : <code>com::sun::star::beans::PropertyChangeEvent::NewValue</code>, which
212 : is rather useless, anyway (see “Using the Observer Pattern”
213 : in <a href="http://tools.openoffice.org/CodingGuidelines.sxw">
214 : OpenOffice.org Coding Guidelines</a>), <em>unless</em> the
215 : attribute that is going to be set is constrained. If the attribute
216 : that is going to be set is neither bound nor constrained, or if it is
217 : only bound but
218 : <code>com::sun::star::beans::PropertyChangeEvent::NewValue</code> should
219 : not be set, a <code>VOID</code> <code>Any</code> can be used instead.
220 :
221 : @param boundListeners a pointer to a fresh
222 : <code>cppu::PropertySetMixinImpl::BoundListeners</code> instance
223 : (which has not been passed to this function before, and on which
224 : <code>notify</code> has not yet been called); may only be null if the
225 : attribute that is going to be set is not bound
226 : */
227 : void prepareSet(
228 : rtl::OUString const & propertyName,
229 : com::sun::star::uno::Any const & oldValue,
230 : com::sun::star::uno::Any const & newValue,
231 : BoundListeners * boundListeners);
232 :
233 : /**
234 : @short Mark this instance as being disposed.
235 :
236 : See <code>com::sun::star::lang::XComponent</code> for the general
237 : concept of disposing UNO objects. On the first call to this function,
238 : all registered listeners
239 : (<code>com::sun::star::beans::XPropertyChangeListener</code>s and
240 : <code>com::sun::star::beans::XVetoableChangeListener</code>s) are
241 : notified of the disposing source. Any subsequent calls to this function
242 : are ignored.
243 :
244 : May throw <code>com::sun::star::uno::RuntimeException</code> and
245 : <code>std::bad_alloc</code>.
246 : */
247 : void dispose();
248 :
249 : /**
250 : @short A function used by subclasses of
251 : <code>cppu::PropertySetMixin</code> when implementing
252 : <code>com::sun::star::uno::XInterface::queryInterface</code>.
253 :
254 : This function checks for support of any of the UNO interface types
255 : specified in the call of the <code>cppu::PropertySetMixin</code>
256 : constructor. It does not check for any other UNO interface types (not
257 : even for <code>com::sun::star::uno::XInterface</code>), and should not
258 : be used directly as the implementation of
259 : <code>com::sun::star::uno::XInterface::queryInterface</code> of this UNO
260 : object.
261 : */
262 : virtual com::sun::star::uno::Any SAL_CALL queryInterface(
263 : com::sun::star::uno::Type const & type)
264 : throw (com::sun::star::uno::RuntimeException);
265 :
266 : // @see com::sun::star::beans::XPropertySet::getPropertySetInfo
267 : virtual
268 : com::sun::star::uno::Reference< com::sun::star::beans::XPropertySetInfo >
269 : SAL_CALL getPropertySetInfo() throw (com::sun::star::uno::RuntimeException);
270 :
271 : // @see com::sun::star::beans::XPropertySet::setPropertyValue
272 : virtual void SAL_CALL setPropertyValue(
273 : rtl::OUString const & propertyName,
274 : com::sun::star::uno::Any const & value)
275 : throw (
276 : com::sun::star::beans::UnknownPropertyException,
277 : com::sun::star::beans::PropertyVetoException,
278 : com::sun::star::lang::IllegalArgumentException,
279 : com::sun::star::lang::WrappedTargetException,
280 : com::sun::star::uno::RuntimeException);
281 :
282 : // @see com::sun::star::beans::XPropertySet::getPropertyValue
283 : virtual com::sun::star::uno::Any SAL_CALL getPropertyValue(
284 : rtl::OUString const & propertyName)
285 : throw (
286 : com::sun::star::beans::UnknownPropertyException,
287 : com::sun::star::lang::WrappedTargetException,
288 : com::sun::star::uno::RuntimeException);
289 :
290 : /**
291 : @short Adds a
292 : <code>com::sun::star::beans::XPropertyChangeListener</code>.
293 :
294 : If a listener is added more than once, it will receive all
295 : relevant notifications multiple times.
296 :
297 : @see com::sun::star::beans::XPropertySet::addPropertyChangeListener
298 : */
299 : virtual void SAL_CALL addPropertyChangeListener(
300 : rtl::OUString const & propertyName,
301 : com::sun::star::uno::Reference<
302 : com::sun::star::beans::XPropertyChangeListener > const & listener)
303 : throw (
304 : com::sun::star::beans::UnknownPropertyException,
305 : com::sun::star::lang::WrappedTargetException,
306 : com::sun::star::uno::RuntimeException);
307 :
308 : // @see com::sun::star::beans::XPropertySet::removePropertyChangeListener
309 : virtual void SAL_CALL removePropertyChangeListener(
310 : rtl::OUString const & propertyName,
311 : com::sun::star::uno::Reference<
312 : com::sun::star::beans::XPropertyChangeListener > const & listener)
313 : throw (
314 : com::sun::star::beans::UnknownPropertyException,
315 : com::sun::star::lang::WrappedTargetException,
316 : com::sun::star::uno::RuntimeException);
317 :
318 : /**
319 : @short Adds a
320 : <code>com::sun::star::beans::XVetoableChangeListener</code>.
321 :
322 : If a listener is added more than once, it will receive all
323 : relevant notifications multiple times.
324 :
325 : @see com::sun::star::beans::XPropertySet::addVetoableChangeListener
326 : */
327 : virtual void SAL_CALL addVetoableChangeListener(
328 : rtl::OUString const & propertyName,
329 : com::sun::star::uno::Reference<
330 : com::sun::star::beans::XVetoableChangeListener > const & listener)
331 : throw (
332 : com::sun::star::beans::UnknownPropertyException,
333 : com::sun::star::lang::WrappedTargetException,
334 : com::sun::star::uno::RuntimeException);
335 :
336 : // @see com::sun::star::beans::XPropertySet::removeVetoableChangeListener
337 : virtual void SAL_CALL removeVetoableChangeListener(
338 : rtl::OUString const & propertyName,
339 : com::sun::star::uno::Reference<
340 : com::sun::star::beans::XVetoableChangeListener > const & listener)
341 : throw (
342 : com::sun::star::beans::UnknownPropertyException,
343 : com::sun::star::lang::WrappedTargetException,
344 : com::sun::star::uno::RuntimeException);
345 :
346 : // @see com::sun::star::beans::XFastPropertySet::setFastPropertyValue
347 : virtual void SAL_CALL setFastPropertyValue(
348 : sal_Int32 handle, com::sun::star::uno::Any const & value)
349 : throw (
350 : com::sun::star::beans::UnknownPropertyException,
351 : com::sun::star::beans::PropertyVetoException,
352 : com::sun::star::lang::IllegalArgumentException,
353 : com::sun::star::lang::WrappedTargetException,
354 : com::sun::star::uno::RuntimeException);
355 :
356 : // @see com::sun::star::beans::XFastPropertySet::getFastPropertyValue
357 : virtual com::sun::star::uno::Any SAL_CALL getFastPropertyValue(
358 : sal_Int32 handle)
359 : throw (
360 : com::sun::star::beans::UnknownPropertyException,
361 : com::sun::star::lang::WrappedTargetException,
362 : com::sun::star::uno::RuntimeException);
363 :
364 : // @see com::sun::star::beans::XPropertyAccess::getPropertyValues
365 : virtual
366 : com::sun::star::uno::Sequence< com::sun::star::beans::PropertyValue >
367 : SAL_CALL getPropertyValues() throw (com::sun::star::uno::RuntimeException);
368 :
369 : // @see com::sun::star::beans::XPropertyAccess::setPropertyValues
370 : virtual void SAL_CALL setPropertyValues(
371 : com::sun::star::uno::Sequence< com::sun::star::beans::PropertyValue >
372 : const & props)
373 : throw (
374 : com::sun::star::beans::UnknownPropertyException,
375 : com::sun::star::beans::PropertyVetoException,
376 : com::sun::star::lang::IllegalArgumentException,
377 : com::sun::star::lang::WrappedTargetException,
378 : com::sun::star::uno::RuntimeException);
379 :
380 : private:
381 : PropertySetMixinImpl( const PropertySetMixinImpl&); // not defined
382 : void operator=( const PropertySetMixinImpl&); // not defined
383 :
384 : PropertySetMixinImpl(
385 : com::sun::star::uno::Reference< com::sun::star::uno::XComponentContext >
386 : const & context,
387 : Implements implements,
388 : com::sun::star::uno::Sequence< rtl::OUString > const & absentOptional,
389 : com::sun::star::uno::Type const & type);
390 :
391 : class Impl;
392 : Impl * m_impl;
393 :
394 : friend class Impl;
395 : template< typename T > friend class PropertySetMixin;
396 :
397 : ~PropertySetMixinImpl();
398 :
399 : void checkUnknown(rtl::OUString const & propertyName);
400 : };
401 : #if HAVE_GCC_PRAGMA_DIAGNOSTIC_MODIFY && HAVE_GCC_PRAGMA_DIAGNOSTIC_SCOPE \
402 : && !defined __clang__
403 : #pragma GCC diagnostic pop
404 : #endif
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 service
428 : <code>com.sun.star.reflection.CoreReflection</code> and the singleton
429 : <code>com.sun.star.reflection.theTypeDescriptionManager</code>
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 3894 : 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 3894 : context, implements, absentOptional, T::static_type())
467 3894 : {}
468 :
469 : /**
470 : @short The destructor.
471 :
472 : Does not throw.
473 : */
474 3883 : ~PropertySetMixin() {}
475 :
476 : private:
477 : PropertySetMixin( const PropertySetMixin&); // not defined
478 : void operator=( const PropertySetMixin&); // not defined
479 : };
480 :
481 : #if defined _MSC_VER
482 : #pragma warning(pop)
483 : #endif
484 :
485 : }
486 :
487 : #endif
488 :
489 : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
