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