1 files changed, 155 insertions, 0 deletions
diff --git a/offapi/com/sun/star/configuration/AccessRootElement.idl b/offapi/com/sun/star/configuration/AccessRootElement.idl
new file mode 100644
index 000000000..0c3900342
--- /dev/null
+++ b/offapi/com/sun/star/configuration/AccessRootElement.idl
@@ -0,0 +1,155 @@
+/* -*- 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_AccessRootElement_idl__
+#define __com_sun_star_configuration_AccessRootElement_idl__
+
+#include <com/sun/star/configuration/HierarchyElement.idl>
+#include <com/sun/star/lang/XComponent.idl>
+#include <com/sun/star/lang/XLocalizable.idl>
+#include <com/sun/star/util/XChangesNotifier.idl>
+
+
+module com { module sun { module star { module configuration {
+
+/** provides information about the root element of a hierarchy and
+    about the hierarchy as a whole.
+
+ <p>Provides information about the element and the whole hierarchy.
+ Allows controlling the lifetime of the hierarchy.
+ Allows observing changes in the hierarchy as a whole.
+ </p>
+
+ <p>When access to a hierarchy is first obtained from a factory or provider,
+ this is the initial object that is created by the factory.
+ It represents the <em>root</em> of the accessible part of the hierarchy.
+ </p>
+
+ <p><em><strong>NOTE:</strong> In this description "hierarchy" may actually
+ designate a part or fragment of a larger hierarchy. It is that part that is
+ rooted in the element represented by an implementation of this service
+ and that is accessible starting from this element.</em>
+ </p>
+
+ <p>Generally it is not possible to navigate the parent or siblings, if any,
+ of this element, so com::sun::star::container::XChild is
+ not supported.
+ </p>
+
+ @see com::sun::star::configuration::UpdateRootElement
+    Implementations that support modifying data in the hierarchy
+    implement service UpdateRootElement.
+
+ @see com::sun::star::configuration::SetElement
+    A complementary service, for children of a dynamic homogeneous container.
+
+ @see com::sun::star::configuration::GroupElement
+    A complementary service, for children of a static heterogeneous collection.
+
+ @see com::sun::star::configuration::ConfigurationProvider
+    Objects provided by a ConfigurationProvider implement this service.
+*/
+published service AccessRootElement
+{
+/** the basic service for accessing information about an element in the
+ hierarchy.
+*/
+    service HierarchyElement;
+
+/** allows controlling or observing the lifetime of the whole hierarchy.
+
+ <p>The owner of the hierarchy may dispose of this object
+ using com::sun::star::lang::XComponent::dispose().
+ As this object owns its child elements and, recursively, the whole hierarchy,
+ any descendant elements obtained, directly or indirectly, from this object
+ will also be disposed. Disposing of the object does not affect a persistent
+ representation of the hierarchy.
+ </p>
+
+ <p>When an implementation is obtained from a factory or provider, ownership
+ of it is usually transferred to the client. See the documentation
+ of the particular provider or factory service for details.
+ </p>
+
+ <p>The provider of this object may still dispose of this object, when the
+ lifetime of the provider ends or if these objects represent
+ the root of only a fragment of an enclosing hierarchy and
+ this fragment is removed from the complete hierarchy by an outside source.
+ </p>
+
+ <p>Clients may register a com::sun::star::lang::XEventListener
+ to be notified when the object is disposed for either cause.
+ </p>
+*/
+    interface com::sun::star::lang::XComponent;
+
+/** allows registering listeners that observe the whole hierarchy.
+
+ <p>A client can register an
+ com::sun::star::util::XChangesListener,
+ which will receive notifications for any changes within the
+ hierarchy (fragment) this object represents.
+ </p>
+
+ <p>An implementation will collect as many changes as possible into a single
+ com::sun::star::util::ChangesEvent. For Example:
+ </p>
+
+ <p>
+ If com::sun::star::beans::XMultiPropertySet::setPropertyValues()
+ or com::sun::star::beans::XMultiHierarchicalPropertySet::setHierarchicalPropertyValues()
+ is used on an element of the hierarchy to change multiple values within
+ the hierarchy, all changes will be notified with a single event.
+ </p>
+
+ <p>If an outside source uses
+ com::sun::star::util::XChangesBatch::commitChanges()
+ on an overlapping hierarchy access, all relevant changes will be notified
+ with a single event.
+ </p>
+
+ @see UpdateRootElement
+ @see com::sun::star::util::XChangesBatch
+*/
+    interface com::sun::star::util::XChangesNotifier;
+
+/** provides access to the locale that applies to locale-dependent data
+ in this hierarchy. [optional]
+
+ <p>This interface may be missing if the implementation does not support
+ locale-dependent data in the hierarchy or if the (partial) hierarchy rooted
+ in this object does not contain any locale-dependent elements.
+ </p>
+
+ <p><em>Changing the locale is generally not supported.</em> If it is supported,
+ there is no guarantee that values already loaded into the hierarchy, or an
+ application cache, are refreshed to reflect the new locale. Use of
+ com::sun::star::lang::XLocalizable::setLocale()
+ is therefore not recommended.
+ </p>
+*/
+    [optional] interface com::sun::star::lang::XLocalizable;
+
+};
+
+
+}; }; }; };
+
+#endif
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */