/src/libreoffice/include/cppuhelper/propshlp.hxx
Line | Count | Source |
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 | | /* |
21 | | * This file is part of LibreOffice published API. |
22 | | */ |
23 | | |
24 | | #ifndef INCLUDED_CPPUHELPER_PROPSHLP_HXX |
25 | | #define INCLUDED_CPPUHELPER_PROPSHLP_HXX |
26 | | |
27 | | #include "rtl/alloc.h" |
28 | | |
29 | | #include "cppuhelper/interfacecontainer.h" |
30 | | |
31 | | #include "com/sun/star/beans/XPropertySet.hpp" |
32 | | #include "com/sun/star/beans/XPropertySetOption.hpp" |
33 | | #include "com/sun/star/beans/XMultiPropertySet.hpp" |
34 | | #include "com/sun/star/beans/XFastPropertySet.hpp" |
35 | | |
36 | | #include "cppuhelper/cppuhelperdllapi.h" |
37 | | |
38 | | |
39 | | namespace cppu |
40 | | { |
41 | | |
42 | | |
43 | | /************************************************************************* |
44 | | *************************************************************************/ |
45 | | |
46 | | |
47 | | /** |
48 | | This interface is used by the OPropertyHelper, to access the property description. |
49 | | */ |
50 | | class SAL_WARN_UNUSED CPPUHELPER_DLLPUBLIC IPropertyArrayHelper |
51 | | { |
52 | | public: |
53 | | // these are here to force memory de/allocation to sal lib. |
54 | | static void * SAL_CALL operator new( size_t nSize ) |
55 | 120k | { return ::rtl_allocateMemory( nSize ); } |
56 | | static void SAL_CALL operator delete( void * pMem ) |
57 | 120k | { ::rtl_freeMemory( pMem ); } |
58 | | static void * SAL_CALL operator new( size_t, void * pMem ) |
59 | 0 | { return pMem; } |
60 | | static void SAL_CALL operator delete( void *, void * ) |
61 | 0 | {} |
62 | | |
63 | | /** |
64 | | Following the rule, the first virtual method implies a virtual destructor. |
65 | | */ |
66 | | virtual ~IPropertyArrayHelper(); |
67 | | |
68 | | /** |
69 | | Return the property members Name and Attribute from the handle nHandle. |
70 | | @param nHandle the handle of a property. If the values of the handles |
71 | | are sorted in the same way as the names and the highest handle value |
72 | | is getCount() -1, then it must be an indexed access to the property array. |
73 | | @param pPropName is an out parameter filled with property name of the property with the |
74 | | handle nHandle. May be NULL. |
75 | | @param pAttributes is an out parameter filled with attributes of the property with the |
76 | | handle nHandle. May be NULL. |
77 | | @return True, if the handle exist, otherwise false. |
78 | | */ |
79 | | virtual sal_Bool SAL_CALL fillPropertyMembersByHandle( |
80 | | ::rtl::OUString * pPropName, sal_Int16 * pAttributes, sal_Int32 nHandle ) = 0; |
81 | | /** |
82 | | Return the sequence of properties. The sequence is sorted by name. |
83 | | */ |
84 | | virtual css::uno::Sequence< css::beans::Property > SAL_CALL getProperties() = 0; |
85 | | /** |
86 | | Return the property with the name rPropertyName. |
87 | | @param rPropertyName the name of the property. |
88 | | @exception UnknownPropertyException thrown if the property name is unknown. |
89 | | */ |
90 | | virtual css::beans::Property SAL_CALL getPropertyByName( |
91 | | const ::rtl::OUString& rPropertyName ) = 0; |
92 | | /** |
93 | | Return true if the property with the name rPropertyName exist, otherwise false. |
94 | | @param rPropertyName the name of the property. |
95 | | */ |
96 | | virtual sal_Bool SAL_CALL hasPropertyByName(const ::rtl::OUString& rPropertyName) = 0; |
97 | | /** |
98 | | Return the handle of the property with the name rPropertyName. |
99 | | If the property does not exist -1 is returned. |
100 | | @param rPropertyName the name of the property. |
101 | | */ |
102 | | virtual sal_Int32 SAL_CALL getHandleByName( const ::rtl::OUString & rPropertyName ) = 0; |
103 | | /** |
104 | | Fill the array with the handles of the properties. |
105 | | @return the handles of the names from the pHandles array. -1 |
106 | | indicates an unknown property name. |
107 | | */ |
108 | | virtual sal_Int32 SAL_CALL fillHandles( |
109 | | /*out*/ sal_Int32 * pHandles, const css::uno::Sequence< ::rtl::OUString > & rPropNames ) = 0; |
110 | | }; |
111 | | |
112 | | /** |
113 | | You can use this helper class to map a XPropertySet-Interface to a XFast- |
114 | | or a XMultiPropertySet interface. |
115 | | */ |
116 | | class SAL_WARN_UNUSED CPPUHELPER_DLLPUBLIC OPropertyArrayHelper : public IPropertyArrayHelper |
117 | | { |
118 | | public: |
119 | | /** |
120 | | Create an object which supports the common property interfaces. |
121 | | |
122 | | @param pProps array of properties |
123 | | The array pProps should be sorted. |
124 | | @param nElements is the number of properties in the pProps structure. |
125 | | @param bSorted indicates that the elements are sorted. |
126 | | *********/ |
127 | | OPropertyArrayHelper( |
128 | | css::beans::Property *pProps, |
129 | | sal_Int32 nElements , |
130 | | sal_Bool bSorted = true ); |
131 | | |
132 | | /** |
133 | | Create an object which supports the common property interfaces. |
134 | | @param aProps sequence of properties which are supported by this helper. |
135 | | The sequence aProps should be sorted. |
136 | | @param bSorted indicates that the elements are sorted. |
137 | | */ |
138 | | OPropertyArrayHelper( |
139 | | const css::uno::Sequence< css::beans::Property > & aProps, |
140 | | sal_Bool bSorted = true ); |
141 | | |
142 | | /** |
143 | | Return the number of properties. |
144 | | */ |
145 | | sal_Int32 SAL_CALL getCount() const; |
146 | | /** |
147 | | Return the property members Name and Attribute from the handle nHandle. |
148 | | @param nHandle the handle of a property. If the values of the handles |
149 | | are sorted in the same way as the names and the highest handle value |
150 | | is getCount() -1, then it is only an indexed access to the property array. |
151 | | Otherwise it is a linear search through the array. |
152 | | @param pPropName is an out parameter filled with property name of the property with the |
153 | | handle nHandle. May be NULL. |
154 | | @param pAttributes is an out parameter filled with attributes of the property with the |
155 | | handle nHandle. May be NULL. |
156 | | @return True, if the handle exist, otherwise false. |
157 | | */ |
158 | | virtual sal_Bool SAL_CALL fillPropertyMembersByHandle( |
159 | | ::rtl::OUString * pPropName, sal_Int16 * pAttributes, sal_Int32 nHandle ) SAL_OVERRIDE; |
160 | | /** |
161 | | Return the sequence of properties. The sequence is sorted by name. |
162 | | */ |
163 | | virtual css::uno::Sequence< css::beans::Property > SAL_CALL getProperties() SAL_OVERRIDE; |
164 | | /** |
165 | | Return the property with the name rPropertyName. |
166 | | @param rPropertyName the name of the property. |
167 | | @exception UnknownPropertyException thrown if the property name is unknown. |
168 | | */ |
169 | | virtual css::beans::Property SAL_CALL getPropertyByName( |
170 | | const ::rtl::OUString& rPropertyName ) SAL_OVERRIDE; |
171 | | /** |
172 | | Return true if the property with the name rPropertyName exist, otherwise false. |
173 | | @param rPropertyName the name of the property. |
174 | | */ |
175 | | virtual sal_Bool SAL_CALL hasPropertyByName(const ::rtl::OUString& rPropertyName) SAL_OVERRIDE; |
176 | | /** |
177 | | Return the handle of the property with the name rPropertyName. |
178 | | If the property does not exist -1 is returned. |
179 | | @param rPropertyName the name of the property. |
180 | | */ |
181 | | virtual sal_Int32 SAL_CALL getHandleByName( const ::rtl::OUString & rPropertyName ) SAL_OVERRIDE; |
182 | | /** |
183 | | Fill the array with the handles of the properties. |
184 | | @return the handles of the names from the pHandles array. -1 |
185 | | indicates an unknown property name. |
186 | | */ |
187 | | virtual sal_Int32 SAL_CALL fillHandles( |
188 | | /*out*/sal_Int32 * pHandles, const css::uno::Sequence< ::rtl::OUString > & rPropNames ) SAL_OVERRIDE; |
189 | | |
190 | | protected: |
191 | | /** reserved for future use. do not use. |
192 | | */ |
193 | | void * m_pReserved; |
194 | | |
195 | | private: |
196 | | void init( sal_Bool bSorted ); |
197 | | |
198 | | /** The sequence generated from the pProperties array. */ |
199 | | css::uno::Sequence< css::beans::Property > aInfos; |
200 | | |
201 | | /** |
202 | | True, If the values of the handles are sorted in the same way as the names |
203 | | and the highest handle value is getCount() -1, otherwise false. |
204 | | */ |
205 | | sal_Bool bRightOrdered; |
206 | | }; |
207 | | |
208 | | |
209 | | // helper defines needed for an interface container with a 32 bit key values |
210 | | |
211 | | struct equalInt32_Impl |
212 | | { |
213 | | bool operator()(const sal_Int32 & i1 , const sal_Int32 & i2) const |
214 | 0 | { return i1 == i2; } |
215 | | }; |
216 | | |
217 | | struct hashInt32_Impl |
218 | | { |
219 | | size_t operator()(const sal_Int32 & i) const |
220 | 0 | { return i; } |
221 | | }; |
222 | | |
223 | | /** Specialized class for key type sal_Int32, |
224 | | without explicit usage of STL symbols. |
225 | | */ |
226 | | class SAL_WARN_UNUSED CPPUHELPER_DLLPUBLIC OMultiTypeInterfaceContainerHelperInt32 |
227 | | { |
228 | | public: |
229 | | // these are here to force memory de/allocation to sal lib. |
230 | | static void * SAL_CALL operator new( size_t nSize ) |
231 | 0 | { return ::rtl_allocateMemory( nSize ); } |
232 | | static void SAL_CALL operator delete( void * pMem ) |
233 | 0 | { ::rtl_freeMemory( pMem ); } |
234 | | static void * SAL_CALL operator new( size_t, void * pMem ) |
235 | 0 | { return pMem; } |
236 | | static void SAL_CALL operator delete( void *, void * ) |
237 | 0 | {} |
238 | | |
239 | | /** |
240 | | Create a container of interface containers. |
241 | | |
242 | | @param rMutex the mutex to protect multi thread access. |
243 | | The lifetime must be longer than the lifetime |
244 | | of this object. |
245 | | */ |
246 | | OMultiTypeInterfaceContainerHelperInt32( ::osl::Mutex & rMutex ); |
247 | | /** |
248 | | Delete all containers. |
249 | | */ |
250 | | ~OMultiTypeInterfaceContainerHelperInt32(); |
251 | | |
252 | | /** |
253 | | Return all id's under which at least one interface is added. |
254 | | */ |
255 | | css::uno::Sequence< sal_Int32 > SAL_CALL getContainedTypes() const; |
256 | | |
257 | | /** |
258 | | Return the container created under this key. |
259 | | @return the container created under this key. If the container |
260 | | was not created, null was returned. |
261 | | */ |
262 | | OInterfaceContainerHelper * SAL_CALL getContainer( const sal_Int32 & rKey ) const; |
263 | | |
264 | | /** |
265 | | Insert an element in the container specified with the key. The position is not specified. |
266 | | @param rKey the id of the container. |
267 | | @param r the added interface. It is allowed to insert null or |
268 | | the same pointer more than once. |
269 | | @return the new count of elements in the container. |
270 | | */ |
271 | | sal_Int32 SAL_CALL addInterface( |
272 | | const sal_Int32 & rKey, |
273 | | const css::uno::Reference< css::uno::XInterface > & r ); |
274 | | |
275 | | /** |
276 | | Remove an element from the container specified with the key. |
277 | | It uses the equal definition of uno objects to remove the interfaces. |
278 | | @param rKey the id of the container. |
279 | | @param rxIFace the removed interface. |
280 | | @return the new count of elements in the container. |
281 | | */ |
282 | | sal_Int32 SAL_CALL removeInterface( |
283 | | const sal_Int32 & rKey, |
284 | | const css::uno::Reference< css::uno::XInterface > & rxIFace ); |
285 | | |
286 | | /** |
287 | | Call disposing on all objects in the container that |
288 | | support XEventListener. Then clear the container. |
289 | | */ |
290 | | void SAL_CALL disposeAndClear( const css::lang::EventObject & rEvt ); |
291 | | /** |
292 | | Remove all elements of all containers. Does not delete the container. |
293 | | */ |
294 | | void SAL_CALL clear(); |
295 | | |
296 | | typedef sal_Int32 keyType; |
297 | | private: |
298 | | void * m_pMap; |
299 | | ::osl::Mutex & rMutex; |
300 | | |
301 | | OMultiTypeInterfaceContainerHelperInt32( const OMultiTypeInterfaceContainerHelperInt32 & ) SAL_DELETED_FUNCTION; |
302 | | OMultiTypeInterfaceContainerHelperInt32 & operator = ( const OMultiTypeInterfaceContainerHelperInt32 & )SAL_DELETED_FUNCTION; |
303 | | }; |
304 | | |
305 | | |
306 | | /** An interface to extend event notification actions. |
307 | | */ |
308 | | class IEventNotificationHook |
309 | | { |
310 | | public: |
311 | | /** |
312 | | Method to be called by OPropertySetHelper::fire. |
313 | | |
314 | | @param pnHandles the id's of the properties that changed. |
315 | | @param nCount the number of elements in the arrays pnHandles, pNewValues and pOldValues. |
316 | | @param bVetoable true means fire to VetoableChangeListener, false means fire to |
317 | | XPropertyChangedListener and XMultiPropertyChangedListener. |
318 | | @param bIgnoreRuntimeExceptionsWhileFiring |
319 | | indicates whether occurring RuntimeExceptions will be |
320 | | ignored when firing notifications |
321 | | (vetoableChange(), propertyChange()) |
322 | | to listeners. |
323 | | PropertyVetoExceptions may still be thrown. |
324 | | This flag is useful in an inter-process scenario when |
325 | | remote bridges may break down |
326 | | (firing DisposedExceptions). |
327 | | |
328 | | @see OPropertySetHelper::fire |
329 | | */ |
330 | | virtual void fireEvents( |
331 | | sal_Int32 * pnHandles, |
332 | | sal_Int32 nCount, |
333 | | sal_Bool bVetoable, |
334 | | bool bIgnoreRuntimeExceptionsWhileFiring) = 0; |
335 | | |
336 | | #if !defined _MSC_VER // public -> protected changes mangled names there |
337 | | protected: |
338 | | #endif |
339 | 9.38k | ~IEventNotificationHook() {} |
340 | | // avoid warnings about virtual members and non-virtual dtor |
341 | | }; |
342 | | |
343 | | |
344 | | /** |
345 | | This abstract class maps the methods of the interfaces XMultiPropertySet, XFastPropertySet |
346 | | and XPropertySet to the methods getInfoHelper, convertFastPropertyValue, |
347 | | setFastPropertyValue_NoBroadcast and getFastPropertyValue. You must derive from |
348 | | this class and override the methods. |
349 | | It provides a standard implementation of the XPropertySetInfo. |
350 | | The XPropertiesChangeListener are inserted in the rBHelper.aLC structure. |
351 | | The XPropertyChangeListener and XVetoableChangeListener with no names are inserted |
352 | | in the rBHelper.aLC structure. So it is possible to advise property listeners with |
353 | | the connection point interfaces. But only listeners that listen to all property changes. |
354 | | |
355 | | */ |
356 | | class CPPUHELPER_DLLPUBLIC OPropertySetHelper : |
357 | | public css::beans::XMultiPropertySet, |
358 | | public css::beans::XFastPropertySet, |
359 | | public css::beans::XPropertySet |
360 | | { |
361 | | public: |
362 | | /** |
363 | | @param rBHelper this structure contains the basic members of |
364 | | a broadcaster. |
365 | | The lifetime must be longer than the lifetime |
366 | | of this object. Stored in the variable rBHelper. |
367 | | */ |
368 | | OPropertySetHelper( OBroadcastHelper & rBHelper ); |
369 | | |
370 | | /** Constructor. |
371 | | |
372 | | @param rBHelper |
373 | | this structure contains the basic members of |
374 | | a broadcaster. |
375 | | The lifetime must be longer than the lifetime |
376 | | of this object. Stored in the variable rBHelper. |
377 | | |
378 | | @param bIgnoreRuntimeExceptionsWhileFiring |
379 | | indicates whether occurring RuntimeExceptions will be |
380 | | ignored when firing notifications |
381 | | (vetoableChange(), propertyChange()) |
382 | | to listeners. |
383 | | PropertyVetoExceptions may still be thrown. |
384 | | This flag is useful in an inter-process scenario when |
385 | | remote bridges may break down |
386 | | (firing DisposedExceptions). |
387 | | */ |
388 | | OPropertySetHelper( |
389 | | OBroadcastHelper & rBHelper, bool bIgnoreRuntimeExceptionsWhileFiring ); |
390 | | |
391 | | /** Constructor. |
392 | | |
393 | | @param rBHelper |
394 | | this structure contains the basic members of |
395 | | a broadcaster. |
396 | | The lifetime must be longer than the lifetime |
397 | | of this object. Stored in the variable rBHelper. |
398 | | |
399 | | @param i_pFireEvents |
400 | | additional event notifier |
401 | | |
402 | | @param bIgnoreRuntimeExceptionsWhileFiring |
403 | | indicates whether occurring RuntimeExceptions will be |
404 | | ignored when firing notifications |
405 | | (vetoableChange(), propertyChange()) |
406 | | to listeners. |
407 | | PropertyVetoExceptions may still be thrown. |
408 | | This flag is useful in an inter-process scenario when |
409 | | remote bridges may break down |
410 | | (firing DisposedExceptions). |
411 | | */ |
412 | | OPropertySetHelper( |
413 | | OBroadcastHelper & rBHelper, |
414 | | IEventNotificationHook *i_pFireEvents, |
415 | | bool bIgnoreRuntimeExceptionsWhileFiring = false); |
416 | | |
417 | | /** |
418 | | Only returns a reference to XMultiPropertySet, XFastPropertySet, XPropertySet and |
419 | | XEventListener. |
420 | | */ |
421 | | virtual css::uno::Any SAL_CALL queryInterface( const css::uno::Type & rType ) SAL_OVERRIDE; |
422 | | |
423 | | /** eases implementing XTypeProvider::getTypes, returns the types of XMultiPropertySet, XFastPropertySet, XPropertySet |
424 | | |
425 | | @throws css::uno::RuntimeException |
426 | | */ |
427 | | css::uno::Sequence< css::uno::Type > getTypes(); |
428 | | |
429 | | /** |
430 | | Send a disposing notification to the listeners in the containers aBoundLC |
431 | | and aVetoableLC. |
432 | | |
433 | | @see OComponentHelper |
434 | | */ |
435 | | void SAL_CALL disposing(); |
436 | | |
437 | | /** |
438 | | Throw UnknownPropertyException or PropertyVetoException if the property with the name |
439 | | rPropertyName does not exist or is readonly. Otherwise rPropertyName is changed to its handle |
440 | | value and setFastPropertyValue is called. |
441 | | */ |
442 | | virtual void SAL_CALL setPropertyValue( const ::rtl::OUString& rPropertyName, const css::uno::Any& aValue ) SAL_OVERRIDE; |
443 | | /** |
444 | | Throw UnknownPropertyException if the property with the name |
445 | | rPropertyName does not exist. |
446 | | */ |
447 | | virtual css::uno::Any SAL_CALL getPropertyValue(const ::rtl::OUString& aPropertyName) SAL_OVERRIDE; |
448 | | /** Ignored if the property is not bound. */ |
449 | | virtual void SAL_CALL addPropertyChangeListener( |
450 | | const ::rtl::OUString& aPropertyName, |
451 | | const css::uno::Reference< css::beans::XPropertyChangeListener >& aListener) SAL_OVERRIDE; |
452 | | |
453 | | /** Ignored if the property is not bound. */ |
454 | | virtual void SAL_CALL removePropertyChangeListener( |
455 | | const ::rtl::OUString& aPropertyName, |
456 | | const css::uno::Reference < css::beans::XPropertyChangeListener >& aListener) SAL_OVERRIDE; |
457 | | |
458 | | /** Ignored if the property is not constrained. */ |
459 | | virtual void SAL_CALL addVetoableChangeListener( |
460 | | const ::rtl::OUString& aPropertyName, |
461 | | const css::uno::Reference< css::beans::XVetoableChangeListener >& aListener) SAL_OVERRIDE; |
462 | | |
463 | | /** Ignored if the property is not constrained. */ |
464 | | virtual void SAL_CALL removeVetoableChangeListener( |
465 | | const ::rtl::OUString& aPropertyName, |
466 | | const css::uno::Reference< css::beans::XVetoableChangeListener > & aListener ) SAL_OVERRIDE; |
467 | | |
468 | | /** |
469 | | Throw UnknownPropertyException or PropertyVetoException if the property with the name |
470 | | rPropertyName does not exist or is readonly. Otherwise the method convertFastPropertyValue |
471 | | is called, then the vetoable listeners are notified. After this the value of the property |
472 | | is changed with the setFastPropertyValue_NoBroadcast method and the bound listeners are |
473 | | notified. |
474 | | */ |
475 | | virtual void SAL_CALL setFastPropertyValue( sal_Int32 nHandle, const css::uno::Any& rValue ) SAL_OVERRIDE; |
476 | | |
477 | | /** |
478 | | @exception css::beans::UnknownPropertyException |
479 | | if the property with the handle nHandle does not exist. |
480 | | */ |
481 | | virtual css::uno::Any SAL_CALL getFastPropertyValue( sal_Int32 nHandle ) SAL_OVERRIDE; |
482 | | |
483 | | // XMultiPropertySet |
484 | | virtual void SAL_CALL setPropertyValues( |
485 | | const css::uno::Sequence< ::rtl::OUString >& PropertyNames, |
486 | | const css::uno::Sequence< css::uno::Any >& Values ) SAL_OVERRIDE; |
487 | | |
488 | | virtual css::uno::Sequence< css::uno::Any > SAL_CALL getPropertyValues( |
489 | | const css::uno::Sequence< ::rtl::OUString >& PropertyNames ) SAL_OVERRIDE; |
490 | | |
491 | | virtual void SAL_CALL addPropertiesChangeListener( |
492 | | const css::uno::Sequence< ::rtl::OUString >& PropertyNames, |
493 | | const css::uno::Reference< css::beans::XPropertiesChangeListener >& Listener ) SAL_OVERRIDE; |
494 | | |
495 | | virtual void SAL_CALL removePropertiesChangeListener( |
496 | | const css::uno::Reference< css::beans::XPropertiesChangeListener >& Listener ) SAL_OVERRIDE; |
497 | | |
498 | | virtual void SAL_CALL firePropertiesChangeEvent( |
499 | | const css::uno::Sequence< ::rtl::OUString >& PropertyNames, |
500 | | const css::uno::Reference< css::beans::XPropertiesChangeListener > & Listener ) SAL_OVERRIDE; |
501 | | |
502 | | /** |
503 | | The property sequence is created in the call. The interface isn't used after the call. |
504 | | */ |
505 | | static css::uno::Reference < css::beans::XPropertySetInfo > SAL_CALL |
506 | | createPropertySetInfo( IPropertyArrayHelper & rProperties ); |
507 | | protected: |
508 | | /** |
509 | | This method fire events to all registered property listeners. |
510 | | @param pnHandles the id's of the properties that changed. |
511 | | @param pNewValues the new values of the properties. |
512 | | @param pOldValues the old values of the properties. |
513 | | @param nCount the number of elements in the arrays pnHandles, pNewValues and pOldValues. |
514 | | @param bVetoable true means fire to VetoableChangeListener, false means fire to |
515 | | XPropertyChangedListener and XMultiPropertyChangedListener. |
516 | | */ |
517 | | void SAL_CALL fire( |
518 | | sal_Int32 * pnHandles, |
519 | | const css::uno::Any * pNewValues, |
520 | | const css::uno::Any * pOldValues, |
521 | | sal_Int32 nCount, |
522 | | sal_Bool bVetoable ); |
523 | | |
524 | | /** |
525 | | Set multiple properties with the handles. |
526 | | @param nSeqLen the length of the arrays pHandles and Values. |
527 | | @param pHandles the handles of the properties. The number of elements |
528 | | in the Values sequence is the length of the handle array. A value of -1 |
529 | | of a handle means invalid property. These are ignored. |
530 | | @param pValues the values of the properties. |
531 | | @param nHitCount the number of valid entries in the handle array. |
532 | | */ |
533 | | void SAL_CALL setFastPropertyValues( |
534 | | sal_Int32 nSeqLen, |
535 | | sal_Int32 * pHandles, |
536 | | const css::uno::Any * pValues, |
537 | | sal_Int32 nHitCount ); |
538 | | |
539 | | /** |
540 | | This abstract method must return the name to index table. This table contains all property |
541 | | names and types of this object. The method is not implemented in this class. |
542 | | */ |
543 | | virtual IPropertyArrayHelper & SAL_CALL getInfoHelper() = 0; |
544 | | |
545 | | /** |
546 | | Converted the value rValue and return the result in rConvertedValue and the |
547 | | old value in rOldValue. An IllegalArgumentException is thrown. |
548 | | The method is not implemented in this class. After this call the vetoable |
549 | | listeners are notified. |
550 | | |
551 | | @param rConvertedValue the converted value. Only set if return is true. |
552 | | @param rOldValue the old value. Only set if return is true. |
553 | | @param nHandle the handle of the property. |
554 | | @param rValue the value to be converted |
555 | | @return true if the value converted. |
556 | | @throws css::lang::IllegalArgumentException |
557 | | @throws css::beans::UnknownPropertyException |
558 | | @throws css::uno::RuntimeException |
559 | | */ |
560 | | virtual sal_Bool SAL_CALL convertFastPropertyValue( |
561 | | css::uno::Any & rConvertedValue, |
562 | | css::uno::Any & rOldValue, |
563 | | sal_Int32 nHandle, |
564 | | const css::uno::Any& rValue ) = 0; |
565 | | |
566 | | /** The same as setFastPropertyValue; nHandle is always valid. |
567 | | The changes must not be broadcasted in this method. |
568 | | The method is implemented in a derived class. |
569 | | |
570 | | @attention |
571 | | Although you are permitted to throw any UNO exception, only the following |
572 | | are valid for usage: |
573 | | -- css::beans::UnknownPropertyException |
574 | | -- css::beans::PropertyVetoException |
575 | | -- css::lang::IllegalArgumentException |
576 | | -- css::lang::WrappedTargetException |
577 | | -- css::uno::RuntimeException |
578 | | |
579 | | @param nHandle |
580 | | handle |
581 | | @param rValue |
582 | | value |
583 | | @throws css::uno::Exception |
584 | | */ |
585 | | virtual void SAL_CALL setFastPropertyValue_NoBroadcast( |
586 | | sal_Int32 nHandle, |
587 | | const css::uno::Any& rValue ) = 0; |
588 | | /** |
589 | | The same as getFastPropertyValue, but return the value through rValue and nHandle |
590 | | is always valid. |
591 | | The method is not implemented in this class. |
592 | | */ |
593 | | virtual void SAL_CALL getFastPropertyValue( |
594 | | css::uno::Any& rValue, |
595 | | sal_Int32 nHandle ) const = 0; |
596 | | |
597 | | /** sets an dependent property's value |
598 | | |
599 | | <p>Sometimes setting a given property needs to implicitly modify another property's value. Calling |setPropertyValue| |
600 | | from within |setFastPropertyValue_NoBroadcast| is not an option here, as it would notify the property listeners |
601 | | while our mutex is still locked. Setting the dependent property's value directly (e.g. by calling |setFastPropertyValue_NoBroadcast| |
602 | | recursively) is not an option, too, since it would miss firing the property change event.</p> |
603 | | |
604 | | <p>So, in such cases, you use |setDependentFastPropertyValue| from within |setFastPropertyValue_NoBroadcast|. |
605 | | It will convert and actually set the property value (invoking |convertFastPropertyValue| and |setFastPropertyValue_NoBroadcast| |
606 | | for the given handle and value), and add the property change event to the list of events to be notified |
607 | | when the bottom-most |setFastPropertyValue_NoBroadcast| on the stack returns.</p> |
608 | | |
609 | | <p><strong>Note</strong>: The method will <em>not</em> invoke veto listeners for the property.</p> |
610 | | |
611 | | <p><strong>Note</strong>: It's the caller's responsibility to ensure that our mutex is locked. This is |
612 | | canonically given when the method is invoked from within |setFastPropertyValue_NoBroadcast|, in other |
613 | | contexts, you might need to take own measures.</p> |
614 | | */ |
615 | | void setDependentFastPropertyValue( |
616 | | sal_Int32 i_handle, |
617 | | const css::uno::Any& i_value |
618 | | ); |
619 | | |
620 | | /** The common data of a broadcaster. Use the mutex, disposing state and the listener container. */ |
621 | | OBroadcastHelper &rBHelper; |
622 | | /** |
623 | | Container for the XPropertyChangedListener. The listeners are inserted by handle. |
624 | | */ |
625 | | OMultiTypeInterfaceContainerHelperInt32 aBoundLC; |
626 | | /** |
627 | | Container for the XPropertyVetoableListener. The listeners are inserted by handle. |
628 | | */ |
629 | | OMultiTypeInterfaceContainerHelperInt32 aVetoableLC; |
630 | | |
631 | | class Impl; |
632 | | |
633 | | /** reserved for future use. finally, the future has arrived... |
634 | | */ |
635 | | Impl * const m_pReserved; |
636 | | |
637 | | private: |
638 | | OPropertySetHelper( const OPropertySetHelper & ) SAL_DELETED_FUNCTION; |
639 | | OPropertySetHelper & operator = ( const OPropertySetHelper & ) |
640 | | SAL_DELETED_FUNCTION; |
641 | | |
642 | | /** notifies the given changes in property's values, <em>plus</em> all property changes collected during recent |
643 | | |setDependentFastPropertyValue| calls. |
644 | | */ |
645 | | void impl_fireAll( |
646 | | sal_Int32* i_handles, |
647 | | const css::uno::Any * i_newValues, |
648 | | const css::uno::Any * i_oldValues, |
649 | | sal_Int32 i_count |
650 | | ); |
651 | | |
652 | | #if defined _MSC_VER // public -> protected changes mangled names there |
653 | | public: |
654 | | #else |
655 | | protected: |
656 | | #endif |
657 | | /** |
658 | | You must call disposing before destruction. |
659 | | */ |
660 | | ~OPropertySetHelper(); |
661 | | }; |
662 | | |
663 | | /** |
664 | | OPropertySetHelper plus XPropertySetOption |
665 | | |
666 | | @attention |
667 | | The getTypes() inherited from OPropertysetHelper does not cover |
668 | | XPropertySetOption. |
669 | | */ |
670 | | class CPPUHELPER_DLLPUBLIC OPropertySetHelper2 : public OPropertySetHelper, |
671 | | public css::beans::XPropertySetOption |
672 | | { |
673 | | public: |
674 | | /** Constructor. |
675 | | |
676 | | See OPropertySetHelper constructors documentation |
677 | | */ |
678 | | explicit OPropertySetHelper2( |
679 | | OBroadcastHelper & rBHelper, |
680 | | IEventNotificationHook *i_pFireEvents = NULL, |
681 | | bool bIgnoreRuntimeExceptionsWhileFiring = false); |
682 | | |
683 | | // XInterface |
684 | | virtual css::uno::Any SAL_CALL queryInterface( const css::uno::Type & rType ) SAL_OVERRIDE; |
685 | | |
686 | | // XPropertySetOption |
687 | | virtual void SAL_CALL enableChangeListenerNotification( sal_Bool bEnable ) SAL_OVERRIDE; |
688 | | |
689 | | |
690 | | private: |
691 | | OPropertySetHelper2( const OPropertySetHelper2 & ) SAL_DELETED_FUNCTION; |
692 | | OPropertySetHelper2 & operator = ( const OPropertySetHelper2 & ) |
693 | | SAL_DELETED_FUNCTION; |
694 | | |
695 | | #if defined _MSC_VER // public -> protected changes mangled names there |
696 | | public: |
697 | | #else |
698 | | protected: |
699 | | #endif |
700 | | // Suppress warning about virtual functions but non-virtual destructor: |
701 | | /** |
702 | | You must call disposing before destruction. |
703 | | */ |
704 | | virtual ~OPropertySetHelper2(); |
705 | | }; |
706 | | |
707 | | } // end namespace cppuhelper |
708 | | #endif |
709 | | |
710 | | |
711 | | /* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |