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_ui_XUIElementFactory_idl__
25#define __com_sun_star_ui_XUIElementFactory_idl__
26
27#ifndef __com_sun_star_ui_XUIElement_idl__
28#include <com/sun/star/ui/XUIElement.idl>
29#endif
30
31#ifndef __com_sun_star_container_NoSuchElementException_idl__
32#include <com/sun/star/container/NoSuchElementException.idl>
33#endif
34
35#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
36#include <com/sun/star/lang/IllegalArgumentException.idl>
37#endif
38
39#ifndef __com_sun_star_beans_PropertyValue_idl__
40#include <com/sun/star/beans/PropertyValue.idl>
41#endif
42
43//=============================================================================
44
45module com { module sun { module star { module ui {
46
47//=============================================================================
48
49/** specifies a user interface element factory that can create and initialize
50    user interface elements.
51
52    <p>
53    User interface element factories must be registered at a
54    <type>UIElementFactoryManager</type> service to provide access to itself.
55
56    Currently the following user interface element types are defined:
57    <ul>
58        <li><b>menubar</b>A configurable user interface element.</li>
59        <li><b>popupmenu</b>A configurable user interface element.</li>
60        <li><b>toolbar</b>A configurable user interface element.</li>
61        <li><b>statusbar</b>A configurable user interface element.</li>
62        <li><b>floater</b>A basic user interface element.</li>
63    </ul>
64    </p>
65
66    @since OpenOffice 2.0
67*/
68
69published interface XUIElementFactory : ::com::sun::star::uno::XInterface
70{
71    /** creates a new instances of a specific user interface element.
72
73        @param ResourceURL
74            specifies which unique user interface element should be created
75            by the factory. A resourcce URL must meet the following syntax:
76            "private:resource/$type/$name. It is only allowed to use ascii
77            characters for type and name. This argument must not be empty to
78            have a working user interface element instance.The implementation
79            can throw an
80            <type scope="com::sun::star::container">NoSuchElementException</type>
81            if it doesn't know how to create the request user interface
82            element.
83
84        @param Args
85            The following arguments are supported:
86            <ul>
87                <li><b>Frame</b><br>
88                    specifies the <type scope="com::sun::star::frame">XFrame</type>
89                    instance to which the user interface element belongs to. To
90                    create a configurable user interface element the frame
91                    instance must contain a visible component. Otherwise it is
92                    not possible to determine the correct user interface
93                    configuration manager. This argument is <b>mandatory</b> to
94                    have a working configurable user interface element instance.
95                </li>
96                <li><b>ParentWindow</b><br/>
97                    specifies a parent window to use for the window(s) representing
98                    the UI element. Depending on the concrete UI element type, this parameter
99                    might be required or ignored by an implementation.
100                </li>
101                <li><b>Persistent</b><br>specifies if changes to a configurable
102                    user interface element should be persistent. This is an
103                    optional argument. The default value is <TRUE/>.</li>
104            </ul>
105
106        <p>
107        An implementation is responsible to initialize every newly created user
108        interface element if the necessary properties are provided. Especially
109        it must connect a configurable user interface element to the correct user
110        interface configuration manager. Without this connection the configurable
111        user interface element cannot retrieve its structure data and changes to
112        the user interface element structure won't be persistent. It is up to the
113        implementation to throw an
114        <type scope="com::sun::star::lang">IllegalArgumentException</type>
115        if it cannot create a user interface element with the provided arguments.
116
117        @see ConfigurableUIElement
118        @see UIElement
119        </p>
120    */
121    ::com::sun::star::ui::XUIElement createUIElement( [in] string ResourceURL, [in] sequence< com::sun::star::beans::PropertyValue > Args ) raises ( com::sun::star::container::NoSuchElementException, com::sun::star::lang::IllegalArgumentException );
122};
123
124}; }; }; };
125
126#endif
127