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