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