| blob | b194e91fa17691fd6b094059a8b2529a2f77c6c0 |
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /**
3 * This file is part of the LibreOffice project.
4 *
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8 *
9 * This file incorporates work covered by the following license notice:
10 *
11 * Licensed to the Apache Software Foundation (ASF) under one or more
12 * contributor license agreements. See the NOTICE file distributed
13 * with this work for additional information regarding copyright
14 * ownership. The ASF licenses this file to you under the Apache
15 * License, Version 2.0 (the "License"); you may not use this file
16 * except in compliance with the License. You may obtain a copy of
17 * the License at http://www.apache.org/licenses/LICENSE-2.0 .
18 */
19 #ifndef __com_sun_star_configuration_HierarchyAccess_idl__
20 #define __com_sun_star_configuration_HierarchyAccess_idl__
33 /** provides access to a hierarchy of descendant elements.
35 <p>Subnodes are accessed by their name. Values that are direct or indirect
36 descendants of this tree node can be retrieved. Non-value subnodes can be
37 navigated using container interfaces.
38 Other interfaces provide access to information about this node.
39 Changes to values in the subtree can be monitored by event listeners.
40 </p>
42 <p>Elements of this container that are not simple values
43 are similar containers themselves, thus (recursively) forming a
44 hierarchical tree.
45 </p>
47 <p>Implementations of this service usually also implement
48 service <type>HierarchyElement</type>, which concerns the complementary role
49 of being accessible as an element of the hierarchy.
50 </p>
51 */
52 published service HierarchyAccess
53 {
54 /** allows access to immediate children of this node.
56 <p><member scope="com::sun::star::container">XNameAccess::getByName()</member>
57 returns an <atom>any</atom> holding either a simple value or an interface
58 on another HierarchyAccess if the child is not a simple value.
59 </p>
60 */
63 /** allows access to all descendants of this node
65 <p><member scope="com::sun::star::container">XHierarchicalNameAccess::getByHierarchicalName()</member>
66 returns an <atom>any</atom> holding either a simple value or an interface
67 on another HierarchyAccess if the descendant is not a simple value.
68 </p>
69 */
72 /** allows attaching listeners to this node to monitor changes to immediate child nodes.
73 */
76 /** provides support for inexact names.
77 <p>Exact names can be obtained for simple or hierarchical names for use in
78 <type scope="com::sun::star::container">XNameAccess</type>,
79 <type scope="com::sun::star::container">XHierarchicalNameAccess</type>,
80 <type scope="com::sun::star::beans">XPropertySet</type> or
81 any other interfaces that allow access to or manipulation of subnodes
82 selected by name or hierarchical name.
83 </p>
84 <p>If an inexact name could be matched to either a simple or a hierarchical
85 name, the simple (immediate child) name is preferred.
86 </p>
87 */
90 /** provides information about immediate children of this node. [optional]
92 <p>This interface may be missing, if the hierarchy supports no traits that are
93 described by <type scope="com::sun::star::beans">PropertyAttribute</type>
94 values or if the same information is available by other means,
95 e.g. if the implementation supports
96 <member scope="com::sun::star::beans">XPropertySet::getPropertySetInfo()</member>.
97 </p>
99 <p>If a child of this node is an object that implements
100 <type scope="com::sun::star::beans">XProperty</type>, then this implementation
101 returns the same <type scope="com::sun::star::beans">Property</type> for that
102 child as the child itself.
103 </p>
104 */
107 /** provides access to the state of child elements of an implementation. [optional]
109 <p>This interface may be missing if the hierarchy (or a hierarchy fragment
110 that contains this implementation as element) does not support default values or
111 if the node does not support accessing the default state of individual children.
112 </p>
114 <p>If elements that are not simple values, but objects themselves, support
115 a default state (as indicated by
116 <const scope="com::sun::star::beans">PropertyAttribute::MAYBEDEFAULT</const>),
117 they should implement
118 <type scope="com::sun::star::beans">XPropertyWithState</type>, in which case
119 the <type scope="com::sun::star::beans">PropertyState</type> applies to all
120 their children and recursively to all descendants.
121 </p>
123 <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
124 attempts to change property states will fail.
125 </p>
126 */
129 /** provides access to the states of multiple child elements of
130 an implementation. [optional]
132 <p>This interface may be missing if the hierarchy (or a hierarchy fragment
133 that contains this implementation as element) does not support default values
134 if the node does not support accessing the default state of individual children.
135 </p>
137 <p>If elements that are not simple values, but objects themselves, support
138 a default state (as indicated by
139 <const scope="com::sun::star::beans">PropertyAttribute::MAYBEDEFAULT</const>),
140 they should implement
141 <type scope="com::sun::star::beans">XPropertyWithState</type>, in which case
142 the <type scope="com::sun::star::beans">PropertyState</type> applies to all
143 their children and recursively to all descendants.
144 </p>
146 <p>If an implementation is part of a <em>read-only</em> view of the hierarchy,
147 attempts to change property states will fail.
148 </p>
149 */
151 };
154 }; }; }; };
156 #endif
158 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */