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