Debian Codegraph @

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