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