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