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