offapi/com/sun/star/frame/XComponentLoader.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 #ifndef __com_sun_star_frame_XComponentLoader_idl__
  28 #define __com_sun_star_frame_XComponentLoader_idl__
  29
  30 #ifndef __com_sun_star_uno_XInterface_idl__
  31 #include <com/sun/star/uno/XInterface.idl>
  32 #endif
  33
  34 #ifndef __com_sun_star_lang_XComponent_idl__
  35 #include <com/sun/star/lang/XComponent.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_beans_PropertyValue_idl__
  39 #include <com/sun/star/beans/PropertyValue.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_io_IOException_idl__
  43 #include <com/sun/star/io/IOException.idl>
  44 #endif
  45
  46 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  47 #include <com/sun/star/lang/IllegalArgumentException.idl>
  48 #endif
  49
  50
  51 //=============================================================================
  52
  53 module com {  module sun {  module star {  module frame {
  54
  55 //=============================================================================
  56 /** this is a simple interface to load components by an URL into a
  57     frame environment
  58
  59     @see Desktop
  60     @see Frame
  61     @see XFrame
  62  */
  63 published interface XComponentLoader: com::sun::star::uno::XInterface
  64 {
  65     //-------------------------------------------------------------------------
  66     /** loads a component specified by an URL into the specified
  67         new or existing frame.
  68
  69         @param URL
  70             specifies the URL of the document to load
  71
  72             <p>
  73             To create new documents, use "private:factory/scalc", "private:factory/swriter", etc.
  74             Other special protocols (e.g. "slot:", ".uno") are not allowed and raise
  75             an <type scope="com::sun::star::lang">IllegalArgumentException</type>.
  76             </p>
  77
  78         @param TargetFrameName
  79             specifies the name of the frame to view the document in
  80
  81             <p>
  82             If a frame with the specified name already exists, it is used, otherwise it
  83             is created. There exist some special targets which never can be used
  84             as real frame names:
  85             <table border=1>
  86                 <tr>
  87                     <td><strong>"_blank"</strong></td>
  88                     <td>always creates a new frame</td>
  89                 </tr>
  90                 <tr>
  91                     <td><strong>"_default"</strong></td>
  92                     <td>special UI functionality<br>(e.g. detecting of already loaded documents, using of empty frames of creating of new top frames as fallback)</td>
  93                 </tr>
  94                 <tr>
  95                     <td><strong>"_self", ""(!)</strong></td>
  96                     <td>means frame himself</td>
  97                 </tr>
  98                 <tr>
  99                     <td><strong>"_parent"</strong></td>
 100                     <td>address direct parent of frame</td>
 101                 </tr>
 102                 <tr>
 103                     <td><strong>"_top"</strong></td>
 104                     <td>indicates top frame of current path in tree</td>
 105                 </tr>
 106                 <tr>
 107                     <td><strong>"_beamer"</strong></td>
 108                     <td>means special sub frame</td>
 109                 </tr>
 110             </table>
 111
 112         @param SearchFlags
 113             use the values of <type>FrameSearchFlag</type> to specify
 114             how to find the specified <var>TargetFrameName</var>
 115
 116             <p>
 117             Note: These flags are optional ones and will be used for non special
 118             target names only.
 119             </p>
 120
 121         @param Arguments
 122             these arguments specify component or filter specific behavior
 123
 124             <p>
 125             For example, "ReadOnly" with a boolean value specifies whether
 126             the document is opened read-only. "FilterName" specifies the
 127             component type to create and the filter to use, for example:
 128             "Text - CSV". For more information see
 129             <type scope="com::sun::star::document">MediaDescriptor</type>.
 130             </p>
 131
 132         @return
 133             a <type scope="com::sun::star::lang">XComponent</type> for successfully loaded
 134             documents or
 135             <br>
 136             <NULL/>if it failed
 137
 138             <p>
 139             This interface is a generic one and can be used to start further requests on
 140             loaded document or control the lifetime of it (means dispose() it after using).
 141             The real document service behind this interface can be one of follow three ones:
 142             <ul>
 143                 <li>
 144                     <type scope="com::sun::star::awt">XWindow</type> for simple components<br/>
 145                     Should be used for viewable components only. It is not allowed to dispose
 146                     it after use directly, because the frame containing the component is its owner.
 147                     Because the frame object is not accessible through the interface too,
 148                     only an interacting user can do this by closing the frames' window.
 149                 </li>
 150                 <li>
 151                     <type>XController</type> for richer components<br/>
 152                     Should be used for real editable components which doesn't need a model.
 153                     It is not allowed to dispose it after use directly, because the frame
 154                     containing the component is its owner. Here the object can be disposed
 155                     by disposing the frame, that the <member>XController::getFrame()</member>
 156                     method of the controller returns. But for visible components the controller
 157                     should be asked for permission by calling <member>XController::suspend()</member> before.
 158                 </li>
 159                 <li>
 160                     <type>XModel</type> for full featured components<br/>
 161                     A model that in general can be shared between several view/controller pairs,
 162                     does not have an explicit owner. Every view and also the component that
 163                     loaded the document may consider itself as an owner.
 164                     Simply calling <method scope="com::sun::star::lang">XComponent::dispose</method> on this model may
 165                     cause problems, if some members of the "owner community" are currently
 166                     busy working on the model. These problems are handled by explicit closing
 167                     negotiations through the interface <type scope="com::sun::star::util">XCloseable</type>.
 168                     Direct dispose of the model is allowed only, if this special interface doesn't exist.
 169                 </li>
 170             </ul>
 171             </p>
 172
 173         @throws com::sun::star::io::IOException
 174             when <var>URL</var> couldn't be found or was corrupt
 175
 176         @throws com::sun::star::lang::IllegalArgumentException
 177             when given parameters doesn't perform the specification
 178      */
 179     com::sun::star::lang::XComponent loadComponentFromURL(
 180         [in] string URL,
 181         [in] string TargetFrameName,
 182         [in] long SearchFlags,
 183         [in] sequence<com::sun::star::beans::PropertyValue> Arguments)
 184         raises( com::sun::star::io::IOException,
 185                 com::sun::star::lang::IllegalArgumentException );
 186 };
 187
 188 //=============================================================================
 189
 190 }; }; }; };
 191
 192 #endif