158 lines
6.8 KiB
Text
158 lines
6.8 KiB
Text
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
|
|
/*
|
|
* This file is part of the LibreOffice project.
|
|
*
|
|
* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
*
|
|
* This file incorporates work covered by the following license notice:
|
|
*
|
|
* Licensed to the Apache Software Foundation (ASF) under one or more
|
|
* contributor license agreements. See the NOTICE file distributed
|
|
* with this work for additional information regarding copyright
|
|
* ownership. The ASF licenses this file to you under the Apache
|
|
* License, Version 2.0 (the "License"); you may not use this file
|
|
* except in compliance with the License. You may obtain a copy of
|
|
* the License at http://www.apache.org/licenses/LICENSE-2.0 .
|
|
*/
|
|
|
|
|
|
|
|
module com { module sun { module star { module frame {
|
|
|
|
/** this is a simple interface to load components by a URL into a
|
|
frame environment
|
|
|
|
@see Desktop
|
|
@see Frame
|
|
@see XFrame
|
|
*/
|
|
published interface XComponentLoader: com::sun::star::uno::XInterface
|
|
{
|
|
/** loads a component specified by a URL into the specified
|
|
new or existing frame.
|
|
|
|
@param URL
|
|
specifies the URL of the document to load
|
|
|
|
<p>
|
|
To create new documents, use "private:factory/scalc", "private:factory/swriter", etc.
|
|
Other special protocols (e.g. "slot:", ".uno") are not allowed and raise
|
|
a com::sun::star::lang::IllegalArgumentException.
|
|
</p>
|
|
|
|
@param TargetFrameName
|
|
specifies the name of the frame to view the document in
|
|
|
|
<p>
|
|
If a frame with the specified name already exists, it is used, otherwise it
|
|
is created. There exist some special targets which never can be used
|
|
as real frame names:
|
|
<table border=1>
|
|
<tr>
|
|
<td><strong>"_blank"</strong></td>
|
|
<td>always creates a new frame</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>"_default"</strong></td>
|
|
<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>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>"_self", ""(!)</strong></td>
|
|
<td>means frame himself</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>"_parent"</strong></td>
|
|
<td>address direct parent of frame</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>"_top"</strong></td>
|
|
<td>indicates top frame of current path in tree</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>"_beamer"</strong></td>
|
|
<td>means special sub frame</td>
|
|
</tr>
|
|
</table>
|
|
|
|
@param SearchFlags
|
|
use the values of FrameSearchFlag to specify
|
|
how to find the specified <var>TargetFrameName</var>
|
|
|
|
<p>
|
|
Note: These flags are optional ones and will be used for non special
|
|
target names only.
|
|
</p>
|
|
|
|
@param Arguments
|
|
these arguments specify component or filter specific behavior
|
|
|
|
<p>
|
|
For example, "ReadOnly" with a boolean value specifies whether
|
|
the document is opened read-only. "FilterName" specifies the
|
|
component type to create and the filter to use, for example:
|
|
"Text - CSV". For more information see
|
|
com::sun::star::document::MediaDescriptor.
|
|
</p>
|
|
|
|
@return
|
|
a com::sun::star::lang::XComponent for successfully loaded
|
|
documents or
|
|
<br>
|
|
`NULL`if it failed
|
|
|
|
<p>
|
|
This interface is a generic one and can be used to start further requests on
|
|
loaded document or control the lifetime of it (means dispose() it after using).
|
|
The real document service behind this interface can be one of follow three ones:
|
|
<ul>
|
|
<li>
|
|
com::sun::star::awt::XWindow for simple components<br/>
|
|
Should be used for viewable components only. It is not allowed to dispose
|
|
it after use directly, because the frame containing the component is its owner.
|
|
Because the frame object is not accessible through the interface too,
|
|
only an interacting user can do this by closing the frame's window.
|
|
</li>
|
|
<li>
|
|
XController for richer components<br/>
|
|
Should be used for real editable components which doesn't need a model.
|
|
It is not allowed to dispose it after use directly, because the frame
|
|
containing the component is its owner. Here the object can be disposed
|
|
by disposing the frame, that the XController::getFrame()
|
|
method of the controller returns. But for visible components the controller
|
|
should be asked for permission by calling XController::suspend() before.
|
|
</li>
|
|
<li>
|
|
XModel for full featured components<br/>
|
|
A model that in general can be shared between several view/controller pairs,
|
|
does not have an explicit owner. Every view and also the component that
|
|
loaded the document may consider itself as an owner.
|
|
Simply calling com::sun::star::lang::XComponent::dispose() on this model may
|
|
cause problems, if some members of the "owner community" are currently
|
|
busy working on the model. These problems are handled by explicit closing
|
|
negotiations through the interface com::sun::star::util::XCloseable.
|
|
Direct dispose of the model is allowed only, if this special interface doesn't exist.
|
|
</li>
|
|
</ul>
|
|
</p>
|
|
|
|
@throws com::sun::star::io::IOException
|
|
when <var>URL</var> couldn't be found or was corrupt
|
|
|
|
@throws com::sun::star::lang::IllegalArgumentException
|
|
when given parameters doesn't perform the specification
|
|
*/
|
|
com::sun::star::lang::XComponent loadComponentFromURL(
|
|
[in] string URL,
|
|
[in] string TargetFrameName,
|
|
[in] long SearchFlags,
|
|
[in] sequence<com::sun::star::beans::PropertyValue> Arguments)
|
|
raises( com::sun::star::io::IOException,
|
|
com::sun::star::lang::IllegalArgumentException );
|
|
};
|
|
|
|
|
|
}; }; }; };
|
|
|
|
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|