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_beans_XHierarchicalPropertySet_idl__
24#define __com_sun_star_beans_XHierarchicalPropertySet_idl__
25
26#ifndef __com_sun_star_uno_XInterface_idl__
27#include <com/sun/star/uno/XInterface.idl>
28#endif
29
30#ifndef __com_sun_star_beans_XHierarchicalPropertySetInfo_idl__
31#include <com/sun/star/beans/XHierarchicalPropertySetInfo.idl>
32#endif
33
34#ifndef __com_sun_star_beans_UnknownPropertyException_idl__
35#include <com/sun/star/beans/UnknownPropertyException.idl>
36#endif
37
38#ifndef __com_sun_star_beans_PropertyVetoException_idl__
39#include <com/sun/star/beans/PropertyVetoException.idl>
40#endif
41
42#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
43#include <com/sun/star/lang/IllegalArgumentException.idl>
44#endif
45
46#ifndef __com_sun_star_lang_WrappedTargetException_idl__
47#include <com/sun/star/lang/WrappedTargetException.idl>
48#endif
49
50
51//=============================================================================
52
53module com {  module sun {  module star {  module beans {
54
55//=============================================================================
56
57/** provides information about and access to the
58	a hierarchy of properties from an implementation.
59
60	<p> Usually an object that implements this interface
61		also implements <type>XPropertySet</type> and at
62		least some of the properties have subproperties.  </p>
63
64	<p> This interface allows direct access to subsubproperties, ...
65		up to an arbitrary nesting depth. Often the intermediate
66		elements of the hierarchy implement <type>XProperty</type>.  </p>
67
68	<p> Each implementation specifies how the
69		hierarchical property names, that are
70		used to access the elements of the hierarchy,
71		are formed.  </p>
72
73	<p> Commonly a notation similar to filesystem pathes
74		(separated by '/' slashes) or nested module names
75		(separated by dots '.' or '::') is used.  </p>
76
77 */
78published interface XHierarchicalPropertySet: com::sun::star::uno::XInterface
79{
80	//-------------------------------------------------------------------------
81
82	/** retrieve information about the hierarchy of properties
83
84		@returns
85				the <type>XHierarchicalPropertySetInfo</type> interface,
86				which describes the property hierarchy of the object which
87				supplies this interface.
88
89		@returns
90				<NULL/> if the implementation cannot or will
91				not provide information about the properties; otherwise the
92				interface <type>XHierarchicalPropertySetInfo</type> is returned.
93	 */
94	com::sun::star::beans::XHierarchicalPropertySetInfo
95				getHierarchicalPropertySetInfo();
96
97	//-------------------------------------------------------------------------
98
99	/** sets the value of the property with the specified nested name.
100
101		@param	aHierarchicalPropertyName
102				This parameter specifies the name of the property.
103
104		@param	aValue
105				This parameter specifies the new value for the property.
106
107		@throws UnknownPropertyException
108				if the property does not exist.
109
110		@throws PropertyVetoException
111				if the property is constrained and the change is vetoed by a
112				<type>XVetoableChangeListener</type>.
113
114		@throws com::sun::star::uno::lang::IllegalArgumentException
115				if <var>aValue</var> is not a legal value for this property or
116				if <var>aHierarchicalPropertyName</var> is not a well-formed
117				nested name for this hierarchy.
118				An implementation is not required to detect the latter condition.
119
120		@throws com::sun::star::lang::WrappedTargetException
121				if the implementation has an internal reason for the exception.
122				In this case the original exception is wrapped into that
123				<type scope="com::sun::star::lang">WrappedTargetException</type>.
124
125		@see XPropertySet::setPropertyValue
126	 */
127	void setHierarchicalPropertyValue( [in] string aHierarchicalPropertyName,
128			 [in] any aValue )
129			raises( com::sun::star::beans::UnknownPropertyException,
130					com::sun::star::beans::PropertyVetoException,
131					com::sun::star::lang::IllegalArgumentException,
132					com::sun::star::lang::WrappedTargetException );
133
134	//-------------------------------------------------------------------------
135
136	/** @returns
137				the value of the property with the specified nested name.
138
139		@param	aHierarchicalPropertyName
140				This parameter specifies the name of the property.
141
142		@throws UnknownPropertyException
143				if the property does not exist.
144
145		@throws com::sun::star::uno::lang::IllegalArgumentException
146				if <var>aHierarchicalPropertyName</var> is not a well-formed
147				nested name for this hierarchy.
148			   	An implementation is not required to detect this
149				condition.
150
151		@throws com::sun::star::lang::WrappedTargetException
152				if the implementation has an internal reason for the exception.
153				In this case the original exception is wrapped into that
154				<type scope="com::sun::star::lang">WrappedTargetException</type>.
155
156		@see XPropertySet::getPropertyValue
157	 */
158	any getHierarchicalPropertyValue( [in] string aHierarchicalPropertyName )
159			raises( com::sun::star::beans::UnknownPropertyException,
160					com::sun::star::lang::IllegalArgumentException,
161					com::sun::star::lang::WrappedTargetException );
162
163	//-------------------------------------------------------------------------
164
165};
166
167//=============================================================================
168
169}; }; }; };
170
171#endif
172