/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0 .
 */
#ifndef __com_sun_star_configuration_HierarchyAccess_idl__
#define __com_sun_star_configuration_HierarchyAccess_idl__

#include <com/sun/star/container/XNameAccess.idl>
#include <com/sun/star/container/XHierarchicalNameAccess.idl>
#include <com/sun/star/container/XContainer.idl>
#include <com/sun/star/beans/XExactName.idl>
#include <com/sun/star/beans/XPropertySetInfo.idl>
#include <com/sun/star/beans/XPropertyState.idl>
#include <com/sun/star/beans/XMultiPropertyStates.idl>


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 HierarchyElement, which concerns the complementary role
 of being accessible as an element of the hierarchy.
 </p>
*/
published service HierarchyAccess
{
/** allows access to immediate children of this node.

 <p>com::sun::star::container::XNameAccess::getByName()
 returns an `any` 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>com::sun::star::container::XHierarchicalNameAccess::getByHierarchicalName()
 returns an `any` 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
 com::sun::star::container::XNameAccess,
 com::sun::star::container::XHierarchicalNameAccess,
 com::sun::star::beans::XPropertySet 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 hierarchical
 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 com::sun::star::beans::PropertyAttribute
 values or if the same information is available by other means,
 e.g. if the implementation supports
 com::sun::star::beans::XPropertySet::getPropertySetInfo().
 </p>

 <p>If a child of this node is an object that implements
 com::sun::star::beans::XProperty, then this implementation
 returns the same com::sun::star::beans::Property 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
 com::sun::star::beans::PropertyAttribute::MAYBEDEFAULT),
 they should implement
 com::sun::star::beans::XPropertyWithState, in which case
 the com::sun::star::beans::PropertyState 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
 com::sun::star::beans::PropertyAttribute::MAYBEDEFAULT),
 they should implement
 com::sun::star::beans::XPropertyWithState, in which case
 the com::sun::star::beans::PropertyState 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

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */