offapi/com/sun/star/configuration/SimpleSetUpdate.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 write access to a dynamic, homogeneous, non-hierarchical set of
  24  values or objects.
  25
  26  <p>Allows adding and removing elements.
  27  Helps create new elements to be added.
  28  </p>
  29
  30  <p>This service extends SimpleSetAccess to support
  31  modifying the container. Any child objects shall in turn support
  32  modifying access.
  33  </p>
  34 */
  35 published service SimpleSetUpdate
  36 {
  37 /** is the basic service providing read access to a (not necessarily
  38  hierarchical) <em>set</em>.
  39 */
  40     service SimpleSetAccess;
  41
  42 /** allows inserting, removing, and replacing elements.
  43
  44  <p>This interface extends the interface
  45  com::sun::star::container::XNameAccess supported
  46  by service SimpleSetAccess to allow modifying the container.
  47  </p>
  48
  49  <p>If available, changes can be observed by registering a listener with interface
  50  com::sun::star::container::XContainer.
  51  </p>
  52
  53  <p>If the elements of this set are of simple type (the type returned by
  54  com::sun::star::container::XElementAccess::getElementType()
  55  is not an interface type), then values of that type can directly be passed to
  56  com::sun::star::container::XNameContainer::insertByName()
  57  and
  58  com::sun::star::container::XNameContainer::replaceByName().
  59  </p>
  60
  61  <p>Otherwise new elements have to be constructed to match the type
  62  prescribed by the element template of this set. Such elements can be created
  63  using interfaces com::sun::star::lang::XSingleServiceFactory
  64  and, if supported, com::sun::star::lang::XMultiServiceFactory.
  65  </p>
  66
  67  <p>Objects to be inserted must not be contained in any set at the time of
  68  insertion. com::sun::star::container::XChild::getParent()
  69  must return `NULL`. If a name had been assigned to the object prior to insertion
  70  (using com::sun::star::container::XNamed::setName()
  71  or by other means), this name is ignored and will be lost.
  72  After insertion the name of the object is the name that was used as argument
  73  to com::sun::star::container::XNameContainer::insertByName()
  74  or com::sun::star::container::XNameContainer::replaceByName().
  75 </p>
  76
  77
  78  <p>Objects that are removed using
  79  com::sun::star::container::XNameContainer::removeByName()
  80  or replaced using
  81  com::sun::star::container::XNameContainer::replaceByName()
  82  remain valid and can be reinserted into a set supporting the same template and
  83  even under a different name.
  84  </p>
  85
  86  <p>An implementation need not support insertion of objects that were not
  87  obtained in one of the ways described above. If it does, the implementation
  88  must reject elements that do not have the correct structure as described
  89  by the template.
  90  </p>
  91 */
  92     interface com::sun::star::container::XNameContainer;
  93
  94 /** allows creating an object that can be inserted into this set. [conditional]
  95
  96  <p>This interface shall be implemented by an implementation,
  97  if and only if the element type of the set, as returned by
  98  com::sun::star::container::XElementAccess::getElementType(),
  99  is an object type, such as an interface.
 100  </p>
 101
 102  <p>Using com::sun::star::lang::XSingleServiceFactory::createInstance()
 103  an instance of the element template of this set is created. If the set
 104  supports multiple templates or variations of the basic template, a default
 105  variant of the basic template is instantiated. If an implementation supports
 106  variations, they may be specified by passing arguments to
 107  com::sun::star::lang::XSingleServiceFactory::createInstanceWithArguments().
 108  There are no predefined arguments for all versions of this service.
 109  </p>
 110
 111  <p>The object created is not contained in the set and does not have a name yet.
 112  It may subsequently be inserted into the set and named using
 113  com::sun::star::container::XNameContainer::insertByName()
 114  or
 115  com::sun::star::container::XNameContainer::replaceByName().
 116  </p>
 117 */
 118     [optional] interface com::sun::star::lang::XSingleServiceFactory;
 119
 120 /** allows creating various objects that can be inserted into this set. [optional]
 121
 122  <p>This interface may be implemented by an implementation of
 123  service SetUpdate to support creating elements from other than
 124  the basic element template. An example of this would be an
 125  implementation that supports inheritance, allowing the use of
 126  templates derived from the basic template by extension.
 127  </p>
 128
 129  <p>This interface may only be implemented if the element type of the set
 130  (as returned by
 131  com::sun::star::container::XElementAccess::getElementType())
 132  is an object type, such as an interface. An implementation should also implement
 133  interface XTemplateContainer which is optional in this service.
 134  </p>
 135
 136  <p>The service identifier argument passed
 137  to com::sun::star::lang::XMultiServiceFactory::createInstance()
 138  or com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
 139  names the template to be instantiated or otherwise identifies the structure
 140  to be built. The implementation must at least support using the template
 141  name obtained from XTemplateContainer::getElementTemplateName()
 142  as a service identifier, in which case the result shall be the same as if
 143  the corresponding member of com::sun::star::lang::XSingleServiceFactory
 144  had been called.
 145  </p>
 146
 147 */
 148     [optional] interface com::sun::star::lang::XMultiServiceFactory;
 149
 150 };
 151
 152
 153 }; }; }; };
 154
 155 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */