1/************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23#ifndef __com_sun_star_configuration_AccessRootElement_idl__ 24#define __com_sun_star_configuration_AccessRootElement_idl__ 25 26#ifndef __com_sun_star_configuration_HierarchyElement_idl__ 27#include <com/sun/star/configuration/HierarchyElement.idl> 28#endif 29 30#ifndef __com_sun_star_lang_XComponent_idl__ 31#include <com/sun/star/lang/XComponent.idl> 32#endif 33 34#ifndef __com_sun_star_lang_XLocalizable_idl__ 35#include <com/sun/star/lang/XLocalizable.idl> 36#endif 37 38#ifndef __com_sun_star_util_XChangesNotifier_idl__ 39#include <com/sun/star/util/XChangesNotifier.idl> 40#endif 41 42//============================================================================= 43 44module com { module sun { module star { module configuration { 45 46//============================================================================= 47/** provides information about the root element of a hierarchy and 48 about the hierarchy as a whole. 49 50 <p>Provides information about the element and the whole hierarchy. 51 Allows controlling the lifetime of the hierarchy. 52 Allows observing changes in the hierarchy as a whole. 53 </p> 54 55 <p>When access to a hierarchy is first obtained from a factory or provider, 56 this is the initial object that is created by the factory. 57 It represents the <em>root</em> of the accessible part of the hierarchy. 58 </p> 59 60 <p><em><strong>NOTE:</strong> In this description 'hierarchy' may actually 61 designate a part or fragment of a larger hierarchy. It is that part that is 62 rooted in the element represented by an implementation of this service 63 and that is accessible starting from this element.</em> 64 </p> 65 66 <p>Generally it is not possible to navigate the parent or siblings, if any, 67 of this element, so <type scope="com::sun::star::container">XChild</type> is 68 not supported. 69 </p> 70 71 @see com::sun::star::configuration::UpdateRootElement 72 Implementations that support modifying data in the hierarchy 73 implement service UpdateRootElement. 74 75 @see com::sun::star::configuration::SetElement 76 A complementary service, for children of a dynamic homogeneous container. 77 78 @see com::sun::star::configuration::GroupElement 79 A complementary service, for children of a static heterogeneous collection. 80 81 @see com::sun::star::configuration::ConfigurationProvider 82 Objects provided by a <type>ConfigurationProvider</type> implement this service. 83*/ 84published service AccessRootElement 85{ 86/** the basic service for accessing information about an element in the 87 hierarchy. 88*/ 89 service HierarchyElement; 90 91/** allows controlling or observing the lifetime of the whole hierarchy. 92 93 <p>The owner of the hierarchy may dispose of this object 94 using <member scope="com::sun::star::lang">XComponent::dispose()</member>. 95 As this object owns its child elements and, recursively, the whole hierarchy, 96 any descendant elements obtained, directly or indirectly, from this object 97 will also be disposed. Disposing of the object does not affect a persistent 98 representation of the hierarchy. 99 </p> 100 101 <p>When an implementation is obtained from a factory or provider, ownership 102 of it is usually transferred to the client. See the documentation 103 of the particular provider or factory service for details. 104 </p> 105 106 <p>The provider of this object may still dispose of this object, when the 107 lifetime of the provider ends or if these objects represent 108 the root of only a fragment of an enclosing hierarchy and 109 this fragment is removed from the complete hierarchy by an outside source. 110 </p> 111 112 <p>Clients may register an <type scope="com::sun::star::lang">XEventListener</type> 113 to be notified when the object is disposed for either cause. 114 </p> 115*/ 116 interface com::sun::star::lang::XComponent; 117 118/** allows registering listeners that observe the whole hierarchy. 119 120 <p>A client can register an 121 <type scope="com::sun::star::util">XChangesListener</type>, 122 which will receive notifications for any changes within the 123 hierarchy (fragment) this object represents. 124 </p> 125 126 <p>An implementation will collect as many changes as possible into a single 127 <type scope="com::sun::star::util">ChangesEvent</type>. For Example: 128 </p> 129 130 <p> 131 If <member scope="com::sun::star::beans">XMultiPropertySet::setPropertyValues()</member> 132 or <member scope="com::sun::star::beans">XMultiHierarchicalPropertySet::setHierarchicalPropertyValues()</member> 133 is used on an element of the hierarchy to change multiple values within 134 the hierarchy, all changes will be notified with a single event. 135 </p> 136 137 <p>If an outside source uses 138 <member scope="com::sun::star::util">XChangesBatch::commitChanges()</member> 139 on an overlapping hierarchy access, all relevant changes will be notified 140 with a single event. 141 </p> 142 143 @ see UpdateRootElement 144 @ see com::sun::star::util::XChangesBatch 145*/ 146 interface com::sun::star::util::XChangesNotifier; 147 148/** provides access to the locale that applies to locale-dependent data 149 in this hierarchy. [optional] 150 151 <p>This interface may be missing if the implementation does not support 152 locale-dependent data in the hierarchy or if the (partial) hierarchy rooted 153 in this object does not contain any locale-dependent elements. 154 </p> 155 156 <p><em>Changing the locale is generally not supported.</em> If it is supported, 157 there is no guarantee that values already loaded into the hierarchy, or an 158 application cache, are refreshed to reflect the new locale. Use of 159 <member scope="com::sun::star::lang">XLocalizable::setLocale()</member> 160 is therefore not recommended. 161 </p> 162*/ 163 [optional] interface com::sun::star::lang::XLocalizable; 164 165}; 166 167//============================================================================= 168 169}; }; }; }; 170 171#endif 172 173