include/vcl/pdfextoutdevdata.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_VCL_PDFEXTOUTDEVDATA_HXX
  21 #define INCLUDED_VCL_PDFEXTOUTDEVDATA_HXX
  22
  23 #include <vcl/dllapi.h>
  24
  25 #include <vcl/pdfwriter.hxx>
  26 #include <vcl/extoutdevdata.hxx>
  27 #include <vcl/gdimtf.hxx>
  28 #include <vcl/mapmod.hxx>
  29 #include <vector>
  30 #include <deque>
  31
  32 class Graphic;
  33
  34 namespace vcl { class PDFWriter; }
  35
  36 namespace vcl
  37 {
  38
  39 /*
  40     A PDFExtOutDevBookmarkEntry is being created by the EditEngine if
  41     a bookmark URL has been parsed. The Application is requested to take
  42     care of each bookmark entry by emptying out the bookmark vector.
  43 */
  44 struct PDFExtOutDevBookmarkEntry
  45 {
  46     /** ID of the link pointing to the bookmark, or -1 if the entry denotes a destination instead of a link.
  47     */
  48     sal_Int32       nLinkId;
  49
  50     /** ID of the named destination denoted by the bookmark, or -1 if the entry denotes a link instead of a named destination.
  51     */
  52     sal_Int32       nDestId;
  53
  54     /** link target name, respectively destination name
  55     */
  56     OUString   aBookmark;
  57
  58     PDFExtOutDevBookmarkEntry()
  59         :nLinkId( -1 )
  60         ,nDestId( -1 )
  61         ,aBookmark()
  62     {
  63     }
  64 };
  65
  66 /*
  67  Class that is being set at the OutputDevice allowing the
  68  application to send enhanced PDF commands like CreateLink
  69 */
  70 struct PageSyncData;
  71 struct GlobalSyncData;
  72 class VCL_DLLPUBLIC PDFExtOutDevData : public ExtOutDevData
  73 {
  74
  75     const OutputDevice&         mrOutDev;
  76
  77     bool                        mbTaggedPDF;
  78     bool                        mbExportNotes;
  79     bool                        mbExportNotesPages;
  80     bool                        mbTransitionEffects;
  81     bool                        mbUseLosslessCompression;
  82     bool                        mbReduceImageResolution;
  83     bool                        mbExportFormFields;
  84     bool                        mbExportBookmarks;
  85     bool                        mbExportHiddenSlides;
  86     bool                        mbExportNDests; //i56629
  87     sal_Int32                   mnFormsFormat;
  88     sal_Int32                   mnPage;
  89     sal_Int32                   mnCompressionQuality;
  90     sal_Int32                   mnMaxImageResolution;
  91     css::lang::Locale           maDocLocale;
  92
  93     PageSyncData*               mpPageSyncData;
  94     GlobalSyncData*             mpGlobalSyncData;
  95
  96     std::vector< PDFExtOutDevBookmarkEntry > maBookmarks;
  97
  98 public:
  99
 100     PDFExtOutDevData( const OutputDevice& rOutDev );
 101     virtual ~PDFExtOutDevData() override;
 102
 103     bool PlaySyncPageAct( PDFWriter& rWriter, sal_uInt32& rCurGDIMtfAction );
 104     void ResetSyncData();
 105
 106     void PlayGlobalActions( PDFWriter& rWriter );
 107
 108     bool    GetIsExportNotes() const { return mbExportNotes;}
 109     void        SetIsExportNotes( const bool bExportNotes );
 110
 111     bool    GetIsExportNotesPages() const { return mbExportNotesPages;}
 112     void        SetIsExportNotesPages( const bool bExportNotesPages );
 113
 114     bool    GetIsExportTaggedPDF() const { return mbTaggedPDF;}
 115     void        SetIsExportTaggedPDF( const bool bTaggedPDF );
 116
 117     bool    GetIsExportTransitionEffects() const { return mbTransitionEffects;}
 118     void        SetIsExportTransitionEffects( const bool bTransitionalEffects );
 119
 120     bool    GetIsExportFormFields() const { return mbExportFormFields;}
 121     void        SetIsExportFormFields( const bool bExportFormFields );
 122
 123     void        SetFormsFormat( const sal_Int32 nFormsFormat );
 124
 125     bool    GetIsExportBookmarks() const { return mbExportBookmarks;}
 126     void        SetIsExportBookmarks( const bool bExportBookmarks );
 127
 128     bool    GetIsExportHiddenSlides() const { return mbExportHiddenSlides;}
 129     void        SetIsExportHiddenSlides( const bool bExportHiddenSlides );
 130
 131     bool    GetIsExportNamedDestinations() const { return mbExportNDests;} //i56629
 132     void        SetIsExportNamedDestinations( const bool bExportNDests ); //i56629
 133
 134     // PageNumber, Compression is being set by the PDFExport
 135     sal_Int32   GetCurrentPageNumber() const { return mnPage;}
 136     void        SetCurrentPageNumber( const sal_Int32 nPage );
 137
 138     bool        GetIsLosslessCompression() const { return mbUseLosslessCompression;}
 139     void        SetIsLosslessCompression( const bool bLosslessCompression );
 140
 141     void        SetCompressionQuality( const sal_Int32 nQuality );
 142
 143     void        SetMaxImageResolution( const sal_Int32 nQuality );
 144
 145     bool        GetIsReduceImageResolution() const { return mbReduceImageResolution;}
 146     void        SetIsReduceImageResolution( const bool bReduceImageResolution );
 147
 148     const css::lang::Locale& GetDocumentLocale() const { return maDocLocale;}
 149     void        SetDocumentLocale( const css::lang::Locale& rLoc );
 150
 151     std::vector< PDFExtOutDevBookmarkEntry >& GetBookmarks() { return maBookmarks;}
 152
 153     const Graphic& GetCurrentGraphic() const;
 154
 155     /** Start a new group of render output
 156
 157         Use this method to group render output.
 158      */
 159     void        BeginGroup();
 160
 161     /** End render output
 162
 163         This method ends grouped render output, that can be
 164         represented by a GfxLink. This is typically used for
 165         external graphic files, such as JPEGs, EPS files etc.
 166         The BeginGroup/EndGroup calls must exactly enclose the
 167         relevant OutputDevice calls issued to render the
 168         graphic the normal way.
 169
 170         @param rGraphic
 171         The link to the original graphic
 172
 173         @param nTransparency
 174         Eight bit transparency value, with 0 denoting full opacity,
 175         and 255 full transparency.
 176
 177         @param rOutputRect
 178         The output rectangle of the graphic.
 179
 180         @param rVisibleOutputRect
 181         The visible part of the output. This might be less than
 182         rOutputRect, e.g. for cropped graphics.
 183      */
 184     void        EndGroup( const Graphic&    rGraphic,
 185                           sal_uInt8         nTransparency,
 186                           const tools::Rectangle&  rOutputRect,
 187                           const tools::Rectangle&  rVisibleOutputRect );
 188
 189     /// Detect if stream is compressed enough to avoid de-compress / scale & re-compress
 190     bool        HasAdequateCompression( const Graphic &rGraphic ) const;
 191
 192 //--->i56629
 193     /** Create a new named destination to be used in a link to this document from another PDF document
 194  (see PDF spec 1.4, 8.2.1)
 195
 196     @param sDestName
 197     the name this destination will be addressed with from others PDF document
 198
 199     @param rRect
 200     target rectangle on page to be displayed if dest is jumped to
 201
 202     @param nPageNr
 203     number of page the dest is on (as returned by NewPage)
 204     or -1 in which case the current page is used
 205
 206     @returns
 207     the destination id (to be used in SetLinkDest) or
 208     -1 if page id does not exist
 209     */
 210     sal_Int32 CreateNamedDest( const OUString& sDestName,  const tools::Rectangle& rRect, sal_Int32 nPageNr = -1 );
 211
 212     /** registers a destination for which a destination ID needs to be known immediately, instead of later on setting it via
 213         SetLinkDest.
 214
 215         This is used in contexts where a destination is referenced by means other than a link.
 216
 217         Later in the export process, a call to DescribeRegisteredDest must be made, providing the information about
 218         the destination.
 219
 220         @return
 221             the unique Id of the destination
 222     */
 223     sal_Int32   RegisterDest();
 224
 225     /** provides detailed information about a destination range which previously has been registered using RegisterDest.
 226     */
 227     void        DescribeRegisteredDest( sal_Int32 nDestId, const tools::Rectangle& rRect, sal_Int32 nPageNr, PDFWriter::DestAreaType eType = PDFWriter::DestAreaType::XYZ );
 228
 229 //<---i56629
 230
 231     /** Create a new destination to be used in a link
 232
 233     @param rRect
 234     target rectangle on page to be displayed if dest is jumped to
 235
 236     @param nPageNr
 237     number of page the dest is on (as returned by NewPage)
 238     or -1 in which case the current page is used
 239
 240     @param eType
 241     what dest type to use
 242
 243     @returns
 244     the destination id (to be used in SetLinkDest) or
 245     -1 if page id does not exist
 246     */
 247     sal_Int32 CreateDest( const tools::Rectangle& rRect, sal_Int32 nPageNr = -1, PDFWriter::DestAreaType eType = PDFWriter::DestAreaType::XYZ );
 248     /** Create a new link on a page
 249
 250     @param rRect
 251     active rectangle of the link (that is the area that has to be
 252     hit to activate the link)
 253
 254     @param nPageNr
 255     number of page the link is on (as returned by NewPage)
 256     or -1 in which case the current page is used
 257
 258     @returns
 259     the link id (to be used in SetLinkDest, SetLinkURL) or
 260     -1 if page id does not exist
 261     */
 262     sal_Int32 CreateLink( const tools::Rectangle& rRect, sal_Int32 nPageNr = -1 );
 263
 264     /// Create a Screen annotation.
 265     sal_Int32 CreateScreen(const tools::Rectangle& rRect, sal_Int32 nPageNr);
 266
 267     /** Set the destination for a link
 268         <p>will change a URL type link to a dest link if necessary</p>
 269
 270         @param nLinkId
 271         the link to be changed
 272
 273         @param nDestId
 274         the dest the link shall point to
 275         @returns
 276         0 for success
 277         -1 in case the link id does not exist
 278         -2 in case the dest id does not exist
 279     */
 280     sal_Int32 SetLinkDest( sal_Int32 nLinkId, sal_Int32 nDestId );
 281     /** Set the URL for a link
 282         <p>will change a dest type link to an URL type link if necessary</p>
 283         @param nLinkId
 284         the link to be changed
 285
 286         @param rURL
 287         the URL the link shall point to.
 288         there will be no error checking or any kind of
 289         conversion done to this parameter execept this:
 290         it will be output as 7bit Ascii. The URL
 291         will appear literally in the PDF file produced
 292
 293         @returns
 294         0 for success
 295         -1 in case the link id does not exist
 296     */
 297     sal_Int32 SetLinkURL( sal_Int32 nLinkId, const OUString& rURL );
 298
 299     /// Set URL for a linked Screen annotation.
 300     void SetScreenURL(sal_Int32 nScreenId, const OUString& rURL);
 301     /// Set URL for an embedded Screen annotation.
 302     void SetScreenStream(sal_Int32 nScreenId, const OUString& rURL);
 303
 304     /** Create a new outline item
 305
 306         @param nParent
 307         declares the parent of the new item in the outline hierarchy.
 308         An invalid value will result in a new toplevel item.
 309
 310         @param rText
 311         sets the title text of the item
 312
 313         @param nDestID
 314         declares which Dest (created with CreateDest) the outline item
 315         will point to
 316
 317         @returns
 318         the outline item id of the new item
 319     */
 320     sal_Int32 CreateOutlineItem( sal_Int32 nParent, const OUString& rText, sal_Int32 nDestID );
 321
 322     /** Create a new note on a page
 323
 324     @param rRect
 325     active rectangle of the note (that is the area that has to be
 326     hit to popup the annotation)
 327
 328     @param rNote
 329     specifies the contents of the note
 330
 331     @param nPageNr
 332     number of page the note is on (as returned by NewPage)
 333     or -1 in which case the current page is used
 334     */
 335     void CreateNote( const tools::Rectangle& rRect, const PDFNote& rNote, sal_Int32 nPageNr = -1 );
 336
 337     /** begin a new logical structure element
 338
 339     BeginStructureElement/EndStructureElement calls build the logical structure
 340     of the PDF - the basis for tagged PDF. Structural elements are implemented
 341     using marked content tags. Each structural element can contain sub elements
 342     (e.g. a section can contain a heading and a paragraph). The structure hierarchy
 343     is build automatically from the Begin/EndStructureElement calls.
 344
 345     A structural element need not be contained on one page; e.g. paragraphs often
 346     run from one page to the next. In this case the corresponding EndStructureElement
 347     must be called while drawing the next page.
 348
 349     BeginStructureElement and EndStructureElement must be called only after
 350     PDFWriter::NewPage has been called and before
 351     PDFWriter::Emit gets called. The current page
 352     number is an implicit context parameter for Begin/EndStructureElement.
 353
 354     For pagination artifacts that are not part of the logical structure
 355     of the document (like header, footer or page number) the special
 356     StructElement NonStructElement exists. To place content
 357     outside of the structure tree simply call
 358     BeginStructureElement( NonStructElement ) then draw your
 359     content and then call EndStructureElement(). Any children
 360     of a NonStructElement will not be part of the structure as well.
 361
 362     @param eType
 363     denotes what kind of element to begin (e.g. a heading or paragraph)
 364
 365     @param rAlias
 366     the specified alias will be used as structure tag. Also an entry in the PDF's
 367     role map will be created mapping alias to regular structure type.
 368
 369     @returns
 370     the id of the newly created structural element
 371      */
 372      sal_Int32 BeginStructureElement( PDFWriter::StructElement eType, const OUString& rAlias = OUString() );
 373     /** end a logical structure element
 374
 375     @see BeginStructureElement
 376      */
 377     void EndStructureElement();
 378     /** set the current structure element
 379
 380     <p>
 381     For different purposes it may be useful to paint a structure element's
 382     content discontinously. In that case an already existing structure element
 383     can be appended to by using SetCurrentStructureElement. The
 384     refenrenced structure element becomes the current structure element with
 385     all consequences: all following structure elements are appended as children
 386     of the current element.
 387     </p>
 388
 389     @param nElement
 390     the id of the new current structure element
 391
 392     @returns
 393     True if the current structure element could be set successfully
 394     False if the current structure element could not be changed
 395     (e.g. if the passed element id is invalid)
 396      */
 397     bool SetCurrentStructureElement( sal_Int32 nElement );
 398     /** get the current structure element id
 399
 400     @returns
 401     the id of the current structure element
 402     */
 403     sal_Int32 GetCurrentStructureElement();
 404
 405     /** set a structure attribute on the current structural element
 406
 407     SetStructureAttribute sets an attribute of the current structural element to a
 408     new value. A consistency check is performed before actually setting the value;
 409     if the check fails, the function returns False and the attribute remains
 410     unchanged.
 411
 412     @param eAttr
 413     denotes what attribute to change
 414
 415     @param eVal
 416     the value to set the attribute to
 417
 418     @returns
 419     True if the value was valid and the change has been performed,
 420     False if the attribute or value was invalid; attribute remains unchanged
 421      */
 422     bool SetStructureAttribute( PDFWriter::StructAttribute eAttr, PDFWriter::StructAttributeValue eVal );
 423     /** set a structure attribute on the current structural element
 424
 425     SetStructureAttributeNumerical sets an attribute of the current structural element
 426     to a new numerical value. A consistency check is performed before actually setting
 427     the value; if the check fails, the function returns False and the attribute
 428     remains unchanged.
 429
 430     @param eAttr
 431     denotes what attribute to change
 432
 433     @param nValue
 434     the value to set the attribute to
 435
 436     @returns
 437     True if the value was valid and the change has been performed,
 438     False if the attribute or value was invalid; attribute remains unchanged
 439      */
 440     bool SetStructureAttributeNumerical( PDFWriter::StructAttribute eAttr, sal_Int32 nValue );
 441     /** set the bounding box of a structural element
 442
 443     SetStructureBoundingBox sets the BBox attribute to a new value. Since the BBox
 444     attribute can only be applied to Table, Figure,
 445     Form and Formula elements, a call of this function
 446     for other element types will be ignored and the BBox attribute not be set.
 447
 448     @param rRect
 449     the new bounding box for the structural element
 450      */
 451     void SetStructureBoundingBox( const tools::Rectangle& rRect );
 452
 453     /** set the ActualText attribute of a structural element
 454
 455     ActualText contains the Unicode text without layout artifacts that is shown by
 456     a structural element. For example if a line is ended prematurely with a break in
 457     a word and continued on the next line (e.g. "happen-<newline>stance") the
 458     corresponding ActualText would contain the unbroken line (e.g. "happenstance").
 459
 460     @param rText
 461     contains the complete logical text the structural element displays.
 462      */
 463     void SetActualText( const OUString& rText );
 464
 465     /** set the Alt attribute of a strutural element
 466
 467     Alt is s replacement text describing the contents of a structural element. This
 468     is mainly used by accessibility applications; e.g. a screen reader would read
 469     the Alt replacement text for an image to a visually impaired user.
 470
 471     @param rText
 472     contains the replacement text for the structural element
 473     */
 474     void SetAlternateText( const OUString& rText );
 475
 476     /** Sets the transitional effect to be applied when the current page gets shown.
 477
 478     @param eType
 479     the kind of effect to be used; use Regular to disable transitional effects
 480     for this page
 481
 482     @param nMilliSec
 483     the duration of the transitional effect in milliseconds;
 484     set 0 to disable transitional effects
 485     */
 486     void SetPageTransition( PDFWriter::PageTransition eType, sal_uInt32 nMilliSec );
 487
 488     /** create a new form control
 489
 490     This function creates a new form control in the PDF and sets its various
 491     properties. Do not pass an actual AnyWidget as rControlType
 492     will be cast to the type described by the type member.
 493
 494     @param rControlType
 495     a descendant of AnyWidget determining the control's properties
 496      */
 497     void    CreateControl( const PDFWriter::AnyWidget& rControlType );
 498 };
 499
 500 }
 501
 502 #endif
 503
 504 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */