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 paths
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	/** gets the value of the property with the specified nested name.
137
138		@returns
139				the value of the property with the specified nested name.
140
141		@param  aHierarchicalPropertyName
142				This parameter specifies the name of the property.
143
144		@throws UnknownPropertyException
145				if the property does not exist.
146
147		@throws com::sun::star::uno::lang::IllegalArgumentException
148				if <var>aHierarchicalPropertyName</var> is not a well-formed
149				nested name for this hierarchy.
150				An implementation is not required to detect this
151				condition.
152
153		@throws com::sun::star::lang::WrappedTargetException
154				if the implementation has an internal reason for the exception.
155				In this case the original exception is wrapped into that
156				<type scope="com::sun::star::lang">WrappedTargetException</type>.
157
158		@see XPropertySet::getPropertyValue
159	 */
160	any getHierarchicalPropertyValue( [in] string aHierarchicalPropertyName )
161			raises( com::sun::star::beans::UnknownPropertyException,
162					com::sun::star::lang::IllegalArgumentException,
163					com::sun::star::lang::WrappedTargetException );
164
165	//-------------------------------------------------------------------------
166
167};
168
169//=============================================================================
170
171}; }; }; };
172
173#endif
174