| /************************************************************** | |
| * | |
| * Licensed to the Apache Software Foundation (ASF) under one | |
| * or more contributor license agreements. See the NOTICE file | |
| * distributed with this work for additional information | |
| * regarding copyright ownership. The ASF licenses this file | |
| * to you under the Apache License, Version 2.0 (the | |
| * "License"); you may not use this file except in compliance | |
| * with the License. You may obtain a copy of the License at | |
| * | |
| * http://www.apache.org/licenses/LICENSE-2.0 | |
| * | |
| * Unless required by applicable law or agreed to in writing, | |
| * software distributed under the License is distributed on an | |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| * KIND, either express or implied. See the License for the | |
| * specific language governing permissions and limitations | |
| * under the License. | |
| * | |
| *************************************************************/ | |
| #ifndef __com_sun_star_configuration_SetElement_idl__ | |
| #define __com_sun_star_configuration_SetElement_idl__ | |
| #ifndef __com_sun_star_configuration_HierarchyElement_idl__ | |
| #include <com/sun/star/configuration/HierarchyElement.idl> | |
| #endif | |
| #ifndef __com_sun_star_container_XChild_idl__ | |
| #include <com/sun/star/container/XChild.idl> | |
| #endif | |
| #ifndef __com_sun_star_lang_XComponent_idl__ | |
| #include <com/sun/star/lang/XComponent.idl> | |
| #endif | |
| #ifndef __com_sun_star_configuration_XTemplateInstance_idl__ | |
| #include <com/sun/star/configuration/XTemplateInstance.idl> | |
| #endif | |
| //============================================================================= | |
| module com { module sun { module star { module configuration { | |
| //============================================================================= | |
| /** provides information about a dynamic element that can be inserted into a | |
| homogeneous set of elements within a hierarchy. | |
| <p>Provides information about the element. | |
| Provides access to its containing set object. | |
| Allows controlling the lifetime of the element. | |
| </p> | |
| <p>Set elements may be added to and removed from the hierarchy at runtime. | |
| They bear user-defined names. They may exist independently, outside any | |
| container. | |
| </p> | |
| <p>New set element instances generally are created through members of | |
| <type scope="com::sun::star::lang">XSingleServiceFactory</type> or, | |
| if supported, <type scope="com::sun::star::lang">XMultiServiceFactory</type> | |
| on an implementation of <type>SetUpdate</type>. Initially, they are not | |
| contained in a set object and have no meaningful name. | |
| </p> | |
| <p>While an instance is not contained in a set object, it is owned by | |
| the client and can be disposed by calling | |
| <member scope="com::sun::star::lang">XComponent::dispose()</member>. The name | |
| of the object can freely be changed in that situation though without | |
| persistent effect. | |
| </p> | |
| <p>When the instance is inserted into a set (this includes replacing an | |
| existing element), ownership is transferred to the container. | |
| While it is contained in the container, clients must not dispose the | |
| object. When inserted, the name of the object is fixed and is used to | |
| identify it within the container. An implementation may support | |
| <member scope="com::sun::star::container">XNamed::setName()</member> even in | |
| this case. If it does, changing the name has the same effect of removing | |
| the object (under the old name) and then reinserting it into the same | |
| container (using the new name). | |
| </p> | |
| <p>When an instance is removed from a set (this includes being replaced by | |
| a new element), ownership is transferred to the client again. It can then be | |
| disposed or reinserted into a container. An instance can only be inserted | |
| into a container, if it was obtained from the same hierarchy. | |
| </p> | |
| <p>When a set element is removed from its set from outside the hierarchy, the | |
| container disposes of the object. This occurrence can be detected by registering | |
| a <type scope="com::sun::star::lang">XEventListener</type> with the object. | |
| </p> | |
| <p>If an implementation is part of a <em>read-only</em> view of the hierarchy, | |
| changing the name or parent is not supported (the object can't be removed from | |
| its container anyway). | |
| </p> | |
| @see com::sun::star::configuration::SetAccess | |
| Parent objects of this service generally implement service SetAccess. | |
| @see com::sun::star::configuration::GroupElement | |
| A complementary service for elements of a static heterogeneous collection. | |
| @see com::sun::star::configuration::AccessRootElement | |
| A complementary service for the root element of a hierarchy. | |
| */ | |
| published service SetElement | |
| { | |
| /** is the basic service for accessing information about an element in the | |
| hierarchy. | |
| */ | |
| service HierarchyElement; | |
| /** provides access to the containing set object. | |
| <p>In this service, this interface is mandatory</p> | |
| <p><member scope="com::sun::star::container">XChild::getParent()</member> | |
| returns <NULL/>, if the object is currently not contained in a container. | |
| </p> | |
| <p>An implementation may also support | |
| <member scope="com::sun::star::container">XChild::setParent()</member>. | |
| If it does, changing the parent has the effect of first removing the object | |
| from its old parent (if any) and then inserting it into the new parent | |
| (unless that is <NULL/>) under the same name. The new parent must be part of | |
| the same hierarchy as the old one. The name of the object must have been set | |
| before. | |
| </p> | |
| */ | |
| interface com::sun::star::container::XChild; | |
| /** allows controlling or observing the lifetime of the object. | |
| <p>Clients may dispose of the object using | |
| <member scope="com::sun::star::lang">XComponent::dispose()</member>, only if | |
| the object is currently not contained in a container ( | |
| <member scope="com::sun::star::container">XChild::getParent()</member> | |
| returns <NULL/>). | |
| </p> | |
| <p>Clients may register an <type scope="com::sun::star::lang">XEventListener</type> | |
| to be notified, if the object is removed from its container by an outside source. | |
| </p> | |
| */ | |
| interface com::sun::star::lang::XComponent; | |
| /** provides information about the type of the element. | |
| <p>Set elements have a predetermined structure (their <em>type</em>), | |
| that is described by and can be generated from a <em>template</em>. | |
| </p> | |
| <p>If the object was created using interface | |
| <type scope="com::sun::star::lang">XSingleServiceFactory</type> | |
| on an implementation of <type>SetUpdate</type>, this interface describes the | |
| same template as interface <type>XTemplateContainer</type> on that | |
| <type>SetUpdate</type>. | |
| </p> | |
| <p>If the object was created using interface | |
| <type scope="com::sun::star::lang">XMultiServiceFactory</type> | |
| on an implementation of <type>SetUpdate</type>, this interface describes the | |
| template whose name was used as a service identifier for the factory method. | |
| </p> | |
| <p>Otherwise, the semantics of the information provided about the template depends on the | |
| implementation. | |
| </p> | |
| @see com::sun::star::configuration::XTemplateContainer | |
| */ | |
| interface com::sun::star::configuration::XTemplateInstance; | |
| }; | |
| //============================================================================= | |
| }; }; }; }; | |
| #endif |