Debian Codegraph @

qt5/src/poppler-annotation.h

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