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