merge the formfield patch from ooo-build
[ooovba.git] / offapi / com / sun / star / configuration / backend / XLayerHandler.idl
blobcaa07549d54e663aa22e912fc5125e42fd26c578
1 /*************************************************************************
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2008 by Sun Microsystems, Inc.
7 * OpenOffice.org - a multi-platform office productivity suite
9 * $RCSfile: XLayerHandler.idl,v $
10 * $Revision: 1.7 $
12 * This file is part of OpenOffice.org.
14 * OpenOffice.org is free software: you can redistribute it and/or modify
15 * it under the terms of the GNU Lesser General Public License version 3
16 * only, as published by the Free Software Foundation.
18 * OpenOffice.org is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU Lesser General Public License version 3 for more details
22 * (a copy is included in the LICENSE file that accompanied this code).
24 * You should have received a copy of the GNU Lesser General Public License
25 * version 3 along with OpenOffice.org. If not, see
26 * <http://www.openoffice.org/license.html>
27 * for a copy of the LGPLv3 License.
29 ************************************************************************/
30 #ifndef __com_sun_star_configuration_backend_XLayerHandler_idl__
31 #define __com_sun_star_configuration_backend_XLayerHandler_idl__
33 #ifndef __com_sun_star_uno_XInterface_idl__
34 #include <com/sun/star/uno/XInterface.idl>
35 #endif
37 #ifndef __com_sun_star_configuration_backend_TemplateIdentifier_idl__
38 #include <com/sun/star/configuration/backend/TemplateIdentifier.idl>
39 #endif
41 #ifndef __com_sun_star_configuration_backend_MalformedDataException_idl__
42 #include <com/sun/star/configuration/backend/MalformedDataException.idl>
43 #endif
45 #ifndef __com_sun_star_lang_WrappedTargetException_idl__
46 #include <com/sun/star/lang/WrappedTargetException.idl>
47 #endif
49 //=============================================================================
51 module com { module sun { module star { module configuration { module backend {
53 //=============================================================================
55 /** receives a description of a configuration layer
56 as a sequence of events.
58 @since OOo 1.1.2
60 published interface XLayerHandler: ::com::sun::star::uno::XInterface
62 //-------------------------------------------------------------------------
64 /** receives notification that a layer description is started
65 for a component.
67 <p> Subsequent calls describe the contents of the layer
68 until a matching call to <member>XLayerHandler::endLayer()</member>
69 is encountered.
70 </p>
72 @throws com::sun::star::configuration::backend::MalformedDataException
73 if there is an unfinished layer in progress
75 @throws com::sun::star::lang::WrappedTargetException
76 if an error occurs processing the event.
78 void startLayer( )
79 raises( MalformedDataException,
80 com::sun::star::lang::WrappedTargetException );
81 //-------------------------------------------------------------------------
83 /** receives notification that a layer description is complete.
85 <p> Must match a previous call to <member>XLayerHandler::startLayer()</member>.
86 </p>
88 @throws com::sun::star::configuration::backend::MalformedDataException
89 <ul>
90 <li>if invalid data is detected in the layer</li>
91 <li>if there is a unfinished subnode in progress</li>
92 <li>if no layer is started at all</li>
93 <li>if the layer tries to override read-only or final data</li>
94 </ul>
95 <p><em>Not every implementation can detect each condition</em></p>
97 @throws com::sun::star::lang::WrappedTargetException
98 if an error occurs processing the event.
100 void endLayer( )
101 raises( MalformedDataException,
102 com::sun::star::lang::WrappedTargetException );
103 //-------------------------------------------------------------------------
105 /** receives notification that a description of a node override is started.
107 <p> Subsequent calls describe overrides to properties and members
108 or items of the node until a matching call to
109 <member>XLayerHandler::endNode()</member>is encountered.
110 </p>
112 @param aName
113 specifies the name of the node.
115 @param aAttributes
116 specifies attribute values to be applied to the node.
118 <p> The value is a combination of
119 <type>NodeAttribute</type> flags.
120 </p>
121 <p> The attributes are combined cumulatively with those
122 set on lower layers.
123 </p>
125 @param bClear
126 if <TRUE/>, specifies that the node should be cleared to an empty
127 state by removing all non-mandatory children from lower layers prior
128 to applying the overrides.
130 @throws com::sun::star::configuration::backend::MalformedDataException
131 <ul>
132 <li>if there isn't a layer in progress</li>
133 <li>if there already was a change to that node</li>
134 <li>if there is no node with that name</li>
135 <li>if the node is marked read-only in a lower layer</li>
136 <li>if the name is not a valid node name</li>
137 <li>if the attributes are not valid for the node</li>
138 </ul>
139 <p><em>Not every implementation can detect each condition</em></p>
141 @throws com::sun::star::lang::WrappedTargetException
142 if an error occurs processing the event.
144 @see com::sun::star::configuration::backend::NodeAttribute
146 void overrideNode( [in] string aName,
147 [in] short aAttributes,
148 [in] boolean bClear )
149 raises( MalformedDataException,
150 com::sun::star::lang::WrappedTargetException );
151 //-------------------------------------------------------------------------
153 /** receives notification that a new item is started.
155 <p> The current node must be a set and
156 a preexisting item (if any) must be removeable.
157 </p>
158 <p> The new item will be created from the default template
159 of the set.
160 </p>
161 <p> Subsequent calls describe the difference from the template
162 of properties and members or items of the node until
163 a matching call to <member>XLayerHandler::endNode()</member>
164 is encountered.
165 </p>
167 @param aName
168 specifies the name of the item.
170 @param aAttributes
171 specifies attribute values to be applied to the new node.
173 <p> The value is a combination of
174 <type>NodeAttribute</type> flags. Note that
175 <member>NodeAttribute::FUSE</member> has an impact on the
176 semantics of this method.
177 </p>
179 @throws com::sun::star::configuration::backend::MalformedDataException
180 <ul>
181 <li>if there isn't a set node in progress currently</li>
182 <li>if there already was a change to a node of that name</li>
183 <li>if the template for the new node is not found</li>
184 <li>if an item of that name on a lower layer is not removeable</li>
185 <li>if the name is not a valid item name</li>
186 <li>if the attributes are not valid for the node</li>
187 </ul>
188 <p><em>Not every implementation can detect each condition</em></p>
190 @throws com::sun::star::lang::WrappedTargetException
191 if an error occurs processing the event.
193 @see com::sun::star::configuration::backend::NodeAttribute
195 void addOrReplaceNode( [in] string aName,
196 [in] short aAttributes )
197 raises( MalformedDataException,
198 com::sun::star::lang::WrappedTargetException );
199 //-------------------------------------------------------------------------
201 /** receives notification that a new item based on a particular template
202 is started.
204 <p> The current node must be a set and
205 a preexisting item (if any) must be removeable.
206 </p>
207 <p> Subsequent calls describe the difference from the template
208 of properties and members or items of the node until
209 a matching call to <member>XLayerHandler::endNode()</member>
210 is encountered.
211 </p>
213 @param aName
214 specifies the name of the item.
216 @param aTemplate
217 specifies the template to use for the new node
219 @param aAttributes
220 specifies attribute values to be applied to the new node.
222 <p> The value is a combination of
223 <type>NodeAttribute</type> flags. Note that
224 <member>NodeAttribute::FUSE</member> has an impact on the
225 semantics of this method.
226 </p>
228 @throws com::sun::star::configuration::backend::MalformedDataException
229 <ul>
230 <li>if there isn't a set node in progress currently</li>
231 <li>if there already was a change to a node of that name</li>
232 <li>if the template for the new node is not found</li>
233 <li>if the template is not a valid item type for the containing set</li>
234 <li>if an item of that name on a lower layer is not removeable</li>
235 <li>if the name is not a valid item name</li>
236 <li>if the attributes are not valid for the node</li>
237 </ul>
238 <p><em>Not every implementation can detect each condition</em></p>
240 @throws com::sun::star::lang::WrappedTargetException
241 if an error occurs processing the event.
243 @see com::sun::star::configuration::backend::NodeAttribute
245 void addOrReplaceNodeFromTemplate( [in] string aName,
246 [in] TemplateIdentifier aTemplate,
247 [in] short aAttributes )
248 raises( MalformedDataException,
249 com::sun::star::lang::WrappedTargetException );
250 //-------------------------------------------------------------------------
252 /** receives notification that a node description is complete.
254 <p> Must match the last open call to
255 <member>XLayerHandler::overrideNode()</member>,
256 <member>XLayerHandler::addOrReplaceNode()</member> or
257 <member>XLayerHandler::addOrReplaceNodeFromTemplate()</member>.
258 </p>
260 @throws com::sun::star::configuration::backend::MalformedDataException
261 <ul>
262 <li>if invalid data is detected in the node</li>
263 <li>if no node is started at all</li>
264 </ul>
265 <p><em>Not every implementation can detect each condition</em></p>
267 @throws com::sun::star::lang::WrappedTargetException
268 if an error occurs processing the event.
270 void endNode( )
271 raises( MalformedDataException,
272 com::sun::star::lang::WrappedTargetException );
273 //-------------------------------------------------------------------------
275 /** receives notification that a node is dropped from a set.
277 <p> The current node must be a set and
278 the item must be removeable.
279 </p>
281 @param aName
282 specifies the name of the node.
284 @throws com::sun::star::configuration::backend::MalformedDataException
285 <ul>
286 <li>if there isn't a set node in progress currently</li>
287 <li>if there already was a change to a node of that name</li>
288 <li>if there is no item with that name</li>
289 <li>if the item is not removeable</li>
290 <li>if the name is not a valid node name</li>
291 </ul>
292 <p><em>Not every implementation can detect each condition</em></p>
294 @throws com::sun::star::lang::WrappedTargetException
295 if an error occurs processing the event.
297 void dropNode( [in] string aName )
298 raises( MalformedDataException,
299 com::sun::star::lang::WrappedTargetException );
300 //-------------------------------------------------------------------------
302 /** receives notification that an existing property is modified.
304 <p> Subsequent calls describe new value(s) for the property until a
305 matching call to <member>XLayerHandler::endProperty()</member>
306 is encountered.
307 </p>
309 @param aName
310 specifies the name of the property.
312 @param aAttributes
313 specifies the new attributes of the property.
315 <p> The value is a combination of
316 <type>NodeAttribute</type> flags.
317 </p>
318 <p> The attributes are combined cumulatively with those
319 set on lower layers.
320 </p>
322 @param aType
323 specifies the type of the property.
325 <p> This must be the same type as is already defined in the schema
326 or lower layers, unless the previous type was unspecified
327 (as indicated by
328 <const scope="com::sun::star::uno">TypeClass::ANY</const>.)
329 </p>
330 <p> A <void/> type indicates that the type is unspecified
331 in this layer.
332 In this case any subsequent value may be of a generic type
333 (e.g. <atom>string</atom> or - for list values -
334 <atom dim="[]">string</atom>.) Such values may be
335 converted to the type defined in the schema by
336 the implementation.
337 </p>
339 @param bClear
340 if <TRUE/>, specifies that the property should be cleared to an empty
341 state by discarding all values from lower layers prior
342 to applying the overrides.
344 @throws com::sun::star::configuration::backend::MalformedDataException
345 <ul>
346 <li>if there isn't a group or extensible node in progress currently</li>
347 <li>if there already was a change to a property of that name</li>
348 <li>if there is no property with that name</li>
349 <li>if the property is read-only</li>
350 <li>if the type does not match the type of the property</li>
351 <li>if a type is missing and cannot be determined otherwise</li>
352 <li>if the name is not a valid property name</li>
353 <li>if the attributes are not valid for the property</li>
354 </ul>
355 <p><em>Not every implementation can detect each condition</em></p>
357 @throws com::sun::star::lang::WrappedTargetException
358 if an error occurs processing the event.
360 @see com::sun::star::configuration::backend::NodeAttribute
362 void overrideProperty( [in] string aName,
363 [in] short aAttributes,
364 [in] type aType,
365 [in] boolean bClear )
366 raises( MalformedDataException,
367 com::sun::star::lang::WrappedTargetException );
369 //-------------------------------------------------------------------------
371 /** receives notification that the value of the current property
372 is overridden. .
374 @param aValue
375 specifies the new value of the property.
377 <p> The value must match the type of the current property.
378 If the property does not have the
379 <const>SchemaAttribute::REQUIRED</const> flag set,
380 the value can be <void/>.
381 </p>
382 <p> If the current property is localized, this value applies
383 to the default locale.
384 </p>
386 @throws com::sun::star::configuration::backend::MalformedDataException
387 <ul>
388 <li>if there isn't a property in progress currently</li>
389 <li>if there already was a change to the value of that property</li>
390 <li>if the value does not have the proper type</li>
391 <li>if the value is not valid for the property</li>
392 </ul>
393 <p><em>Not every implementation can detect each condition</em></p>
395 @throws com::sun::star::lang::WrappedTargetException
396 if an error occurs processing the event.
398 @see com::sun::star::configuration::backend::NodeAttribute
400 void setPropertyValue( [in] any aValue )
401 raises( MalformedDataException,
402 com::sun::star::lang::WrappedTargetException );
404 //-------------------------------------------------------------------------
406 /** receives notification that the value of the current localized property
407 is overridden for a specific locale .
409 @param aValue
410 specifies the new value of the property.
412 <p> The value must match the type of the current property.
413 If the property does not have the
414 <const>SchemaAttribute::REQUIRED</const> flag set,
415 the value can be <void/>.
416 </p>
418 @param aLocale
419 specifies the locale this value should apply to.
421 @throws com::sun::star::configuration::backend::MalformedDataException
422 <ul>
423 <li>if there isn't a property in progress currently</li>
424 <li>if the current property isn't localized</li>
425 <li>if there already was a change to the property for that locale</li>
426 <li>if the value does not have the proper type</li>
427 <li>if the value is not valid for the property</li>
428 <li>if the locale is not a valid locale</li>
429 </ul>
430 <p><em>Not every implementation can detect each condition</em></p>
432 @throws com::sun::star::lang::WrappedTargetException
433 if an error occurs processing the event.
435 @see com::sun::star::configuration::backend::NodeAttribute
437 void setPropertyValueForLocale([in] any aValue,
438 [in] string aLocale )
439 raises( MalformedDataException,
440 com::sun::star::lang::WrappedTargetException );
442 //-------------------------------------------------------------------------
444 /** receives notification that a property description is complete.
446 <p> Must match an open call to
447 <member>XLayerHandler::overrideProperty()</member>,
448 </p>
450 @throws com::sun::star::configuration::backend::MalformedDataException
451 <ul>
452 <li>if invalid data is detected in the property</li>
453 <li>if no property is started at all</li>
454 </ul>
455 <p><em>Not every implementation can detect each condition</em></p>
457 @throws com::sun::star::lang::WrappedTargetException
458 if an error occurs processing the event.
460 void endProperty( )
461 raises( MalformedDataException,
462 com::sun::star::lang::WrappedTargetException );
463 //-------------------------------------------------------------------------
465 /** receives notification that a property having a <void/> value is added
466 to the current node.
468 <p> The current node must be extensible.
469 </p>
471 @param aName
472 specifies the name of the new property.
474 @param aAttributes
475 specifies the attributes of the new property.
477 <p> The value is a combination of
478 <type>NodeAttribute</type> flags and may also contain the
479 <const>SchemaAttribute::REQUIRED</const> flag.
480 </p>
481 <p> <const>NodeAttribute::MANDATORY</const> need not be set,
482 as dynamically added properties always are mandatory
483 in subsequent layers.
484 </p>
486 @param aType
487 specifies the type of the new property.
489 @throws com::sun::star::configuration::backend::MalformedDataException
490 <ul>
491 <li>if there isn't an extensible node in progress currently</li>
492 <li>if a property with that name already exists</li>
493 <li>if the specified type is not allowed for a property</li>
494 <li>if the name is not a valid property name</li>
495 <li><li>if the attributes are not valid for the property</li>
496 </ul>
497 <p><em>Not every implementation can detect each condition</em></p>
499 @throws com::sun::star::lang::WrappedTargetException
500 if an error occurs processing the event.
502 @see com::sun::star::configuration::backend::SchemaAttribute
504 void addProperty( [in] string aName,
505 [in] short aAttributes,
506 [in] type aType )
507 raises( MalformedDataException,
508 com::sun::star::lang::WrappedTargetException );
510 //-------------------------------------------------------------------------
512 /** receives notification that a property having a non-<void/> value
513 is added to the current node.
515 <p> The current node must be extensible.
516 </p>
518 @param aName
519 specifies the name of the new property.
521 @param aAttributes
522 specifies the attributes of the new property.
524 <p> The value is a combination of
525 <type>NodeAttribute</type> flags and may also contain the
526 <const>SchemaAttribute::REQUIRED</const> flag.
527 </p>
528 </p>
529 <p> <const>NodeAttribute::MANDATORY</const> need not be set,
530 as dynamic properties always are mandatory
531 in subsequent layers.
532 </p>
534 @param aValue
535 specifies the value of the new property.
537 <p> The value also determines the type.
538 Therefore the value must not be <void/>.
539 </p>
541 @throws com::sun::star::configuration::backend::MalformedDataException
542 <ul>
543 <li>if there isn't an extensible node in progress currently</li>
544 <li>if a property with that name already exists</li>
545 <li>if the type of the value is not an allowed type
546 or if the value is <void/></li>
547 <li>if the name is not a valid property name</li>
548 <li>if the value is not valid for the property</li>
549 <li>if the attributes are not valid for the property</li>
550 </ul>
551 <p><em>Not every implementation can detect each condition</em></p>
553 @throws com::sun::star::lang::WrappedTargetException
554 if an error occurs processing the event.
556 @see com::sun::star::configuration::backend::SchemaAttribute
558 void addPropertyWithValue( [in] string aName,
559 [in] short aAttributes,
560 [in] any aValue )
561 raises( MalformedDataException,
562 com::sun::star::lang::WrappedTargetException );
564 //-------------------------------------------------------------------------
567 //=============================================================================
569 }; }; }; }; };
571 //=============================================================================
573 #endif