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

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