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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*************************************************************************
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   6  * Copyright 2000, 2010 Oracle and/or its affiliates.
   7  *
   8  * OpenOffice.org - a multi-platform office productivity suite
   9  *
  10  * This file is part of OpenOffice.org.
  11  *
  12  * OpenOffice.org is free software: you can redistribute it and/or modify
  13  * it under the terms of the GNU Lesser General Public License version 3
  14  * only, as published by the Free Software Foundation.
  15  *
  16  * OpenOffice.org is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU Lesser General Public License version 3 for more details
  20  * (a copy is included in the LICENSE file that accompanied this code).
  21  *
  22  * You should have received a copy of the GNU Lesser General Public License
  23  * version 3 along with OpenOffice.org.  If not, see
  24  * <http://www.openoffice.org/license.html>
  25  * for a copy of the LGPLv3 License.
  26  *
  27  ************************************************************************/
  28 #ifndef __com_sun_star_configuration_HierarchyAccess_idl__
  29 #define __com_sun_star_configuration_HierarchyAccess_idl__
  30
  31 #include <com/sun/star/container/XNameAccess.idl>
  32 #include <com/sun/star/container/XHierarchicalNameAccess.idl>
  33 #include <com/sun/star/container/XContainer.idl>
  34 #include <com/sun/star/beans/XExactName.idl>
  35 #include <com/sun/star/beans/XPropertySetInfo.idl>
  36 #include <com/sun/star/beans/XPropertyState.idl>
  37 #include <com/sun/star/beans/XMultiPropertyStates.idl>
  38
  39 //=============================================================================
  40
  41 module com { module sun { module star { module configuration {
  42
  43 //=============================================================================
  44 /** provides access to a hierarchy of descendant elements.
  45
  46  <p>Subnodes are accessed by their name. Values that are direct or indirect
  47  descendants of this tree node can be retrieved. Non-value subnodes can be
  48  navigated using container interfaces.
  49  Other interfaces provide access to information about this node.
  50  Changes to values in the subtree can be monitored by event listeners.
  51  </p>
  52
  53  <p>Elements of this container that are not simple values
  54  are similar containers themselves, thus (recursively) forming a
  55  hierarchical tree.
  56  </p>
  57
  58  <p>Implementations of this service usually also implement
  59  service <type>HierarchyElement</type>, which concerns the complementary role
  60  of being accessible as an element of the hierarchy.
  61  </p>
  62 */
  63 published service HierarchyAccess
  64 {
  65 /** allows access to immediate children of this node.
  66
  67  <p><member scope="com::sun::star::container">XNameAccess::getByName()</member>
  68  returns an <atom>any</atom> holding either a simple value or an interface
  69  on another HierarchyAccess if the child is not a simple value.
  70  </p>
  71 */
  72     interface com::sun::star::container::XNameAccess;
  73
  74 /** allows access to all descendants of this node
  75
  76  <p><member scope="com::sun::star::container">XHierarchicalNameAccess::getByHierarchicalName()</member>
  77  returns an <atom>any</atom> holding either a simple value or an interface
  78  on another HierarchyAccess if the descendant is not a simple value.
  79  </p>
  80 */
  81     interface com::sun::star::container::XHierarchicalNameAccess;
  82
  83 /** allows attaching listeners to this node to monitor changes to immediate child nodes.
  84 */
  85     interface com::sun::star::container::XContainer;
  86
  87 /** provides support for inexact names.
  88  <p>Exact names can be obtained for simple or hierarchical names for use in
  89  <type scope="com::sun::star::container">XNameAccess</type>,
  90  <type scope="com::sun::star::container">XHierarchicalNameAccess</type>,
  91  <type scope="com::sun::star::beans">XPropertySet</type> or
  92  any other interfaces that allow access to or manipulation of subnodes
  93  selected by name or hierarchical name.
  94  </p>
  95  <p>If an inexact name could be matched to either a simple or a hierarchical
  96  name, the simple (immediate child) name is preferred.
  97  </p>
  98 */
  99     interface com::sun::star::beans::XExactName;
 100
 101 /** provides information about immediate children of this node. [optional]
 102
 103  <p>This interface may be missing, if the hierarchy supports no traits that are
 104  described by <type scope="com::sun::star::beans">PropertyAttribute</type>
 105  values or if the same information is available by other means,
 106  e.g. if the implementation supports
 107  <member scope="com::sun::star::beans">XPropertySet::getPropertySetInfo()</member>.
 108  </p>
 109
 110  <p>If a child of this node is an object that implements
 111  <type scope="com::sun::star::beans">XProperty</type>, then this implementation
 112  returns the same <type scope="com::sun::star::beans">Property</type> for that
 113  child as the child itself.
 114  </p>
 115 */
 116     [optional] interface com::sun::star::beans::XPropertySetInfo;
 117
 118 /** provides access to the state of child elements of an implementation. [optional]
 119
 120  <p>This interface may be missing if the hierarchy (or a hierarchy fragment
 121  that contains this implementation as element) does not support default values or
 122  if the node does not support accessing the default state of individual children.
 123  </p>
 124
 125  <p>If elements that are not simple values, but objects themselves, support
 126  a default state (as indicated by
 127  <const scope="com::sun::star::beans">PropertyAttribute::MAYBEDEFAULT</const>),
 128  they should implement
 129  <type scope="com::sun::star::beans">XPropertyWithState</type>, in which case
 130  the <type scope="com::sun::star::beans">PropertyState</type> applies to all
 131  their children and recursively to all descendants.
 132  </p>
 133
 134  <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
 135  attempts to change property states will fail.
 136  </p>
 137 */
 138     [optional] interface com::sun::star::beans::XPropertyState;
 139
 140 /** provides access to the states of multiple child elements of
 141  an implementation. [optional]
 142
 143  <p>This interface may be missing if the hierarchy (or a hierarchy fragment
 144  that contains this implementation as element) does not support default values
 145  if the node does not support accessing the default state of individual children.
 146  </p>
 147
 148  <p>If elements that are not simple values, but objects themselves, support
 149  a default state (as indicated by
 150  <const scope="com::sun::star::beans">PropertyAttribute::MAYBEDEFAULT</const>),
 151  they should implement
 152  <type scope="com::sun::star::beans">XPropertyWithState</type>, in which case
 153  the <type scope="com::sun::star::beans">PropertyState</type> applies to all
 154  their children and recursively to all descendants.
 155  </p>
 156
 157  <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
 158  attempts to change property states will fail.
 159  </p>
 160 */
 161     [optional] interface com::sun::star::beans::XMultiPropertyStates;
 162 };
 163
 164 //=============================================================================
 165
 166 }; }; }; };
 167
 168 #endif
 169
 170 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */