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
28#ifndef __com_sun_star_ui_XUIConfigurationManager_idl__
29#define __com_sun_star_ui_XUIConfigurationManager_idl__
30
31#ifndef __com_sun_star_container_XIndexContainer_idl__
32#include <com/sun/star/container/XIndexContainer.idl>
33#endif
34
35#ifndef __com_sun_star_container_XIndexAccess_idl__
36#include <com/sun/star/container/XIndexAccess.idl>
37#endif
38
39#ifndef __com_sun_star_beans_XPropertySet_idl__
40#include <com/sun/star/beans/XPropertySet.idl>
41#endif
42
43#ifndef __com_sun_star_beans_PropertyValue_idl__
44#include <com/sun/star/beans/PropertyValue.idl>
45#endif
46
47#ifndef __com_sun_star_ui_XUIConfigurationListener_idl__
48#include <com/sun/star/ui/XUIConfigurationListener.idl>
49#endif
50
51#ifndef __com_sun_star_container_ElementExistException_idl__
52#include <com/sun/star/container/ElementExistException.idl>
53#endif
54
55#ifndef __com_sun_star_container_NoSuchElementException_idl__
56#include <com/sun/star/container/NoSuchElementException.idl>
57#endif
58
59#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
60#include <com/sun/star/lang/IllegalArgumentException.idl>
61#endif
62
63#ifndef __com_sun_star_lang_IllegalAccessException_idl__
64#include <com/sun/star/lang/IllegalAccessException.idl>
65#endif
66
67module com { module sun { module star { module ui {
68
69/** specifies a user interface configuration manager interface which
70    controls the structure of all customizable user interface
71    elements.
72
73    @since OOo 2.0
74*/
75
76published interface XUIConfigurationManager : ::com::sun::star::uno::XInterface
77{
78    /** resets the configuration manager to the default user interface
79        configuration data.
80        <p>
81        This means that all user interface configuration data of the
82        instance will be removed. A module based user interface
83        configuration manager removes user defined elements, but set all
84        other elements back to default. It is not possible to remove
85        default elements from a module user interface configuration
86        manager.
87        </p>
88    */
89    void reset();
90
91    /** retrieves information about all user interface elements within
92        the user interface configuration manager.
93
94        @param ElementType
95            makes it possible to narrow the result set to only one type
96            of user interface elements. If all user interface element
97            types should be returned
98            <value scope=com::sun::star::ui>UIElementType::UNKNOWN</value>
99            must be provided.
100
101        @return
102            returns all user interface elements within the user interface
103            configuration manager that meet the given ElementType
104            specification. <p>The following
105            <type scope="com::sun::star::beans">PropertyValue</type> entries
106            are defined inside the sequence for every user interface element.
107            <ul>
108                <li><b>ResourceURL<b/>specifies the unique resource URL for
109                the user interface element.</li>
110                <li><b>UIName<b/>specifies the user interface name for the
111                user interface element. Not all user interface elements have
112                set UIName. At least menubars do not.</li>
113            </ul>
114            <p>
115
116        @see UIElementType
117    */
118    sequence< sequence< com::sun::star::beans::PropertyValue > > getUIElementsInfo( [in] short ElementType ) raises ( com::sun::star::lang::IllegalArgumentException );
119
120    /** creates an empty settings data container.
121
122        @return
123            an empty user interface element settings data container, which
124            implements <type>UIElementSettings</type>.
125    */
126    ::com::sun::star::container::XIndexContainer createSettings();
127
128    /** determines if the settings of a user interface element is part the
129        user interface configuration manager.
130
131        @param ResourceURL
132            a resource URL which identifies the user interface element. A
133            resourcce URL must meet the following syntax:
134            "private:resource/$type/$name. It is only allowed to use ascii
135            characters for type and name.
136
137        @return
138            <TRUE/> if settings have been found, otherwise <FALSE/>.
139    */
140    boolean hasSettings( [in] string ResourceURL ) raises ( com::sun::star::lang::IllegalArgumentException );
141
142    /** retrieves the settings of a user interface element.
143
144        @param ResourceURL
145            a resource URL which identifies the user interface element. A
146            resourcce URL must meet the following syntax:
147            "private:resource/$type/$name. It is only allowed to use ascii
148            characters for type and name.
149
150        @param bWriteable
151            must be <TRUE/> if the retrieved settings should be a writeable.
152            Otherwise <FALSE/> should be provided to get a shareable reference
153            to the settings data.
154
155        @return
156            settings data of an existing user interface element, which
157            implements <type>UIElementSettings</type>. If the settings data
158            cannot be found a
159            <type scope="com::sun::star::container">NoSuchElementException</type>
160            is thrown.  If the <member>ResourceURL</member> is not valid or
161            describes an unknown type a
162            <type scope="com::sun::star::lang">IllegalArgumentException</type>
163            is thrown.
164    */
165    ::com::sun::star::container::XIndexAccess getSettings( [in] string ResourceURL, [in] boolean bWriteable ) raises ( com::sun::star::container::NoSuchElementException, com::sun::star::lang::IllegalArgumentException );
166
167    /** replaces the settings of a user interface element with new settings.
168
169        @param ResourceURL
170            a resource URL which identifies the user interface element to
171            be replaced. If no element with the given resource URL exists a
172            <type scope="com::sun::star::container">NoSuchElementException</type>
173            is thrown.
174
175        @param aNewData
176            the new settings data of an existing user interface element, which
177            implements <type>UIElementSettings</type>.
178
179        <p>
180        If the settings data cannot be found a
181        <type scope="com::sun::star::container">NoSuchElementException</type>
182        is thrown. If the <member>ResourceURL</member> is not valid or describes
183        an unknown type a
184        <type scope="com::sun::star::lang">IllegalArgumentException</type>
185        is thrown. If the configuration manager is read-only a
186        <type scope="com::sun::star::lang">IllegalAccessException</type> is
187        thrown.
188        </p>
189    */
190    void replaceSettings( [in] string ResourceURL, [in] ::com::sun::star::container::XIndexAccess aNewData ) raises ( com::sun::star::container::NoSuchElementException, com::sun::star::lang::IllegalArgumentException, com::sun::star::lang::IllegalAccessException );
191
192    /** removes the settings of an existing user interface element.
193
194        @param ResourceURL
195            a resource URL which identifies the user interface element settings
196            to be removed.
197
198        <p>
199        If the settings data cannot be found a
200        <type scope="com::sun::star::container">NoSuchElementException</type> is
201        thrown. If the <member>ResourceURL</member> is not valid or describes an
202        unknown type a <type scope="com::sun::star::lang">IllegalArgumentException</type>
203        is thrown. If the configuration manager is read-only a
204        <type scope="com::sun::star::lang">IllegalAccessException</type> is thrown.
205        </p>
206    */
207    void removeSettings( [in] string ResourceURL ) raises ( com::sun::star::container::NoSuchElementException, com::sun::star::lang::IllegalArgumentException, com::sun::star::lang::IllegalAccessException );
208
209    /** inserts the settings of a new user interface element.
210
211        @param ResourceURL
212            a resource URL which identifies the new user interface element.
213
214        @param aNewData
215            the settings data of the new user interface element, which implements
216            <type>UIElementSettings</type>.
217
218        <p>
219        If the settings data is already present a
220        <type scope="com::sun::star::container">ElementExistException</type>
221        is thrown. If the <member>ResourceURL</member> is not valid or describes
222        an unknown type a <type scope="com::sun::star::lang">IllegalArgumentException</type>
223        is thrown. If the configuration manager is read-only a
224        <type scope="com::sun::star::lang">IllegalAccessException</type> is thrown.
225        </p>
226    */
227    void insertSettings( [in] string NewResourceURL, [in] ::com::sun::star::container::XIndexAccess aNewData ) raises ( com::sun::star::container::ElementExistException, com::sun::star::lang::IllegalArgumentException, com::sun::star::lang::IllegalAccessException );
228
229    /** retrieves the image manager from the user interface configuration
230        manager.
231
232        <p>
233        Every user interface configuration manager has one image manager
234        instance which controls all images of a module or document.
235        </p>
236
237        @return
238            the image manager of the user interface configuration manager.
239    */
240    com::sun::star::uno::XInterface getImageManager();
241
242    /** retrieves the keyboard short cut manager from the user interface
243        configuration manager.
244
245        <p>
246        Every user interface configuration manager has one keyboard short cut
247        manager instance which controls all short cuts of a module or document.
248        </p>
249
250        @return
251            the short cut manager of the user interface configuration manager.
252    */
253    com::sun::star::uno::XInterface getShortCutManager();
254
255    /** retrieves the events manager from the user interface configuration manager.
256
257        <p>
258        Every user interface configuration manager has one events manager
259        instance which controls the mapping of events to script URLs of a module
260        or document.
261        </p>
262
263        @return
264            the events manager of the user interface configuration
265            manager, if one exists.
266    */
267    com::sun::star::uno::XInterface getEventsManager();
268};
269
270//=============================================================================
271
272}; }; }; };
273
274#endif
275