offapi/com/sun/star/document/MediaDescriptor.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: MediaDescriptor.idl,v $
  10  * $Revision: 1.24 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_document_MediaDescriptor_idl__
  31 #define __com_sun_star_document_MediaDescriptor_idl__
  32
  33 #ifndef __com_sun_star_io_XOutputStream_idl__
  34 #include <com/sun/star/io/XOutputStream.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_io_XInputStream_idl__
  38 #include <com/sun/star/io/XInputStream.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_awt_Rectangle_idl__
  42 #include <com/sun/star/awt/Rectangle.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_util_URL_idl__
  46 #include <com/sun/star/util/URL.idl>
  47 #endif
  48
  49 #ifndef __com_sun_star_task_XInteractionHandler_idl__
  50 #include <com/sun/star/task/XInteractionHandler.idl>
  51 #endif
  52
  53 #ifndef __com_sun_star_task_XStatusIndicator_idl__
  54 #include <com/sun/star/task/XStatusIndicator.idl>
  55 #endif
  56
  57 //=============================================================================
  58
  59 module com { module sun { module star { module document {
  60
  61 //=============================================================================
  62 /** describes properties of a document, regarding the relationship
  63     between the loaded document and the resource the document is
  64     loaded from / stored to.
  65
  66     <p>
  67     This service may be represented by a
  68     <type scope="com::sun::star::beans" dim="[]">PropertyValue</type>.
  69     Such descriptors will be passed to different functions, included into possible
  70     load/save proccesses. Every member of such process can use this descriptor
  71     and may change it if to actualize the informations about the document.
  72     So this descriptor should be used as an in/out parameter.
  73     </p>
  74
  75     <p>
  76     Note:<br>
  77     It's not allowed to hold member of this descriptor by references longer the they
  78     will be used (especialy a possible stream). It's allowed to use it directly
  79     or by copying it only.
  80     </p>
  81
  82     @see com::sun::star::beans::PropertyValue
  83  */
  84 published service MediaDescriptor
  85 {
  86     //-------------------------------------------------------------------------
  87     /** May be set by filters or detection services if user has choosen to
  88         abort loading/saving, e.g. while entering a password.
  89      */
  90     [optional,property] boolean Aborted;
  91
  92     //-------------------------------------------------------------------------
  93     /** document is a template
  94
  95         <p>
  96         Loading a component of type "template" creates a new untitled document
  97         by default, but setting the "AsTemplate" property to <FALSE/> loads the
  98         template document for editing. Setting "AsTemplate" to <TRUE/> creates a
  99         new untitled document out of the loaded document, even if it has not
 100         a "template" type.
 101         </p>
 102      */
 103     [optional,property] boolean AsTemplate;
 104
 105     //-------------------------------------------------------------------------
 106     /** the author of the document
 107
 108         <p>
 109         Only for storing versions in components supporting versioning:
 110         author of version.
 111         </p>
 112      */
 113     [optional,property] string Author;
 114
 115     //-------------------------------------------------------------------------
 116     /** identifier of used character set
 117
 118         <p>
 119         Defines the character set for document formats that contain single
 120         byte characters (if necessary).
 121         </p>
 122      */
 123     [optional,property] string CharacterSet;
 124
 125     //-------------------------------------------------------------------------
 126     /** description of document
 127
 128         <p>
 129         Only for storing versions in components supporting versioning:
 130         comment (description) for stored version.
 131         </p>
 132      */
 133     [optional,property] string Comment;
 134
 135     //-------------------------------------------------------------------------
 136     /** pack specific properties of caller
 137
 138         <p>
 139         This is a parameter that can be used for any properties specific
 140         for a special component type. Format of that depends from real
 141         type of adressed component.
 142         </p>
 143      */
 144     [optional,property] any ComponentData;
 145
 146     //-------------------------------------------------------------------------
 147     /** The base URL of the document to be used to resolve relative links.
 148      */
 149     [optional,property] string DocumentBaseURL;
 150
 151     //-------------------------------------------------------------------------
 152     /** document title
 153
 154         <p>
 155         This parameter can be used to specify a title for a document.
 156         </p>
 157      */
 158     [optional,property] string DocumentTitle;
 159
 160     //-------------------------------------------------------------------------
 161     /** same as <member>MediaDescriptor::URL</member>
 162
 163         <p>
 164         It will be supported for compatibility reasons only.
 165         </p>
 166
 167         @deprecated
 168      */
 169     [optional,property] string FileName;
 170
 171     //-------------------------------------------------------------------------
 172     /** internal filter name
 173
 174         <p>
 175         Name of a filter that should be used for loading or storing the component.
 176         Names must match the names of the <type>TypeDetection</type> configuration,
 177         invalid names are ignored. If a name is specified on loading,
 178         it still will be verified by a filter detection, but in case of doubt
 179         it will be preferred.
 180         </p>
 181      */
 182     [optional,property] string FilterName;
 183
 184     //-------------------------------------------------------------------------
 185     /** same as <member>MediaDescriptor::FilterOptions</member>
 186
 187         <p>
 188         It will be supported for compatibility reasons only.
 189         </p>
 190
 191         @deprecated
 192      */
 193     [optional,property] string FilterFlags;
 194
 195     //-------------------------------------------------------------------------
 196     /** additional properties for filter
 197
 198         <p>
 199         Some filters need additional parameters; use only together with property
 200         <member>MediaDescriptor::FilterName</member>. Details must be documented
 201         by the filter. This is an old format for some filters. If a string is not
 202         enough, filters can use the property <member>MediaDescriptor::FilterData</member>.
 203         </p>
 204      */
 205     [optional,property] string FilterOptions;
 206
 207         //-------------------------------------------------------------------------
 208     /** additional properties for filter
 209
 210         <p>
 211         This is a parameter that can be used for any properties specific
 212         for a special filter type. It should be used if
 213         <member>MediaDescriptor::FilterOptions</member> isn't enough.
 214         </p>
 215      */
 216     [optional,property] any FilterData;
 217
 218     //-------------------------------------------------------------------------
 219     /** load document invisible
 220
 221         <p>
 222         Defines if the loaded component is made visible. If this property is not
 223         specified, the component is made visible by default.
 224         </p>
 225      */
 226     [optional,property] boolean Hidden;
 227
 228     //-------------------------------------------------------------------------
 229     /** The hierarchical path to the embedded document from topmost container.
 230      */
 231     [optional,property] string HierarchicalDocumentName;
 232
 233     //-------------------------------------------------------------------------
 234     /** a stream to receive the document data.
 235
 236         <p>
 237         If used when storing a document: writing must be done using this stream.
 238         If no stream is provided, the loader will create a stream by itself using
 239         the other properties. It is not allowed to keep a reference to this
 240         OutputStream after storing the component.
 241         </p>
 242      */
 243     [optional,property] com::sun::star::io::XOutputStream OutputStream;
 244
 245     //-------------------------------------------------------------------------
 246     /** content of document
 247
 248         <p>
 249         If used when loading a document: reading must be done using this stream.
 250         If no stream is provided, the loader will create a stream by itself using
 251         the other properties. It is not allowed to keep a reference to this
 252         InputStream after loading the component, and it would be useless, because
 253         in general an InputStream is usable for readong only once, except when it
 254         also implements the <type scope="com::sun::star::io">XSeekable</type> interface.
 255         </p>
 256      */
 257     [optional,property] com::sun::star::io::XInputStream InputStream;
 258
 259     //-------------------------------------------------------------------------
 260     /** handle exceptional situations
 261
 262         <p>
 263         Object implementing the <type scope="com::sun::star::task">InteractionHandler</type>
 264         service that is used to handle exceptional situations where proceeding with the task
 265         is impossible without additional information or impossible at all.
 266         The implemented api provides a default implementation for it that can handle many situations.
 267         If no InteractionHandler is set, a suitable exception is thrown.
 268         It is not allowed to keep a reference to this object, even not in the loaded
 269         or stored components' copy of the MediaDescriptor provided by its arguments attribute.
 270         </p>
 271      */
 272     [optional,property] com::sun::star::task::XInteractionHandler InteractionHandler;
 273
 274     //-------------------------------------------------------------------------
 275     /** jump to a marked position after loading
 276
 277         <p>
 278         This is the same as the text behind a '#' in a http URL. But
 279         this syntax with a '#' is not specified in most URL schemas.
 280         </p>
 281      */
 282     [optional,property] string JumpMark;
 283
 284     //-------------------------------------------------------------------------
 285     /** specify mime type of content
 286
 287         <p>
 288         Type of the medium to load, that must match to one of the types defined
 289         in the <type>TypeDetection</type> configuration (otherwise it's ignored).
 290         This bypasses the type detection of the <type scope="com::sun::star::frame">Desktop</type> environment,
 291         so passing a wrong MediaType will cause failure of loading.
 292         </p>
 293      */
 294     [optional,property] string MediaType;
 295
 296     //-------------------------------------------------------------------------
 297     /** please use the corresponding parameters of this descriptor instead
 298
 299         <p>
 300         String that summarizes some flags for loading. The string contains capital
 301         letters for the flags:<br>
 302         <table border=1>
 303             <tr>
 304                 <td><strong>flag</strong></td>
 305                 <td><strong>value</strong></td>
 306                 <td><strong>replacement</strong></td>
 307             </tr>
 308             <tr>
 309                 <td><em>ReadOnly</em></td>
 310                 <td>R</td>
 311                 <td><member>MediaDescriptor::ReadOnly</member></td>
 312             </tr>
 313             <tr>
 314                 <td><em>Preview</em></td>
 315                 <td>B</td>
 316                 <td><member>MediaDescriptor::Preview</member></td>
 317             </tr>
 318             <tr>
 319                 <td><em>AsTemplate</em></td>
 320                 <td>T</td>
 321                 <td><member>MediaDescriptor::AsTemplate</member></td>
 322             </tr>
 323             <tr>
 324                 <td><em>Hidden</em></td>
 325                 <td>H</td>
 326                 <td><member>MediaDescriptor::Hidden</member></td>
 327             </tr>
 328         </table>
 329         </p>
 330
 331         @deprecated
 332      */
 333     [optional,property] string OpenFlags;
 334
 335     //-------------------------------------------------------------------------
 336     /** opens a new view for an already loaded document
 337
 338         <p>
 339         Setting this to <TRUE/> forces the component to create a new window on loading
 340         in any case. If the component supports multiple views, a second view is
 341         opened, if not, the component is loaded one more time. Otherwise the behavior
 342         depends on the default window handling of the <type scope="com::sun::star::frame">Desktop</type> environment.
 343         </p>
 344      */
 345     [optional,property] boolean OpenNewView;
 346
 347
 348     //-------------------------------------------------------------------------
 349     /** overwrite any existing file
 350
 351         <p>
 352         For storing only: overwrite any existing file, default is <FALSE/>,
 353         so an error occurs if the target file already exists.
 354         </p>
 355      */
 356     [optional,property] boolean Overwrite;
 357
 358     //-------------------------------------------------------------------------
 359     /** pasword for loading storing documents
 360
 361         <p>
 362         It caontains a password for loading or storing a component (if necessary).
 363         If no password is specified, loading of a password protected document
 364         will fail, storing will be done without encryption.
 365         </p>
 366      */
 367     [optional,property] string Password;
 368
 369     //-------------------------------------------------------------------------
 370     /** contains the data for HTTP post method as a sequence of bytes.
 371
 372         <p>
 373         Data to send to a location described by the media descriptor to get
 374         a result in return that will be loaded as a component
 375         (usually in webforms). Default is: no PostData.
 376         </p>
 377      */
 378     [optional,property] sequence< byte > PostData;
 379
 380     //-------------------------------------------------------------------------
 381     /** use <member>MediaDescriptor::PostData</member> instead of this
 382
 383         <p>
 384         Same as PostData, but the data is transferred as a string
 385         (just for compatibility).
 386         </p>
 387
 388         @deprecated
 389      */
 390     [optional,property] string PostString;
 391
 392     //-------------------------------------------------------------------------
 393     /** show preview
 394
 395         <p>
 396         Setting this to <TRUE/> tells the a loaded component that it is loaded as
 397         a preview, so it can optimize loading and viewing for this special purpose.
 398         Default is <FALSE/>.
 399         </p>
 400      */
 401     [optional,property] boolean Preview;
 402
 403     //-------------------------------------------------------------------------
 404     /** open document readonly
 405
 406         <p>
 407         Tells whether a document should be loaded in a (logical) readonly or in
 408         read/write mode. If opening in the desired mode is impossible, an error occurs.
 409         By default the loaded content decides what to do: if its UCB content supports
 410         a "readonly" property, the logical open mode depends on that, otherwise
 411         it will be read/write. This is only a UI related property, opening a
 412         document in read only mode will not prevent the component from being
 413         modified by API calls, but all modifying functionality in the UI will
 414         be disabled or removed.
 415         </p>
 416      */
 417     [optional,property] boolean ReadOnly;
 418
 419     //-------------------------------------------------------------------------
 420     /** start presentation from a document
 421
 422         <p>
 423         Tells the component loading the document that a presentation that is in the
 424         document is to be started right away.
 425         </p>
 426     */
 427     [optional,property] boolean StartPresentation;
 428
 429     //-------------------------------------------------------------------------
 430     /** name of document referrer
 431
 432         <p>
 433         A URL describing the environment of the request; f.e. a referrer may be a
 434         URL of a document, if a hyperlink inside this document is clicked to load
 435         another document. The referrer may be evaluated by the addressed UCB content
 436         or the loaded document. Without a referrer the processing of URLs that
 437         needs security checks will be denied, f.e. "macro:" URLs.
 438         <br>
 439         Don't be confused about the wrong spelling; is kept for compatibility reasons.
 440         </p>
 441      */
 442     [optional,property] string Referer;
 443
 444     //-------------------------------------------------------------------------
 445     /** let the document be opened in repair mode
 446
 447         <p>
 448         For loading of corrupted zip packages: Setting this to <TRUE/> let the document
 449         be opened in repair mode, so as much as possible information will be retrieved.
 450         </p>
 451
 452      @since OOo 1.1.2
 453      */
 454     [optional,property] boolean RepairPackage;
 455
 456     //-------------------------------------------------------------------------
 457     /** can be used for status informations
 458
 459         <p>
 460         Object implementing the <type scope="com::sun::star::task">XStatusIndicator</type>
 461         interface that can be used to give status information (text or progress) for the task.
 462         The office provides a default implementation for it. It is not allowed to keep
 463         a reference to this object, even not in the loaded or stored components'
 464         copy of the MediaDescriptor provided by its arguments attribute.
 465         </p>
 466      */
 467     [optional,property] com::sun::star::task::XStatusIndicator StatusIndicator;
 468
 469     //-------------------------------------------------------------------------
 470     /** allows to specify the URL that is used next time SaveAs dialog is opened
 471
 472         <p>
 473         If the parameter is specified, the URL will be used by SaveAs dialog
 474         next time as target folder.
 475         </p>
 476      */
 477     [optional,property] string SuggestedSaveAsDir;
 478
 479     //-------------------------------------------------------------------------
 480     /** allows to specify the suggested file name that is used next time SaveAs
 481         dialog is opened
 482
 483         <p>
 484         If the parameter is specified, the file name will be suggested by
 485         SaveAs dialog next time.
 486         </p>
 487      */
 488     [optional,property] string SuggestedSaveAsName;
 489
 490     //-------------------------------------------------------------------------
 491     /** name of the template instead of the URL
 492
 493         <p>
 494         The logical name of a template to load. Together with the <member>MediaDescriptor::TemplateRegion</member>
 495         property it can be used instead of the URL of the template. Use always in conjunction with
 496         <member>MediaDescriptor::TemplateRegionName</member>.
 497         </p>
 498      */
 499     [optional,property] string TemplateName;
 500
 501     //-------------------------------------------------------------------------
 502     /** name of the template instead of the URL
 503
 504         <p>
 505         The logical name of a template to load. Together with the <member>MediaDescriptor::TemplateRegion</member>
 506         property it can be used instead of the URL of the template. Use always in conjunction with
 507         <member>MediaDescriptor::TemplateRegionName</member>.
 508         </p>
 509      */
 510     [optional,property] string TemplateRegionName;
 511
 512     //-------------------------------------------------------------------------
 513     /** regulate using of compressing
 514
 515         <p>
 516         For storing: Setting this to <TRUE/> means, don't use a zip file to save
 517         the document, use a folder instead (only usable for UCB contents, that
 518         support folders). Default is <FALSE/>.
 519         </p>
 520      */
 521     [optional,property] boolean Unpacked;
 522
 523     //-------------------------------------------------------------------------
 524     /** URL of the document
 525
 526         <p>
 527         The location of the component in URL syntax. It must be the full qualified URL and
 528         must include f.e. an optional <member>MediaDescriptor::JumpMark</member> too.
 529         </p>
 530      */
 531     [optional,property] string URL;
 532
 533     //-------------------------------------------------------------------------
 534     /** storage version
 535
 536         <p>
 537         For components supporting versioning: the number of the version to be
 538         loaded or saved. Default is zero and means: no version is created or
 539         loaded, the "main" document is processed.
 540         </p>
 541      */
 542     [optional,property] short Version;
 543
 544     //-------------------------------------------------------------------------
 545     /** set special view state
 546         <p>
 547         Data to set a special view state after loading. The type depends on
 548         the component and is usually retrieved from a <type scope="com::sun::star::frame">Controller</type>
 549         object by its <type scope="com::sun::star::frame">XController</type>
 550         interface. Default is: no view data.
 551         </p>
 552      */
 553     [optional,property] any ViewData;
 554
 555     //-------------------------------------------------------------------------
 556     /** id of the initial view
 557
 558         <p>
 559         For components supporting different views: a number to define the view
 560         that should be constructed after loading. Default is: zero, and this
 561         should be treated by the component as the default view.
 562         </p>
 563      */
 564     [optional,property] short ViewId;
 565
 566     //-------------------------------------------------------------------------
 567     /** should the macro be executed.
 568         the value should be one from <type scope="com::sun::star::document">MacroExecMode</type>
 569         constant list.
 570
 571         @since OOo 1.1.2
 572      */
 573     [optional,property] short MacroExecutionMode;
 574
 575     //-------------------------------------------------------------------------
 576     /** can the document be updated depending from links.
 577         the value should be one from <type scope="com::sun::star::document">UpdateDocMode</type>
 578         constant list.
 579
 580         @since OOo 1.1.2
 581      */
 582     [optional,property] short UpdateDocMode;
 583
 584     //-------------------------------------------------------------------------
 585     /** specifies the name of the view controller to create when loading a document
 586
 587         <p>If this property is used when loading a document into a frame, then it
 588         specifies the name of the view controller to create. That is, the property
 589         is passed to the document's <member scope="com::sun::star::frame">XModel2::createViewController</member>
 590         method.<br/>
 591         If the loaded document does not support the <code>XModel2</code> interface,
 592         the property is ignored.</p>
 593
 594         @see ::com::sun::star::frame::XModel2::createViewController
 595         @see ::com::sun::star::frame::XController2::ViewControllerName
 596
 597         @since OOo 3.0
 598      */
 599     [optional,property] string ViewControllerName;
 600 };
 601
 602 //=============================================================================
 603
 604 }; }; }; };
 605
 606 #endif