| /************************************************************** |
| * |
| * 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 |