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