61e1e04132
Per default, a document opened by a user action will always open in a new frame. For tdf#83722, this behaviour was extended to documents created from templates. But this currently also affects the default factory templates, if these are replaced by a config setting with a real template, which was not intentional. So this patch introduces a new MediaDescriptor property, which allows to mark a document as replaceable and automatically sets it for factory default documents. If this property is set to true, a document just acts as a placeholder while it's unmodified. I.e. the next opened document from its frame will close and replace it. Change-Id: I45ffa8709f7cdda949fac78f3b363f120f0c4a03 Reviewed-on: https://gerrit.libreoffice.org/c/core/+/88257 Tested-by: Jenkins Reviewed-by: Thorsten Behrens <Thorsten.Behrens@CIB.de>
619 lines
21 KiB
Text
619 lines
21 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 .
|
|
*/
|
|
#ifndef __com_sun_star_document_MediaDescriptor_idl__
|
|
#define __com_sun_star_document_MediaDescriptor_idl__
|
|
|
|
#include <com/sun/star/io/XOutputStream.idl>
|
|
#include <com/sun/star/io/XInputStream.idl>
|
|
#include <com/sun/star/awt/Rectangle.idl>
|
|
#include <com/sun/star/beans/NamedValue.idl>
|
|
#include <com/sun/star/util/URL.idl>
|
|
#include <com/sun/star/task/XInteractionHandler.idl>
|
|
#include <com/sun/star/task/XStatusIndicator.idl>
|
|
#include <com/sun/star/frame/XFrame.idl>
|
|
|
|
|
|
module com { module sun { module star { module document {
|
|
|
|
/** describes properties of a document, regarding the relationship
|
|
between the loaded document and the resource the document is
|
|
loaded from / stored to.
|
|
|
|
<p>
|
|
This service may be represented by a com::sun::star::beans::PropertyValue[].
|
|
Such descriptors will be passed to different functions, included into possible
|
|
load/save processes. Every member of such process can use this descriptor
|
|
and may change it if to actualize the information about the document.
|
|
So this descriptor should be used as an in/out parameter.
|
|
</p>
|
|
|
|
<p>
|
|
Note:<br>
|
|
It's not allowed to hold member of this descriptor by references longer than they
|
|
will be used (especially a possible stream). It's allowed to use it directly
|
|
or by copying it only.
|
|
</p>
|
|
|
|
@see com::sun::star::beans::PropertyValue
|
|
*/
|
|
service MediaDescriptor
|
|
{
|
|
/** May be set by filters or detection services if user has chosen to
|
|
abort loading/saving, e.g. while entering a password.
|
|
*/
|
|
[optional,property] boolean Aborted;
|
|
|
|
/** document is a template
|
|
|
|
<p>
|
|
Loading a component of type "template" creates a new untitled document
|
|
by default, but setting the "AsTemplate" property to `FALSE` loads the
|
|
template document for editing. Setting "AsTemplate" to `TRUE` creates a
|
|
new untitled document out of the loaded document, even if it has not
|
|
a "template" type.
|
|
</p>
|
|
*/
|
|
[optional,property] boolean AsTemplate;
|
|
|
|
/** the author of the document
|
|
|
|
<p>
|
|
Only for storing versions in components supporting versioning:
|
|
author of version.
|
|
</p>
|
|
*/
|
|
[optional,property] string Author;
|
|
|
|
/** identifier of used character set
|
|
|
|
<p>
|
|
Defines the character set for document formats that contain single
|
|
byte characters (if necessary).
|
|
</p>
|
|
*/
|
|
[optional,property] string CharacterSet;
|
|
|
|
/** description of document
|
|
|
|
<p>
|
|
Only for storing versions in components supporting versioning:
|
|
comment (description) for stored version.
|
|
</p>
|
|
*/
|
|
[optional,property] string Comment;
|
|
|
|
/** pack specific properties of caller
|
|
|
|
<p>
|
|
This is a parameter that can be used for any properties specific
|
|
for a special component type. Format of that depends from real
|
|
type of addressed component.
|
|
</p>
|
|
|
|
<p>
|
|
For extensibility, it is recommended to use values of type
|
|
sequence<com.sun.star.beans.NamedValue> with this property.
|
|
</p>
|
|
*/
|
|
[optional,property] any ComponentData;
|
|
|
|
/** The base URL of the document to be used to resolve relative links.
|
|
*/
|
|
[optional,property] string DocumentBaseURL;
|
|
|
|
/** document title
|
|
|
|
<p>
|
|
This parameter can be used to specify a title for a document.
|
|
</p>
|
|
*/
|
|
[optional,property] string DocumentTitle;
|
|
|
|
/** encryption information for encryption/decryption of documents
|
|
|
|
<p>
|
|
It contains the necessary information for encryption/decryption of
|
|
a component (if necessary).
|
|
If neither password nor encryption data is specified, loading of
|
|
a password protected document will fail, storing will be done without
|
|
encryption. If both are provided, the encryption data is used
|
|
( if the filter supports it ).
|
|
</p>
|
|
<p>
|
|
The encryption data is generated based on the password.
|
|
</p>
|
|
*/
|
|
[optional,property] sequence< ::com::sun::star::beans::NamedValue > EncryptionData;
|
|
|
|
/** same as MediaDescriptor::URL
|
|
|
|
<p>
|
|
It will be supported for compatibility reasons only.
|
|
</p>
|
|
|
|
@deprecated
|
|
*/
|
|
[optional,property] string FileName;
|
|
|
|
/** internal filter name
|
|
|
|
<p>
|
|
Name of a filter that should be used for loading or storing the component.
|
|
Names must match the names of the TypeDetection configuration,
|
|
invalid names are ignored. If a name is specified on loading,
|
|
it still will be verified by a filter detection, but in case of doubt
|
|
it will be preferred.
|
|
|
|
See this page for a list of internal filter names: https://help.libreoffice.org/latest/en-US/text/shared/guide/convertfilters.html
|
|
</p>
|
|
*/
|
|
[optional,property] string FilterName;
|
|
|
|
/** same as MediaDescriptor::FilterOptions
|
|
|
|
<p>
|
|
It will be supported for compatibility reasons only.
|
|
</p>
|
|
|
|
@deprecated
|
|
*/
|
|
[optional,property] string FilterFlags;
|
|
|
|
/** additional properties for filter
|
|
|
|
<p>
|
|
Some filters need additional parameters; use only together with property
|
|
MediaDescriptor::FilterName. Details must be documented
|
|
by the filter. This is an old format for some filters. If a string is not
|
|
enough, filters can use the property MediaDescriptor::FilterData.
|
|
</p>
|
|
*/
|
|
[optional,property] string FilterOptions;
|
|
|
|
/** additional properties for filter
|
|
|
|
<p>
|
|
This is a parameter that can be used for any properties specific
|
|
for a special filter type. It should be used if
|
|
MediaDescriptor::FilterOptions isn't enough.
|
|
</p>
|
|
*/
|
|
[optional,property] any FilterData;
|
|
|
|
/** load document invisible
|
|
|
|
<p>
|
|
Defines if the loaded component is made visible. If this property is not
|
|
specified, the component is made visible by default.
|
|
</p>
|
|
*/
|
|
[optional,property] boolean Hidden;
|
|
|
|
/** The hierarchical path to the embedded document from topmost container.
|
|
*/
|
|
[optional,property] string HierarchicalDocumentName;
|
|
|
|
/** a stream to receive the document data.
|
|
|
|
<p>
|
|
If used when storing a document: writing must be done using this stream.
|
|
If no stream is provided, the loader will create a stream by itself using
|
|
the other properties. It is not allowed to keep a reference to this
|
|
OutputStream after storing the component.
|
|
</p>
|
|
*/
|
|
[optional,property] com::sun::star::io::XOutputStream OutputStream;
|
|
|
|
/** content of document
|
|
|
|
<p>
|
|
If used when loading a document: reading must be done using this stream.
|
|
If no stream is provided, the loader will create a stream by itself using
|
|
the other properties. It is not allowed to keep a reference to this
|
|
InputStream after loading the component, and it would be useless, because
|
|
in general an InputStream is usable for reading only once, except when it
|
|
also implements the com::sun::star::io::XSeekable interface.
|
|
</p>
|
|
*/
|
|
[optional,property] com::sun::star::io::XInputStream InputStream;
|
|
|
|
/** handle exceptional situations
|
|
|
|
<p>
|
|
Object implementing the com::sun::star::task::InteractionHandler
|
|
service that is used to handle exceptional situations where proceeding with the task
|
|
is impossible without additional information or impossible at all.
|
|
The implemented API provides a default implementation for it that can handle many situations.
|
|
If no InteractionHandler is set, a suitable exception is thrown.
|
|
It is not allowed to keep a reference to this object, even not in the loaded
|
|
or stored component's copy of the MediaDescriptor provided by its arguments attribute.
|
|
</p>
|
|
*/
|
|
[optional,property] com::sun::star::task::XInteractionHandler InteractionHandler;
|
|
|
|
/** jump to a marked position after loading
|
|
|
|
<p>
|
|
This is the same as the text behind a "#" in a http URL. But
|
|
this syntax with a "#" is not specified in most URL schemas.
|
|
</p>
|
|
*/
|
|
[optional,property] string JumpMark;
|
|
|
|
/** specify mime type of content
|
|
|
|
<p>
|
|
Type of the medium to load, that must match to one of the types defined
|
|
in the TypeDetection configuration (otherwise it's ignored).
|
|
This bypasses the type detection of the com::sun::star::frame::Desktop environment,
|
|
so passing a wrong MediaType will cause failure of loading.
|
|
</p>
|
|
*/
|
|
[optional,property] string MediaType;
|
|
|
|
/** please use the corresponding parameters of this descriptor instead
|
|
|
|
<p>
|
|
String that summarizes some flags for loading. The string contains capital
|
|
letters for the flags:<br>
|
|
<table border=1>
|
|
<tr>
|
|
<td><strong>flag</strong></td>
|
|
<td><strong>value</strong></td>
|
|
<td><strong>replacement</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td><em>ReadOnly</em></td>
|
|
<td>R</td>
|
|
<td>MediaDescriptor::ReadOnly</td>
|
|
</tr>
|
|
<tr>
|
|
<td><em>Preview</em></td>
|
|
<td>B</td>
|
|
<td>MediaDescriptor::Preview</td>
|
|
</tr>
|
|
<tr>
|
|
<td><em>AsTemplate</em></td>
|
|
<td>T</td>
|
|
<td>MediaDescriptor::AsTemplate</td>
|
|
</tr>
|
|
<tr>
|
|
<td><em>Hidden</em></td>
|
|
<td>H</td>
|
|
<td>MediaDescriptor::Hidden</td>
|
|
</tr>
|
|
</table>
|
|
</p>
|
|
|
|
@deprecated
|
|
*/
|
|
[optional,property] string OpenFlags;
|
|
|
|
/** opens a new view for an already loaded document
|
|
|
|
<p>
|
|
Setting this to `TRUE` forces the component to create a new window on loading
|
|
in any case. If the component supports multiple views, a second view is
|
|
opened, if not, the component is loaded one more time. Otherwise the behavior
|
|
depends on the default window handling of the com::sun::star::frame::Desktop environment.
|
|
</p>
|
|
*/
|
|
[optional,property] boolean OpenNewView;
|
|
|
|
|
|
/** overwrite any existing file
|
|
|
|
<p>
|
|
For storing only: overwrite any existing file, default is `FALSE`,
|
|
so an error occurs if the target file already exists.
|
|
</p>
|
|
*/
|
|
[optional,property] boolean Overwrite;
|
|
|
|
/** password for loading or storing documents
|
|
|
|
<p>
|
|
It contains a password for loading or storing a component (if necessary).
|
|
If neither password nor encryption data is specified, loading of
|
|
a password protected document will fail, storing will be done without
|
|
encryption. If both are provided, the encryption data is used
|
|
( if the filter supports it ).
|
|
</p>
|
|
*/
|
|
[optional,property] string Password;
|
|
|
|
/** contains the data for HTTP post method as a sequence of bytes.
|
|
|
|
<p>
|
|
Data to send to a location described by the media descriptor to get
|
|
a result in return that will be loaded as a component
|
|
(usually in webforms). Default is: no PostData.
|
|
</p>
|
|
*/
|
|
[optional,property] sequence< byte > PostData;
|
|
|
|
/** add loaded document to recent document list
|
|
|
|
<p>
|
|
Setting this to `FALSE` prevents the loaded document to be added to the recent documents list.
|
|
Default is `TRUE`.
|
|
</p>
|
|
|
|
@since LibreOffice 5.1
|
|
*/
|
|
[optional,property] boolean PickListEntry;
|
|
|
|
/** use MediaDescriptor::PostData instead of this
|
|
|
|
<p>
|
|
Same as PostData, but the data is transferred as a string
|
|
(just for compatibility).
|
|
</p>
|
|
|
|
@deprecated
|
|
*/
|
|
[optional,property] string PostString;
|
|
|
|
/** show preview
|
|
|
|
<p>
|
|
Setting this to `TRUE` tells the a loaded component that it is loaded as
|
|
a preview, so it can optimize loading and viewing for this special purpose.
|
|
Default is `FALSE`.
|
|
</p>
|
|
*/
|
|
[optional,property] boolean Preview;
|
|
|
|
/** open document readonly
|
|
|
|
<p>
|
|
Tells whether a document should be loaded in a (logical) readonly or in
|
|
read/write mode. If opening in the desired mode is impossible, an error occurs.
|
|
By default the loaded content decides what to do: if its UCB content supports
|
|
a "readonly" property, the logical open mode depends on that, otherwise
|
|
it will be read/write. This is only a UI related property, opening a
|
|
document in read only mode will not prevent the component from being
|
|
modified by API calls, but all modifying functionality in the UI will
|
|
be disabled or removed.
|
|
</p>
|
|
*/
|
|
[optional,property] boolean ReadOnly;
|
|
|
|
/** start presentation from a document
|
|
|
|
<p>
|
|
Tells the component loading the document that a presentation that is in the
|
|
document is to be started right away.
|
|
</p>
|
|
*/
|
|
[optional,property] boolean StartPresentation;
|
|
|
|
/** name of document referrer
|
|
|
|
<p>
|
|
A URL describing the environment of the request; e.g. a referrer may be a
|
|
URL of a document, if a hyperlink inside this document is clicked to load
|
|
another document. The referrer may be evaluated by the addressed UCB content
|
|
or the loaded document. Without a referrer the processing of URLs that
|
|
needs security checks will be denied, e.g. "macro:" URLs.
|
|
<br>
|
|
Don't be confused about the wrong spelling; it is kept for compatibility reasons.
|
|
</p>
|
|
*/
|
|
[optional,property] string Referer;
|
|
|
|
/** let the document be opened in repair mode
|
|
|
|
<p>
|
|
For loading of corrupted zip packages: Setting this to `TRUE` let the document
|
|
be opened in repair mode, so as much as possible information will be retrieved.
|
|
</p>
|
|
|
|
@since OOo 1.1.2
|
|
*/
|
|
[optional,property] boolean RepairPackage;
|
|
|
|
/** can be used for status information
|
|
|
|
<p>
|
|
Object implementing the com::sun::star::task::XStatusIndicator
|
|
interface that can be used to give status information (text or progress) for the task.
|
|
The office provides a default implementation for it. It is not allowed to keep
|
|
a reference to this object, even not in the loaded or stored component's
|
|
copy of the MediaDescriptor provided by its arguments attribute.
|
|
</p>
|
|
*/
|
|
[optional,property] com::sun::star::task::XStatusIndicator StatusIndicator;
|
|
|
|
/** allows to specify the URL that is used next time SaveAs dialog is opened
|
|
|
|
<p>
|
|
If the parameter is specified, the URL will be used by SaveAs dialog
|
|
next time as target folder.
|
|
</p>
|
|
*/
|
|
[optional,property] string SuggestedSaveAsDir;
|
|
|
|
/** allows to specify the suggested file name that is used next time SaveAs
|
|
dialog is opened
|
|
|
|
<p>
|
|
If the parameter is specified, the file name will be suggested by
|
|
SaveAs dialog next time.
|
|
</p>
|
|
*/
|
|
[optional,property] string SuggestedSaveAsName;
|
|
|
|
/** name of the template instead of the URL
|
|
|
|
<p>
|
|
The logical name of a template to load. Together with the MediaDescriptor::TemplateRegion
|
|
property it can be used instead of the URL of the template. Use always in conjunction with
|
|
MediaDescriptor::TemplateRegionName.
|
|
</p>
|
|
*/
|
|
[optional,property] string TemplateName;
|
|
|
|
/** name of the template instead of the URL
|
|
|
|
<p>
|
|
See MediaDescriptor::TemplateName. The template region names are the folder names you see
|
|
in the templates dialog.
|
|
</p>
|
|
*/
|
|
[optional,property] string TemplateRegionName;
|
|
|
|
/** regulate using of compressing
|
|
|
|
<p>
|
|
For storing: Setting this to `TRUE` means, don't use a zip file to save
|
|
the document, use a folder instead (only usable for UCB contents, that
|
|
support folders). Default is `FALSE`.
|
|
</p>
|
|
*/
|
|
[optional,property] boolean Unpacked;
|
|
|
|
/** URL of the document
|
|
|
|
<p>
|
|
The location of the component in URL syntax. It must be a fully qualified URL.
|
|
</p>
|
|
*/
|
|
[optional,property] string URL;
|
|
|
|
/** storage version
|
|
|
|
<p>
|
|
For components supporting versioning: the number of the version to be
|
|
loaded or saved. Default is zero and means: no version is created or
|
|
loaded, the "main" document is processed.
|
|
</p>
|
|
*/
|
|
[optional,property] short Version;
|
|
|
|
/** set special view state
|
|
<p>
|
|
Data to set a special view state after loading. The type depends on
|
|
the component and is usually retrieved from a com::sun::star::frame::Controller
|
|
object by its com::sun::star::frame::XController
|
|
interface. Default is: no view data.
|
|
</p>
|
|
*/
|
|
[optional,property] any ViewData;
|
|
|
|
/** id of the initial view
|
|
|
|
<p>
|
|
For components supporting different views: a number to define the view
|
|
that should be constructed after loading. Default is: zero, and this
|
|
should be treated by the component as the default view.
|
|
</p>
|
|
*/
|
|
[optional,property] short ViewId;
|
|
|
|
/** should the macro be executed.
|
|
the value should be one from com::sun::star::document::MacroExecMode
|
|
constant list.
|
|
|
|
@since OOo 1.1.2
|
|
*/
|
|
[optional,property] short MacroExecutionMode;
|
|
|
|
/** can the document be updated depending from links.
|
|
the value should be one from com::sun::star::document::UpdateDocMode
|
|
constant list.
|
|
|
|
@since OOo 1.1.2
|
|
*/
|
|
[optional,property] short UpdateDocMode;
|
|
|
|
/** specifies the name of the view controller to create when loading a document
|
|
|
|
<p>If this property is used when loading a document into a frame, then it
|
|
specifies the name of the view controller to create. That is, the property
|
|
is passed to the document's com::sun::star::frame::XModel2::createViewController()
|
|
method.<br/>
|
|
If the loaded document does not support the <code>XModel2</code> interface,
|
|
the property is ignored.</p>
|
|
|
|
@see ::com::sun::star::frame::XModel2::createViewController
|
|
@see ::com::sun::star::frame::XController2::ViewControllerName
|
|
|
|
@since OOo 3.0
|
|
*/
|
|
[optional,property] string ViewControllerName;
|
|
|
|
/** specifies the frame containing the document. May be empty.
|
|
*/
|
|
[optional,property] com::sun::star::frame::XFrame Frame;
|
|
|
|
/** Setting this option will prevent copying/dragging any content anywhere.
|
|
The commands 'Copy' and 'Cut' will be disabled; selection clipboard won't work,
|
|
and dragging with mouse will also be disabled.
|
|
|
|
@since LibreOffice 6.4
|
|
*/
|
|
[optional,property] boolean LockContentExtraction;
|
|
|
|
/** Setting this option will prevent exporting document content to any file.
|
|
Export, Send, save as, etc will be disabled,
|
|
as well as individual graphic/chart export and mail merge.
|
|
|
|
@since LibreOffice 6.4
|
|
*/
|
|
[optional,property] boolean LockExport;
|
|
|
|
/** Setting this option will disable all print functions (including Printer setup)
|
|
|
|
@since LibreOffice 6.4
|
|
*/
|
|
[optional,property] boolean LockPrint;
|
|
|
|
/** Setting this option will disable the save function.
|
|
*
|
|
@since LibreOffice 6.4
|
|
*/
|
|
[optional,property] boolean LockSave;
|
|
|
|
/** Setting this option will disable switching to edit mode from read-only mode.
|
|
*
|
|
@since LibreOffice 6.4
|
|
*/
|
|
[optional,property] boolean LockEditDoc;
|
|
|
|
/** Mark the document as replaceable / a placeholder
|
|
|
|
<p>Normally a document is always opened in a new frame. If this property is
|
|
set to true, this document just acts as a placeholder while it's unmodified.
|
|
I.e. the next opened document from its frame will close and replace it.</p>
|
|
|
|
<p>This defaults to false, except for the default template of a LibreOffice
|
|
module, referenced as "private:factory/<module>".</p>
|
|
|
|
@since LibreOffice 7.0
|
|
*/
|
|
[optional,property] boolean Replaceable;
|
|
};
|
|
|
|
|
|
}; }; }; };
|
|
|
|
#endif
|
|
|
|
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|