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