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

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