1/************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23#ifndef __com_sun_star_configuration_SetElement_idl__ 24#define __com_sun_star_configuration_SetElement_idl__ 25 26#ifndef __com_sun_star_configuration_HierarchyElement_idl__ 27#include <com/sun/star/configuration/HierarchyElement.idl> 28#endif 29 30#ifndef __com_sun_star_container_XChild_idl__ 31#include <com/sun/star/container/XChild.idl> 32#endif 33 34#ifndef __com_sun_star_lang_XComponent_idl__ 35#include <com/sun/star/lang/XComponent.idl> 36#endif 37 38#ifndef __com_sun_star_configuration_XTemplateInstance_idl__ 39#include <com/sun/star/configuration/XTemplateInstance.idl> 40#endif 41 42//============================================================================= 43 44module com { module sun { module star { module configuration { 45 46//============================================================================= 47/** provides information about a dynamic element that can be inserted into a 48 homogeneous set of elements within a hierarchy. 49 50 <p>Provides information about the element. 51 Provides access to its containing set object. 52 Allows controlling the lifetime of the element. 53 </p> 54 55 <p>Set elements may be added to and removed from the hierarchy at runtime. 56 They bear user-defined names. They may exist independently, outside any 57 container. 58 </p> 59 60 <p>New set element instances generally are created through members of 61 <type scope="com::sun::star::lang">XSingleServiceFactory</type> or, 62 if supported, <type scope="com::sun::star::lang">XMultiServiceFactory</type> 63 on an implementation of <type>SetUpdate</type>. Initially, they are not 64 contained in a set object and have no meaningful name. 65 </p> 66 67 <p>While an instance is not contained in a set object, it is owned by 68 the client and can be disposed by calling 69 <member scope="com::sun::star::lang">XComponent::dispose()</member>. The name 70 of the object can freely be changed in that situation though without 71 persistent effect. 72 </p> 73 74 <p>When the instance is inserted into a set (this includes replacing an 75 existing element), ownership is transferred to the container. 76 While it is contained in the container, clients must not dispose the 77 object. When inserted, the name of the object is fixed and is used to 78 identify it within the container. An implementation may support 79 <member scope="com::sun::star::container">XNamed::setName()</member> even in 80 this case. If it does, changing the name has the same effect of removing 81 the object (under the old name) and then reinserting it into the same 82 container (using the new name). 83 </p> 84 85 <p>When an instance is removed from a set (this includes being replaced by 86 a new element), ownership is transferred to the client again. It can then be 87 disposed or reinserted into a container. An instance can only be inserted 88 into a container, if it was obtained from the same hierarchy. 89 </p> 90 91 <p>When a set element is removed from its set from outside the hierarchy, the 92 container disposes of the object. This occurrence can be detected by registering 93 a <type scope="com::sun::star::lang">XEventListener</type> with the object. 94 </p> 95 96 <p>If an implementation is part of a <em>read-only</em> view of the hierarchy, 97 changing the name or parent is not supported (the object can't be removed from 98 its container anyway). 99 </p> 100 101 @see com::sun::star::configuration::SetAccess 102 Parent objects of this service generally implement service SetAccess. 103 104 @see com::sun::star::configuration::GroupElement 105 A complementary service for elements of a static heterogeneous collection. 106 107 @see com::sun::star::configuration::AccessRootElement 108 A complementary service for the root element of a hierarchy. 109 110*/ 111published service SetElement 112{ 113/** is the basic service for accessing information about an element in the 114 hierarchy. 115*/ 116 service HierarchyElement; 117 118/** provides access to the containing set object. 119 120 <p>In this service, this interface is mandatory</p> 121 122 <p><member scope="com::sun::star::container">XChild::getParent()</member> 123 returns <NULL/>, if the object is currently not contained in a container. 124 </p> 125 126 <p>An implementation may also support 127 <member scope="com::sun::star::container">XChild::setParent()</member>. 128 If it does, changing the parent has the effect of first removing the object 129 from its old parent (if any) and then inserting it into the new parent 130 (unless that is <NULL/>) under the same name. The new parent must be part of 131 the same hierarchy as the old one. The name of the object must have been set 132 before. 133 </p> 134*/ 135 interface com::sun::star::container::XChild; 136 137/** allows controlling or observing the lifetime of the object. 138 139 <p>Clients may dispose of the object using 140 <member scope="com::sun::star::lang">XComponent::dispose()</member>, only if 141 the object is currently not contained in a container ( 142 <member scope="com::sun::star::container">XChild::getParent()</member> 143 returns <NULL/>). 144 </p> 145 146 <p>Clients may register an <type scope="com::sun::star::lang">XEventListener</type> 147 to be notified, if the object is removed from its container by an outside source. 148 </p> 149*/ 150 interface com::sun::star::lang::XComponent; 151 152/** provides information about the type of the element. 153 154 <p>Set elements have a predetermined structure (their <em>type</em>), 155 that is described by and can be generated from a <em>template</em>. 156 </p> 157 158 <p>If the object was created using interface 159 <type scope="com::sun::star::lang">XSingleServiceFactory</type> 160 on an implementation of <type>SetUpdate</type>, this interface describes the 161 same template as interface <type>XTemplateContainer</type> on that 162 <type>SetUpdate</type>. 163 </p> 164 <p>If the object was created using interface 165 <type scope="com::sun::star::lang">XMultiServiceFactory</type> 166 on an implementation of <type>SetUpdate</type>, this interface describes the 167 template whose name was used as a service identifier for the factory method. 168 </p> 169 <p>Otherwise, the semantics of the information provided about the template depends on the 170 implementation. 171 </p> 172 173 @ see com::sun::star::configuration::XTemplateContainer 174*/ 175 interface com::sun::star::configuration::XTemplateInstance; 176}; 177 178//============================================================================= 179 180}; }; }; }; 181 182#endif 183