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

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