offapi/com/sun/star/ui/XUIElementFactory.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XUIElementFactory.idl,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __com_sun_star_ui_XUIElementFactory_idl__
  32 #define __com_sun_star_ui_XUIElementFactory_idl__
  33
  34 #ifndef __com_sun_star_ui_XUIElement_idl__
  35 #include <com/sun/star/ui/XUIElement.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_container_NoSuchElementException_idl__
  39 #include <com/sun/star/container/NoSuchElementException.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  43 #include <com/sun/star/lang/IllegalArgumentException.idl>
  44 #endif
  45
  46 #ifndef __com_sun_star_beans_PropertyValue_idl__
  47 #include <com/sun/star/beans/PropertyValue.idl>
  48 #endif
  49
  50 //=============================================================================
  51
  52 module com { module sun { module star { module ui {
  53
  54 //=============================================================================
  55
  56 /** specifies a user interface element factory that can create and initialize
  57     user interface elements.
  58
  59     <p>
  60     User interface element factories must be registered at a
  61     <type>UIElementFactoryManager</type> service to provide access to itself.
  62
  63     Currently the following user interface element types are defined:
  64     <ul>
  65         <li><b>menubar</b>A configurable user interface element.</li>
  66         <li><b>popupmenu</b>A configurable user interface element.</li>
  67         <li><b>toolbar</b>A configurable user interface element.</li>
  68         <li><b>statusbar</b>A configurable user interface element.</li>
  69         <li><b>floater</b>A basic user interface element.</li>
  70     </ul>
  71     </p>
  72
  73     @since OOo 2.0.0
  74 */
  75
  76 interface XUIElementFactory : ::com::sun::star::uno::XInterface
  77 {
  78     /** creates a new instances of a specific user interface element.
  79
  80         @param ResourceURL
  81             specifies which unique user interface element should be created
  82             by the factory. A resourcce URL must meet the following syntax:
  83             "private:resource/$type/$name. It is only allowed to use ascii
  84             characters for type and name. This argument must not be empty to
  85             have a working user interface element instance.The implementation
  86             can throw an
  87             <type scope="com::sun::star::container">NoSuchElementException</type>
  88             if it doesn't know how to create the request user interface
  89             element.
  90
  91         @param Args
  92             The following arguments are supported:
  93             <ul>
  94                 <li><b>Frame</b><br>
  95                     specifies the <type scope="com::sun::star::frame">XFrame</type>
  96                     instance to which the user interface element belongs to. To
  97                     create a configurable user interface element the frame
  98                     instance must contain a visible component. Otherwise it is
  99                     not possible to determine the correct user interface
 100                     configuration manager. This argument is <b>mandatory</b> to
 101                     have a working configurable user interface element instance.
 102                 </li>
 103                 <li><b>Persistent</b><br>specifies if changes to a configurable
 104                     user interface element should be persistent. This is an
 105                     optional argument. The default value is <TRUE/>.</li>
 106             </ul>
 107
 108         <p>
 109         An implementation is responsible to initialize every newly created user
 110         interface element if the necessary properties are provided. Especially
 111         it must connect a configurable user interface element to the correct user
 112         interface configuration manager. Without this connection the configurable
 113         user interface element cannot retrieve its structure data and changes to
 114         the user interface element structure won't be persistent. It is up to the
 115         implementation to throw an
 116         <type scope="com::sun::star::lang">IllegalArgumentException</type>
 117         if it cannot create a user interface element with the provided arguments.
 118
 119         @see ConfigurableUIElement
 120         @see UIElement
 121         </p>
 122     */
 123     ::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 );
 124 };
 125
 126 }; }; }; };
 127
 128 #endif