1 /* poppler-annotation.h: qt interface to poppler 2 * Copyright (C) 2006-2008, 2012, 2013, 2018-2021 Albert Astals Cid <aacid@kde.org> 3 * Copyright (C) 2006, 2008 Pino Toscano <pino@kde.org> 4 * Copyright (C) 2007, Brad Hards <bradh@frogmouth.net> 5 * Copyright (C) 2010, Philip Lorenz <lorenzph+freedesktop@gmail.com> 6 * Copyright (C) 2012, 2015, Tobias Koenig <tobias.koenig@kdab.com> 7 * Copyright (C) 2012, Guillermo A. Amaral B. <gamaral@kde.org> 8 * Copyright (C) 2012, 2013 Fabio D'Urso <fabiodurso@hotmail.it> 9 * Copyright (C) 2013, Anthony Granger <grangeranthony@gmail.com> 10 * Copyright (C) 2018, Dileep Sankhla <sankhla.dileep96@gmail.com> 11 * Copyright (C) 2020, Katarina Behrens <Katarina.Behrens@cib.de> 12 * Copyright (C) 2020, Klarälvdalens Datakonsult AB, a KDAB Group company, <info@kdab.com>. Work sponsored by Technische Universität Dresden 13 * Copyright (C) 2021, Mahmoud Ahmed Khalil <mahmoudkhalil11@gmail.com> 14 * Adapting code from 15 * Copyright (C) 2004 by Enrico Ros <eros.kde@email.it> 16 * 17 * This program is free software; you can redistribute it and/or modify 18 * it under the terms of the GNU General Public License as published by 19 * the Free Software Foundation; either version 2, or (at your option) 20 * any later version. 21 * 22 * This program is distributed in the hope that it will be useful, 23 * but WITHOUT ANY WARRANTY; without even the implied warranty of 24 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 25 * GNU General Public License for more details. 26 * 27 * You should have received a copy of the GNU General Public License 28 * along with this program; if not, write to the Free Software 29 * Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA. 30 */ 31 32 #ifndef _POPPLER_ANNOTATION_H_ 33 #define _POPPLER_ANNOTATION_H_ 34 35 #include <QtCore/QDateTime> 36 #include <QtCore/QSharedDataPointer> 37 #include <QtCore/QLinkedList> 38 #include <QtCore/QList> 39 #include <QtCore/QPointF> 40 #include <QtCore/QRectF> 41 #include <QtCore/QScopedPointer> 42 #include <QtCore/QVector> 43 #include <QtGui/QColor> 44 #include <QtGui/QFont> 45 #include <QtXml/QDomDocument> 46 #include "poppler-export.h" 47 48 #include <memory> 49 50 namespace Poppler { 51 52 class Annotation; 53 class AnnotationPrivate; 54 class AnnotationAppearancePrivate; 55 class TextAnnotationPrivate; 56 class LineAnnotationPrivate; 57 class GeomAnnotationPrivate; 58 class HighlightAnnotationPrivate; 59 class StampAnnotationPrivate; 60 class InkAnnotationPrivate; 61 class LinkAnnotationPrivate; 62 class CaretAnnotationPrivate; 63 class FileAttachmentAnnotationPrivate; 64 class SoundAnnotationPrivate; 65 class MovieAnnotationPrivate; 66 class ScreenAnnotationPrivate; 67 class WidgetAnnotationPrivate; 68 class RichMediaAnnotationPrivate; 69 class EmbeddedFile; 70 class Link; 71 class SoundObject; 72 class MovieObject; 73 class LinkRendition; 74 class Page; 75 76 /** 77 * \short Helper class for (recursive) Annotation retrieval/storage. 78 * 79 */ 80 class POPPLER_QT5_EXPORT AnnotationUtils 81 { 82 public: 83 /** 84 * Restore an Annotation (with revisions if needed) from the DOM 85 * element \p annElement. 86 * \returns a pointer to the complete Annotation or 0 if element is 87 * invalid. 88 */ 89 Q_DECL_DEPRECATED static Annotation *createAnnotation(const QDomElement &annElement); 90 91 /** 92 * Save the Annotation \p ann as a child of \p annElement taking 93 * care of saving all revisions if \p ann has any. 94 */ 95 Q_DECL_DEPRECATED static void storeAnnotation(const Annotation *ann, QDomElement &annElement, QDomDocument &document); 96 97 /** 98 * Returns an element called \p name from the direct children of 99 * \p parentNode or a null element if not found. 100 */ 101 Q_DECL_DEPRECATED static QDomElement findChildElement(const QDomNode &parentNode, const QString &name); 102 }; 103 104 /** 105 * \short AnnotationAppearance class wrapping Poppler's AP stream object 106 * 107 * The Annotation's Appearance Stream is a Form XObject containing 108 * information required to properly render the Annotation on the document. 109 * 110 * This class wraps Poppler's Object implementing the appearance stream 111 * for the calling annotation. It can be used to preserve the current 112 * Appearance Stream for the calling annotation. 113 * 114 * \since 21.10.0 115 */ 116 class POPPLER_QT5_EXPORT AnnotationAppearance 117 { 118 friend class Annotation; 119 120 public: 121 explicit AnnotationAppearance(AnnotationAppearancePrivate *annotationAppearancePrivate); 122 ~AnnotationAppearance(); 123 124 private: 125 AnnotationAppearancePrivate *d; 126 Q_DISABLE_COPY(AnnotationAppearance) 127 }; 128 129 /** 130 * \short Annotation class holding properties shared by all annotations. 131 * 132 * An Annotation is an object (text note, highlight, sound, popup window, ..) 133 * contained by a Page in the document. 134 * 135 * \warning Different Annotation objects might point to the same annotation. 136 * 137 * \section annotCreation How to add annotations 138 * 139 * Create an Annotation object of the desired subclass (for example 140 * TextAnnotation) and set its properties: 141 * @code 142 * Poppler::TextAnnotation* myann = new Poppler::TextAnnotation(Poppler::TextAnnotation::InPlace); 143 * myann->setBoundary(QRectF(0.1, 0.1, 0.2, 0.2)); // normalized coordinates: (0,0) is top-left, (1,1) is bottom-right 144 * myann->setContents("Hello, world!"); 145 * @endcode 146 * \note Always set a boundary rectangle, or nothing will be shown! 147 * 148 * Obtain a pointer to the Page where you want to add the annotation (refer to 149 * \ref req for instructions) and add the annotation: 150 * @code 151 * Poppler::Page* mypage = ...; 152 * mypage->addAnnotation(myann); 153 * @endcode 154 * 155 * You can keep on editing the annotation after it has been added to the page: 156 * @code 157 * myann->setContents("World, hello!"); // Let's change text... 158 * myann->setAuthor("Your name here"); // ...and set an author too 159 * @endcode 160 * 161 * When you're done with editing the annotation, you must destroy the Annotation 162 * object: 163 * @code 164 * delete myann; 165 * @endcode 166 * 167 * Use the PDFConverter class to save the modified document. 168 * 169 * \section annotFixedRotation FixedRotation flag specifics 170 * 171 * According to the PDF specification, annotations whose 172 * Annotation::FixedRotation flag is set must always be shown in their original 173 * orientation, no matter what the current rendering rotation or the page's 174 * Page::orientation() values are. In comparison with regular annotations, such 175 * annotations should therefore be transformed by an extra rotation at rendering 176 * time to "undo" such context-related rotations, which is equal to 177 * <code>-(rendering_rotation + page_orientation)</code>. The rotation pivot 178 * is the top-left corner of the boundary rectangle. 179 * 180 * In practice, %Poppler's \ref Page::renderToImage only "unrotates" the 181 * page orientation, and does <b>not</b> unrotate the rendering rotation. 182 * This ensures consistent renderings at different Page::Rotation values: 183 * annotations are always positioned as if they were being positioned at the 184 * default page orientation. 185 * 186 * Just like regular annotations, %Poppler Qt5 exposes normalized coordinates 187 * relative to the page's default orientation. However, behind the scenes, the 188 * coordinate system is different and %Poppler transparently transforms each 189 * shape. If you never call either Annotation::setFlags or 190 * Annotation::setBoundary, you don't need to worry about this; but if you do 191 * call them, then you need to adhere to the following rules: 192 * - Whenever you toggle the Annotation::FixedRotation flag, you <b>must</b> 193 * set again the boundary rectangle first, and then you <b>must</b> set 194 * again any other geometry-related property. 195 * - Whenever you modify the boundary rectangle of an annotation whose 196 * Annotation::FixedRotation flag is set, you <b>must</b> set again any other 197 * geometry-related property. 198 * 199 * These two rules are necessary to make %Poppler's transparent coordinate 200 * conversion work properly. 201 */ 202 class POPPLER_QT5_EXPORT Annotation 203 { 204 friend class AnnotationUtils; 205 friend class LinkMovie; 206 friend class LinkRendition; 207 208 public: 209 // enum definitions 210 /** 211 * Annotation subclasses 212 * 213 * \sa subType() 214 */ 215 // WARNING!!! oKular uses that very same values so if you change them notify the author! 216 enum SubType 217 { 218 AText = 1, ///< TextAnnotation 219 ALine = 2, ///< LineAnnotation 220 AGeom = 3, ///< GeomAnnotation 221 AHighlight = 4, ///< HighlightAnnotation 222 AStamp = 5, ///< StampAnnotation 223 AInk = 6, ///< InkAnnotation 224 ALink = 7, ///< LinkAnnotation 225 ACaret = 8, ///< CaretAnnotation 226 AFileAttachment = 9, ///< FileAttachmentAnnotation 227 ASound = 10, ///< SoundAnnotation 228 AMovie = 11, ///< MovieAnnotation 229 AScreen = 12, ///< ScreenAnnotation \since 0.20 230 AWidget = 13, ///< WidgetAnnotation \since 0.22 231 ARichMedia = 14, ///< RichMediaAnnotation \since 0.36 232 A_BASE = 0 233 }; 234 235 /** 236 * Annotation flags 237 * 238 * They can be OR'd together (e.g. Annotation::FixedRotation | Annotation::DenyPrint). 239 * 240 * \sa flags(), setFlags(int) 241 */ 242 // NOTE: Only flags that are known to work are documented 243 enum Flag 244 { 245 Hidden = 1, ///< Do not display or print the annotation 246 FixedSize = 2, 247 FixedRotation = 4, ///< Do not rotate the annotation according to page orientation and rendering rotation \warning Extra care is needed with this flag: see \ref annotFixedRotation 248 DenyPrint = 8, ///< Do not print the annotation 249 DenyWrite = 16, 250 DenyDelete = 32, 251 ToggleHidingOnMouse = 64, 252 External = 128 253 }; 254 255 enum LineStyle 256 { 257 Solid = 1, 258 Dashed = 2, 259 Beveled = 4, 260 Inset = 8, 261 Underline = 16 262 }; 263 enum LineEffect 264 { 265 NoEffect = 1, 266 Cloudy = 2 267 }; 268 enum RevScope 269 { 270 Root = 0 /** \since 0.20 */, 271 Reply = 1, 272 Group = 2, 273 Delete = 4 274 }; 275 enum RevType 276 { 277 None = 1, 278 Marked = 2, 279 Unmarked = 4, 280 Accepted = 8, 281 Rejected = 16, 282 Cancelled = 32, 283 Completed = 64 284 }; 285 286 /** 287 * Returns the author of the annotation. 288 */ 289 QString author() const; 290 /** 291 * Sets a new author for the annotation. 292 */ 293 void setAuthor(const QString &author); 294 295 QString contents() const; 296 void setContents(const QString &contents); 297 298 /** 299 * Returns the unique name (ID) of the annotation. 300 */ 301 QString uniqueName() const; 302 /** 303 * Sets a new unique name for the annotation. 304 * 305 * \note no check of the new uniqueName is done 306 */ 307 void setUniqueName(const QString &uniqueName); 308 309 QDateTime modificationDate() const; 310 void setModificationDate(const QDateTime &date); 311 312 QDateTime creationDate() const; 313 void setCreationDate(const QDateTime &date); 314 315 /** 316 * Returns this annotation's flags 317 * 318 * \sa Flag, setFlags(int) 319 */ 320 int flags() const; 321 /** 322 * Sets this annotation's flags 323 * 324 * \sa Flag, flags(), \ref annotFixedRotation 325 */ 326 void setFlags(int flags); 327 328 /** 329 * Returns this annotation's boundary rectangle in normalized coordinates 330 * 331 * \sa setBoundary(const QRectF&) 332 */ 333 QRectF boundary() const; 334 /** 335 * Sets this annotation's boundary rectangle 336 * 337 * The boundary rectangle is the smallest rectangle that contains the 338 * annotation. 339 * 340 * \warning This property is mandatory: you must always set this. 341 * 342 * \sa boundary(), \ref annotFixedRotation 343 */ 344 void setBoundary(const QRectF &boundary); 345 346 /** 347 * \short Container class for Annotation style information 348 * 349 * \since 0.20 350 */ 351 class POPPLER_QT5_EXPORT Style 352 { 353 public: 354 Style(); 355 Style(const Style &other); 356 Style &operator=(const Style &other); 357 ~Style(); 358 359 // appearance properties 360 QColor color() const; // black 361 void setColor(const QColor &color); 362 double opacity() const; // 1.0 363 void setOpacity(double opacity); 364 365 // pen properties 366 double width() const; // 1.0 367 void setWidth(double width); 368 LineStyle lineStyle() const; // LineStyle::Solid 369 void setLineStyle(LineStyle style); 370 double xCorners() const; // 0.0 371 void setXCorners(double radius); 372 double yCorners() const; // 0.0 373 void setYCorners(double radius); 374 const QVector<double> &dashArray() const; // [ 3 ] 375 void setDashArray(const QVector<double> &array); 376 377 // pen effects 378 LineEffect lineEffect() const; // LineEffect::NoEffect 379 void setLineEffect(LineEffect effect); 380 double effectIntensity() const; // 1.0 381 void setEffectIntensity(double intens); 382 383 private: 384 class Private; 385 QSharedDataPointer<Private> d; 386 }; 387 388 /// \since 0.20 389 Style style() const; 390 /// \since 0.20 391 void setStyle(const Style &style); 392 393 /** 394 * \short Container class for Annotation pop-up window information 395 * 396 * \since 0.20 397 */ 398 class POPPLER_QT5_EXPORT Popup 399 { 400 public: 401 Popup(); 402 Popup(const Popup &other); 403 Popup &operator=(const Popup &other); 404 ~Popup(); 405 406 // window state (Hidden, FixedRotation, Deny* flags allowed) 407 int flags() const; // -1 (never initialized) -> 0 (if inited and shown) 408 void setFlags(int flags); 409 410 // geometric properties 411 QRectF geometry() const; // no default 412 void setGeometry(const QRectF &geom); 413 414 // window contents/override properties 415 QString title() const; // '' text in the titlebar (overrides author) 416 void setTitle(const QString &title); 417 QString summary() const; // '' short description (displayed if not empty) 418 void setSummary(const QString &summary); 419 QString text() const; // '' text for the window (overrides annot->contents) 420 void setText(const QString &text); 421 422 private: 423 class Private; 424 QSharedDataPointer<Private> d; 425 }; 426 427 /// \since 0.20 428 Popup popup() const; 429 /// \warning Currently does nothing \since 0.20 430 void setPopup(const Popup &popup); 431 432 /// \since 0.20 433 RevScope revisionScope() const; // Root 434 435 /// \since 0.20 436 RevType revisionType() const; // None 437 438 /** 439 * Returns the revisions of this annotation 440 * 441 * \note The caller owns the returned annotations and they should 442 * be deleted when no longer required. 443 * 444 * \since 0.20 445 */ 446 QList<Annotation *> revisions() const; 447 448 /** 449 * The type of the annotation. 450 */ 451 virtual SubType subType() const = 0; 452 453 /** 454 * Returns the current appearance stream of this annotation. 455 * 456 * \since 21.10.0 457 */ 458 std::unique_ptr<AnnotationAppearance> annotationAppearance() const; 459 460 /** 461 * Sets the annotation's appearance stream with the @p annotationAppearance. 462 * 463 * \since 21.10.0 464 */ 465 void setAnnotationAppearance(const AnnotationAppearance &annotationAppearance); 466 467 /** 468 * Destructor. 469 */ 470 virtual ~Annotation(); 471 472 /** 473 * Describes the flags from an annotations 'AA' dictionary. 474 * 475 * This flag is used by the additionalAction() method for ScreenAnnotation 476 * and WidgetAnnotation. 477 * 478 * \since 0.22 479 */ 480 enum AdditionalActionType 481 { 482 CursorEnteringAction, ///< Performed when the cursor enters the annotation's active area 483 CursorLeavingAction, ///< Performed when the cursor exists the annotation's active area 484 MousePressedAction, ///< Performed when the mouse button is pressed inside the annotation's active area 485 MouseReleasedAction, ///< Performed when the mouse button is released inside the annotation's active area 486 FocusInAction, ///< Performed when the annotation receives the input focus 487 FocusOutAction, ///< Performed when the annotation loses the input focus 488 PageOpeningAction, ///< Performed when the page containing the annotation is opened 489 PageClosingAction, ///< Performed when the page containing the annotation is closed 490 PageVisibleAction, ///< Performed when the page containing the annotation becomes visible 491 PageInvisibleAction ///< Performed when the page containing the annotation becomes invisible 492 }; 493 494 protected: 495 /// \cond PRIVATE 496 explicit Annotation(AnnotationPrivate &dd); 497 Annotation(AnnotationPrivate &dd, const QDomNode &annNode); 498 void storeBaseAnnotationProperties(QDomNode &annNode, QDomDocument &document) const; 499 Q_DECLARE_PRIVATE(Annotation) 500 QExplicitlySharedDataPointer<AnnotationPrivate> d_ptr; 501 /// \endcond 502 503 private: 504 virtual void store(QDomNode &parentNode, QDomDocument &document) const = 0; 505 Q_DISABLE_COPY(Annotation) 506 }; 507 508 /** 509 * \short Annotation containing text. 510 * 511 * A text annotation is an object showing some text directly on the page, or 512 * linked to the contents using an icon shown on a page. 513 */ 514 class POPPLER_QT5_EXPORT TextAnnotation : public Annotation 515 { 516 friend class AnnotationUtils; 517 friend class AnnotationPrivate; 518 519 public: 520 // local enums 521 enum TextType 522 { 523 Linked, 524 InPlace 525 }; 526 enum InplaceIntent 527 { 528 Unknown, 529 Callout, 530 TypeWriter 531 }; 532 533 explicit TextAnnotation(TextType type); 534 ~TextAnnotation() override; 535 SubType subType() const override; 536 537 /** 538 The type of text annotation represented by this object 539 */ 540 TextType textType() const; 541 542 /** 543 The name of the icon for this text annotation. 544 545 Standard names for text annotation icons are: 546 - Comment 547 - Help 548 - Insert 549 - Key 550 - NewParagraph 551 - Note (this is the default icon to use) 552 - Paragraph 553 */ 554 QString textIcon() const; 555 556 /** 557 Set the name of the icon to use for this text annotation. 558 559 \sa textIcon for the list of standard names 560 */ 561 void setTextIcon(const QString &icon); 562 563 QFont textFont() const; 564 void setTextFont(const QFont &font); 565 /// \since 0.69 566 QColor textColor() const; 567 /// \since 0.69 568 void setTextColor(const QColor &color); 569 570 // 0:left, 1:center, 2:right 571 int inplaceAlign() const; 572 void setInplaceAlign(int align); 573 574 QPointF calloutPoint(int id) const; 575 /// \since 0.20 576 QVector<QPointF> calloutPoints() const; 577 /// \since 0.20 578 void setCalloutPoints(const QVector<QPointF> &points); 579 580 InplaceIntent inplaceIntent() const; 581 void setInplaceIntent(InplaceIntent intent); 582 583 private: 584 explicit TextAnnotation(const QDomNode &node); 585 explicit TextAnnotation(TextAnnotationPrivate &dd); 586 void store(QDomNode &parentNode, QDomDocument &document) const override; 587 void setTextType(TextType type); 588 Q_DECLARE_PRIVATE(TextAnnotation) 589 Q_DISABLE_COPY(TextAnnotation) 590 }; 591 592 /** 593 * \short Polygon/polyline annotation. 594 * 595 * This annotation represents a polygon (or polyline) to be drawn on a page. 596 */ 597 class POPPLER_QT5_EXPORT LineAnnotation : public Annotation 598 { 599 friend class AnnotationUtils; 600 friend class AnnotationPrivate; 601 602 public: 603 // local enums 604 /// \since 0.20 605 enum LineType 606 { 607 StraightLine, 608 Polyline 609 }; 610 enum TermStyle 611 { 612 Square, 613 Circle, 614 Diamond, 615 OpenArrow, 616 ClosedArrow, 617 None, 618 Butt, 619 ROpenArrow, 620 RClosedArrow, 621 Slash 622 }; 623 enum LineIntent 624 { 625 Unknown, 626 Arrow, 627 Dimension, 628 PolygonCloud 629 }; 630 631 /// \since 0.20 632 explicit LineAnnotation(LineType type); 633 ~LineAnnotation() override; 634 SubType subType() const override; 635 636 /// \since 0.20 637 LineType lineType() const; 638 639 QLinkedList<QPointF> linePoints() const; 640 void setLinePoints(const QLinkedList<QPointF> &points); 641 642 TermStyle lineStartStyle() const; 643 void setLineStartStyle(TermStyle style); 644 645 TermStyle lineEndStyle() const; 646 void setLineEndStyle(TermStyle style); 647 648 bool isLineClosed() const; 649 void setLineClosed(bool closed); 650 651 QColor lineInnerColor() const; 652 void setLineInnerColor(const QColor &color); 653 654 double lineLeadingForwardPoint() const; 655 void setLineLeadingForwardPoint(double point); 656 657 double lineLeadingBackPoint() const; 658 void setLineLeadingBackPoint(double point); 659 660 bool lineShowCaption() const; 661 void setLineShowCaption(bool show); 662 663 LineIntent lineIntent() const; 664 void setLineIntent(LineIntent intent); 665 666 private: 667 explicit LineAnnotation(const QDomNode &node); 668 explicit LineAnnotation(LineAnnotationPrivate &dd); 669 void store(QDomNode &parentNode, QDomDocument &document) const override; 670 void setLineType(LineType type); 671 Q_DECLARE_PRIVATE(LineAnnotation) 672 Q_DISABLE_COPY(LineAnnotation) 673 }; 674 675 /** 676 * \short Geometric annotation. 677 * 678 * The geometric annotation represents a geometric figure, like a rectangle or 679 * an ellipse. 680 */ 681 class POPPLER_QT5_EXPORT GeomAnnotation : public Annotation 682 { 683 friend class AnnotationUtils; 684 friend class AnnotationPrivate; 685 686 public: 687 GeomAnnotation(); 688 ~GeomAnnotation() override; 689 SubType subType() const override; 690 691 // common enums 692 enum GeomType 693 { 694 InscribedSquare, 695 InscribedCircle 696 }; 697 698 GeomType geomType() const; 699 void setGeomType(GeomType type); 700 701 QColor geomInnerColor() const; 702 void setGeomInnerColor(const QColor &color); 703 704 private: 705 explicit GeomAnnotation(const QDomNode &node); 706 explicit GeomAnnotation(GeomAnnotationPrivate &dd); 707 void store(QDomNode &parentNode, QDomDocument &document) const override; 708 Q_DECLARE_PRIVATE(GeomAnnotation) 709 Q_DISABLE_COPY(GeomAnnotation) 710 }; 711 712 /** 713 * \short Text highlight annotation. 714 * 715 * The highlight annotation represents some areas of text being "highlighted". 716 */ 717 class POPPLER_QT5_EXPORT HighlightAnnotation : public Annotation 718 { 719 friend class AnnotationUtils; 720 friend class AnnotationPrivate; 721 722 public: 723 HighlightAnnotation(); 724 ~HighlightAnnotation() override; 725 SubType subType() const override; 726 727 /** 728 The type of highlight 729 */ 730 enum HighlightType 731 { 732 Highlight, ///< highlighter pen style annotation 733 Squiggly, ///< jagged or squiggly underline 734 Underline, ///< straight line underline 735 StrikeOut ///< straight line through-line 736 }; 737 738 /** 739 Structure corresponding to a QuadPoints array. This matches a 740 quadrilateral that describes the area around a word (or set of 741 words) that are to be highlighted. 742 */ 743 struct Quad 744 { 745 QPointF points[4]; // 8 valid coords 746 bool capStart; // false (vtx 1-4) [K] 747 bool capEnd; // false (vtx 2-3) [K] 748 double feather; // 0.1 (in range 0..1) [K] 749 }; 750 751 /** 752 The type (style) of highlighting to use for this area 753 or these areas. 754 */ 755 HighlightType highlightType() const; 756 757 /** 758 Set the type of highlighting to use for the given area 759 or areas. 760 */ 761 void setHighlightType(HighlightType type); 762 763 /** 764 The list of areas to highlight. 765 */ 766 QList<Quad> highlightQuads() const; 767 768 /** 769 Set the areas to highlight. 770 */ 771 void setHighlightQuads(const QList<Quad> &quads); 772 773 private: 774 explicit HighlightAnnotation(const QDomNode &node); 775 explicit HighlightAnnotation(HighlightAnnotationPrivate &dd); 776 void store(QDomNode &parentNode, QDomDocument &document) const override; 777 Q_DECLARE_PRIVATE(HighlightAnnotation) 778 Q_DISABLE_COPY(HighlightAnnotation) 779 }; 780 781 /** 782 * \short Stamp annotation. 783 * 784 * A simple annotation drawing a stamp on a page. 785 */ 786 class POPPLER_QT5_EXPORT StampAnnotation : public Annotation 787 { 788 friend class AnnotationUtils; 789 friend class AnnotationPrivate; 790 791 public: 792 StampAnnotation(); 793 ~StampAnnotation() override; 794 SubType subType() const override; 795 796 /** 797 The name of the icon for this stamp annotation. 798 799 Standard names for stamp annotation icons are: 800 - Approved 801 - AsIs 802 - Confidential 803 - Departmental 804 - Draft (this is the default icon type) 805 - Experimental 806 - Expired 807 - Final 808 - ForComment 809 - ForPublicRelease 810 - NotApproved 811 - NotForPublicRelease 812 - Sold 813 - TopSecret 814 */ 815 QString stampIconName() const; 816 817 /** 818 Set the icon type for this stamp annotation. 819 820 \sa stampIconName for the list of standard icon names 821 */ 822 void setStampIconName(const QString &name); 823 824 /** 825 Set a custom icon for this stamp annotation. 826 827 \since 21.10.0 828 */ 829 void setStampCustomImage(const QImage &image); 830 831 private: 832 explicit StampAnnotation(const QDomNode &node); 833 explicit StampAnnotation(StampAnnotationPrivate &dd); 834 void store(QDomNode &parentNode, QDomDocument &document) const override; 835 Q_DECLARE_PRIVATE(StampAnnotation) 836 Q_DISABLE_COPY(StampAnnotation) 837 }; 838 839 /** 840 * \short Ink Annotation. 841 * 842 * Annotation representing an ink path on a page. 843 */ 844 class POPPLER_QT5_EXPORT InkAnnotation : public Annotation 845 { 846 friend class AnnotationUtils; 847 friend class AnnotationPrivate; 848 849 public: 850 InkAnnotation(); 851 ~InkAnnotation() override; 852 SubType subType() const override; 853 854 QList<QLinkedList<QPointF>> inkPaths() const; 855 void setInkPaths(const QList<QLinkedList<QPointF>> &paths); 856 857 private: 858 explicit InkAnnotation(const QDomNode &node); 859 void store(QDomNode &parentNode, QDomDocument &document) const override; 860 explicit InkAnnotation(InkAnnotationPrivate &dd); 861 Q_DECLARE_PRIVATE(InkAnnotation) 862 Q_DISABLE_COPY(InkAnnotation) 863 }; 864 865 class POPPLER_QT5_EXPORT LinkAnnotation : public Annotation 866 { 867 friend class AnnotationUtils; 868 friend class AnnotationPrivate; 869 870 public: 871 ~LinkAnnotation() override; 872 SubType subType() const override; 873 874 // local enums 875 enum HighlightMode 876 { 877 None, 878 Invert, 879 Outline, 880 Push 881 }; 882 883 /** \since 0.20 */ 884 Link *linkDestination() const; 885 void setLinkDestination(Link *link); 886 887 HighlightMode linkHighlightMode() const; 888 void setLinkHighlightMode(HighlightMode mode); 889 890 QPointF linkRegionPoint(int id) const; 891 // TODO Next ABI break, remove ref from point 892 void setLinkRegionPoint(int id, const QPointF &point); 893 894 private: 895 LinkAnnotation(); 896 explicit LinkAnnotation(const QDomNode &node); 897 explicit LinkAnnotation(LinkAnnotationPrivate &dd); 898 void store(QDomNode &parentNode, QDomDocument &document) const override; 899 Q_DECLARE_PRIVATE(LinkAnnotation) 900 Q_DISABLE_COPY(LinkAnnotation) 901 }; 902 903 /** 904 * \short Caret annotation. 905 * 906 * The caret annotation represents a symbol to indicate the presence of text. 907 */ 908 class POPPLER_QT5_EXPORT CaretAnnotation : public Annotation 909 { 910 friend class AnnotationUtils; 911 friend class AnnotationPrivate; 912 913 public: 914 CaretAnnotation(); 915 ~CaretAnnotation() override; 916 SubType subType() const override; 917 918 /** 919 * The symbols for the caret annotation. 920 */ 921 enum CaretSymbol 922 { 923 None, 924 P 925 }; 926 927 CaretSymbol caretSymbol() const; 928 void setCaretSymbol(CaretSymbol symbol); 929 930 private: 931 explicit CaretAnnotation(const QDomNode &node); 932 explicit CaretAnnotation(CaretAnnotationPrivate &dd); 933 void store(QDomNode &parentNode, QDomDocument &document) const override; 934 Q_DECLARE_PRIVATE(CaretAnnotation) 935 Q_DISABLE_COPY(CaretAnnotation) 936 }; 937 938 /** 939 * \short File attachment annotation. 940 * 941 * The file attachment annotation represents a file embedded in the document. 942 * 943 * \since 0.10 944 */ 945 class POPPLER_QT5_EXPORT FileAttachmentAnnotation : public Annotation 946 { 947 friend class AnnotationPrivate; 948 949 public: 950 ~FileAttachmentAnnotation() override; 951 SubType subType() const override; 952 953 /** 954 * Returns the name of the icon of this annotation. 955 */ 956 QString fileIconName() const; 957 /** 958 * Sets a new name for the icon of this annotation. 959 */ 960 void setFileIconName(const QString &icon); 961 962 /** 963 * Returns the EmbeddedFile of this annotation. 964 */ 965 EmbeddedFile *embeddedFile() const; 966 /** 967 * Sets a new EmbeddedFile for this annotation. 968 * 969 * \note FileAttachmentAnnotation takes ownership of the object 970 */ 971 void setEmbeddedFile(EmbeddedFile *ef); 972 973 private: 974 FileAttachmentAnnotation(); 975 explicit FileAttachmentAnnotation(const QDomNode &node); 976 explicit FileAttachmentAnnotation(FileAttachmentAnnotationPrivate &dd); 977 void store(QDomNode &parentNode, QDomDocument &document) const override; 978 Q_DECLARE_PRIVATE(FileAttachmentAnnotation) 979 Q_DISABLE_COPY(FileAttachmentAnnotation) 980 }; 981 982 /** 983 * \short Sound annotation. 984 * 985 * The sound annotation represents a sound to be played when activated. 986 * 987 * \since 0.10 988 */ 989 class POPPLER_QT5_EXPORT SoundAnnotation : public Annotation 990 { 991 friend class AnnotationPrivate; 992 993 public: 994 ~SoundAnnotation() override; 995 SubType subType() const override; 996 997 /** 998 * Returns the name of the icon of this annotation. 999 */ 1000 QString soundIconName() const; 1001 /** 1002 * Sets a new name for the icon of this annotation. 1003 */ 1004 void setSoundIconName(const QString &icon); 1005 1006 /** 1007 * Returns the SoundObject of this annotation. 1008 */ 1009 SoundObject *sound() const; 1010 /** 1011 * Sets a new SoundObject for this annotation. 1012 * 1013 * \note SoundAnnotation takes ownership of the object 1014 */ 1015 void setSound(SoundObject *s); 1016 1017 private: 1018 SoundAnnotation(); 1019 explicit SoundAnnotation(const QDomNode &node); 1020 explicit SoundAnnotation(SoundAnnotationPrivate &dd); 1021 void store(QDomNode &parentNode, QDomDocument &document) const override; 1022 Q_DECLARE_PRIVATE(SoundAnnotation) 1023 Q_DISABLE_COPY(SoundAnnotation) 1024 }; 1025 1026 /** 1027 * \short Movie annotation. 1028 * 1029 * The movie annotation represents a movie to be played when activated. 1030 * 1031 * \since 0.10 1032 */ 1033 class POPPLER_QT5_EXPORT MovieAnnotation : public Annotation 1034 { 1035 friend class AnnotationPrivate; 1036 1037 public: 1038 ~MovieAnnotation() override; 1039 SubType subType() const override; 1040 1041 /** 1042 * Returns the MovieObject of this annotation. 1043 */ 1044 MovieObject *movie() const; 1045 /** 1046 * Sets a new MovieObject for this annotation. 1047 * 1048 * \note MovieAnnotation takes ownership of the object 1049 */ 1050 void setMovie(MovieObject *movie); 1051 1052 /** 1053 * Returns the title of the movie of this annotation. 1054 */ 1055 QString movieTitle() const; 1056 /** 1057 * Sets a new title for the movie of this annotation. 1058 */ 1059 void setMovieTitle(const QString &title); 1060 1061 private: 1062 MovieAnnotation(); 1063 explicit MovieAnnotation(const QDomNode &node); 1064 explicit MovieAnnotation(MovieAnnotationPrivate &dd); 1065 void store(QDomNode &parentNode, QDomDocument &document) const override; 1066 Q_DECLARE_PRIVATE(MovieAnnotation) 1067 Q_DISABLE_COPY(MovieAnnotation) 1068 }; 1069 1070 /** 1071 * \short Screen annotation. 1072 * 1073 * The screen annotation represents a screen to be played when activated. 1074 * 1075 * \since 0.20 1076 */ 1077 class POPPLER_QT5_EXPORT ScreenAnnotation : public Annotation 1078 { 1079 friend class AnnotationPrivate; 1080 1081 public: 1082 ~ScreenAnnotation() override; 1083 1084 SubType subType() const override; 1085 1086 /** 1087 * Returns the LinkRendition of this annotation. 1088 */ 1089 LinkRendition *action() const; 1090 1091 /** 1092 * Sets a new LinkRendition for this annotation. 1093 * 1094 * \note ScreenAnnotation takes ownership of the object 1095 */ 1096 void setAction(LinkRendition *action); 1097 1098 /** 1099 * Returns the title of the screen of this annotation. 1100 */ 1101 QString screenTitle() const; 1102 1103 /** 1104 * Sets a new title for the screen of this annotation. 1105 */ 1106 void setScreenTitle(const QString &title); 1107 1108 /** 1109 * Returns the additional action of the given @p type fo the annotation or 1110 * @c 0 if no action has been defined. 1111 * 1112 * \since 0.22 1113 */ 1114 Link *additionalAction(AdditionalActionType type) const; 1115 1116 private: 1117 ScreenAnnotation(); 1118 explicit ScreenAnnotation(ScreenAnnotationPrivate &dd); 1119 void store(QDomNode &parentNode, QDomDocument &document) const override; // stub 1120 Q_DECLARE_PRIVATE(ScreenAnnotation) 1121 Q_DISABLE_COPY(ScreenAnnotation) 1122 }; 1123 1124 /** 1125 * \short Widget annotation. 1126 * 1127 * The widget annotation represents a widget (form field) on a page. 1128 * 1129 * \note This class is just provided for consistency of the annotation API, 1130 * use the FormField classes to get all the form-related information. 1131 * 1132 * \since 0.22 1133 */ 1134 class POPPLER_QT5_EXPORT WidgetAnnotation : public Annotation 1135 { 1136 friend class AnnotationPrivate; 1137 1138 public: 1139 ~WidgetAnnotation() override; 1140 1141 SubType subType() const override; 1142 1143 /** 1144 * Returns the additional action of the given @p type fo the annotation or 1145 * @c 0 if no action has been defined. 1146 * 1147 * \since 0.22 1148 */ 1149 Link *additionalAction(AdditionalActionType type) const; 1150 1151 private: 1152 WidgetAnnotation(); 1153 explicit WidgetAnnotation(WidgetAnnotationPrivate &dd); 1154 void store(QDomNode &parentNode, QDomDocument &document) const override; // stub 1155 Q_DECLARE_PRIVATE(WidgetAnnotation) 1156 Q_DISABLE_COPY(WidgetAnnotation) 1157 }; 1158 1159 /** 1160 * \short RichMedia annotation. 1161 * 1162 * The RichMedia annotation represents a video or sound on a page. 1163 * 1164 * \since 0.36 1165 */ 1166 class POPPLER_QT5_EXPORT RichMediaAnnotation : public Annotation 1167 { 1168 friend class AnnotationPrivate; 1169 1170 public: 1171 ~RichMediaAnnotation() override; 1172 1173 SubType subType() const override; 1174 1175 /** 1176 * The params object of a RichMediaAnnotation::Instance object. 1177 * 1178 * The params object provides media specific parameters, to play 1179 * back the media inside the PDF viewer. 1180 * 1181 * At the moment only parameters for flash player are supported. 1182 */ 1183 class POPPLER_QT5_EXPORT Params 1184 { 1185 friend class AnnotationPrivate; 1186 1187 public: 1188 Params(); 1189 ~Params(); 1190 1191 /** 1192 * Returns the parameters for the flash player. 1193 */ 1194 QString flashVars() const; 1195 1196 private: 1197 void setFlashVars(const QString &flashVars); 1198 1199 class Private; 1200 QScopedPointer<Private> d; 1201 }; 1202 1203 /** 1204 * The instance object of a RichMediaAnnotation::Configuration object. 1205 * 1206 * The instance object represents one media object, that should be shown 1207 * on the page. It has a media type and a Params object, to define the 1208 * media specific parameters. 1209 */ 1210 class POPPLER_QT5_EXPORT Instance 1211 { 1212 friend class AnnotationPrivate; 1213 1214 public: 1215 /** 1216 * Describes the media type of the instance. 1217 */ 1218 enum Type 1219 { 1220 Type3D, ///< A 3D media file. 1221 TypeFlash, ///< A Flash media file. 1222 TypeSound, ///< A sound media file. 1223 TypeVideo ///< A video media file. 1224 }; 1225 1226 Instance(); 1227 ~Instance(); 1228 1229 /** 1230 * Returns the media type of the instance. 1231 */ 1232 Type type() const; 1233 1234 /** 1235 * Returns the params object of the instance or @c 0 if it doesn't exist. 1236 */ 1237 RichMediaAnnotation::Params *params() const; 1238 1239 private: 1240 void setType(Type type); 1241 void setParams(RichMediaAnnotation::Params *params); 1242 1243 class Private; 1244 QScopedPointer<Private> d; 1245 }; 1246 1247 /** 1248 * The configuration object of a RichMediaAnnotation::Content object. 1249 * 1250 * The configuration object provides access to the various Instance objects 1251 * of the rich media annotation. 1252 */ 1253 class POPPLER_QT5_EXPORT Configuration 1254 { 1255 friend class AnnotationPrivate; 1256 1257 public: 1258 /** 1259 * Describes the media type of the configuration. 1260 */ 1261 enum Type 1262 { 1263 Type3D, ///< A 3D media file. 1264 TypeFlash, ///< A Flash media file. 1265 TypeSound, ///< A sound media file. 1266 TypeVideo ///< A video media file. 1267 }; 1268 1269 Configuration(); 1270 ~Configuration(); 1271 1272 /** 1273 * Returns the media type of the configuration. 1274 */ 1275 Type type() const; 1276 1277 /** 1278 * Returns the name of the configuration. 1279 */ 1280 QString name() const; 1281 1282 /** 1283 * Returns the list of Instance objects of the configuration. 1284 */ 1285 QList<RichMediaAnnotation::Instance *> instances() const; 1286 1287 private: 1288 void setType(Type type); 1289 void setName(const QString &name); 1290 void setInstances(const QList<RichMediaAnnotation::Instance *> &instances); 1291 1292 class Private; 1293 QScopedPointer<Private> d; 1294 }; 1295 1296 /** 1297 * The asset object of a RichMediaAnnotation::Content object. 1298 * 1299 * The asset object provides a mapping between identifier name, as 1300 * used in the flash vars string of RichMediaAnnotation::Params, and the 1301 * associated file spec object. 1302 */ 1303 class POPPLER_QT5_EXPORT Asset 1304 { 1305 friend class AnnotationPrivate; 1306 1307 public: 1308 Asset(); 1309 ~Asset(); 1310 1311 /** 1312 * Returns the identifier name of the asset. 1313 */ 1314 QString name() const; 1315 1316 /** 1317 * Returns the embedded file the asset points to. 1318 */ 1319 EmbeddedFile *embeddedFile() const; 1320 1321 private: 1322 void setName(const QString &name); 1323 void setEmbeddedFile(EmbeddedFile *embeddedFile); 1324 1325 class Private; 1326 QScopedPointer<Private> d; 1327 }; 1328 1329 /** 1330 * The content object of a RichMediaAnnotation. 1331 * 1332 * The content object provides access to the list of configurations 1333 * and assets of the rich media annotation. 1334 */ 1335 class POPPLER_QT5_EXPORT Content 1336 { 1337 friend class AnnotationPrivate; 1338 1339 public: 1340 Content(); 1341 ~Content(); 1342 1343 /** 1344 * Returns the list of configuration objects of the content object. 1345 */ 1346 QList<RichMediaAnnotation::Configuration *> configurations() const; 1347 1348 /** 1349 * Returns the list of asset objects of the content object. 1350 */ 1351 QList<RichMediaAnnotation::Asset *> assets() const; 1352 1353 private: 1354 void setConfigurations(const QList<RichMediaAnnotation::Configuration *> &configurations); 1355 void setAssets(const QList<RichMediaAnnotation::Asset *> &assets); 1356 1357 class Private; 1358 QScopedPointer<Private> d; 1359 }; 1360 1361 /** 1362 * The activation object of the RichMediaAnnotation::Settings object. 1363 * 1364 * The activation object is a wrapper around the settings for the activation 1365 * state. At the moment it provides only the activation condition. 1366 */ 1367 class POPPLER_QT5_EXPORT Activation 1368 { 1369 friend class AnnotationPrivate; 1370 1371 public: 1372 /** 1373 * Describes the condition for activating the rich media. 1374 */ 1375 enum Condition 1376 { 1377 PageOpened, ///< Activate when page is opened. 1378 PageVisible, ///< Activate when page becomes visible. 1379 UserAction ///< Activate when user interacts with the annotation. 1380 }; 1381 1382 Activation(); 1383 ~Activation(); 1384 1385 /** 1386 * Returns the activation condition. 1387 */ 1388 Condition condition() const; 1389 1390 private: 1391 void setCondition(Condition condition); 1392 1393 class Private; 1394 QScopedPointer<Private> d; 1395 }; 1396 1397 /** 1398 * The deactivation object of the RichMediaAnnotation::Settings object. 1399 * 1400 * The deactivation object is a wrapper around the settings for the deactivation 1401 * state. At the moment it provides only the deactivation condition. 1402 */ 1403 class POPPLER_QT5_EXPORT Deactivation 1404 { 1405 friend class AnnotationPrivate; 1406 1407 public: 1408 /** 1409 * Describes the condition for deactivating the rich media. 1410 */ 1411 enum Condition 1412 { 1413 PageClosed, ///< Deactivate when page is closed. 1414 PageInvisible, ///< Deactivate when page becomes invisible. 1415 UserAction ///< Deactivate when user interacts with the annotation. 1416 }; 1417 1418 Deactivation(); 1419 ~Deactivation(); 1420 1421 /** 1422 * Returns the deactivation condition. 1423 */ 1424 Condition condition() const; 1425 1426 private: 1427 void setCondition(Condition condition); 1428 1429 class Private; 1430 QScopedPointer<Private> d; 1431 }; 1432 1433 /** 1434 * The settings object of a RichMediaAnnotation. 1435 * 1436 * The settings object provides access to the configuration objects 1437 * for annotation activation and deactivation. 1438 */ 1439 class POPPLER_QT5_EXPORT Settings 1440 { 1441 friend class AnnotationPrivate; 1442 1443 public: 1444 Settings(); 1445 ~Settings(); 1446 1447 /** 1448 * Returns the Activation object of the settings object or @c 0 if it doesn't exist. 1449 */ 1450 RichMediaAnnotation::Activation *activation() const; 1451 1452 /** 1453 * Returns the Deactivation object of the settings object or @c 0 if it doesn't exist. 1454 */ 1455 RichMediaAnnotation::Deactivation *deactivation() const; 1456 1457 private: 1458 void setActivation(RichMediaAnnotation::Activation *activation); 1459 void setDeactivation(RichMediaAnnotation::Deactivation *deactivation); 1460 1461 class Private; 1462 QScopedPointer<Private> d; 1463 }; 1464 1465 /** 1466 * Returns the Settings object of the rich media annotation or @c 0 if it doesn't exist. 1467 */ 1468 RichMediaAnnotation::Settings *settings() const; 1469 1470 /** 1471 * Returns the Content object of the rich media annotation or @c 0 if it doesn't exist. 1472 */ 1473 RichMediaAnnotation::Content *content() const; 1474 1475 private: 1476 void setSettings(RichMediaAnnotation::Settings *settings); 1477 void setContent(RichMediaAnnotation::Content *content); 1478 1479 RichMediaAnnotation(); 1480 explicit RichMediaAnnotation(const QDomNode &node); 1481 explicit RichMediaAnnotation(RichMediaAnnotationPrivate &dd); 1482 void store(QDomNode &parentNode, QDomDocument &document) const override; 1483 Q_DECLARE_PRIVATE(RichMediaAnnotation) 1484 Q_DISABLE_COPY(RichMediaAnnotation) 1485 }; 1486 1487 } 1488 1489 #endif 1490