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

source code of poppler/qt6/src/poppler-annotation.h