1 /* poppler-qt.h: qt interface to poppler 2 * Copyright (C) 2005, Net Integration Technologies, Inc. 3 * Copyright (C) 2005, 2007, Brad Hards <bradh@frogmouth.net> 4 * Copyright (C) 2005-2015, 2017-2021, Albert Astals Cid <aacid@kde.org> 5 * Copyright (C) 2005, Stefan Kebekus <stefan.kebekus@math.uni-koeln.de> 6 * Copyright (C) 2006-2011, Pino Toscano <pino@kde.org> 7 * Copyright (C) 2009 Shawn Rutledge <shawn.t.rutledge@gmail.com> 8 * Copyright (C) 2010 Suzuki Toshiya <mpsuzuki@hiroshima-u.ac.jp> 9 * Copyright (C) 2010 Matthias Fauconneau <matthias.fauconneau@gmail.com> 10 * Copyright (C) 2011 Andreas Hartmetz <ahartmetz@gmail.com> 11 * Copyright (C) 2011 Glad Deschrijver <glad.deschrijver@gmail.com> 12 * Copyright (C) 2012, Guillermo A. Amaral B. <gamaral@kde.org> 13 * Copyright (C) 2012, Fabio D'Urso <fabiodurso@hotmail.it> 14 * Copyright (C) 2012, Tobias Koenig <tobias.koenig@kdab.com> 15 * Copyright (C) 2012, 2014, 2015, 2018, 2019 Adam Reichold <adamreichold@myopera.com> 16 * Copyright (C) 2012, 2013 Thomas Freitag <Thomas.Freitag@alfa.de> 17 * Copyright (C) 2013 Anthony Granger <grangeranthony@gmail.com> 18 * Copyright (C) 2016 Jakub Alba <jakubalba@gmail.com> 19 * Copyright (C) 2017, 2020, 2021 Oliver Sander <oliver.sander@tu-dresden.de> 20 * Copyright (C) 2017, 2018 Klarälvdalens Datakonsult AB, a KDAB Group company, <info@kdab.com>. Work sponsored by the LiMux project of the city of Munich 21 * Copyright (C) 2018, 2021 Nelson Benítez León <nbenitezl@gmail.com> 22 * Copyright (C) 2019 Jan Grulich <jgrulich@redhat.com> 23 * Copyright (C) 2019 Alexander Volkov <a.volkov@rusbitech.ru> 24 * Copyright (C) 2020 Philipp Knechtges <philipp-dev@knechtges.com> 25 * Copyright (C) 2020 Katarina Behrens <Katarina.Behrens@cib.de> 26 * Copyright (C) 2020 Thorsten Behrens <Thorsten.Behrens@CIB.de> 27 * Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, <info@kdab.com>. Work sponsored by Technische Universität Dresden 28 * Copyright (C) 2021 Klarälvdalens Datakonsult AB, a KDAB Group company, <info@kdab.com>. 29 * Copyright (C) 2021 Mahmoud Khalil <mahmoudkhalil11@gmail.com> 30 * Copyright (C) 2021 Georgiy Sgibnev <georgiy@sgibnev.com>. Work sponsored by lab50.net. 31 * 32 * This program is free software; you can redistribute it and/or modify 33 * it under the terms of the GNU General Public License as published by 34 * the Free Software Foundation; either version 2, or (at your option) 35 * any later version. 36 * 37 * This program is distributed in the hope that it will be useful, 38 * but WITHOUT ANY WARRANTY; without even the implied warranty of 39 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 40 * GNU General Public License for more details. 41 * 42 * You should have received a copy of the GNU General Public License 43 * along with this program; if not, write to the Free Software 44 * Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA. 45 */ 46 47 #ifndef __POPPLER_QT_H__ 48 #define __POPPLER_QT_H__ 49 50 #include <functional> 51 #include <memory> 52 #include <vector> 53 54 #include "poppler-annotation.h" 55 #include "poppler-link.h" 56 #include "poppler-optcontent.h" 57 #include "poppler-page-transition.h" 58 59 #include <QtCore/QByteArray> 60 #include <QtCore/QDateTime> 61 #include <QtCore/QIODevice> 62 #include <QtCore/QSet> 63 #include "poppler-export.h" 64 65 class EmbFile; 66 class Sound; 67 class AnnotMovie; 68 69 /** 70 The %Poppler Qt6 binding. 71 */ 72 namespace Poppler { 73 74 class Document; 75 class DocumentData; 76 77 class PageData; 78 79 class FormField; 80 class FormFieldSignature; 81 82 class TextBoxData; 83 84 class PDFConverter; 85 class PSConverter; 86 87 struct OutlineItemData; 88 89 /** 90 Debug/error function. 91 92 This function type is used for debugging & error output; 93 the first parameter is the actual message, the second is the unaltered 94 closure argument which was passed to the setDebugErrorFunction call. 95 */ 96 typedef void (*PopplerDebugFunc)(const QString & /*message*/, const QVariant & /*closure*/); 97 98 /** 99 Set a new debug/error output function. 100 101 If not set, by default error and debug messages will be sent to the 102 Qt \p qDebug() function. 103 104 \param debugFunction the new debug function 105 \param closure user data which will be passes as-is to the debug function 106 */ 107 POPPLER_QT6_EXPORT void setDebugErrorFunction(PopplerDebugFunc debugFunction, const QVariant &closure); 108 109 /** 110 Describes the physical location of text on a document page 111 112 This very simple class describes the physical location of text 113 on the page. It consists of 114 - a QString that contains the text 115 - a QRectF that gives a box that describes where on the page 116 the text is found. 117 */ 118 class POPPLER_QT6_EXPORT TextBox 119 { 120 friend class Page; 121 122 public: 123 /** 124 The default constructor sets the \p text and the rectangle that 125 contains the text. Coordinates for the \p bBox are in points = 126 1/72 of an inch. 127 */ 128 TextBox(const QString &text, const QRectF &bBox); 129 /** 130 Destructor. 131 */ 132 ~TextBox(); 133 134 /** 135 Returns the text of this text box 136 */ 137 QString text() const; 138 139 /** 140 Returns the position of the text, in point, i.e., 1/72 of 141 an inch 142 */ 143 QRectF boundingBox() const; 144 145 /** 146 Returns the pointer to the next text box, if there is one. 147 148 Otherwise, it returns a null pointer. 149 */ 150 TextBox *nextWord() const; 151 152 /** 153 Returns the bounding box of the \p i -th characted of the word. 154 */ 155 QRectF charBoundingBox(int i) const; 156 157 /** 158 Returns whether there is a space character after this text box 159 */ 160 bool hasSpaceAfter() const; 161 162 private: 163 Q_DISABLE_COPY(TextBox) 164 165 TextBoxData *m_data; 166 }; 167 168 class FontInfoData; 169 /** 170 Container class for information about a font within a PDF 171 document 172 */ 173 class POPPLER_QT6_EXPORT FontInfo 174 { 175 friend class Document; 176 177 public: 178 /** 179 The type of font. 180 */ 181 enum Type 182 { 183 unknown, 184 Type1, 185 Type1C, 186 Type1COT, 187 Type3, 188 TrueType, 189 TrueTypeOT, 190 CIDType0, 191 CIDType0C, 192 CIDType0COT, 193 CIDTrueType, 194 CIDTrueTypeOT 195 }; 196 197 /// \cond PRIVATE 198 /** 199 Create a new font information container. 200 */ 201 FontInfo(); 202 203 /** 204 Create a new font information container. 205 */ 206 explicit FontInfo(const FontInfoData &fid); 207 /// \endcond 208 209 /** 210 Copy constructor. 211 */ 212 FontInfo(const FontInfo &fi); 213 214 /** 215 Destructor. 216 */ 217 ~FontInfo(); 218 219 /** 220 The name of the font. Can be a null QString if the font has no name 221 */ 222 QString name() const; 223 224 /** 225 The name of the substitute font. Can be a null QString if the font has no substitute font 226 */ 227 QString substituteName() const; 228 229 /** 230 The path of the font file used to represent this font on this system, 231 or a null string is the font is embedded 232 */ 233 QString file() const; 234 235 /** 236 Whether the font is embedded in the file, or not 237 238 \return true if the font is embedded 239 */ 240 bool isEmbedded() const; 241 242 /** 243 Whether the font provided is only a subset of the full 244 font or not. This only has meaning if the font is embedded. 245 246 \return true if the font is only a subset 247 */ 248 bool isSubset() const; 249 250 /** 251 The type of font encoding 252 253 \return a enumerated value corresponding to the font encoding used 254 255 \sa typeName for a string equivalent 256 */ 257 Type type() const; 258 259 /** 260 The name of the font encoding used 261 262 \note if you are looking for the name of the font (as opposed to the 263 encoding format used), you probably want name(). 264 265 \sa type for a enumeration version 266 */ 267 QString typeName() const; 268 269 /** 270 Standard assignment operator 271 */ 272 FontInfo &operator=(const FontInfo &fi); 273 274 private: 275 FontInfoData *m_data; 276 }; 277 278 class FontIteratorData; 279 /** 280 Iterator for reading the fonts in a document. 281 282 FontIterator provides a Java-style iterator for reading the fonts in a 283 document. 284 285 You can use it in the following way: 286 \code 287 std::unique_ptr<Poppler::FontIterator> it = doc->newFontIterator(); 288 while (it->hasNext()) { 289 QList<Poppler::FontInfo> fonts = it->next(); 290 // do something with the fonts 291 } 292 // no need to free the iterator after doing the job 293 \endcode 294 */ 295 class POPPLER_QT6_EXPORT FontIterator 296 { 297 friend class Document; 298 friend class DocumentData; 299 300 public: 301 /** 302 Destructor. 303 */ 304 ~FontIterator(); 305 306 /** 307 Returns the fonts of the current page and then advances the iterator 308 to the next page. 309 */ 310 QList<FontInfo> next(); 311 312 /** 313 Checks whether there is at least one more page to iterate, ie returns 314 false when the iterator is beyond the last page. 315 */ 316 bool hasNext() const; 317 318 /** 319 Returns the current page where the iterator is. 320 */ 321 int currentPage() const; 322 323 private: 324 Q_DISABLE_COPY(FontIterator) 325 FontIterator(int, DocumentData *dd); 326 327 FontIteratorData *d; 328 }; 329 330 class EmbeddedFileData; 331 /** 332 Container class for an embedded file with a PDF document 333 */ 334 class POPPLER_QT6_EXPORT EmbeddedFile 335 { 336 friend class DocumentData; 337 friend class AnnotationPrivate; 338 339 public: 340 /// \cond PRIVATE 341 explicit EmbeddedFile(EmbFile *embfile); 342 /// \endcond 343 344 /** 345 Destructor. 346 */ 347 ~EmbeddedFile(); 348 349 /** 350 The name associated with the file 351 */ 352 QString name() const; 353 354 /** 355 The description associated with the file, if any. 356 357 This will return an empty QString if there is no description element 358 */ 359 QString description() const; 360 361 /** 362 The size of the file. 363 364 This will return < 0 if there is no size element 365 */ 366 int size() const; 367 368 /** 369 The modification date for the embedded file, if known. 370 */ 371 QDateTime modDate() const; 372 373 /** 374 The creation date for the embedded file, if known. 375 */ 376 QDateTime createDate() const; 377 378 /** 379 The MD5 checksum of the file. 380 381 This will return an empty QByteArray if there is no checksum element. 382 */ 383 QByteArray checksum() const; 384 385 /** 386 The MIME type of the file, if known. 387 */ 388 QString mimeType() const; 389 390 /** 391 The data as a byte array 392 */ 393 QByteArray data(); 394 395 /** 396 Is the embedded file valid? 397 */ 398 bool isValid() const; 399 400 /** 401 A QDataStream for the actual data? 402 */ 403 // QDataStream dataStream() const; 404 405 private: 406 Q_DISABLE_COPY(EmbeddedFile) 407 explicit EmbeddedFile(EmbeddedFileData &dd); 408 409 EmbeddedFileData *m_embeddedFile; 410 }; 411 412 /** 413 \brief A page in a document. 414 415 The Page class represents a single page within a PDF document. 416 417 You cannot construct a Page directly, but you have to use the Document 418 functions that return a new Page out of an index or a label. 419 */ 420 class POPPLER_QT6_EXPORT Page 421 { 422 friend class Document; 423 424 public: 425 /** 426 Destructor. 427 */ 428 ~Page(); 429 430 /** 431 The type of rotation to apply for an operation 432 */ 433 enum Rotation 434 { 435 Rotate0 = 0, ///< Do not rotate 436 Rotate90 = 1, ///< Rotate 90 degrees clockwise 437 Rotate180 = 2, ///< Rotate 180 degrees 438 Rotate270 = 3 ///< Rotate 270 degrees clockwise (90 degrees counterclockwise) 439 }; 440 441 /** 442 The kinds of page actions 443 */ 444 enum PageAction 445 { 446 Opening, ///< The action when a page is "opened" 447 Closing ///< The action when a page is "closed" 448 }; 449 450 /** 451 How the text is going to be returned 452 */ 453 enum TextLayout 454 { 455 PhysicalLayout, ///< The text is layouted to resemble the real page layout 456 RawOrderLayout ///< The text is returned without any type of processing 457 }; 458 459 /** 460 Additional flags for the renderToPainter method 461 */ 462 enum PainterFlag 463 { 464 NoPainterFlags = 0x00000000, 465 /** 466 Do not save/restore the caller-owned painter. 467 468 renderToPainter() by default preserves, using save() + restore(), 469 the state of the painter specified; if this is not needed, this 470 flag can avoid this job 471 */ 472 DontSaveAndRestore = 0x00000001 473 }; 474 Q_DECLARE_FLAGS(PainterFlags, PainterFlag) 475 476 /** 477 Render the page to a QImage using the current 478 \link Document::renderBackend() Document renderer\endlink. 479 480 If \p x = \p y = \p w = \p h = -1, the method will automatically 481 compute the size of the image from the horizontal and vertical 482 resolutions specified in \p xres and \p yres. Otherwise, the 483 method renders only a part of the page, specified by the 484 parameters (\p x, \p y, \p w, \p h) in pixel coordinates. The returned 485 QImage then has size (\p w, \p h), independent of the page 486 size. 487 488 \param x specifies the left x-coordinate of the box, in 489 pixels. 490 491 \param y specifies the top y-coordinate of the box, in 492 pixels. 493 494 \param w specifies the width of the box, in pixels. 495 496 \param h specifies the height of the box, in pixels. 497 498 \param xres horizontal resolution of the graphics device, 499 in dots per inch 500 501 \param yres vertical resolution of the graphics device, in 502 dots per inch 503 504 \param rotate how to rotate the page 505 506 \warning The parameter (\p x, \p y, \p w, \p h) are not 507 well-tested. Unusual or meaningless parameters may lead to 508 rather unexpected results. 509 510 \returns a QImage of the page, or a null image on failure. 511 */ 512 QImage renderToImage(double xres = 72.0, double yres = 72.0, int x = -1, int y = -1, int w = -1, int h = -1, Rotation rotate = Rotate0) const; 513 514 /** 515 Partial Update renderToImage callback. 516 517 This function type is used for doing partial rendering updates; 518 the first parameter is the image as rendered up to now, the second is the unaltered 519 closure argument which was passed to the renderToImage call. 520 */ 521 typedef void (*RenderToImagePartialUpdateFunc)(const QImage & /*image*/, const QVariant & /*closure*/); 522 523 /** 524 Partial Update query renderToImage callback. 525 526 This function type is used for query if the partial rendering update should happen; 527 the parameter is the unaltered closure argument which was passed to the renderToImage call. 528 */ 529 typedef bool (*ShouldRenderToImagePartialQueryFunc)(const QVariant & /*closure*/); 530 531 /** 532 Render the page to a QImage using the current 533 \link Document::renderBackend() Document renderer\endlink. 534 535 If \p x = \p y = \p w = \p h = -1, the method will automatically 536 compute the size of the image from the horizontal and vertical 537 resolutions specified in \p xres and \p yres. Otherwise, the 538 method renders only a part of the page, specified by the 539 parameters (\p x, \p y, \p w, \p h) in pixel coordinates. The returned 540 QImage then has size (\p w, \p h), independent of the page 541 size. 542 543 \param x specifies the left x-coordinate of the box, in 544 pixels. 545 546 \param y specifies the top y-coordinate of the box, in 547 pixels. 548 549 \param w specifies the width of the box, in pixels. 550 551 \param h specifies the height of the box, in pixels. 552 553 \param xres horizontal resolution of the graphics device, 554 in dots per inch 555 556 \param yres vertical resolution of the graphics device, in 557 dots per inch 558 559 \param rotate how to rotate the page 560 561 \param partialUpdateCallback callback that will be called to 562 report a partial rendering update 563 564 \param shouldDoPartialUpdateCallback callback that will be called 565 to ask if a partial rendering update is wanted. This exists 566 because doing a partial rendering update needs to copy the image 567 buffer so if it is not wanted it is better skipped early. 568 569 \param payload opaque structure that will be passed 570 back to partialUpdateCallback and shouldDoPartialUpdateCallback. 571 572 \warning The parameter (\p x, \p y, \p w, \p h) are not 573 well-tested. Unusual or meaningless parameters may lead to 574 rather unexpected results. 575 576 \returns a QImage of the page, or a null image on failure. 577 */ 578 QImage renderToImage(double xres, double yres, int x, int y, int w, int h, Rotation rotate, RenderToImagePartialUpdateFunc partialUpdateCallback, ShouldRenderToImagePartialQueryFunc shouldDoPartialUpdateCallback, 579 const QVariant &payload) const; 580 581 /** 582 Abort query function callback. 583 584 This function type is used for query if the current rendering/text extraction should be cancelled. 585 */ 586 typedef bool (*ShouldAbortQueryFunc)(const QVariant & /*closure*/); 587 588 /** 589 Render the page to a QImage using the current 590 \link Document::renderBackend() Document renderer\endlink. 591 592 If \p x = \p y = \p w = \p h = -1, the method will automatically 593 compute the size of the image from the horizontal and vertical 594 resolutions specified in \p xres and \p yres. Otherwise, the 595 method renders only a part of the page, specified by the 596 parameters (\p x, \p y, \p w, \p h) in pixel coordinates. The returned 597 QImage then has size (\p w, \p h), independent of the page 598 size. 599 600 \param x specifies the left x-coordinate of the box, in 601 pixels. 602 603 \param y specifies the top y-coordinate of the box, in 604 pixels. 605 606 \param w specifies the width of the box, in pixels. 607 608 \param h specifies the height of the box, in pixels. 609 610 \param xres horizontal resolution of the graphics device, 611 in dots per inch 612 613 \param yres vertical resolution of the graphics device, in 614 dots per inch 615 616 \param rotate how to rotate the page 617 618 \param partialUpdateCallback callback that will be called to 619 report a partial rendering update 620 621 \param shouldDoPartialUpdateCallback callback that will be called 622 to ask if a partial rendering update is wanted. This exists 623 because doing a partial rendering update needs to copy the image 624 buffer so if it is not wanted it is better skipped early. 625 626 \param shouldAbortRenderCallback callback that will be called 627 to ask if the rendering should be cancelled. 628 629 \param payload opaque structure that will be passed 630 back to partialUpdateCallback, shouldDoPartialUpdateCallback 631 and shouldAbortRenderCallback. 632 633 \warning The parameter (\p x, \p y, \p w, \p h) are not 634 well-tested. Unusual or meaningless parameters may lead to 635 rather unexpected results. 636 637 \returns a QImage of the page, or a null image on failure. 638 */ 639 QImage renderToImage(double xres, double yres, int x, int y, int w, int h, Rotation rotate, RenderToImagePartialUpdateFunc partialUpdateCallback, ShouldRenderToImagePartialQueryFunc shouldDoPartialUpdateCallback, 640 ShouldAbortQueryFunc shouldAbortRenderCallback, const QVariant &payload) const; 641 642 /** 643 Render the page to the specified QPainter using the current 644 \link Document::renderBackend() Document renderer\endlink. 645 646 If \p x = \p y = \p w = \p h = -1, the method will automatically 647 compute the size of the page area from the horizontal and vertical 648 resolutions specified in \p xres and \p yres. Otherwise, the 649 method renders only a part of the page, specified by the 650 parameters (\p x, \p y, \p w, \p h) in pixel coordinates. 651 652 \param painter the painter to paint on 653 654 \param x specifies the left x-coordinate of the box, in 655 pixels. 656 657 \param y specifies the top y-coordinate of the box, in 658 pixels. 659 660 \param w specifies the width of the box, in pixels. 661 662 \param h specifies the height of the box, in pixels. 663 664 \param xres horizontal resolution of the graphics device, 665 in dots per inch 666 667 \param yres vertical resolution of the graphics device, in 668 dots per inch 669 670 \param rotate how to rotate the page 671 672 \param flags additional painter flags 673 674 \warning The parameter (\p x, \p y, \p w, \p h) are not 675 well-tested. Unusual or meaningless parameters may lead to 676 rather unexpected results. 677 678 \returns whether the painting succeeded 679 680 \note This method is only supported for the QPainterOutputDev 681 */ 682 bool renderToPainter(QPainter *painter, double xres = 72.0, double yres = 72.0, int x = -1, int y = -1, int w = -1, int h = -1, Rotation rotate = Rotate0, PainterFlags flags = NoPainterFlags) const; 683 684 /** 685 Get the page thumbnail if it exists. 686 687 \return a QImage of the thumbnail, or a null image 688 if the PDF does not contain one for this page 689 */ 690 QImage thumbnail() const; 691 692 /** 693 Returns the text that is inside a specified rectangle 694 695 \param rect the rectangle specifying the area of interest, 696 with coordinates given in points, i.e., 1/72th of an inch. 697 If rect is null, all text on the page is given 698 **/ 699 QString text(const QRectF &rect, TextLayout textLayout) const; 700 701 /** 702 Returns the text that is inside a specified rectangle. 703 The text is returned using the physical layout of the page 704 705 \param rect the rectangle specifying the area of interest, 706 with coordinates given in points, i.e., 1/72th of an inch. 707 If rect is null, all text on the page is given 708 **/ 709 QString text(const QRectF &rect) const; 710 711 /** 712 The starting point for a search 713 */ 714 enum SearchDirection 715 { 716 FromTop, ///< Start sorting at the top of the document 717 NextResult, ///< Find the next result, moving "down the page" 718 PreviousResult ///< Find the previous result, moving "up the page" 719 }; 720 721 /** 722 The type of search to perform 723 */ 724 enum SearchMode 725 { 726 CaseSensitive, ///< Case differences cause no match in searching 727 CaseInsensitive ///< Case differences are ignored in matching 728 }; 729 730 /** 731 Flags to modify the search behaviour 732 */ 733 enum SearchFlag 734 { 735 NoSearchFlags = 0x00000000, 736 IgnoreCase = 0x00000001, ///< Case differences are ignored 737 WholeWords = 0x00000002, ///< Only whole words are matched 738 IgnoreDiacritics = 0x00000004, ///< Diacritic differences (eg. accents, umlauts, diaeresis) are ignored. 739 ///< This option will have no effect if the search term contains characters which 740 ///< are not pure ascii. 741 AcrossLines = 0x00000008 ///< Allows to match on text spanning from end of a line to the next line. 742 ///< It won't match on text spanning more than two lines. Automatically ignores hyphen 743 ///< at end of line, and allows whitespace in search term to match on newline. \since 21.05.0 744 }; 745 Q_DECLARE_FLAGS(SearchFlags, SearchFlag) 746 747 /** 748 Returns true if the specified text was found. 749 750 \param text the text the search 751 \param rectXXX in all directions is used to return where the text was found, for NextResult and PreviousResult 752 indicates where to continue searching for 753 \param direction in which direction do the search 754 \param flags the flags to consider during matching 755 \param rotate the rotation to apply for the search order 756 **/ 757 bool search(const QString &text, double &sLeft, double &sTop, double &sRight, double &sBottom, SearchDirection direction, SearchFlags flags = NoSearchFlags, Rotation rotate = Rotate0) const; 758 759 /** 760 Returns a list of all occurrences of the specified text on the page. 761 762 if SearchFlags::AcrossLines is given in \param flags, then rects may just 763 be parts of the text itself if it's split between multiple lines. 764 765 \param text the text to search 766 \param flags the flags to consider during matching 767 \param rotate the rotation to apply for the search order 768 769 \warning Do not use the returned QRectF as arguments of another search call because of truncation issues if qreal is defined as float. 770 **/ 771 QList<QRectF> search(const QString &text, SearchFlags flags = NoSearchFlags, Rotation rotate = Rotate0) const; 772 773 /** 774 Returns a list of text of the page 775 776 This method returns a QList of TextBoxes that contain all 777 the text of the page, with roughly one text word of text 778 per TextBox item. 779 780 For text written in western languages (left-to-right and 781 up-to-down), the QList contains the text in the proper 782 order. 783 784 \warning This method is not tested with Asian scripts 785 */ 786 std::vector<std::unique_ptr<TextBox>> textList(Rotation rotate = Rotate0) const; 787 788 /** 789 Returns a list of text of the page 790 791 This method returns a QList of TextBoxes that contain all 792 the text of the page, with roughly one text word of text 793 per TextBox item. 794 795 For text written in western languages (left-to-right and 796 up-to-down), the QList contains the text in the proper 797 order. 798 799 \param shouldAbortExtractionCallback callback that will be called 800 to ask if the text extraction should be cancelled. 801 802 \param closure opaque structure that will be passed 803 back to shouldAbortExtractionCallback. 804 805 \warning This method is not tested with Asian scripts 806 */ 807 std::vector<std::unique_ptr<TextBox>> textList(Rotation rotate, ShouldAbortQueryFunc shouldAbortExtractionCallback, const QVariant &closure) const; 808 809 /** 810 \return The dimensions (cropbox) of the page, in points (i.e. 1/72th of an inch) 811 */ 812 QSizeF pageSizeF() const; 813 814 /** 815 \return The dimensions (cropbox) of the page, in points (i.e. 1/72th of an inch) 816 */ 817 QSize pageSize() const; 818 819 /** 820 Returns the transition of this page 821 822 \returns a pointer to a PageTransition structure that 823 defines how transition to this page shall be performed. 824 825 \note The PageTransition structure is owned by this page, and will 826 automatically be destroyed when this page class is 827 destroyed. 828 **/ 829 PageTransition *transition() const; 830 831 /** 832 Gets the page action specified, or empty unique pointer if there is no action. 833 **/ 834 std::unique_ptr<Link> action(PageAction act) const; 835 836 /** 837 Types of orientations that are possible 838 */ 839 enum Orientation 840 { 841 Landscape, ///< Landscape orientation (portrait, with 90 degrees clockwise rotation ) 842 Portrait, ///< Normal portrait orientation 843 Seascape, ///< Seascape orientation (portrait, with 270 degrees clockwise rotation) 844 UpsideDown ///< Upside down orientation (portrait, with 180 degrees rotation) 845 }; 846 847 /** 848 The orientation of the page 849 */ 850 Orientation orientation() const; 851 852 /** 853 The default CTM 854 */ 855 void defaultCTM(double *CTM, double dpiX, double dpiY, int rotate, bool upsideDown); 856 857 /** 858 Gets the links of the page 859 */ 860 std::vector<std::unique_ptr<Link>> links() const; 861 862 /** 863 Returns the annotations of the page 864 865 \note If you call this method twice, you get different objects 866 pointing to the same annotations (see Annotation). 867 */ 868 std::vector<std::unique_ptr<Annotation>> annotations() const; 869 870 /** 871 Returns the annotations of the page 872 873 \param subtypes the subtypes of annotations you are interested in 874 875 \note If you call this method twice, you get different objects 876 pointing to the same annotations (see Annotation). 877 */ 878 std::vector<std::unique_ptr<Annotation>> annotations(const QSet<Annotation::SubType> &subtypes) const; 879 880 /** 881 Adds an annotation to the page 882 883 \note Ownership of the annotation object stays with the caller, who can 884 delete it at any time. 885 */ 886 void addAnnotation(const Annotation *ann); 887 888 /** 889 Removes an annotation from the page and destroys the annotation object 890 891 \note There mustn't be other Annotation objects pointing this annotation 892 */ 893 void removeAnnotation(const Annotation *ann); 894 895 /** 896 Returns the form fields on the page 897 */ 898 std::vector<std::unique_ptr<FormField>> formFields() const; 899 900 /** 901 Returns the page duration. That is the time, in seconds, that the page 902 should be displayed before the presentation automatically advances to the next page. 903 Returns < 0 if duration is not set. 904 */ 905 double duration() const; 906 907 /** 908 Returns the label of the page, or a null string is the page has no label. 909 **/ 910 QString label() const; 911 912 /** 913 Returns the index of the page. 914 **/ 915 int index() const; 916 917 private: 918 Q_DISABLE_COPY(Page) 919 920 Page(DocumentData *doc, int index); 921 PageData *m_page; 922 }; 923 924 /** 925 \brief Item in the outline of a PDF document 926 927 Represents an item in the outline of PDF document, i.e. a name, an internal or external link and a set of child items. 928 **/ 929 class POPPLER_QT6_EXPORT OutlineItem 930 { 931 friend class Document; 932 933 public: 934 /** 935 Constructs a null item, i.e. one that does not represent a valid item in the outline of some PDF document. 936 **/ 937 OutlineItem(); 938 ~OutlineItem(); 939 940 OutlineItem(const OutlineItem &other); 941 OutlineItem &operator=(const OutlineItem &other); 942 943 OutlineItem(OutlineItem &&other) noexcept; 944 OutlineItem &operator=(OutlineItem &&other) noexcept; 945 946 /** 947 Indicates whether an item is null, i.e. whether it does not represent a valid item in the outline of some PDF document. 948 **/ 949 bool isNull() const; 950 951 /** 952 The name of the item which should be displayed to the user. 953 **/ 954 QString name() const; 955 956 /** 957 Indicates whether the item should initially be display in an expanded or collapsed state. 958 **/ 959 bool isOpen() const; 960 961 /** 962 The destination referred to by this item. 963 964 \returns a shared pointer to an immutable link destination 965 **/ 966 QSharedPointer<const LinkDestination> destination() const; 967 968 /** 969 The external file name of the document to which the \see destination refers 970 971 \returns a string with the external file name or an empty string if there is none 972 */ 973 QString externalFileName() const; 974 975 /** 976 The URI to which the item links 977 978 \returns a string with the URI which this item links or an empty string if there is none 979 **/ 980 QString uri() const; 981 982 /** 983 Determines if this item has any child items 984 985 \returns true if there are any child items 986 **/ 987 bool hasChildren() const; 988 989 /** 990 Gets the child items of this item 991 992 \returns a vector outline items, empty if there are none 993 **/ 994 QVector<OutlineItem> children() const; 995 996 private: 997 explicit OutlineItem(OutlineItemData *data); 998 OutlineItemData *m_data; 999 }; 1000 1001 /** 1002 \brief PDF document. 1003 1004 The Document class represents a PDF document: its pages, and all the global 1005 properties, metadata, etc. 1006 1007 \section ownership Ownership of the returned objects 1008 1009 All the functions that returns class pointers create new object, and the 1010 responsibility of those is given to the caller. 1011 1012 The only exception is \link Poppler::Page::transition() Page::transition()\endlink. 1013 1014 \section document-loading Loading 1015 1016 To get a Document, you have to load it via the load() & loadFromData() 1017 functions. 1018 1019 In all the functions that have passwords as arguments, they \b must be Latin1 1020 encoded. If you have a password that is a UTF-8 string, you need to use 1021 QString::toLatin1() (or similar) to convert the password first. 1022 If you have a UTF-8 character array, consider converting it to a QString first 1023 (QString::fromUtf8(), or similar) before converting to Latin1 encoding. 1024 1025 \section document-rendering Rendering 1026 1027 To render pages of a document, you have different Document functions to set 1028 various options. 1029 1030 \subsection document-rendering-backend Backends 1031 1032 %Poppler offers a different backends for rendering the pages. Currently 1033 there are two backends (see #RenderBackend), but only the Splash engine works 1034 well and has been tested. 1035 1036 The available rendering backends can be discovered via availableRenderBackends(). 1037 The current rendering backend can be changed using setRenderBackend(). 1038 Please note that setting a backend not listed in the available ones 1039 will always result in null QImage's. 1040 1041 \section document-cms Color management support 1042 1043 %Poppler, if compiled with this support, provides functions to handle color 1044 profiles. 1045 1046 To know whether the %Poppler version you are using has support for color 1047 management, you can query Poppler::isCmsAvailable(). In case it is not 1048 available, all the color management-related functions will either do nothing 1049 or return null. 1050 */ 1051 class POPPLER_QT6_EXPORT Document 1052 { 1053 friend class Page; 1054 friend class DocumentData; 1055 1056 public: 1057 /** 1058 The page mode 1059 */ 1060 enum PageMode 1061 { 1062 UseNone, ///< No mode - neither document outline nor thumbnail images are visible 1063 UseOutlines, ///< Document outline visible 1064 UseThumbs, ///< Thumbnail images visible 1065 FullScreen, ///< Fullscreen mode (no menubar, windows controls etc) 1066 UseOC, ///< Optional content group panel visible 1067 UseAttach ///< Attachments panel visible 1068 }; 1069 1070 /** 1071 The page layout 1072 */ 1073 enum PageLayout 1074 { 1075 NoLayout, ///< Layout not specified 1076 SinglePage, ///< Display a single page 1077 OneColumn, ///< Display a single column of pages 1078 TwoColumnLeft, ///< Display the pages in two columns, with odd-numbered pages on the left 1079 TwoColumnRight, ///< Display the pages in two columns, with odd-numbered pages on the right 1080 TwoPageLeft, ///< Display the pages two at a time, with odd-numbered pages on the left 1081 TwoPageRight ///< Display the pages two at a time, with odd-numbered pages on the right 1082 }; 1083 1084 /** 1085 The render backends available 1086 */ 1087 enum RenderBackend 1088 { 1089 SplashBackend, ///< Splash backend 1090 QPainterBackend ///< Qt backend 1091 }; 1092 1093 /** 1094 The render hints available 1095 */ 1096 enum RenderHint 1097 { 1098 Antialiasing = 0x00000001, ///< Antialiasing for graphics 1099 TextAntialiasing = 0x00000002, ///< Antialiasing for text 1100 TextHinting = 0x00000004, ///< Hinting for text 1101 TextSlightHinting = 0x00000008, ///< Lighter hinting for text when combined with TextHinting 1102 OverprintPreview = 0x00000010, ///< Overprint preview 1103 ThinLineSolid = 0x00000020, ///< Enhance thin lines solid 1104 ThinLineShape = 0x00000040, ///< Enhance thin lines shape. Wins over ThinLineSolid 1105 IgnorePaperColor = 0x00000080, ///< Do not compose with the paper color 1106 HideAnnotations = 0x00000100 ///< Do not render annotations 1107 }; 1108 Q_DECLARE_FLAGS(RenderHints, RenderHint) 1109 1110 /** 1111 Form types 1112 */ 1113 enum FormType 1114 { 1115 NoForm, ///< Document doesn't contain forms 1116 AcroForm, ///< AcroForm 1117 XfaForm ///< Adobe XML Forms Architecture (XFA), currently unsupported 1118 }; 1119 1120 /** 1121 Set a color display profile for the current document. 1122 1123 \param outputProfileA is a \c cmsHPROFILE of the LCMS library. 1124 1125 \note This should be called before any rendering happens. 1126 1127 \note It is assumed that poppler takes over the owernship of the corresponding cmsHPROFILE. In particular, 1128 it is no longer the caller's responsibility to close the profile after use. 1129 */ 1130 void setColorDisplayProfile(void *outputProfileA); 1131 /** 1132 Set a color display profile for the current document. 1133 1134 \param name is the name of the display profile to set. 1135 1136 \note This should be called before any rendering happens. 1137 */ 1138 void setColorDisplayProfileName(const QString &name); 1139 /** 1140 Return the current RGB profile. 1141 1142 \return a \c cmsHPROFILE of the LCMS library. 1143 1144 \note The returned profile stays a property of poppler and shall NOT be closed by the user. It's 1145 existence is guaranteed for as long as this instance of the Document class is not deleted. 1146 */ 1147 void *colorRgbProfile() const; 1148 /** 1149 Return the current display profile. 1150 1151 \return a \c cmsHPROFILE of the LCMS library. 1152 1153 \note The returned profile stays a property of poppler and shall NOT be closed by the user. It's 1154 existence is guaranteed for as long as this instance of the Document class is not deleted. 1155 */ 1156 void *colorDisplayProfile() const; 1157 1158 /** 1159 Load the document from a file on disk 1160 1161 \param filePath the name (and path, if required) of the file to load 1162 \param ownerPassword the Latin1-encoded owner password to use in 1163 loading the file 1164 \param userPassword the Latin1-encoded user ("open") password 1165 to use in loading the file 1166 1167 \return the loaded document, or empty unique pointer on error 1168 1169 \warning The returning document may be locked if a password is required 1170 to open the file, and one is not provided (as the userPassword). 1171 */ 1172 static std::unique_ptr<Document> load(const QString &filePath, const QByteArray &ownerPassword = QByteArray(), const QByteArray &userPassword = QByteArray()); 1173 1174 /** 1175 Load the document from a device 1176 1177 \param device the device of the data to load 1178 \param ownerPassword the Latin1-encoded owner password to use in 1179 loading the file 1180 \param userPassword the Latin1-encoded user ("open") password 1181 to use in loading the file 1182 1183 \return the loaded document, or empty unique pointer on error 1184 1185 \note if the file is on disk it is recommended to use the other load overload 1186 since it is less resource intensive 1187 1188 \warning The returning document may be locked if a password is required 1189 to open the file, and one is not provided (as the userPassword). 1190 */ 1191 static std::unique_ptr<Document> load(QIODevice *device, const QByteArray &ownerPassword = QByteArray(), const QByteArray &userPassword = QByteArray()); 1192 1193 /** 1194 Load the document from memory 1195 1196 \param fileContents the file contents. They are copied so there is no need 1197 to keep the byte array around for the full life time of 1198 the document. 1199 \param ownerPassword the Latin1-encoded owner password to use in 1200 loading the file 1201 \param userPassword the Latin1-encoded user ("open") password 1202 to use in loading the file 1203 1204 \return the loaded document, or empty unique pointer on error 1205 1206 \warning The returning document may be locked if a password is required 1207 to open the file, and one is not provided (as the userPassword). 1208 */ 1209 static std::unique_ptr<Document> loadFromData(const QByteArray &fileContents, const QByteArray &ownerPassword = QByteArray(), const QByteArray &userPassword = QByteArray()); 1210 1211 /** 1212 Get a specified Page 1213 1214 Note that this follows the PDF standard of being zero based - if you 1215 want the first page, then you need an index of zero. 1216 1217 This function can return empty unique pointer if for some reason the page can't be properly parsed. 1218 1219 \param index the page number index 1220 1221 \warning The Page object returned by this method internally stores a pointer 1222 to the document that it was created from. This pointer will go stale if you 1223 delete the Document object. Therefore the Document object needs to be kept alive 1224 as long as you want to use the Page object. 1225 */ 1226 std::unique_ptr<Page> page(int index) const; 1227 1228 /** 1229 \overload 1230 1231 1232 The intent is that you can pass in a label like \c "ix" and 1233 get the page with that label (which might be in the table of 1234 contents), or pass in \c "1" and get the page that the user 1235 expects (which might not be the first page, if there is a 1236 title page and a table of contents). 1237 1238 \param label the page label 1239 */ 1240 std::unique_ptr<Page> page(const QString &label) const; 1241 1242 /** 1243 The number of pages in the document 1244 */ 1245 int numPages() const; 1246 1247 /** 1248 The type of mode that should be used by the application 1249 when the document is opened. Note that while this is 1250 called page mode, it is really viewer application mode. 1251 */ 1252 PageMode pageMode() const; 1253 1254 /** 1255 The layout that pages should be shown in when the document 1256 is first opened. This basically describes how pages are 1257 shown relative to each other. 1258 */ 1259 PageLayout pageLayout() const; 1260 1261 /** 1262 The predominant reading order for text as supplied by 1263 the document's viewer preferences. 1264 */ 1265 Qt::LayoutDirection textDirection() const; 1266 1267 /** 1268 Provide the passwords required to unlock the document 1269 1270 \param ownerPassword the Latin1-encoded owner password to use in 1271 loading the file 1272 \param userPassword the Latin1-encoded user ("open") password 1273 to use in loading the file 1274 */ 1275 bool unlock(const QByteArray &ownerPassword, const QByteArray &userPassword); 1276 1277 /** 1278 Determine if the document is locked 1279 */ 1280 bool isLocked() const; 1281 1282 /** 1283 The date associated with the document 1284 1285 You would use this method with something like: 1286 \code 1287 QDateTime created = m_doc->date("CreationDate"); 1288 QDateTime modified = m_doc->date("ModDate"); 1289 \endcode 1290 1291 The available dates are: 1292 - CreationDate: the date of creation of the document 1293 - ModDate: the date of the last change in the document 1294 1295 \param type the type of date that is required 1296 */ 1297 QDateTime date(const QString &type) const; 1298 1299 /** 1300 Set the Info dict date entry specified by \param key to \param val 1301 1302 \returns true on success, false on failure 1303 */ 1304 bool setDate(const QString &key, const QDateTime &val); 1305 1306 /** 1307 The date of the creation of the document 1308 */ 1309 QDateTime creationDate() const; 1310 1311 /** 1312 Set the creation date of the document to \param val 1313 1314 \returns true on success, false on failure 1315 */ 1316 bool setCreationDate(const QDateTime &val); 1317 1318 /** 1319 The date of the last change in the document 1320 */ 1321 QDateTime modificationDate() const; 1322 1323 /** 1324 Set the modification date of the document to \param val 1325 1326 \returns true on success, false on failure 1327 */ 1328 bool setModificationDate(const QDateTime &val); 1329 1330 /** 1331 Get specified information associated with the document 1332 1333 You would use this method with something like: 1334 \code 1335 QString title = m_doc->info("Title"); 1336 QString subject = m_doc->info("Subject"); 1337 \endcode 1338 1339 In addition to \c Title and \c Subject, other information that may 1340 be available include \c Author, \c Keywords, \c Creator and \c Producer. 1341 1342 \param type the information that is required 1343 1344 \sa infoKeys() to get a list of the available keys 1345 */ 1346 QString info(const QString &type) const; 1347 1348 /** 1349 Set the value of the document's Info dictionary entry specified by \param key to \param val 1350 1351 \returns true on success, false on failure 1352 */ 1353 bool setInfo(const QString &key, const QString &val); 1354 1355 /** 1356 The title of the document 1357 */ 1358 QString title() const; 1359 1360 /** 1361 Set the title of the document to \param val 1362 1363 \returns true on success, false on failure 1364 */ 1365 bool setTitle(const QString &val); 1366 1367 /** 1368 The author of the document 1369 */ 1370 QString author() const; 1371 1372 /** 1373 Set the author of the document to \param val 1374 1375 \returns true on success, false on failure 1376 */ 1377 bool setAuthor(const QString &val); 1378 1379 /** 1380 The subject of the document 1381 */ 1382 QString subject() const; 1383 1384 /** 1385 Set the subject of the document to \param val 1386 1387 \returns true on success, false on failure 1388 */ 1389 bool setSubject(const QString &val); 1390 1391 /** 1392 The keywords of the document 1393 */ 1394 QString keywords() const; 1395 1396 /** 1397 Set the keywords of the document to \param val 1398 1399 \returns true on success, false on failure 1400 */ 1401 bool setKeywords(const QString &val); 1402 1403 /** 1404 The creator of the document 1405 */ 1406 QString creator() const; 1407 1408 /** 1409 Set the creator of the document to \param val 1410 1411 \returns true on success, false on failure 1412 */ 1413 bool setCreator(const QString &val); 1414 1415 /** 1416 The producer of the document 1417 */ 1418 QString producer() const; 1419 1420 /** 1421 Set the producer of the document to \param val 1422 1423 \returns true on success, false on failure 1424 */ 1425 bool setProducer(const QString &val); 1426 1427 /** 1428 Remove the document's Info dictionary 1429 1430 \returns true on success, false on failure 1431 */ 1432 bool removeInfo(); 1433 1434 /** 1435 Obtain a list of the available string information keys. 1436 */ 1437 QStringList infoKeys() const; 1438 1439 /** 1440 Test if the document is encrypted 1441 */ 1442 bool isEncrypted() const; 1443 1444 /** 1445 Test if the document is linearised 1446 1447 In some cases, this is called "fast web view", since it 1448 is mostly an optimisation for viewing over the Web. 1449 */ 1450 bool isLinearized() const; 1451 1452 /** 1453 Test if the permissions on the document allow it to be 1454 printed 1455 */ 1456 bool okToPrint() const; 1457 1458 /** 1459 Test if the permissions on the document allow it to be 1460 printed at high resolution 1461 */ 1462 bool okToPrintHighRes() const; 1463 1464 /** 1465 Test if the permissions on the document allow it to be 1466 changed. 1467 1468 \note depending on the type of change, it may be more 1469 appropriate to check other properties as well. 1470 */ 1471 bool okToChange() const; 1472 1473 /** 1474 Test if the permissions on the document allow the 1475 contents to be copied / extracted 1476 */ 1477 bool okToCopy() const; 1478 1479 /** 1480 Test if the permissions on the document allow annotations 1481 to be added or modified, and interactive form fields (including 1482 signature fields) to be completed. 1483 */ 1484 bool okToAddNotes() const; 1485 1486 /** 1487 Test if the permissions on the document allow interactive 1488 form fields (including signature fields) to be completed. 1489 1490 \note this can be true even if okToAddNotes() is false - this 1491 means that only form completion is permitted. 1492 */ 1493 bool okToFillForm() const; 1494 1495 /** 1496 Test if the permissions on the document allow interactive 1497 form fields (including signature fields) to be set, created and 1498 modified 1499 */ 1500 bool okToCreateFormFields() const; 1501 1502 /** 1503 Test if the permissions on the document allow content extraction 1504 (text and perhaps other content) for accessibility usage (eg for 1505 a screen reader) 1506 */ 1507 bool okToExtractForAccessibility() const; 1508 1509 /** 1510 Test if the permissions on the document allow it to be 1511 "assembled" - insertion, rotation and deletion of pages; 1512 or creation of bookmarks and thumbnail images. 1513 1514 \note this can be true even if okToChange() is false 1515 */ 1516 bool okToAssemble() const; 1517 1518 /** \brief The version specification of a pdf file */ 1519 struct PdfVersion 1520 { 1521 int major; 1522 int minor; 1523 }; 1524 1525 /** 1526 The version of the PDF specification that the document 1527 conforms to 1528 1529 \since 21.08 1530 */ 1531 PdfVersion getPdfVersion() const; 1532 1533 /** 1534 The fonts within the PDF document. 1535 1536 This is a shorthand for getting all the fonts at once. 1537 1538 \note this can take a very long time to run with a large 1539 document. You may wish to use a FontIterator if you have more 1540 than say 20 pages 1541 1542 \see newFontIterator() 1543 */ 1544 QList<FontInfo> fonts() const; 1545 1546 /** 1547 Creates a new FontIterator object for font scanning. 1548 1549 The new iterator can be used for reading the font information of the 1550 document, reading page by page. 1551 1552 \param startPage the initial page from which start reading fonts 1553 1554 \see fonts() 1555 */ 1556 std::unique_ptr<FontIterator> newFontIterator(int startPage = 0) const; 1557 1558 /** 1559 The font data if the font is an embedded one. 1560 */ 1561 QByteArray fontData(const FontInfo &fi) const; 1562 1563 /** 1564 The documents embedded within the PDF document. 1565 1566 \note there are two types of embedded document - this call 1567 only accesses documents that are embedded at the document level. 1568 1569 \note The ownership of the EmbeddedFile objects remain with the callee. 1570 */ 1571 QList<EmbeddedFile *> embeddedFiles() const; 1572 1573 /** 1574 Whether there are any documents embedded in this PDF document. 1575 */ 1576 bool hasEmbeddedFiles() const; 1577 1578 /** 1579 Gets the outline of the document 1580 1581 \returns a vector of outline items, empty if there are none 1582 **/ 1583 QVector<OutlineItem> outline() const; 1584 1585 /** 1586 Tries to resolve the named destination \p name. 1587 1588 \note this operation starts a search through the whole document 1589 1590 \returns a new LinkDestination object if the named destination was 1591 actually found, or empty unique pointer otherwise 1592 */ 1593 std::unique_ptr<LinkDestination> linkDestination(const QString &name); 1594 1595 /** 1596 Sets the paper color 1597 1598 \param color the new paper color 1599 */ 1600 void setPaperColor(const QColor &color); 1601 /** 1602 The paper color 1603 1604 The default color is white. 1605 */ 1606 QColor paperColor() const; 1607 1608 /** 1609 Sets the backend used to render the pages. 1610 1611 \param backend the new rendering backend 1612 */ 1613 void setRenderBackend(RenderBackend backend); 1614 /** 1615 The currently set render backend 1616 1617 The default backend is \ref SplashBackend 1618 */ 1619 RenderBackend renderBackend() const; 1620 1621 /** 1622 The available rendering backends. 1623 */ 1624 static QSet<RenderBackend> availableRenderBackends(); 1625 1626 /** 1627 Sets the render \p hint . 1628 1629 \note some hints may not be supported by some rendering backends. 1630 1631 \param on whether the flag should be added or removed. 1632 */ 1633 void setRenderHint(RenderHint hint, bool on = true); 1634 /** 1635 The currently set render hints. 1636 */ 1637 RenderHints renderHints() const; 1638 1639 /** 1640 Gets a new PS converter for this document. 1641 */ 1642 std::unique_ptr<PSConverter> psConverter() const; 1643 1644 /** 1645 Gets a new PDF converter for this document. 1646 */ 1647 std::unique_ptr<PDFConverter> pdfConverter() const; 1648 1649 /** 1650 Gets the metadata stream contents 1651 */ 1652 QString metadata() const; 1653 1654 /** 1655 Test whether this document has "optional content". 1656 1657 Optional content is used to optionally turn on (display) 1658 and turn off (not display) some elements of the document. 1659 The most common use of this is for layers in design 1660 applications, but it can be used for a range of things, 1661 such as not including some content in printing, and 1662 displaying content in the appropriate language. 1663 */ 1664 bool hasOptionalContent() const; 1665 1666 /** 1667 Itemviews model for optional content. 1668 1669 The model is owned by the document. 1670 */ 1671 OptContentModel *optionalContentModel(); 1672 1673 /** 1674 Document-level JavaScript scripts. 1675 1676 Returns the list of document level JavaScript scripts to be always 1677 executed before any other script. 1678 */ 1679 QStringList scripts() const; 1680 1681 /** 1682 The PDF identifiers. 1683 1684 \param permanentId an optional pointer to a variable where store the 1685 permanent ID of the document 1686 \param updateId an optional pointer to a variable where store the 1687 update ID of the document 1688 1689 \return whether the document has the IDs 1690 */ 1691 bool getPdfId(QByteArray *permanentId, QByteArray *updateId) const; 1692 1693 /** 1694 Returns the type of forms contained in the document 1695 */ 1696 FormType formType() const; 1697 1698 /** 1699 Returns the calculate order for forms (using their id) 1700 */ 1701 QVector<int> formCalculateOrder() const; 1702 1703 /** 1704 Returns the signatures of this document. 1705 1706 Prefer to use this over getting the signatures for all the pages of the document 1707 since there are documents with signatures that don't belong to a given page 1708 */ 1709 std::vector<std::unique_ptr<FormFieldSignature>> signatures() const; 1710 1711 /** 1712 Returns whether the document's XRef table has been reconstructed or not 1713 1714 \since 21.06 1715 */ 1716 bool xrefWasReconstructed() const; 1717 1718 /** 1719 Sets the document's XRef reconstruction callback, so whenever a XRef table 1720 reconstruction happens the callback will get triggered. 1721 1722 \since 21.06 1723 */ 1724 void setXRefReconstructedCallback(const std::function<void()> &callback); 1725 1726 /** 1727 Destructor. 1728 */ 1729 ~Document(); 1730 1731 private: 1732 Q_DISABLE_COPY(Document) 1733 1734 DocumentData *m_doc; 1735 1736 explicit Document(DocumentData *dataA); 1737 }; 1738 1739 class BaseConverterPrivate; 1740 class PSConverterPrivate; 1741 class PDFConverterPrivate; 1742 /** 1743 \brief Base converter. 1744 1745 This is the base class for the converters. 1746 */ 1747 class POPPLER_QT6_EXPORT BaseConverter 1748 { 1749 friend class Document; 1750 1751 public: 1752 /** 1753 Destructor. 1754 */ 1755 virtual ~BaseConverter(); 1756 1757 /** Sets the output file name. You must set this or the output device. */ 1758 void setOutputFileName(const QString &outputFileName); 1759 1760 /** 1761 * Sets the output device. You must set this or the output file name. 1762 */ 1763 void setOutputDevice(QIODevice *device); 1764 1765 /** 1766 Does the conversion. 1767 1768 \return whether the conversion succeeded 1769 */ 1770 virtual bool convert() = 0; 1771 1772 enum Error 1773 { 1774 NoError, 1775 FileLockedError, 1776 OpenOutputError, 1777 NotSupportedInputFileError 1778 }; 1779 1780 /** 1781 Returns the last error 1782 */ 1783 Error lastError() const; 1784 1785 protected: 1786 /// \cond PRIVATE 1787 explicit BaseConverter(BaseConverterPrivate &dd); 1788 Q_DECLARE_PRIVATE(BaseConverter) 1789 BaseConverterPrivate *d_ptr; 1790 /// \endcond 1791 1792 private: 1793 Q_DISABLE_COPY(BaseConverter) 1794 }; 1795 1796 /** 1797 Converts a PDF to PS 1798 1799 Sizes have to be in Points (1/72 inch) 1800 1801 If you are using QPrinter you can get paper size by doing: 1802 \code 1803 QPrinter dummy(QPrinter::PrinterResolution); 1804 dummy.setFullPage(true); 1805 dummy.setPageSize(myPageSize); 1806 width = dummy.width(); 1807 height = dummy.height(); 1808 \endcode 1809 */ 1810 class POPPLER_QT6_EXPORT PSConverter : public BaseConverter 1811 { 1812 friend class Document; 1813 1814 public: 1815 /** 1816 Options for the PS export. 1817 */ 1818 enum PSOption 1819 { 1820 Printing = 0x00000001, ///< The PS is generated for printing purposes 1821 StrictMargins = 0x00000002, 1822 ForceRasterization = 0x00000004, 1823 PrintToEPS = 0x00000008, ///< Output EPS instead of PS 1824 HideAnnotations = 0x00000010 ///< Don't print annotations 1825 }; 1826 Q_DECLARE_FLAGS(PSOptions, PSOption) 1827 1828 /** 1829 Destructor. 1830 */ 1831 ~PSConverter() override; 1832 1833 /** Sets the list of pages to print. Mandatory. */ 1834 void setPageList(const QList<int> &pageList); 1835 1836 /** 1837 Sets the title of the PS Document. Optional 1838 */ 1839 void setTitle(const QString &title); 1840 1841 /** 1842 Sets the horizontal DPI. Defaults to 72.0 1843 */ 1844 void setHDPI(double hDPI); 1845 1846 /** 1847 Sets the vertical DPI. Defaults to 72.0 1848 */ 1849 void setVDPI(double vDPI); 1850 1851 /** 1852 Sets the rotate. Defaults to not rotated 1853 */ 1854 void setRotate(int rotate); 1855 1856 /** 1857 Sets the output paper width. Has to be set. 1858 */ 1859 void setPaperWidth(int paperWidth); 1860 1861 /** 1862 Sets the output paper height. Has to be set. 1863 */ 1864 void setPaperHeight(int paperHeight); 1865 1866 /** 1867 Sets the output right margin. Defaults to 0 1868 */ 1869 void setRightMargin(int marginRight); 1870 1871 /** 1872 Sets the output bottom margin. Defaults to 0 1873 */ 1874 void setBottomMargin(int marginBottom); 1875 1876 /** 1877 Sets the output left margin. Defaults to 0 1878 */ 1879 void setLeftMargin(int marginLeft); 1880 1881 /** 1882 Sets the output top margin. Defaults to 0 1883 */ 1884 void setTopMargin(int marginTop); 1885 1886 /** 1887 Defines if margins have to be strictly followed (even if that 1888 means changing aspect ratio), or if the margins can be adapted 1889 to keep aspect ratio. 1890 1891 Defaults to false. 1892 */ 1893 void setStrictMargins(bool strictMargins); 1894 1895 /** Defines if the page will be rasterized to an image before printing. Defaults to false */ 1896 void setForceRasterize(bool forceRasterize); 1897 1898 /** 1899 Sets the options for the PS export. 1900 */ 1901 void setPSOptions(PSOptions options); 1902 1903 /** 1904 The currently set options for the PS export. 1905 1906 The default flags are: Printing. 1907 */ 1908 PSOptions psOptions() const; 1909 1910 /** 1911 Sets a function that will be called each time a page is converted. 1912 1913 The payload belongs to the caller. 1914 */ 1915 void setPageConvertedCallback(void (*callback)(int page, void *payload), void *payload); 1916 1917 bool convert() override; 1918 1919 private: 1920 Q_DECLARE_PRIVATE(PSConverter) 1921 Q_DISABLE_COPY(PSConverter) 1922 1923 explicit PSConverter(DocumentData *document); 1924 }; 1925 1926 /** 1927 Converts a PDF to PDF (thus saves a copy of the document). 1928 */ 1929 class POPPLER_QT6_EXPORT PDFConverter : public BaseConverter 1930 { 1931 friend class Document; 1932 1933 public: 1934 /** 1935 Options for the PDF export. 1936 */ 1937 enum PDFOption 1938 { 1939 WithChanges = 0x00000001 ///< The changes done to the document are saved as well 1940 }; 1941 Q_DECLARE_FLAGS(PDFOptions, PDFOption) 1942 1943 /** 1944 Destructor. 1945 */ 1946 ~PDFConverter() override; 1947 1948 /** 1949 Sets the options for the PDF export. 1950 */ 1951 void setPDFOptions(PDFOptions options); 1952 /** 1953 The currently set options for the PDF export. 1954 */ 1955 PDFOptions pdfOptions() const; 1956 1957 /** 1958 * Holds data for a new signature 1959 * - Common Name of cert to sign (aka nickname) 1960 * - password for the cert 1961 * - page where to add the signature 1962 * - rect for the signature annotation 1963 * - text that will be shown inside the rect 1964 * - font size and color 1965 * - border width and color 1966 * - background color 1967 * \since 21.01 1968 */ 1969 class POPPLER_QT6_EXPORT NewSignatureData 1970 { 1971 public: 1972 NewSignatureData(); 1973 ~NewSignatureData(); 1974 NewSignatureData(const NewSignatureData &) = delete; 1975 NewSignatureData &operator=(const NewSignatureData &) = delete; 1976 1977 QString certNickname() const; 1978 void setCertNickname(const QString &certNickname); 1979 1980 QString password() const; 1981 void setPassword(const QString &password); 1982 1983 int page() const; 1984 void setPage(int page); 1985 1986 QRectF boundingRectangle() const; 1987 void setBoundingRectangle(const QRectF &rect); 1988 1989 QString signatureText() const; 1990 void setSignatureText(const QString &text); 1991 1992 /** 1993 * If this text is not empty, the signature representation 1994 * will split in two, with this text on the left and signatureText 1995 * on the right 1996 * 1997 * \since 21.06 1998 */ 1999 QString signatureLeftText() const; 2000 void setSignatureLeftText(const QString &text); 2001 2002 /** 2003 * Signature's property Reason. 2004 * 2005 * Default: an empty string. 2006 * 2007 * \since 21.10 2008 */ 2009 QString reason() const; 2010 void setReason(const QString &reason); 2011 2012 /** 2013 * Signature's property Location. 2014 * 2015 * Default: an empty string. 2016 * 2017 * \since 21.10 2018 */ 2019 QString location() const; 2020 void setLocation(const QString &location); 2021 2022 /** 2023 * Default: 10 2024 */ 2025 double fontSize() const; 2026 void setFontSize(double fontSize); 2027 2028 /** 2029 * Default: 20 2030 * 2031 * \since 21.06 2032 */ 2033 double leftFontSize() const; 2034 void setLeftFontSize(double fontSize); 2035 2036 /** 2037 * Default: red 2038 */ 2039 QColor fontColor() const; 2040 void setFontColor(const QColor &color); 2041 2042 /** 2043 * Default: red 2044 */ 2045 QColor borderColor() const; 2046 void setBorderColor(const QColor &color); 2047 2048 /** 2049 * border width in points 2050 * 2051 * Default: 1.5 2052 * 2053 * \since 21.05 2054 */ 2055 double borderWidth() const; 2056 void setBorderWidth(double width); 2057 2058 /** 2059 * Default: QColor(240, 240, 240) 2060 */ 2061 QColor backgroundColor() const; 2062 void setBackgroundColor(const QColor &color); 2063 2064 /** 2065 * Default: QUuid::createUuid().toString() 2066 */ 2067 QString fieldPartialName() const; 2068 void setFieldPartialName(const QString &name); 2069 2070 private: 2071 struct NewSignatureDataPrivate; 2072 NewSignatureDataPrivate *const d; 2073 }; 2074 2075 /** 2076 Sign PDF at given Annotation / signature form 2077 2078 \param data new signature data 2079 2080 \return whether the signing succeeded 2081 2082 \since 21.01 2083 */ 2084 bool sign(const NewSignatureData &data); 2085 2086 bool convert() override; 2087 2088 private: 2089 Q_DECLARE_PRIVATE(PDFConverter) 2090 Q_DISABLE_COPY(PDFConverter) 2091 2092 explicit PDFConverter(DocumentData *document); 2093 }; 2094 2095 /** 2096 Conversion from PDF date string format to QDateTime 2097 */ 2098 POPPLER_QT6_EXPORT QDateTime convertDate(const char *dateString); 2099 2100 /** 2101 Whether the color management functions are available. 2102 */ 2103 POPPLER_QT6_EXPORT bool isCmsAvailable(); 2104 2105 /** 2106 Whether the overprint preview functionality is available. 2107 */ 2108 POPPLER_QT6_EXPORT bool isOverprintPreviewAvailable(); 2109 2110 class SoundData; 2111 /** 2112 Container class for a sound file in a PDF document. 2113 2114 A sound can be either External (in that case should be loaded the file 2115 whose url is represented by url() ), or Embedded, and the player has to 2116 play the data contained in data(). 2117 */ 2118 class POPPLER_QT6_EXPORT SoundObject 2119 { 2120 public: 2121 /** 2122 The type of sound 2123 */ 2124 enum SoundType 2125 { 2126 External, ///< The real sound file is external 2127 Embedded ///< The sound is contained in the data 2128 }; 2129 2130 /** 2131 The encoding format used for the sound 2132 */ 2133 enum SoundEncoding 2134 { 2135 Raw, ///< Raw encoding, with unspecified or unsigned values in the range [ 0, 2^B - 1 ] 2136 Signed, ///< Twos-complement values 2137 muLaw, ///< mu-law-encoded samples 2138 ALaw ///< A-law-encoded samples 2139 }; 2140 2141 /** \cond PRIVATE 2142 The caller keeps the ownership of the popplersound argument 2143 */ 2144 explicit SoundObject(Sound *popplersound); 2145 /// \endcond 2146 2147 ~SoundObject(); 2148 2149 /** 2150 Is the sound embedded (SoundObject::Embedded) or external (SoundObject::External)? 2151 */ 2152 SoundType soundType() const; 2153 2154 /** 2155 The URL of the sound file to be played, in case of SoundObject::External 2156 */ 2157 QString url() const; 2158 2159 /** 2160 The data of the sound, in case of SoundObject::Embedded 2161 */ 2162 QByteArray data() const; 2163 2164 /** 2165 The sampling rate of the sound 2166 */ 2167 double samplingRate() const; 2168 2169 /** 2170 The number of sound channels to use to play the sound 2171 */ 2172 int channels() const; 2173 2174 /** 2175 The number of bits per sample value per channel 2176 */ 2177 int bitsPerSample() const; 2178 2179 /** 2180 The encoding used for the sound 2181 */ 2182 SoundEncoding soundEncoding() const; 2183 2184 private: 2185 Q_DISABLE_COPY(SoundObject) 2186 2187 SoundData *m_soundData; 2188 }; 2189 2190 class MovieData; 2191 /** 2192 Container class for a movie object in a PDF document. 2193 */ 2194 class POPPLER_QT6_EXPORT MovieObject 2195 { 2196 friend class AnnotationPrivate; 2197 2198 public: 2199 /** 2200 The play mode for playing the movie 2201 */ 2202 enum PlayMode 2203 { 2204 PlayOnce, ///< Play the movie once, closing the movie controls at the end 2205 PlayOpen, ///< Like PlayOnce, but leaving the controls open 2206 PlayRepeat, ///< Play continuously until stopped 2207 PlayPalindrome ///< Play forward, then backward, then again foward and so on until stopped 2208 }; 2209 2210 ~MovieObject(); 2211 2212 /** 2213 The URL of the movie to be played 2214 */ 2215 QString url() const; 2216 2217 /** 2218 The size of the movie 2219 */ 2220 QSize size() const; 2221 2222 /** 2223 The rotation (either 0, 90, 180, or 270 degrees clockwise) for the movie, 2224 */ 2225 int rotation() const; 2226 2227 /** 2228 Whether show a bar with movie controls 2229 */ 2230 bool showControls() const; 2231 2232 /** 2233 How to play the movie 2234 */ 2235 PlayMode playMode() const; 2236 2237 /** 2238 Returns whether a poster image should be shown if the movie is not playing. 2239 */ 2240 bool showPosterImage() const; 2241 2242 /** 2243 Returns the poster image that should be shown if the movie is not playing. 2244 If the image is null but showImagePoster() returns @c true, the first frame of the movie 2245 should be used as poster image. 2246 */ 2247 QImage posterImage() const; 2248 2249 private: 2250 /// \cond PRIVATE 2251 explicit MovieObject(AnnotMovie *ann); 2252 /// \endcond 2253 2254 Q_DISABLE_COPY(MovieObject) 2255 2256 MovieData *m_movieData; 2257 }; 2258 2259 } 2260 2261 Q_DECLARE_OPERATORS_FOR_FLAGS(Poppler::Page::PainterFlags) 2262 Q_DECLARE_OPERATORS_FOR_FLAGS(Poppler::Page::SearchFlags) 2263 Q_DECLARE_OPERATORS_FOR_FLAGS(Poppler::Document::RenderHints) 2264 Q_DECLARE_OPERATORS_FOR_FLAGS(Poppler::PDFConverter::PDFOptions) 2265 Q_DECLARE_OPERATORS_FOR_FLAGS(Poppler::PSConverter::PSOptions) 2266 2267 #endif 2268