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_frame_XUIElementFactoryRegistration_idl__
29#define __com_sun_star_frame_XUIElementFactoryRegistration_idl__
30
31#ifndef __com_sun_star_uno_XInterface_idl__
32#include <com/sun/star/uno/XInterface.idl>
33#endif
34
35#ifndef __com_sun_star_ui_XUIElementFactory_idl__
36#include <com/sun/star/ui/XUIElementFactory.idl>
37#endif
38
39#ifndef __com_sun_star_container_ElementExistException_idl__
40#include <com/sun/star/container/ElementExistException.idl>
41#endif
42
43#ifndef __com_sun_star_container_NoSuchElementException_idl__
44#include <com/sun/star/container/NoSuchElementException.idl>
45#endif
46
47#ifndef __com_sun_star_beans_PropertyValue_idl__
48#include <com/sun/star/beans/PropertyValue.idl>
49#endif
50
51//=============================================================================
52
53module com { module sun { module star { module ui {
54
55//=============================================================================
56
57/** is used to query, register and deregister user interface element factories.
58
59    <p>
60    A user interface element factory is registered for a set of three properties.
61    <ul>
62        <li><b>Type</b>a string that identifies a type of a user interface element.</li>
63        <li><b>Name</b>a string that identifies a single user interface element within a type class.</li>
64        <li><b>Module</b>a string that identifies a single module of OpenOffice.</li>
65    <ul>
66    A combination of these three property values can uniquely identifiy every user interface
67    element within OpenOffice.
68
69    Currently the following user interface element types are defined:
70    <ul>
71        <li><b>menubar</b></li>
72        <li><b>popupmenu</b></li>
73        <li><b>toolbar</b></li>
74        <li><b>statusbar</b></li>
75        <li><b>floater</b></li>
76    </ul>
77    </p>
78
79    @since OOo 2.0
80 */
81
82interface XUIElementFactoryRegistration : com::sun::star::uno::XInterface
83{
84    /** function to retrieve a list of all registered user interface element factories
85
86        @returns
87            a sequence of sequence of propert values which describe every registered
88            user interface element factory.<br/>
89
90            The following properties are defined:
91            <ul>
92                <li><b>Type</b>a string property that identifies the type of the user interface
93                element which this factory can create.</li>
94                <li><b>Name</b>an optional string property which identifies a single user interface
95                element within a type class which this factory can create. If this property is not
96                returned, the factory is a generic factory for all user interface elements of the
97                same type.</li>
98                <li><b>Module</b>an optional string property that specifies to which module this factory is
99                bound to. If this property is not returned, the factory is a generic factory.</li>
100            </ul>
101    */
102    sequence< sequence< com::sun::star::beans::PropertyValue > > getRegisteredFactories();
103
104    /** function to retrieve a previously registered user interface element factory.
105
106        @returns
107            a reference to a registered user interface element factory if a factory has been
108            found. An empty reference when no factory has been found.
109            <b>The defined search order of factories must be from special to generic ones.</b>
110
111        @param ResourceURL
112            a resource URL which identifies a user interface element. A resource URL uses the
113            following syntax: "private:resource/$type/$name". It is only allowed to use ascii
114            characters for type and name.
115
116        @param ModuleName
117            an optional module identifier. This value can remain empty, if a generic factory is requested.
118            The module identifier can be retrieved from the <type scope="com::sun::star::frame">ModuleManager</type> service.
119    */
120    ::com::sun::star::ui::XUIElementFactory getFactory( [in] string ResourceURL, [in] string ModuleIdentifier );
121
122    /** function to register a user interface element factory.
123
124        @param aType
125            a string that identifies a type of a user interface element. Currently the following types
126            are supported:
127            <ul>
128                <li><b>menubar</b></li>
129                <li><b>toolbar</b></li>
130                <li><b>statusbar</b></li>
131            </ul>
132
133        @param aName
134            an optional name of a single user interface element. This name must be unique within a user
135            interface element type class. This value can remain empty if no special factory for a single
136            user interface element is needed.
137
138        @param aModuleIdentifier
139            an optional module identifier that can be used to register a factory only for a single module. This value
140            can remain empty if no special factory for a single module is needed. The module identifier can be retrieved
141            from the <type scope="com::sun::star::frame">ModuleManager</type> service.
142
143        @param aFactoryImplementationName
144            a UNO implementation name that can be used by an implementation to create a factory instance.
145    */
146    void registerFactory( [in] string aType, [in] string aName, [in] string aModuleIdentifier, [in] string aFactoryImplementationName ) raises (com::sun::star::container::ElementExistException);
147
148    /** function to remove a previously defined user interface element factory.
149
150        @param aType
151            a string that identifies a type of a user interface element. Currently the following types
152            are supported:
153            <ul>
154                <li><b>menubar</b></li>
155                <li><b>toolbar</b></li>
156                <li><b>statusbar</b></li>
157            </ul>
158
159        @param aName
160            an optional name of a single user interface element. This name must be unique within a user
161            interface element type class. This value can remain empty if no special factory for a single
162            user interface element should be deregistered.
163
164        @param aModuleName
165            an optional module name that can be used to deregister a factory only for a single module. This value
166            can remain empty if not a module based factory should be deregisted. The module identifier can be retrieved
167            from the <type scope="com::sun::star::frame">ModuleManager</type> service.
168
169        <p>
170        <b>Using this function can be very dangerous as other implementation with OpenOffice may not be able to  create their
171        user interface element anymore.
172        </b>
173        </p>
174    */
175    void deregisterFactory( [in] string aType, [in] string aName, [in] string aModuleIdentifier ) raises (com::sun::star::container::NoSuchElementException);
176};
177
178}; }; }; };
179
180//=============================================================================
181
182#endif
183