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