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