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 53module 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 */ 63published 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 193