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