Debian Codegraph @

qt6/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, 2021 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_QT6_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 QString destinationName() const;
165
166 /**
167 * Assignment operator.
168 */
169 LinkDestination &operator=(const LinkDestination &other);
170
171 private:
172 QSharedDataPointer<LinkDestinationPrivate> d;
173 };
174
175 /**
176 * \short Encapsulates data that describes a link.
177 *
178 * This is the base class for links. It makes mandatory for inherited
179 * kind of links to reimplement the linkType() method and return the type of
180 * the link described by the reimplemented class.
181 */
182 class POPPLER_QT6_EXPORT Link
183 {
184 public:
185 /// \cond PRIVATE
186 explicit Link(const QRectF &linkArea);
187 /// \endcond
188
189 /**
190 * The possible kinds of link.
191 *
192 * Inherited classes must return an unique identifier
193 */
194 enum LinkType
195 {
196 None, ///< Unknown link
197 Goto, ///< A "Go To" link
198 Execute, ///< A command to be executed
199 Browse, ///< An URL to be browsed (eg "http://poppler.freedesktop.org")
200 Action, ///< A "standard" action to be executed in the viewer
201 Sound, ///< A link representing a sound to be played
202 Movie, ///< An action to be executed on a movie
203 Rendition, ///< A rendition link
204 JavaScript, ///< A JavaScript code to be interpreted
205 OCGState, ///< An Optional Content Group state change
206 Hide, ///< An action to hide a field
207 ResetForm, ///< An action to reset the form \since 24.07
208 SubmitForm, ///< An action to submit a form \since 24.10
209 };
210
211 /**
212 * The type of this link.
213 */
214 virtual LinkType linkType() const;
215
216 /**
217 * Destructor.
218 */
219 virtual ~Link();
220
221 /**
222 * The area of a Page where the link should be active.
223 *
224 * \note this can be a null rect, in this case the link represents
225 * a general action. The area is given in 0..1 range
226 */
227 QRectF linkArea() const;
228
229 /**
230 * Get the next links to be activated / executed after this link.
231 *
232 * \note The caller does not get ownership of the returned objects.
233 */
234 QVector<Link *> nextLinks() const;
235
236 protected:
237 /// \cond PRIVATE
238 explicit Link(LinkPrivate &dd);
239 Q_DECLARE_PRIVATE(Link)
240 LinkPrivate *d_ptr;
241 /// \endcond
242
243 private:
244 Q_DISABLE_COPY(Link)
245 };
246
247 /**
248 * \brief Viewport reaching request.
249 *
250 * With a LinkGoto link, the document requests the specified viewport to be
251 * reached (aka, displayed in a viewer). Furthermore, if a file name is specified,
252 * then the destination refers to that document (and not to the document the
253 * current LinkGoto belongs to).
254 */
255 class POPPLER_QT6_EXPORT LinkGoto : public Link
256 {
257 public:
258 /**
259 * Create a new Goto link.
260 *
261 * \param linkArea the active area of the link
262 * \param extFileName if not empty, the file name to be open
263 * \param destination the destination to be reached
264 */
265 LinkGoto(const QRectF &linkArea, const QString &extFileName, const LinkDestination &destination);
266 /**
267 * Destructor.
268 */
269 ~LinkGoto() override;
270
271 /**
272 * Whether the destination is in an external document
273 * (i.e. not the current document)
274 */
275 bool isExternal() const;
276 // query for goto parameters
277 /**
278 * The file name of the document the destination() refers to,
279 * or an empty string in case it refers to the current document.
280 */
281 QString fileName() const;
282 /**
283 * The destination to reach.
284 */
285 LinkDestination destination() const;
286 LinkType linkType() const override;
287
288 private:
289 Q_DECLARE_PRIVATE(LinkGoto)
290 Q_DISABLE_COPY(LinkGoto)
291 };
292
293 /**
294 * \brief Generic execution request.
295 *
296 * The LinkExecute link represent a "file name" execution request. The result
297 * depends on the \link fileName() file name\endlink:
298 * - if it is a document, then it is requested to be open
299 * - otherwise, it represents an executable to be run with the specified parameters
300 */
301 class POPPLER_QT6_EXPORT LinkExecute : public Link
302 {
303 public:
304 /**
305 * The file name to be executed
306 */
307 QString fileName() const;
308 /**
309 * The parameters for the command.
310 */
311 QString parameters() const;
312
313 /**
314 * Create a new Execute link.
315 *
316 * \param linkArea the active area of the link
317 * \param file the file name to be open, or the program to be execute
318 * \param params the parameters for the program to execute
319 */
320 LinkExecute(const QRectF &linkArea, const QString &file, const QString &params);
321 /**
322 * Destructor.
323 */
324 ~LinkExecute() override;
325 LinkType linkType() const override;
326
327 private:
328 Q_DECLARE_PRIVATE(LinkExecute)
329 Q_DISABLE_COPY(LinkExecute)
330 };
331
332 /**
333 * \brief An URL to browse.
334 *
335 * The LinkBrowse link holds a URL (eg 'http://poppler.freedesktop.org',
336 * 'mailto:[email protected]', etc) to be open.
337 *
338 * The format of the URL is specified by RFC 2396 (http://www.ietf.org/rfc/rfc2396.txt)
339 */
340 class POPPLER_QT6_EXPORT LinkBrowse : public Link
341 {
342 public:
343 /**
344 * The URL to open
345 */
346 QString url() const;
347
348 /**
349 * Create a new browse link.
350 *
351 * \param linkArea the active area of the link
352 * \param url the URL to be open
353 */
354 LinkBrowse(const QRectF &linkArea, const QString &url);
355 /**
356 * Destructor.
357 */
358 ~LinkBrowse() override;
359 LinkType linkType() const override;
360
361 private:
362 Q_DECLARE_PRIVATE(LinkBrowse)
363 Q_DISABLE_COPY(LinkBrowse)
364 };
365
366 /**
367 * \brief "Standard" action request.
368 *
369 * The LinkAction class represents a link that request a "standard" action
370 * to be performed by the viewer on the displayed document.
371 */
372 class POPPLER_QT6_EXPORT LinkAction : public Link
373 {
374 public:
375 /**
376 * The possible types of actions
377 */
378 enum ActionType
379 {
380 PageFirst = 1,
381 PagePrev = 2,
382 PageNext = 3,
383 PageLast = 4,
384 HistoryBack = 5,
385 HistoryForward = 6,
386 Quit = 7,
387 Presentation = 8,
388 EndPresentation = 9,
389 Find = 10,
390 GoToPage = 11,
391 Close = 12,
392 Print = 13,
393 SaveAs = 14 ///< \since 22.04
394 };
395
396 /**
397 * The action of the current LinkAction
398 */
399 ActionType actionType() const;
400
401 /**
402 * Create a new Action link, that executes a specified action
403 * on the document.
404 *
405 * \param linkArea the active area of the link
406 * \param actionType which action should be executed
407 */
408 LinkAction(const QRectF &linkArea, ActionType actionType);
409 /**
410 * Destructor.
411 */
412 ~LinkAction() override;
413 LinkType linkType() const override;
414
415 private:
416 Q_DECLARE_PRIVATE(LinkAction)
417 Q_DISABLE_COPY(LinkAction)
418 };
419
420 /**
421 * Sound: a sound to be played.
422 */
423 class POPPLER_QT6_EXPORT LinkSound : public Link
424 {
425 public:
426 // create a Link_Sound
427 LinkSound(const QRectF &linkArea, double volume, bool sync, bool repeat, bool mix, SoundObject *sound);
428 /**
429 * Destructor.
430 */
431 ~LinkSound() override;
432
433 LinkType linkType() const override;
434
435 /**
436 * The volume to be used when playing the sound.
437 *
438 * The volume is in the range [ -1, 1 ], where:
439 * - a negative number: no volume (mute)
440 * - 1: full volume
441 */
442 double volume() const;
443 /**
444 * Whether the playback of the sound should be synchronous
445 * (thus blocking, waiting for the end of the sound playback).
446 */
447 bool synchronous() const;
448 /**
449 * Whether the sound should be played continuously (that is,
450 * started again when it ends)
451 */
452 bool repeat() const;
453 /**
454 * Whether the playback of this sound can be mixed with
455 * playbacks with other sounds of the same document.
456 *
457 * \note When false, any other playback must be stopped before
458 * playing the sound.
459 */
460 bool mix() const;
461 /**
462 * The sound object to be played
463 */
464 SoundObject *sound() const;
465
466 private:
467 Q_DECLARE_PRIVATE(LinkSound)
468 Q_DISABLE_COPY(LinkSound)
469 };
470
471 /**
472 * Rendition: Rendition link.
473 */
474 class POPPLER_QT6_EXPORT LinkRendition : public Link
475 {
476 public:
477 /**
478 * Describes the possible rendition actions.
479 */
480 enum RenditionAction
481 {
482 NoRendition,
483 PlayRendition,
484 StopRendition,
485 PauseRendition,
486 ResumeRendition
487 };
488
489 /**
490 * Create a new rendition link.
491 *
492 * \param linkArea the active area of the link
493 * \param rendition the media rendition object. Ownership is taken
494 * \param operation the numeric operation (action) (@see ::LinkRendition::RenditionOperation)
495 * \param script the java script code
496 * \param annotationReference the object reference of the screen annotation associated with this rendition action
497 */
498 [[deprecated]] LinkRendition(const QRectF &linkArea, ::MediaRendition *rendition, int operation, const QString &script, const Ref annotationReference);
499
500 /**
501 * Create a new rendition link.
502 *
503 * \param linkArea the active area of the link
504 * \param rendition the media rendition object.
505 * \param operation the numeric operation (action) (@see ::LinkRendition::RenditionOperation)
506 * \param script the java script code
507 * \param annotationReference the object reference of the screen annotation associated with this rendition action
508 */
509 LinkRendition(const QRectF &linkArea, std::unique_ptr<::MediaRendition> &&rendition, int operation, const QString &script, const Ref annotationReference);
510
511 /**
512 * Destructor.
513 */
514 ~LinkRendition() override;
515
516 LinkType linkType() const override;
517
518 /**
519 * Returns the media rendition object if the redition provides one, @c 0 otherwise
520 */
521 MediaRendition *rendition() const;
522
523 /**
524 * Returns the action that should be executed if a rendition object is provided.
525 */
526 RenditionAction action() const;
527
528 /**
529 * The JS code that shall be executed or an empty string.
530 */
531 QString script() const;
532
533 /**
534 * Returns whether the given @p annotation is the referenced screen annotation for this rendition @p link.
535 */
536 bool isReferencedAnnotation(const ScreenAnnotation *annotation) const;
537
538 private:
539 Q_DECLARE_PRIVATE(LinkRendition)
540 Q_DISABLE_COPY(LinkRendition)
541 };
542
543 /**
544 * JavaScript: a JavaScript code to be interpreted.
545 */
546 class POPPLER_QT6_EXPORT LinkJavaScript : public Link
547 {
548 public:
549 /**
550 * Create a new JavaScript link.
551 *
552 * \param linkArea the active area of the link
553 * \param js the JS code to be interpreted
554 */
555 LinkJavaScript(const QRectF &linkArea, const QString &js);
556 /**
557 * Destructor.
558 */
559 ~LinkJavaScript() override;
560
561 LinkType linkType() const override;
562
563 /**
564 * The JS code
565 */
566 QString script() const;
567
568 private:
569 Q_DECLARE_PRIVATE(LinkJavaScript)
570 Q_DISABLE_COPY(LinkJavaScript)
571 };
572
573 /**
574 * Movie: a movie to be played.
575 */
576 class POPPLER_QT6_EXPORT LinkMovie : public Link
577 {
578 public:
579 /**
580 * Describes the operation to be performed on the movie.
581 */
582 enum Operation
583 {
584 Play,
585 Stop,
586 Pause,
587 Resume
588 };
589
590 /**
591 * Create a new Movie link.
592 *
593 * \param linkArea the active area of the link
594 * \param operation the operation to be performed on the movie
595 * \param annotationTitle the title of the movie annotation identifying the movie to be played
596 * \param annotationReference the object reference of the movie annotation identifying the movie to be played
597 *
598 * Note: This constructor is supposed to be used by Poppler::Page only.
599 */
600 LinkMovie(const QRectF &linkArea, Operation operation, const QString &annotationTitle, const Ref annotationReference);
601 /**
602 * Destructor.
603 */
604 ~LinkMovie() override;
605 LinkType linkType() const override;
606 /**
607 * Returns the operation to be performed on the movie.
608 */
609 Operation operation() const;
610 /**
611 * Returns whether the given @p annotation is the referenced movie annotation for this movie @p link.
612 */
613 bool isReferencedAnnotation(const MovieAnnotation *annotation) const;
614
615 private:
616 Q_DECLARE_PRIVATE(LinkMovie)
617 Q_DISABLE_COPY(LinkMovie)
618 };
619
620 /**
621 * OCGState: an optional content group state change.
622 */
623 class POPPLER_QT6_EXPORT LinkOCGState : public Link
624 {
625 friend class OptContentModel;
626
627 public:
628 /**
629 * Create a new OCGState link. This is only used by Poppler::Page.
630 */
631 explicit LinkOCGState(LinkOCGStatePrivate *ocgp);
632 /**
633 * Destructor.
634 */
635 ~LinkOCGState() override;
636
637 LinkType linkType() const override;
638
639 private:
640 Q_DECLARE_PRIVATE(LinkOCGState)
641 Q_DISABLE_COPY(LinkOCGState)
642 };
643
644 /**
645 * Hide: an action to show / hide a field.
646 */
647 class POPPLER_QT6_EXPORT LinkHide : public Link
648 {
649 public:
650 /**
651 * Create a new Hide link. This is only used by Poppler::Page.
652 */
653 explicit LinkHide(LinkHidePrivate *lhidep);
654 /**
655 * Destructor.
656 */
657 ~LinkHide() override;
658
659 LinkType linkType() const override;
660
661 /**
662 * The fully qualified target names of the action.
663 */
664 QVector<QString> targets() const;
665
666 /**
667 * Should this action change the visibility of the target to true.
668 */
669 bool isShowAction() const;
670
671 private:
672 Q_DECLARE_PRIVATE(LinkHide)
673 Q_DISABLE_COPY(LinkHide)
674 };
675
676 /**
677 * ResetForm: an action to reset form fields.
678 *
679 * \since 24.07
680 */
681 class POPPLER_QT6_EXPORT LinkResetForm : public Link
682 {
683 friend class Document;
684
685 public:
686 /**
687 * Creates a new ResetForm link. This is only used by Poppler::Page
688 */
689 explicit LinkResetForm(LinkResetFormPrivate *lrfp);
690 /*
691 * Destructor
692 */
693 ~LinkResetForm() override;
694
695 LinkType linkType() const override;
696
697 private:
698 Q_DECLARE_PRIVATE(LinkResetForm)
699 Q_DISABLE_COPY(LinkResetForm)
700 };
701
702 /**
703 * SubmitForm : An action to submit a form.
704 *
705 * \since 24.10
706 */
707
708 class POPPLER_QT6_EXPORT LinkSubmitForm : public Link
709 {
710 public:
711 enum SubmitFormFlag
712 {
713 NoOpFlag = 0,
714 ExcludeFlag = 1,
715 IncludeNoValueFieldsFlag = 1 << 1,
716 ExportFormatFlag = 1 << 2,
717 GetMethodFlag = 1 << 3,
718 SubmitCoordinatesFlag = 1 << 4,
719 XFDFFlag = 1 << 5,
720 IncludeAppendSavesFlag = 1 << 6,
721 IncludeAnnotationsFlag = 1 << 7,
722 SubmitPDFFlag = 1 << 8,
723 CanonicalFormatFlag = 1 << 9,
724 ExclNonUserAnnotsFlag = 1 << 10,
725 ExclFKeyFlag = 1 << 11,
726 // 13th high bit flag is undefined
727 EmbedFormFlag = 1 << 13,
728 };
729 Q_DECLARE_FLAGS(SubmitFormFlags, SubmitFormFlag)
730
731 /**
732 * Create a new SubmitForm link.
733 */
734 explicit LinkSubmitForm(LinkSubmitFormPrivate *lsfp);
735 /**
736 * Destructor
737 */
738 ~LinkSubmitForm() override;
739
740 LinkType linkType() const override;
741
742 /**
743 * The ids of fields that are to be submitted.
744 */
745 QVector<int> getFieldIds() const;
746
747 /**
748 * The url to which the form is to be submitted.
749 */
750 QString getUrl() const;
751
752 /**
753 * The flags specifying how the form should be submitted.
754 */
755 SubmitFormFlags getFlags() const;
756
757 private:
758 Q_DECLARE_PRIVATE(LinkSubmitForm)
759 Q_DISABLE_COPY(LinkSubmitForm)
760 };
761
762 }
763
764 #endif