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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21 module com { module sun { module star { module ui {
  22
  23
  24 /** is used to query, register and deregister user interface element factories.
  25
  26     <p>
  27     A user interface element factory is registered for a set of three properties.
  28     <ul>
  29         <li><b>Type</b>a string that identifies a type of a user interface element.</li>
  30         <li><b>Name</b>a string that identifies a single user interface element within a type class.</li>
  31         <li><b>Module</b>a string that identifies a single module of OpenOffice.</li>
  32     </ul>
  33     A combination of these three property values can uniquely identify every user interface
  34     element within OpenOffice.
  35
  36     Currently the following user interface element types are defined:
  37     <ul>
  38         <li><b>menubar</b></li>
  39         <li><b>popupmenu</b></li>
  40         <li><b>toolbar</b></li>
  41         <li><b>statusbar</b></li>
  42         <li><b>floater</b></li>
  43     </ul>
  44     </p>
  45
  46     @since OOo 2.0
  47  */
  48
  49 interface XUIElementFactoryRegistration : com::sun::star::uno::XInterface
  50 {
  51     /** function to retrieve a list of all registered user interface element factories
  52
  53         @returns
  54             a sequence of sequence of property values which describe every registered
  55             user interface element factory.<br/>
  56
  57             The following properties are defined:
  58             <ul>
  59                 <li><b>Type</b>a string property that identifies the type of the user interface
  60                 element which this factory can create.</li>
  61                 <li><b>Name</b>an optional string property which identifies a single user interface
  62                 element within a type class which this factory can create. If this property is not
  63                 returned, the factory is a generic factory for all user interface elements of the
  64                 same type.</li>
  65                 <li><b>Module</b>an optional string property that specifies to which module this factory is
  66                 bound to. If this property is not returned, the factory is a generic factory.</li>
  67             </ul>
  68     */
  69     sequence< sequence< com::sun::star::beans::PropertyValue > > getRegisteredFactories();
  70
  71     /** function to retrieve a previously registered user interface element factory.
  72
  73         @returns
  74             a reference to a registered user interface element factory if a factory has been
  75             found. An empty reference when no factory has been found.
  76             <b>The defined search order of factories must be from special to generic ones.</b>
  77
  78         @param ResourceURL
  79             a resource URL which identifies a user interface element. A resource URL uses the
  80             following syntax: "private:resource/$type/$name". It is only allowed to use ASCII
  81             characters for type and name.
  82
  83         @param ModuleIdentifier
  84             an optional module identifier. This value can remain empty, if a generic factory is requested.
  85             The module identifier can be retrieved from the com::sun::star::frame::ModuleManager service.
  86     */
  87     ::com::sun::star::ui::XUIElementFactory getFactory( [in] string ResourceURL, [in] string ModuleIdentifier );
  88
  89     /** function to register a user interface element factory.
  90
  91         @param aType
  92             a string that identifies a type of a user interface element. Currently the following types
  93             are supported:
  94             <ul>
  95                 <li><b>menubar</b></li>
  96                 <li><b>toolbar</b></li>
  97                 <li><b>statusbar</b></li>
  98             </ul>
  99
 100         @param aName
 101             an optional name of a single user interface element. This name must be unique within a user
 102             interface element type class. This value can remain empty if no special factory for a single
 103             user interface element is needed.
 104
 105         @param aModuleIdentifier
 106             an optional module identifier that can be used to register a factory only for a single module. This value
 107             can remain empty if no special factory for a single module is needed. The module identifier can be retrieved
 108             from the com::sun::star::frame::ModuleManager service.
 109
 110         @param aFactoryImplementationName
 111             a UNO implementation name that can be used by an implementation to create a factory instance.
 112     */
 113     void registerFactory( [in] string aType, [in] string aName, [in] string aModuleIdentifier, [in] string aFactoryImplementationName ) raises (com::sun::star::container::ElementExistException);
 114
 115     /** function to remove a previously defined user interface element factory.
 116
 117         @param aType
 118             a string that identifies a type of a user interface element. Currently the following types
 119             are supported:
 120             <ul>
 121                 <li><b>menubar</b></li>
 122                 <li><b>toolbar</b></li>
 123                 <li><b>statusbar</b></li>
 124             </ul>
 125
 126         @param aName
 127             an optional name of a single user interface element. This name must be unique within a user
 128             interface element type class. This value can remain empty if no special factory for a single
 129             user interface element should be deregistered.
 130
 131         @param ModuleIdentifier
 132             an optional module name that can be used to deregister a factory only for a single module. This value
 133             can remain empty if not a module based factory should be deregistered. The module identifier can be retrieved
 134             from the com::sun::star::frame::ModuleManager service.
 135
 136         <p>
 137         <b>Using this function can be very dangerous as other implementation with OpenOffice may not be able to  create their
 138         user interface element anymore.
 139         </b>
 140         </p>
 141     */
 142     void deregisterFactory( [in] string aType, [in] string aName, [in] string ModuleIdentifier ) raises (com::sun::star::container::NoSuchElementException);
 143 };
 144
 145 }; }; }; };
 146
 147
 148 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */