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