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