| /************************************************************** | |
| * | |
| * 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 | |
| * | |
| * Unless required by applicable law or agreed to in writing, | |
| * software distributed under the License is distributed on an | |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| * KIND, either express or implied. See the License for the | |
| * specific language governing permissions and limitations | |
| * under the License. | |
| * | |
| *************************************************************/ | |
| #ifndef __com_sun_star_configuration_AccessRootElement_idl__ | |
| #define __com_sun_star_configuration_AccessRootElement_idl__ | |
| #ifndef __com_sun_star_configuration_HierarchyElement_idl__ | |
| #include <com/sun/star/configuration/HierarchyElement.idl> | |
| #endif | |
| #ifndef __com_sun_star_lang_XComponent_idl__ | |
| #include <com/sun/star/lang/XComponent.idl> | |
| #endif | |
| #ifndef __com_sun_star_lang_XLocalizable_idl__ | |
| #include <com/sun/star/lang/XLocalizable.idl> | |
| #endif | |
| #ifndef __com_sun_star_util_XChangesNotifier_idl__ | |
| #include <com/sun/star/util/XChangesNotifier.idl> | |
| #endif | |
| //============================================================================= | |
| 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 <type scope="com::sun::star::container">XChild</type> 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 <type>ConfigurationProvider</type> 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 <member scope="com::sun::star::lang">XComponent::dispose()</member>. | |
| 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 an <type scope="com::sun::star::lang">XEventListener</type> | |
| 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 | |
| <type scope="com::sun::star::util">XChangesListener</type>, | |
| 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 | |
| <type scope="com::sun::star::util">ChangesEvent</type>. For Example: | |
| </p> | |
| <p> | |
| If <member scope="com::sun::star::beans">XMultiPropertySet::setPropertyValues()</member> | |
| or <member scope="com::sun::star::beans">XMultiHierarchicalPropertySet::setHierarchicalPropertyValues()</member> | |
| 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 | |
| <member scope="com::sun::star::util">XChangesBatch::commitChanges()</member> | |
| 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 | |
| <member scope="com::sun::star::lang">XLocalizable::setLocale()</member> | |
| is therefore not recommended. | |
| </p> | |
| */ | |
| [optional] interface com::sun::star::lang::XLocalizable; | |
| }; | |
| //============================================================================= | |
| }; }; }; }; | |
| #endif |