offapi/com/sun/star/configuration/SetElement.idl

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