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
  20
  21 module com { module sun { module star { module configuration {
  22
  23 /** provides information about a dynamic element that can be inserted into a
  24  homogeneous set of elements within a hierarchy.
  25
  26  <p>Provides information about the element.
  27  Provides access to its containing set object.
  28  Allows controlling the lifetime of the element.
  29  </p>
  30
  31  <p>Set elements may be added to and removed from the hierarchy at runtime.
  32  They bear user-defined names. They may exist independently, outside any
  33  container.
  34  </p>
  35
  36  <p>New set element instances generally are created through members of
  37  com::sun::star::lang::XSingleServiceFactory or,
  38  if supported, com::sun::star::lang::XMultiServiceFactory
  39  on an implementation of SetUpdate. Initially, they are not
  40  contained in a set object and have no meaningful name.
  41  </p>
  42
  43  <p>While an instance is not contained in a set object, it is owned by
  44  the client and can be disposed by calling
  45  com::sun::star::lang::XComponent::dispose(). The name
  46  of the object can freely be changed in that situation though without
  47  persistent effect.
  48  </p>
  49
  50  <p>When the instance is inserted into a set (this includes replacing an
  51  existing element), ownership is transferred to the container.
  52  While it is contained in the container, clients must not dispose the
  53  object. When inserted, the name of the object is fixed and is used to
  54  identify it within the container. An implementation may support
  55  com::sun::star::container::XNamed::setName() even in
  56  this case. If it does, changing the name has the same effect of removing
  57  the object (under the old name) and then reinserting it into the same
  58  container (using the new name).
  59  </p>
  60
  61  <p>When an instance is removed from a set (this includes being replaced by
  62  a new element), ownership is transferred to the client again. It can then be
  63  disposed or reinserted into a container. An instance can only be inserted
  64  into a container, if it was obtained from the same hierarchy.
  65  </p>
  66
  67  <p>When a set element is removed from its set from outside the hierarchy, the
  68  container disposes of the object. This occurrence can be detected by registering
  69  a com::sun::star::lang::XEventListener with the object.
  70  </p>
  71
  72  <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
  73  changing the name or parent is not supported (the object can't be removed from
  74  its container anyway).
  75  </p>
  76
  77  @see com::sun::star::configuration::SetAccess
  78     Parent objects of this service generally implement service SetAccess.
  79
  80  @see com::sun::star::configuration::GroupElement
  81     A complementary service for elements of a static heterogeneous collection.
  82
  83  @see com::sun::star::configuration::AccessRootElement
  84     A complementary service for the root element of a hierarchy.
  85
  86 */
  87 published service SetElement
  88 {
  89 /** is the basic service for accessing information about an element in the
  90  hierarchy.
  91 */
  92     service HierarchyElement;
  93
  94 /** provides access to the containing set object.
  95
  96  <p>In this service, this interface is mandatory</p>
  97
  98  <p>com::sun::star::container::XChild::getParent()
  99  returns `NULL`, if the object is currently not contained in a container.
 100  </p>
 101
 102  <p>An implementation may also support
 103  com::sun::star::container::XChild::setParent().
 104  If it does, changing the parent has the effect of first removing the object
 105  from its old parent (if any) and then inserting it into the new parent
 106  (unless that is `NULL`) under the same name. The new parent must be part of
 107  the same hierarchy as the old one. The name of the object must have been set
 108  before.
 109  </p>
 110 */
 111     interface com::sun::star::container::XChild;
 112
 113 /** allows controlling or observing the lifetime of the object.
 114
 115  <p>Clients may dispose of the object using
 116  com::sun::star::lang::XComponent::dispose(), only if
 117  the object is currently not contained in a container (
 118  com::sun::star::container::XChild::getParent()
 119  returns `NULL`).
 120  </p>
 121
 122  <p>Clients may register a com::sun::star::lang::XEventListener
 123  to be notified, if the object is removed from its container by an outside source.
 124  </p>
 125 */
 126     interface com::sun::star::lang::XComponent;
 127
 128 /** provides information about the type of the element.
 129
 130  <p>Set elements have a predetermined structure (their <em>type</em>),
 131  that is described by and can be generated from a <em>template</em>.
 132  </p>
 133
 134  <p>If the object was created using interface
 135  com::sun::star::lang::XSingleServiceFactory
 136  on an implementation of SetUpdate, this interface describes the
 137  same template as interface XTemplateContainer on that
 138  SetUpdate.
 139  </p>
 140  <p>If the object was created using interface
 141  com::sun::star::lang::XMultiServiceFactory
 142  on an implementation of SetUpdate, this interface describes the
 143  template whose name was used as a service identifier for the factory method.
 144  </p>
 145  <p>Otherwise, the semantics of the information provided about the template depends on the
 146  implementation.
 147  </p>
 148
 149  @see com::sun::star::configuration::XTemplateContainer
 150 */
 151     interface com::sun::star::configuration::XTemplateInstance;
 152 };
 153
 154
 155 }; }; }; };
 156
 157 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */