/*************************************************************************
 *
 *  $RCSfile: HierarchyAccess.idl,v $
 *
 *  $Revision: 1.6 $
 *
 *  last change: $Author: rt $ $Date: 2003/04/17 14:12:02 $
 *
 *  The Contents of this file are made available subject to the terms of
 *  either of the following licenses
 *
 *         - GNU Lesser General Public License Version 2.1
 *         - Sun Industry Standards Source License Version 1.1
 *
 *  Sun Microsystems Inc., October, 2000
 *
 *  GNU Lesser General Public License Version 2.1
 *  =============================================
 *  Copyright 2000 by Sun Microsystems, Inc.
 *  901 San Antonio Road, Palo Alto, CA 94303, USA
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License version 2.1, as published by the Free Software Foundation.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 *  MA  02111-1307  USA
 *
 *
 *  Sun Industry Standards Source License Version 1.1
 *  =================================================
 *  The contents of this file are subject to the Sun Industry Standards
 *  Source License Version 1.1 (the "License"); You may not use this file
 *  except in compliance with the License. You may obtain a copy of the
 *  License at http://www.openoffice.org/license.html.
 *
 *  Software provided under this License is provided on an "AS IS" basis,
 *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
 *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
 *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
 *  See the License for the specific provisions governing your rights and
 *  obligations concerning the Software.
 *
 *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
 *
 *  Copyright: 2000 by Sun Microsystems, Inc.
 *
 *  All Rights Reserved.
 *
 *  Contributor(s): _______________________________________
 *
 *
 ************************************************************************/
#ifndef __com_sun_star_configuration_HierarchyAccess_idl__
#define __com_sun_star_configuration_HierarchyAccess_idl__

#ifndef __com_sun_star_container_XNameAccess_idl__
#include <com/sun/star/container/XNameAccess.idl>
#endif

#ifndef __com_sun_star_container_XHierarchicalNameAccess_idl__
#include <com/sun/star/container/XHierarchicalNameAccess.idl>
#endif

#ifndef __com_sun_star_container_XContainer_idl__
#include <com/sun/star/container/XContainer.idl>
#endif

#ifndef __com_sun_star_beans_XExactName_idl__
#include <com/sun/star/beans/XExactName.idl>
#endif

#ifndef __com_sun_star_beans_XPropertySetInfo_idl__
#include <com/sun/star/beans/XPropertySetInfo.idl>
#endif

#ifndef __com_sun_star_beans_XPropertyState_idl__
#include <com/sun/star/beans/XPropertyState.idl>
#endif

#ifndef __com_sun_star_beans_XMultiPropertyState_idl__
#include <com/sun/star/beans/XMultiPropertyStates.idl>
#endif

//=============================================================================

module com { module sun { module star { module configuration { 

//=============================================================================
/** provides access to a hierarchy of descendant elements.

 <p>Subnodes are accessed by their name. Values that are direct or indirect 
 descendants of this tree node can be retrieved. Non-value subnodes can be 
 navigated using container interfaces.
 Other interfaces provide access to information about this node.
 Changes to values in the subtree can be monitored by event listeners.
 </p>

 <p>Elements of this container that are not simple values
 are similar containers themselves, thus (recursively) forming a
 hierarchical tree.
 </p>

 <p>Implementations of this service usually also implement
 service <type>HierarchyElement</type>, which concerns the complementary role
 of being accessible as an element of the hierarchy.
 </p>
*/
service HierarchyAccess
{
/** allows access to immediate children of this node.

 <p><member scope="com::sun::star::container">XNameAccess::getByName()</member>
 returns an <atom>any</atom> holding either a simple value or an interface
 on another HierarchyAccess if the child is not a simple value.
 </p>
*/
	interface com::sun::star::container::XNameAccess;

/** allows access to all descendants of this node 

 <p><member scope="com::sun::star::container">XHierarchicalNameAccess::getByHierarchicalName()</member>
 returns an <atom>any</atom> holding either a simple value or an interface
 on another HierarchyAccess if the descendant is not a simple value.
 </p>
*/
	interface com::sun::star::container::XHierarchicalNameAccess;

/** allows attaching listeners to this node to monitor changes to immediate child nodes.
*/
	interface com::sun::star::container::XContainer;

/** provides support for inexact names.
 <p>Exact names can be obtained for simple or hierarchical names for use in
 <type scope="com::sun::star::container">XNameAccess</type>,
 <type scope="com::sun::star::container">XHierarchicalNameAccess</type>,
 <type scope="com::sun::star::beans">XPropertySet</type> or
 any other interfaces that allow access to or manipulation of subnodes 
 selected by name or hierarchical name. 
 </p>
 <p>If an inexact name could be matched to either a simple or a hierachical 
 name, the simple (immediate child) name is preferred.
 </p>
*/
	interface com::sun::star::beans::XExactName;

/** provides information about immediate children of this node. [optional]

 <p>This interface may be missing, if the hierarchy supports no traits that are
 described by <type scope="com::sun::star::beans">PropertyAttribute</type>
 values or if the same information is available by other means, 
 e.g. if the implementation supports 
 <member scope="com::sun::star::beans">XPropertySet::getPropertySetInfo()</member>.
 </p>

 <p>If a child of this node is an object that implements 
 <type scope="com::sun::star::beans">XProperty</type>, then this implementation  
 returns the same <type scope="com::sun::star::beans">Property</type> for that
 child as the child itself.
 </p>
*/
	[optional] interface com::sun::star::beans::XPropertySetInfo;

/** provides access to the state of child elements of an implementation. [optional]
 
 <p>This interface may be missing if the hierarchy (or a hierarchy fragment
 that contains this implementation as element) does not support default values or
 if the node does not support accessing the default state of individual children.
 </p>
 
 <p>If elements that are not simple values, but objects themselves, support
 a default state (as indicated by 
 <const scope="com::sun::star::beans">PropertyAttribute::MAYBEDEFAULT</const>),
 they should implement 
 <type scope="com::sun::star::beans">XPropertyWithState</type>, in which case
 the <type scope="com::sun::star::beans">PropertyState</type> applies to all
 their children and recursively to all descendants. 
 </p>

 <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
 attempts to change property states will fail.
 </p>
*/
	[optional] interface com::sun::star::beans::XPropertyState;

/** provides access to the states of multiple child elements of 
 an implementation. [optional]
 
 <p>This interface may be missing if the hierarchy (or a hierarchy fragment
 that contains this implementation as element) does not support default values 
 if the node does not support accessing the default state of individual children.
 </p>
 
 <p>If elements that are not simple values, but objects themselves, support
 a default state (as indicated by 
 <const scope="com::sun::star::beans">PropertyAttribute::MAYBEDEFAULT</const>),
 they should implement 
 <type scope="com::sun::star::beans">XPropertyWithState</type>, in which case
 the <type scope="com::sun::star::beans">PropertyState</type> applies to all
 their children and recursively to all descendants. 
 </p>

 <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
 attempts to change property states will fail.
 </p>
*/
	[optional] interface com::sun::star::beans::XMultiPropertyStates;
};

//=============================================================================

}; }; }; }; 

#endif
