Debian Codegraph @

qt5/src/poppler-link.h

raw
1 /* poppler-link.h: qt interface to poppler
2 * Copyright (C) 2006, 2013, 2016, 2018, 2019, 2021, 2022, 2024, Albert Astals Cid <[email protected]>
3 * Copyright (C) 2007-2008, 2010, Pino Toscano <[email protected]>
4 * Copyright (C) 2010, 2012, Guillermo Amaral <[email protected]>
5 * Copyright (C) 2012, Tobias Koenig <[email protected]>
6 * Copyright (C) 2013, Anthony Granger <[email protected]>
7 * Copyright (C) 2018 Intevation GmbH <[email protected]>
8 * Copyright (C) 2020 Oliver Sander <[email protected]>
9 * Copyright (C) 2024 Pratham Gandhi <[email protected]>
10 * Adapting code from
11 * Copyright (C) 2004 by Enrico Ros <[email protected]>
12 *
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2, or (at your option)
16 * any later version.
17 *
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
22 *
23 * You should have received a copy of the GNU General Public License
24 * along with this program; if not, write to the Free Software
25 * Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA.
26 */
27
28 #ifndef _POPPLER_LINK_H_
29 #define _POPPLER_LINK_H_
30
31 #include <QtCore/QString>
32 #include <QtCore/QRectF>
33 #include <QtCore/QSharedDataPointer>
34 #include <QtCore/QVector>
35 #include "poppler-export.h"
36
37 #include <memory>
38
39 struct Ref;
40 class MediaRendition;
41
42 namespace Poppler {
43
44 class LinkPrivate;
45 class LinkGotoPrivate;
46 class LinkExecutePrivate;
47 class LinkBrowsePrivate;
48 class LinkActionPrivate;
49 class LinkSoundPrivate;
50 class LinkJavaScriptPrivate;
51 class LinkMoviePrivate;
52 class LinkDestinationData;
53 class LinkDestinationPrivate;
54 class LinkRenditionPrivate;
55 class LinkOCGStatePrivate;
56 class LinkHidePrivate;
57 class LinkResetFormPrivate;
58 class LinkSubmitFormPrivate;
59 class MediaRendition;
60 class MovieAnnotation;
61 class ScreenAnnotation;
62 class SoundObject;
63
64 /**
65 * \short A destination.
66 *
67 * The LinkDestination class represent a "destination" (in terms of visual
68 * viewport to be displayed) for \link Poppler::LinkGoto GoTo\endlink links,
69 * and items in the table of contents (TOC) of a document.
70 *
71 * Coordinates are in 0..1 range
72 */
73 class POPPLER_QT5_EXPORT LinkDestination
74 {
75 public:
76 /**
77 * The possible kind of "viewport destination".
78 */
79 enum Kind
80 {
81 /**
82 * The new viewport is specified in terms of:
83 * - possible new left coordinate (see isChangeLeft() )
84 * - possible new top coordinate (see isChangeTop() )
85 * - possible new zoom level (see isChangeZoom() )
86 */
87 destXYZ = 1,
88 destFit = 2,
89 destFitH = 3,
90 destFitV = 4,
91 destFitR = 5,
92 destFitB = 6,
93 destFitBH = 7,
94 destFitBV = 8
95 };
96
97 /// \cond PRIVATE
98 explicit LinkDestination(const LinkDestinationData &data);
99 explicit LinkDestination(const QString &description);
100 /// \endcond
101 /**
102 * Copy constructor.
103 */
104 LinkDestination(const LinkDestination &other);
105 /**
106 * Destructor.
107 */
108 ~LinkDestination();
109
110 // Accessors.
111 /**
112 * The kind of destination.
113 */
114 Kind kind() const;
115 /**
116 * Which page is the target of this destination.
117 *
118 * \note this number is 1-based, so for a 5 pages document the
119 * valid page numbers go from 1 to 5 (both included).
120 */
121 int pageNumber() const;
122 /**
123 * The new left for the viewport of the target page, in case
124 * it is specified to be changed (see isChangeLeft() )
125 */
126 double left() const;
127 double bottom() const;
128 double right() const;
129 /**
130 * The new top for the viewport of the target page, in case
131 * it is specified to be changed (see isChangeTop() )
132 */
133 double top() const;
134 double zoom() const;
135 /**
136 * Whether the left of the viewport on the target page should
137 * be changed.
138 *
139 * \see left()
140 */
141 bool isChangeLeft() const;
142 /**
143 * Whether the top of the viewport on the target page should
144 * be changed.
145 *
146 * \see top()
147 */
148 bool isChangeTop() const;
149 /**
150 * Whether the zoom level should be changed.
151 *
152 * \see zoom()
153 */
154 bool isChangeZoom() const;
155
156 /**
157 * Return a string repesentation of this destination.
158 */
159 QString toString() const;
160
161 /**
162 * Return the name of this destination.
163 *
164 * \since 0.12
165 */
166 QString destinationName() const;
167
168 /**
169 * Assignment operator.
170 */
171 LinkDestination &operator=(const LinkDestination &other);
172
173 private:
174 QSharedDataPointer<LinkDestinationPrivate> d;
175 };
176
177 /**
178 * \short Encapsulates data that describes a link.
179 *
180 * This is the base class for links. It makes mandatory for inherited
181 * kind of links to reimplement the linkType() method and return the type of
182 * the link described by the reimplemented class.
183 */
184 class POPPLER_QT5_EXPORT Link
185 {
186 public:
187 /// \cond PRIVATE
188 explicit Link(const QRectF &linkArea);
189 /// \endcond
190
191 /**
192 * The possible kinds of link.
193 *
194 * Inherited classes must return an unique identifier
195 */
196 enum LinkType
197 {
198 None, ///< Unknown link
199 Goto, ///< A "Go To" link
200 Execute, ///< A command to be executed
201 Browse, ///< An URL to be browsed (eg "http://poppler.freedesktop.org")
202 Action, ///< A "standard" action to be executed in the viewer
203 Sound, ///< A link representing a sound to be played
204 Movie, ///< An action to be executed on a movie
205 Rendition, ///< A rendition link \since 0.20
206 JavaScript, ///< A JavaScript code to be interpreted \since 0.10
207 OCGState, ///< An Optional Content Group state change \since 0.50
208 Hide, ///< An action to hide a field \since 0.64
209 ResetForm, ///< An action to reset the form \since 24.07
210 SubmitForm, ///< An action to submit a form \since 24.10
211 };
212
213 /**
214 * The type of this link.
215 */
216 virtual LinkType linkType() const;
217
218 /**
219 * Destructor.
220 */
221 virtual ~Link();
222
223 /**
224 * The area of a Page where the link should be active.
225 *
226 * \note this can be a null rect, in this case the link represents
227 * a general action. The area is given in 0..1 range
228 */
229 QRectF linkArea() const;
230
231 /**
232 * Get the next links to be activated / executed after this link.
233 *
234 * \since 0.64
235 */
236 QVector<Link *> nextLinks() const;
237
238 protected:
239 /// \cond PRIVATE
240 explicit Link(LinkPrivate &dd);
241 Q_DECLARE_PRIVATE(Link)
242 LinkPrivate *d_ptr;
243 /// \endcond
244
245 private:
246 Q_DISABLE_COPY(Link)
247 };
248
249 /**
250 * \brief Viewport reaching request.
251 *
252 * With a LinkGoto link, the document requests the specified viewport to be
253 * reached (aka, displayed in a viewer). Furthermore, if a file name is specified,
254 * then the destination refers to that document (and not to the document the
255 * current LinkGoto belongs to).
256 */
257 class POPPLER_QT5_EXPORT LinkGoto : public Link
258 {
259 public:
260 /**
261 * Create a new Goto link.
262 *
263 * \param linkArea the active area of the link
264 * \param extFileName if not empty, the file name to be open
265 * \param destination the destination to be reached
266 */
267 // TODO Next ABI break, make extFileName const &
268 LinkGoto(const QRectF &linkArea, QString extFileName, const LinkDestination &destination);
269 /**
270 * Destructor.
271 */
272 ~LinkGoto() override;
273
274 /**
275 * Whether the destination is in an external document
276 * (i.e. not the current document)
277 */
278 bool isExternal() const;
279 // query for goto parameters
280 /**
281 * The file name of the document the destination() refers to,
282 * or an empty string in case it refers to the current document.
283 */
284 QString fileName() const;
285 /**
286 * The destination to reach.
287 */
288 LinkDestination destination() const;
289 LinkType linkType() const override;
290
291 private:
292 Q_DECLARE_PRIVATE(LinkGoto)
293 Q_DISABLE_COPY(LinkGoto)
294 };
295
296 /**
297 * \brief Generic execution request.
298 *
299 * The LinkExecute link represent a "file name" execution request. The result
300 * depends on the \link fileName() file name\endlink:
301 * - if it is a document, then it is requested to be open
302 * - otherwise, it represents an executable to be run with the specified parameters
303 */
304 class POPPLER_QT5_EXPORT LinkExecute : public Link
305 {
306 public:
307 /**
308 * The file name to be executed
309 */
310 QString fileName() const;
311 /**
312 * The parameters for the command.
313 */
314 QString parameters() const;
315
316 /**
317 * Create a new Execute link.
318 *
319 * \param linkArea the active area of the link
320 * \param file the file name to be open, or the program to be execute
321 * \param params the parameters for the program to execute
322 */
323 LinkExecute(const QRectF &linkArea, const QString &file, const QString &params);
324 /**
325 * Destructor.
326 */
327 ~LinkExecute() override;
328 LinkType linkType() const override;
329
330 private:
331 Q_DECLARE_PRIVATE(LinkExecute)
332 Q_DISABLE_COPY(LinkExecute)
333 };
334
335 /**
336 * \brief An URL to browse.
337 *
338 * The LinkBrowse link holds a URL (eg 'http://poppler.freedesktop.org',
339 * 'mailto:[email protected]', etc) to be open.
340 *
341 * The format of the URL is specified by RFC 2396 (http://www.ietf.org/rfc/rfc2396.txt)
342 */
343 class POPPLER_QT5_EXPORT LinkBrowse : public Link
344 {
345 public:
346 /**
347 * The URL to open
348 */
349 QString url() const;
350
351 /**
352 * Create a new browse link.
353 *
354 * \param linkArea the active area of the link
355 * \param url the URL to be open
356 */
357 LinkBrowse(const QRectF &linkArea, const QString &url);
358 /**
359 * Destructor.
360 */
361 ~LinkBrowse() override;
362 LinkType linkType() const override;
363
364 private:
365 Q_DECLARE_PRIVATE(LinkBrowse)
366 Q_DISABLE_COPY(LinkBrowse)
367 };
368
369 /**
370 * \brief "Standard" action request.
371 *
372 * The LinkAction class represents a link that request a "standard" action
373 * to be performed by the viewer on the displayed document.
374 */
375 class POPPLER_QT5_EXPORT LinkAction : public Link
376 {
377 public:
378 /**
379 * The possible types of actions
380 */
381 enum ActionType
382 {
383 PageFirst = 1,
384 PagePrev = 2,
385 PageNext = 3,
386 PageLast = 4,
387 HistoryBack = 5,
388 HistoryForward = 6,
389 Quit = 7,
390 Presentation = 8,
391 EndPresentation = 9,
392 Find = 10,
393 GoToPage = 11,
394 Close = 12,
395 Print = 13, ///< \since 0.16
396 SaveAs = 14 ///< \since 22.04
397 };
398
399 /**
400 * The action of the current LinkAction
401 */
402 ActionType actionType() const;
403
404 /**
405 * Create a new Action link, that executes a specified action
406 * on the document.
407 *
408 * \param linkArea the active area of the link
409 * \param actionType which action should be executed
410 */
411 LinkAction(const QRectF &linkArea, ActionType actionType);
412 /**
413 * Destructor.
414 */
415 ~LinkAction() override;
416 LinkType linkType() const override;
417
418 private:
419 Q_DECLARE_PRIVATE(LinkAction)
420 Q_DISABLE_COPY(LinkAction)
421 };
422
423 /**
424 * Sound: a sound to be played.
425 *
426 * \since 0.6
427 */
428 class POPPLER_QT5_EXPORT LinkSound : public Link
429 {
430 public:
431 // create a Link_Sound
432 LinkSound(const QRectF &linkArea, double volume, bool sync, bool repeat, bool mix, SoundObject *sound);
433 /**
434 * Destructor.
435 */
436 ~LinkSound() override;
437
438 LinkType linkType() const override;
439
440 /**
441 * The volume to be used when playing the sound.
442 *
443 * The volume is in the range [ -1, 1 ], where:
444 * - a negative number: no volume (mute)
445 * - 1: full volume
446 */
447 double volume() const;
448 /**
449 * Whether the playback of the sound should be synchronous
450 * (thus blocking, waiting for the end of the sound playback).
451 */
452 bool synchronous() const;
453 /**
454 * Whether the sound should be played continuously (that is,
455 * started again when it ends)
456 */
457 bool repeat() const;
458 /**
459 * Whether the playback of this sound can be mixed with
460 * playbacks with other sounds of the same document.
461 *
462 * \note When false, any other playback must be stopped before
463 * playing the sound.
464 */
465 bool mix() const;
466 /**
467 * The sound object to be played
468 */
469 SoundObject *sound() const;
470
471 private:
472 Q_DECLARE_PRIVATE(LinkSound)
473 Q_DISABLE_COPY(LinkSound)
474 };
475
476 /**
477 * Rendition: Rendition link.
478 *
479 * \since 0.20
480 */
481 class POPPLER_QT5_EXPORT LinkRendition : public Link
482 {
483 public:
484 /**
485 * Describes the possible rendition actions.
486 *
487 * \since 0.22
488 */
489 enum RenditionAction
490 {
491 NoRendition,
492 PlayRendition,
493 StopRendition,
494 PauseRendition,
495 ResumeRendition
496 };
497
498 /**
499 * Create a new rendition link.
500 *
501 * \param linkArea the active area of the link
502 * \param rendition the media rendition object. Ownership is taken
503 * \param operation the numeric operation (action) (@see ::LinkRendition::RenditionOperation)
504 * \param script the java script code
505 * \param annotationReference the object reference of the screen annotation associated with this rendition action
506 * \since 0.22
507 */
508 // TODO Next ABI break, remove & from annotationReference
509 [[deprecated]] LinkRendition(const QRectF &linkArea, ::MediaRendition *rendition, int operation, const QString &script, const Ref &annotationReference);
510
511 /**
512 * Create a new rendition link.
513 *
514 * \param linkArea the active area of the link
515 * \param rendition the media rendition object.
516 * \param operation the numeric operation (action) (@see ::LinkRendition::RenditionOperation)
517 * \param script the java script code
518 * \param annotationReference the object reference of the screen annotation associated with this rendition action
519 */
520 LinkRendition(const QRectF &linkArea, std::unique_ptr<::MediaRendition> &&rendition, int operation, const QString &script, const Ref annotationReference);
521
522 /**
523 * Destructor.
524 */
525 ~LinkRendition() override;
526
527 LinkType linkType() const override;
528
529 /**
530 * Returns the media rendition object if the redition provides one, @c 0 otherwise
531 */
532 MediaRendition *rendition() const;
533
534 /**
535 * Returns the action that should be executed if a rendition object is provided.
536 *
537 * \since 0.22
538 */
539 RenditionAction action() const;
540
541 /**
542 * The JS code that shall be executed or an empty string.
543 *
544 * \since 0.22
545 */
546 QString script() const;
547
548 /**
549 * Returns whether the given @p annotation is the referenced screen annotation for this rendition @p link.
550 *
551 * \since 0.22
552 */
553 bool isReferencedAnnotation(const ScreenAnnotation *annotation) const;
554
555 private:
556 Q_DECLARE_PRIVATE(LinkRendition)
557 Q_DISABLE_COPY(LinkRendition)
558 };
559
560 /**
561 * JavaScript: a JavaScript code to be interpreted.
562 *
563 * \since 0.10
564 */
565 class POPPLER_QT5_EXPORT LinkJavaScript : public Link
566 {
567 public:
568 /**
569 * Create a new JavaScript link.
570 *
571 * \param linkArea the active area of the link
572 * \param js the JS code to be interpreted
573 */
574 LinkJavaScript(const QRectF &linkArea, const QString &js);
575 /**
576 * Destructor.
577 */
578 ~LinkJavaScript() override;
579
580 LinkType linkType() const override;
581
582 /**
583 * The JS code
584 */
585 QString script() const;
586
587 private:
588 Q_DECLARE_PRIVATE(LinkJavaScript)
589 Q_DISABLE_COPY(LinkJavaScript)
590 };
591
592 /**
593 * Movie: a movie to be played.
594 *
595 * \since 0.20
596 */
597 class POPPLER_QT5_EXPORT LinkMovie : public Link
598 {
599 public:
600 /**
601 * Describes the operation to be performed on the movie.
602 */
603 enum Operation
604 {
605 Play,
606 Stop,
607 Pause,
608 Resume
609 };
610
611 /**
612 * Create a new Movie link.
613 *
614 * \param linkArea the active area of the link
615 * \param operation the operation to be performed on the movie
616 * \param annotationTitle the title of the movie annotation identifying the movie to be played
617 * \param annotationReference the object reference of the movie annotation identifying the movie to be played
618 *
619 * Note: This constructor is supposed to be used by Poppler::Page only.
620 */
621 // TODO Next ABI break, remove & from annotationReference
622 LinkMovie(const QRectF &linkArea, Operation operation, const QString &annotationTitle, const Ref &annotationReference);
623 /**
624 * Destructor.
625 */
626 ~LinkMovie() override;
627 LinkType linkType() const override;
628 /**
629 * Returns the operation to be performed on the movie.
630 */
631 Operation operation() const;
632 /**
633 * Returns whether the given @p annotation is the referenced movie annotation for this movie @p link.
634 */
635 bool isReferencedAnnotation(const MovieAnnotation *annotation) const;
636
637 private:
638 Q_DECLARE_PRIVATE(LinkMovie)
639 Q_DISABLE_COPY(LinkMovie)
640 };
641
642 /**
643 * OCGState: an optional content group state change.
644 *
645 * \since 0.50
646 */
647 class POPPLER_QT5_EXPORT LinkOCGState : public Link
648 {
649 friend class OptContentModel;
650
651 public:
652 /**
653 * Create a new OCGState link. This is only used by Poppler::Page.
654 */
655 explicit LinkOCGState(LinkOCGStatePrivate *ocgp);
656 /**
657 * Destructor.
658 */
659 ~LinkOCGState() override;
660
661 LinkType linkType() const override;
662
663 private:
664 Q_DECLARE_PRIVATE(LinkOCGState)
665 Q_DISABLE_COPY(LinkOCGState)
666 };
667
668 /**
669 * Hide: an action to show / hide a field.
670 *
671 * \since 0.64
672 */
673 class POPPLER_QT5_EXPORT LinkHide : public Link
674 {
675 public:
676 /**
677 * Create a new Hide link. This is only used by Poppler::Page.
678 */
679 explicit LinkHide(LinkHidePrivate *lhidep);
680 /**
681 * Destructor.
682 */
683 ~LinkHide() override;
684
685 LinkType linkType() const override;
686
687 /**
688 * The fully qualified target names of the action.
689 */
690 QVector<QString> targets() const;
691
692 /**
693 * Should this action change the visibility of the target to true.
694 */
695 bool isShowAction() const;
696
697 private:
698 Q_DECLARE_PRIVATE(LinkHide)
699 Q_DISABLE_COPY(LinkHide)
700 };
701
702 /**
703 * ResetForm: an action to reset form fields.
704 *
705 * \since 24.07
706 */
707 class POPPLER_QT5_EXPORT LinkResetForm : public Link
708 {
709 friend class Document;
710
711 public:
712 /**
713 * Creates a new ResetForm link. This is only used by Poppler::Page
714 */
715 explicit LinkResetForm(LinkResetFormPrivate *lrfp);
716 /*
717 * Destructor
718 */
719 ~LinkResetForm() override;
720
721 LinkType linkType() const override;
722
723 private:
724 Q_DECLARE_PRIVATE(LinkResetForm)
725 Q_DISABLE_COPY(LinkResetForm)
726 };
727
728 /**
729 * SubmitForm : An action to submit a form.
730 *
731 * \since 24.10
732 */
733 class POPPLER_QT5_EXPORT LinkSubmitForm : public Link
734 {
735 public:
736 enum SubmitFormFlag
737 {
738 NoOpFlag = 0,
739 ExcludeFlag = 1,
740 IncludeNoValueFieldsFlag = 1 << 1,
741 ExportFormatFlag = 1 << 2,
742 GetMethodFlag = 1 << 3,
743 SubmitCoordinatesFlag = 1 << 4,
744 XFDFFlag = 1 << 5,
745 IncludeAppendSavesFlag = 1 << 6,
746 IncludeAnnotationsFlag = 1 << 7,
747 SubmitPDFFlag = 1 << 8,
748 CanonicalFormatFlag = 1 << 9,
749 ExclNonUserAnnotsFlag = 1 << 10,
750 ExclFKeyFlag = 1 << 11,
751 // 13th high bit flag is undefined
752 EmbedFormFlag = 1 << 13,
753 };
754 Q_DECLARE_FLAGS(SubmitFormFlags, SubmitFormFlag)
755
756 /**
757 * Create a new SubmitFormLink.
758 */
759 explicit LinkSubmitForm(LinkSubmitFormPrivate *lsfp);
760 /**
761 * Destructor
762 */
763 ~LinkSubmitForm() override;
764
765 LinkType linkType() const override;
766
767 /**
768 * The ids of fields that are to be submitted.
769 */
770 QVector<int> getFieldIds() const;
771
772 /**
773 * The url to which the form is to be submitted.
774 */
775 QString getUrl() const;
776
777 /**
778 * The flags specifying how the form should be submitted.
779 */
780 SubmitFormFlags getFlags() const;
781
782 private:
783 Q_DECLARE_PRIVATE(LinkSubmitForm)
784 Q_DISABLE_COPY(LinkSubmitForm)
785 };
786 }
787
788 #endif