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