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 : INCLUDED_CPPUHELPER_PROPERTYSETMIXIN_HXX
23 :
24 : #include "sal/config.h"
25 : #include "com/sun/star/beans/PropertyVetoException.hpp"
26 : #include "com/sun/star/beans/UnknownPropertyException.hpp"
27 : #include "com/sun/star/beans/XFastPropertySet.hpp"
28 : #include "com/sun/star/beans/XPropertyAccess.hpp"
29 : #include "com/sun/star/beans/XPropertySet.hpp"
30 : #include "com/sun/star/lang/IllegalArgumentException.hpp"
31 : #include "com/sun/star/lang/WrappedTargetException.hpp"
32 : #include "com/sun/star/uno/Reference.hxx"
33 : #include "com/sun/star/uno/RuntimeException.hpp"
34 : #include "com/sun/star/uno/Sequence.hxx"
35 : #include "sal/types.h"
36 : #include "cppuhelperdllapi.h"
37 :
38 : namespace com { namespace sun { namespace star {
39 : namespace beans {
40 : class XPropertyChangeListener;
41 : class XPropertySetInfo;
42 : class XVetoableChangeListener;
43 : struct PropertyValue;
44 : }
45 : namespace uno {
46 : class Any;
47 : class Type;
48 : class XComponentContext;
49 : }
50 : } } }
51 : namespace rtl { class OUString; }
52 :
53 : namespace cppu {
54 :
55 : template< typename T > class PropertySetMixin;
56 :
57 : // Suppress warnings about virtual functions but non-virtual destructor:
58 : #if defined _MSC_VER
59 : #pragma warning(push)
60 : #pragma warning(disable: 4265)
61 : #endif
62 :
63 : /**
64 : @short A helper base class for <code>cppu::PropertySetMixin</code>.
65 :
66 : @descr See the documentation of <code>cppu::PropertySetMixin</code> for
67 : further details.
68 :
69 : @descr That <code>cppu::PropertySetMixin</code> is derived from this
70 : base class should be considered an implementation detail. The functionality
71 : of <code>cppu::PropertySetMixin</code> that is inherited from this base
72 : class and is visible to subclasses of
73 : <code>cppu::PropertySetMixin</code> should be treated by such
74 : subclasses as being provided by <code>cppu::PropertySetMixin</code>
75 : directly (e.g., in such subclasses, use
76 : “<code>PropertySetMixin::Implements</code>” instead of
77 : “<code>PropertySetMixinImpl::Implements</code>”).
78 :
79 : @since UDK 3.2.1
80 : */
81 : #if defined __GNUC__ && ((__GNUC__ == 4 && __GNUC_MINOR__ >= 6) || __GNUC__ > 4)
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 : @descr 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 : @descr 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 : @descr May throw <code>std::bad_alloc</code>.
136 : */
137 : BoundListeners();
138 :
139 : /**
140 : @short The destructor.
141 :
142 : @descr Does not throw.
143 : */
144 : ~BoundListeners();
145 :
146 : /**
147 : @short Notifies any
148 : <code>com::sun::star::beans::XPropertyChangeListener</code>s.
149 :
150 : @descr May throw <code>com::sun::star::uno::RuntimeException</code>
151 : and <code>std::bad_alloc</code>.
152 :
153 : @descr See <code>cppu::PropertySetMixinImpl::prepareSet</code>
154 : for further details.
155 : */
156 : void notify() const;
157 :
158 : private:
159 : BoundListeners(BoundListeners &); // not defined
160 : void operator =(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 : @descr 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 : @descr 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 : <cite>OpenOffice.org Coding Guidelines</cite></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 : <cite>OpenOffice.org Coding Guidelines</cite></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 : @descr 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 : @descr 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 : @descr 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 : @descr 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 : @descr 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(PropertySetMixinImpl &); // not defined
382 : void operator =(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 defined __GNUC__ && ((__GNUC__ == 4 && __GNUC_MINOR__ >= 6) || __GNUC__ > 4)
402 : #pragma GCC diagnostic pop
403 : #endif
404 :
405 : /**
406 : @short A helper mixin to implement certain UNO interfaces related to property
407 : set handling on top of the attributes of a given UNO interface type.
408 :
409 : @descr The UNO interface type is specified by the type parameter
410 : <code>T</code> (which must correspond to a UNO interface type).
411 :
412 : @descr No specializations of this class template should be added by client
413 : code.
414 :
415 : @since UDK 3.2.1
416 : */
417 : template< typename T > class PropertySetMixin: public PropertySetMixinImpl {
418 : protected:
419 : /**
420 : @short The constructor.
421 :
422 : @descr May throw <code>com::sun::star::uno::RuntimeException</code> and
423 : <code>std::bad_alloc</code>.
424 :
425 : @param context the component context used by this class template; must
426 : not be null, and must supply the service
427 : <code>com.sun.star.reflection.CoreReflection</code> and the singleton
428 : <code>com.sun.star.reflection.theTypeDescriptionManager</code>
429 :
430 : @param implements a combination of zero or more flags specifying what
431 : UNO interface types shall be supported
432 :
433 : @param absentOptional a list of optional properties that are not
434 : present, and should thus not be visible via
435 : <code>com::sun::star::beans::XPropertySet::getPropertySetInfo</code>,
436 : <code>com::sun::star::beans::XPropertySet::addPropertyChangeListener<!--
437 : --></code>, <code>com::sun::star::beans::XPropertySet::<!--
438 : -->removePropertyChangeListener</code>,
439 : <code>com::sun::star::beans::XPropertySet::addVetoableChangeListener<!--
440 : --></code>, and <code>com::sun::star::beans::XPropertySet::<!--
441 : -->removeVetoableChangeListener</code>. For consistency reasons, the
442 : given <code>absentOptional</code> should only contain the names of
443 : attributes that represent optional properties that are not present (that
444 : is, the attribute getters and setters always throw a
445 : <code>com::sun::star::beans::UnknownPropertyException</code>), and should
446 : contain each such name only once. If an optional property is not present
447 : (that is, the corresponding attribute getter and setter always throw a
448 : <code>com::sun::star::beans::UnknownPropertyException</code>) but is not
449 : contained in the given <code>absentOptional</code>, then it will be
450 : visible via
451 : <code>com::sun::star::beans::XPropertySet::getPropertySetInfo</code> as a
452 : <code>com::sun::star::beans::Property</code> with a set
453 : <code>com::sun::star::beans::PropertyAttribute::OPTIONAL</code>. If the
454 : given <code>implements</code> specifies that
455 : <code>com::sun::star::beans::XPropertySet</code> is not supported, then
456 : the given <code>absentOptional</code> is effectively ignored and can be
457 : empty.
458 : */
459 1990 : PropertySetMixin(
460 : com::sun::star::uno::Reference< com::sun::star::uno::XComponentContext >
461 : const & context,
462 : Implements implements,
463 : com::sun::star::uno::Sequence< rtl::OUString > const & absentOptional):
464 : PropertySetMixinImpl(
465 1990 : context, implements, absentOptional, T::static_type())
466 1990 : {}
467 :
468 : /**
469 : @short The destructor.
470 :
471 : @descr Does not throw.
472 : */
473 1718 : ~PropertySetMixin() {}
474 :
475 : private:
476 : PropertySetMixin(PropertySetMixin &); // not defined
477 : void operator =(PropertySetMixin &); // not defined
478 : };
479 :
480 : #if defined _MSC_VER
481 : #pragma warning(pop)
482 : #endif
483 :
484 : }
485 :
486 : #endif
487 :
488 : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
