offapi/com/sun/star/configuration/HierarchyAccess.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 access to a hierarchy of descendant elements.
  24
  25  <p>Subnodes are accessed by their name. Values that are direct or indirect
  26  descendants of this tree node can be retrieved. Non-value subnodes can be
  27  navigated using container interfaces.
  28  Other interfaces provide access to information about this node.
  29  Changes to values in the subtree can be monitored by event listeners.
  30  </p>
  31
  32  <p>Elements of this container that are not simple values
  33  are similar containers themselves, thus (recursively) forming a
  34  hierarchical tree.
  35  </p>
  36
  37  <p>Implementations of this service usually also implement
  38  service HierarchyElement, which concerns the complementary role
  39  of being accessible as an element of the hierarchy.
  40  </p>
  41 */
  42 published service HierarchyAccess
  43 {
  44 /** allows access to immediate children of this node.
  45
  46  <p>com::sun::star::container::XNameAccess::getByName()
  47  returns an `any` holding either a simple value or an interface
  48  on another HierarchyAccess if the child is not a simple value.
  49  </p>
  50 */
  51     interface com::sun::star::container::XNameAccess;
  52
  53 /** allows access to all descendants of this node
  54
  55  <p>com::sun::star::container::XHierarchicalNameAccess::getByHierarchicalName()
  56  returns an `any` holding either a simple value or an interface
  57  on another HierarchyAccess if the descendant is not a simple value.
  58  </p>
  59 */
  60     interface com::sun::star::container::XHierarchicalNameAccess;
  61
  62 /** allows attaching listeners to this node to monitor changes to immediate child nodes.
  63 */
  64     interface com::sun::star::container::XContainer;
  65
  66 /** provides support for inexact names.
  67  <p>Exact names can be obtained for simple or hierarchical names for use in
  68  com::sun::star::container::XNameAccess,
  69  com::sun::star::container::XHierarchicalNameAccess,
  70  com::sun::star::beans::XPropertySet or
  71  any other interfaces that allow access to or manipulation of subnodes
  72  selected by name or hierarchical name.
  73  </p>
  74  <p>If an inexact name could be matched to either a simple or a hierarchical
  75  name, the simple (immediate child) name is preferred.
  76  </p>
  77 */
  78     interface com::sun::star::beans::XExactName;
  79
  80 /** provides information about immediate children of this node. [optional]
  81
  82  <p>This interface may be missing, if the hierarchy supports no traits that are
  83  described by com::sun::star::beans::PropertyAttribute
  84  values or if the same information is available by other means,
  85  e.g. if the implementation supports
  86  com::sun::star::beans::XPropertySet::getPropertySetInfo().
  87  </p>
  88
  89  <p>If a child of this node is an object that implements
  90  com::sun::star::beans::XProperty, then this implementation
  91  returns the same com::sun::star::beans::Property for that
  92  child as the child itself.
  93  </p>
  94 */
  95     [optional] interface com::sun::star::beans::XPropertySetInfo;
  96
  97 /** provides access to the state of child elements of an implementation. [optional]
  98
  99  <p>This interface may be missing if the hierarchy (or a hierarchy fragment
 100  that contains this implementation as element) does not support default values or
 101  if the node does not support accessing the default state of individual children.
 102  </p>
 103
 104  <p>If elements that are not simple values, but objects themselves, support
 105  a default state (as indicated by
 106  com::sun::star::beans::PropertyAttribute::MAYBEDEFAULT),
 107  they should implement
 108  com::sun::star::beans::XPropertyWithState, in which case
 109  the com::sun::star::beans::PropertyState applies to all
 110  their children and recursively to all descendants.
 111  </p>
 112
 113  <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
 114  attempts to change property states will fail.
 115  </p>
 116 */
 117     [optional] interface com::sun::star::beans::XPropertyState;
 118
 119 /** provides access to the states of multiple child elements of
 120  an implementation. [optional]
 121
 122  <p>This interface may be missing if the hierarchy (or a hierarchy fragment
 123  that contains this implementation as element) does not support default values
 124  if the node does not support accessing the default state of individual children.
 125  </p>
 126
 127  <p>If elements that are not simple values, but objects themselves, support
 128  a default state (as indicated by
 129  com::sun::star::beans::PropertyAttribute::MAYBEDEFAULT),
 130  they should implement
 131  com::sun::star::beans::XPropertyWithState, in which case
 132  the com::sun::star::beans::PropertyState applies to all
 133  their children and recursively to all descendants.
 134  </p>
 135
 136  <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
 137  attempts to change property states will fail.
 138  </p>
 139 */
 140     [optional] interface com::sun::star::beans::XMultiPropertyStates;
 141 };
 142
 143
 144 }; }; }; };
 145
 146 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */