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