1	/* poppler-qt.h: qt interface to poppler
2	* Copyright (C) 2005, Net Integration Technologies, Inc.
3	* Copyright (C) 2005, 2007, Brad Hards <bradh@frogmouth.net>
4	* Copyright (C) 2005-2015, 2017-2022, Albert Astals Cid <aacid@kde.org>
5	* Copyright (C) 2005, Stefan Kebekus <stefan.kebekus@math.uni-koeln.de>
6	* Copyright (C) 2006-2011, Pino Toscano <pino@kde.org>
7	* Copyright (C) 2009 Shawn Rutledge <shawn.t.rutledge@gmail.com>
8	* Copyright (C) 2010 Suzuki Toshiya <mpsuzuki@hiroshima-u.ac.jp>
9	* Copyright (C) 2010 Matthias Fauconneau <matthias.fauconneau@gmail.com>
10	* Copyright (C) 2011 Andreas Hartmetz <ahartmetz@gmail.com>
11	* Copyright (C) 2011 Glad Deschrijver <glad.deschrijver@gmail.com>
12	* Copyright (C) 2012, Guillermo A. Amaral B. <gamaral@kde.org>
13	* Copyright (C) 2012, Fabio D'Urso <fabiodurso@hotmail.it>
14	* Copyright (C) 2012, Tobias Koenig <tobias.koenig@kdab.com>
15	* Copyright (C) 2012, 2014, 2015, 2018, 2019 Adam Reichold <adamreichold@myopera.com>
16	* Copyright (C) 2012, 2013 Thomas Freitag <Thomas.Freitag@alfa.de>
17	* Copyright (C) 2013 Anthony Granger <grangeranthony@gmail.com>
18	* Copyright (C) 2016 Jakub Alba <jakubalba@gmail.com>
19	* Copyright (C) 2017, 2020, 2021 Oliver Sander <oliver.sander@tu-dresden.de>
20	* Copyright (C) 2017, 2018 Klarälvdalens Datakonsult AB, a KDAB Group company, <info@kdab.com>. Work sponsored by the LiMux project of the city of Munich
21	* Copyright (C) 2018, 2021 Nelson Benítez León <nbenitezl@gmail.com>
22	* Copyright (C) 2019 Jan Grulich <jgrulich@redhat.com>
23	* Copyright (C) 2019 Alexander Volkov <a.volkov@rusbitech.ru>
24	* Copyright (C) 2020 Philipp Knechtges <philipp-dev@knechtges.com>
25	* Copyright (C) 2020 Katarina Behrens <Katarina.Behrens@cib.de>
26	* Copyright (C) 2020 Thorsten Behrens <Thorsten.Behrens@CIB.de>
27	* Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, <info@kdab.com>. Work sponsored by Technische Universität Dresden
28	* Copyright (C) 2021 Klarälvdalens Datakonsult AB, a KDAB Group company, <info@kdab.com>.
29	* Copyright (C) 2021 Mahmoud Khalil <mahmoudkhalil11@gmail.com>
30	* Copyright (C) 2021 Georgiy Sgibnev <georgiy@sgibnev.com>. Work sponsored by lab50.net.
31	* Copyright (C) 2022 Martin <martinbts@gmx.net>
32	* Copyright (C) 2023 Kevin Ottens <kevin.ottens@enioka.com>. Work sponsored by De Bortoli Wines
33	*
34	* This program is free software; you can redistribute it and/or modify
35	* it under the terms of the GNU General Public License as published by
36	* the Free Software Foundation; either version 2, or (at your option)
37	* any later version.
38	*
39	* This program is distributed in the hope that it will be useful,
40	* but WITHOUT ANY WARRANTY; without even the implied warranty of
41	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
42	* GNU General Public License for more details.
43	*
44	* You should have received a copy of the GNU General Public License
45	* along with this program; if not, write to the Free Software
46	* Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA.
47	*/
48
49	#ifndef __POPPLER_QT_H__
50	#define __POPPLER_QT_H__
51
52	#include <functional>
53	#include <memory>
54	#include <vector>
55
56	#include "poppler-annotation.h"
57	#include "poppler-link.h"
58	#include "poppler-optcontent.h"
59	#include "poppler-page-transition.h"
60
61	#include <QtCore/QByteArray>
62	#include <QtCore/QDateTime>
63	#include <QtCore/QIODevice>
64	#include <QtCore/QSet>
65	#include "poppler-export.h"
66
67	class EmbFile;
68	class Sound;
69	class AnnotMovie;
70
71	/**
72	The %Poppler Qt6 binding.
73	*/
74	namespace Poppler {
75
76	class Document;
77	class DocumentData;
78
79	class PageData;
80
81	class FormField;
82	class FormFieldSignature;
83
84	class TextBoxData;
85
86	class PDFConverter;
87	class PSConverter;
88
89	struct OutlineItemData;
90
91	/**
92	Debug/error function.
93
94	This function type is used for debugging & error output;
95	the first parameter is the actual message, the second is the unaltered
96	closure argument which was passed to the setDebugErrorFunction call.
97	*/
98	using PopplerDebugFunc = void (*)(const QString & /*message*/, const QVariant & /*closure*/);
99
100	/**
101	Set a new debug/error output function.
102
103	If not set, by default error and debug messages will be sent to the
104	Qt \p qDebug() function.
105
106	\param debugFunction the new debug function
107	\param closure user data which will be passes as-is to the debug function
108	*/
109	POPPLER_QT6_EXPORT void setDebugErrorFunction(PopplerDebugFunc debugFunction, const QVariant &closure);
110
111	/**
112	Describes the physical location of text on a document page
113
114	This very simple class describes the physical location of text
115	on the page. It consists of
116	- a QString that contains the text
117	- a QRectF that gives a box that describes where on the page
118	the text is found.
119	*/
120	class POPPLER_QT6_EXPORT TextBox
121	{
122	friend class Page;
123
124	public:
125	/**
126	The default constructor sets the \p text and the rectangle that
127	contains the text. Coordinates for the \p bBox are in points =
128	1/72 of an inch.
129	*/
130	TextBox(const QString &text, const QRectF &bBox);
131	/**
132	Destructor.
133	*/
134	~TextBox();
135
136	/**
137	Returns the text of this text box
138	*/
139	QString text() const;
140
141	/**
142	Returns the position of the text, in point, i.e., 1/72 of
143	an inch
144	*/
145	QRectF boundingBox() const;
146
147	/**
148	Returns the pointer to the next text box, if there is one.
149
150	Otherwise, it returns a null pointer.
151	*/
152	TextBox *nextWord() const;
153
154	/**
155	Returns the bounding box of the \p i -th characted of the word.
156	*/
157	QRectF charBoundingBox(int i) const;
158
159	/**
160	Returns whether there is a space character after this text box
161	*/
162	bool hasSpaceAfter() const;
163
164	private:
165	Q_DISABLE_COPY(TextBox)
166
167	TextBoxData *m_data;
168	};
169
170	class FontInfoData;
171	/**
172	Container class for information about a font within a PDF
173	document
174	*/
175	class POPPLER_QT6_EXPORT FontInfo
176	{
177	friend class Document;
178
179	public:
180	/**
181	The type of font.
182	*/
183	enum Type
184	{
185	unknown,
186	Type1,
187	Type1C,
188	Type1COT,
189	Type3,
190	TrueType,
191	TrueTypeOT,
192	CIDType0,
193	CIDType0C,
194	CIDType0COT,
195	CIDTrueType,
196	CIDTrueTypeOT
197	};
198
199	/// \cond PRIVATE
200	/**
201	Create a new font information container.
202	*/
203	FontInfo();
204
205	/**
206	Create a new font information container.
207	*/
208	explicit FontInfo(const FontInfoData &fid);
209	/// \endcond
210
211	/**
212	Copy constructor.
213	*/
214	FontInfo(const FontInfo &fi);
215
216	/**
217	Destructor.
218	*/
219	~FontInfo();
220
221	/**
222	The name of the font. Can be a null QString if the font has no name
223	*/
224	QString name() const;
225
226	/**
227	The name of the substitute font. Can be a null QString if the font has no substitute font
228	*/
229	QString substituteName() const;
230
231	/**
232	The path of the font file used to represent this font on this system,
233	or a null string is the font is embedded
234	*/
235	QString file() const;
236
237	/**
238	Whether the font is embedded in the file, or not
239
240	\return true if the font is embedded
241	*/
242	bool isEmbedded() const;
243
244	/**
245	Whether the font provided is only a subset of the full
246	font or not. This only has meaning if the font is embedded.
247
248	\return true if the font is only a subset
249	*/
250	bool isSubset() const;
251
252	/**
253	The type of font encoding
254
255	\return a enumerated value corresponding to the font encoding used
256
257	\sa typeName for a string equivalent
258	*/
259	Type type() const;
260
261	/**
262	The name of the font encoding used
263
264	\note if you are looking for the name of the font (as opposed to the
265	encoding format used), you probably want name().
266
267	\sa type for a enumeration version
268	*/
269	QString typeName() const;
270
271	/**
272	Standard assignment operator
273	*/
274	FontInfo &operator=(const FontInfo &fi);
275
276	private:
277	FontInfoData *m_data;
278	};
279
280	class FontIteratorData;
281	/**
282	Iterator for reading the fonts in a document.
283
284	FontIterator provides a Java-style iterator for reading the fonts in a
285	document.
286
287	You can use it in the following way:
288	\code
289	std::unique_ptr<Poppler::FontIterator> it = doc->newFontIterator();
290	while (it->hasNext()) {
291	QList<Poppler::FontInfo> fonts = it->next();
292	// do something with the fonts
293	}
294	// no need to free the iterator after doing the job
295	\endcode
296	*/
297	class POPPLER_QT6_EXPORT FontIterator
298	{
299	friend class Document;
300	friend class DocumentData;
301
302	public:
303	/**
304	Destructor.
305	*/
306	~FontIterator();
307
308	/**
309	Returns the fonts of the current page and then advances the iterator
310	to the next page.
311	*/
312	QList<FontInfo> next();
313
314	/**
315	Checks whether there is at least one more page to iterate, ie returns
316	false when the iterator is beyond the last page.
317	*/
318	bool hasNext() const;
319
320	/**
321	Returns the current page where the iterator is.
322	*/
323	int currentPage() const;
324
325	private:
326	Q_DISABLE_COPY(FontIterator)
327	FontIterator(int, DocumentData *dd);
328
329	FontIteratorData *d;
330	};
331
332	class EmbeddedFileData;
333	/**
334	Container class for an embedded file with a PDF document
335	*/
336	class POPPLER_QT6_EXPORT EmbeddedFile
337	{
338	friend class DocumentData;
339	friend class AnnotationPrivate;
340
341	public:
342	/// \cond PRIVATE
343	explicit EmbeddedFile(EmbFile *embfile);
344	/// \endcond
345
346	/**
347	Destructor.
348	*/
349	~EmbeddedFile();
350
351	/**
352	The name associated with the file
353	*/
354	QString name() const;
355
356	/**
357	The description associated with the file, if any.
358
359	This will return an empty QString if there is no description element
360	*/
361	QString description() const;
362
363	/**
364	The size of the file.
365
366	This will return < 0 if there is no size element
367	*/
368	int size() const;
369
370	/**
371	The modification date for the embedded file, if known.
372	*/
373	QDateTime modDate() const;
374
375	/**
376	The creation date for the embedded file, if known.
377	*/
378	QDateTime createDate() const;
379
380	/**
381	The MD5 checksum of the file.
382
383	This will return an empty QByteArray if there is no checksum element.
384	*/
385	QByteArray checksum() const;
386
387	/**
388	The MIME type of the file, if known.
389	*/
390	QString mimeType() const;
391
392	/**
393	The data as a byte array
394	*/
395	QByteArray data();
396
397	/**
398	Is the embedded file valid?
399	*/
400	bool isValid() const;
401
402	/**
403	A QDataStream for the actual data?
404	*/
405	// QDataStream dataStream() const;
406
407	private:
408	Q_DISABLE_COPY(EmbeddedFile)
409	explicit EmbeddedFile(EmbeddedFileData &dd);
410
411	EmbeddedFileData *m_embeddedFile;
412	};
413
414	/**
415	\brief A page in a document.
416
417	The Page class represents a single page within a PDF document.
418
419	You cannot construct a Page directly, but you have to use the Document
420	functions that return a new Page out of an index or a label.
421	*/
422	class POPPLER_QT6_EXPORT Page
423	{
424	friend class Document;
425
426	public:
427	/**
428	Destructor.
429	*/
430	~Page();
431
432	/**
433	The type of rotation to apply for an operation
434	*/
435	enum Rotation
436	{
437	Rotate0 = 0, ///< Do not rotate
438	Rotate90 = 1, ///< Rotate 90 degrees clockwise
439	Rotate180 = 2, ///< Rotate 180 degrees
440	Rotate270 = 3 ///< Rotate 270 degrees clockwise (90 degrees counterclockwise)
441	};
442
443	/**
444	The kinds of page actions
445	*/
446	enum PageAction
447	{
448	Opening, ///< The action when a page is "opened"
449	Closing ///< The action when a page is "closed"
450	};
451
452	/**
453	How the text is going to be returned
454	*/
455	enum TextLayout
456	{
457	PhysicalLayout, ///< The text is layouted to resemble the real page layout
458	RawOrderLayout ///< The text is returned without any type of processing
459	};
460
461	/**
462	Additional flags for the renderToPainter method
463	*/
464	enum PainterFlag
465	{
466	NoPainterFlags = 0x00000000,
467	/**
468	Do not save/restore the caller-owned painter.
469
470	renderToPainter() by default preserves, using save() + restore(),
471	the state of the painter specified; if this is not needed, this
472	flag can avoid this job
473	*/
474	DontSaveAndRestore = 0x00000001
475	};
476	Q_DECLARE_FLAGS(PainterFlags, PainterFlag)
477
478	/**
479	Render the page to a QImage using the current
480	\link Document::renderBackend() Document renderer\endlink.
481
482	If \p x = \p y = \p w = \p h = -1, the method will automatically
483	compute the size of the image from the horizontal and vertical
484	resolutions specified in \p xres and \p yres. Otherwise, the
485	method renders only a part of the page, specified by the
486	parameters (\p x, \p y, \p w, \p h) in pixel coordinates. The returned
487	QImage then has size (\p w, \p h), independent of the page
488	size.
489
490	\param x specifies the left x-coordinate of the box, in
491	pixels.
492
493	\param y specifies the top y-coordinate of the box, in
494	pixels.
495
496	\param w specifies the width of the box, in pixels.
497
498	\param h specifies the height of the box, in pixels.
499
500	\param xres horizontal resolution of the graphics device,
501	in dots per inch
502
503	\param yres vertical resolution of the graphics device, in
504	dots per inch
505
506	\param rotate how to rotate the page
507
508	\warning The parameter (\p x, \p y, \p w, \p h) are not
509	well-tested. Unusual or meaningless parameters may lead to
510	rather unexpected results.
511
512	\returns a QImage of the page, or a null image on failure.
513	*/
514	QImage renderToImage(double xres = 72.0, double yres = 72.0, int x = -1, int y = -1, int w = -1, int h = -1, Rotation rotate = Rotate0) const;
515
516	/**
517	Partial Update renderToImage callback.
518
519	This function type is used for doing partial rendering updates;
520	the first parameter is the image as rendered up to now, the second is the unaltered
521	closure argument which was passed to the renderToImage call.
522	*/
523	using RenderToImagePartialUpdateFunc = void (*)(const QImage & /*image*/, const QVariant & /*closure*/);
524
525	/**
526	Partial Update query renderToImage callback.
527
528	This function type is used for query if the partial rendering update should happen;
529	the parameter is the unaltered closure argument which was passed to the renderToImage call.
530	*/
531	using ShouldRenderToImagePartialQueryFunc = bool (*)(const QVariant & /*closure*/);
532
533	/**
534	Render the page to a QImage using the current
535	\link Document::renderBackend() Document renderer\endlink.
536
537	If \p x = \p y = \p w = \p h = -1, the method will automatically
538	compute the size of the image from the horizontal and vertical
539	resolutions specified in \p xres and \p yres. Otherwise, the
540	method renders only a part of the page, specified by the
541	parameters (\p x, \p y, \p w, \p h) in pixel coordinates. The returned
542	QImage then has size (\p w, \p h), independent of the page
543	size.
544
545	\param x specifies the left x-coordinate of the box, in
546	pixels.
547
548	\param y specifies the top y-coordinate of the box, in
549	pixels.
550
551	\param w specifies the width of the box, in pixels.
552
553	\param h specifies the height of the box, in pixels.
554
555	\param xres horizontal resolution of the graphics device,
556	in dots per inch
557
558	\param yres vertical resolution of the graphics device, in
559	dots per inch
560
561	\param rotate how to rotate the page
562
563	\param partialUpdateCallback callback that will be called to
564	report a partial rendering update
565
566	\param shouldDoPartialUpdateCallback callback that will be called
567	to ask if a partial rendering update is wanted. This exists
568	because doing a partial rendering update needs to copy the image
569	buffer so if it is not wanted it is better skipped early.
570
571	\param payload opaque structure that will be passed
572	back to partialUpdateCallback and shouldDoPartialUpdateCallback.
573
574	\warning The parameter (\p x, \p y, \p w, \p h) are not
575	well-tested. Unusual or meaningless parameters may lead to
576	rather unexpected results.
577
578	\returns a QImage of the page, or a null image on failure.
579	*/
580	QImage renderToImage(double xres, double yres, int x, int y, int w, int h, Rotation rotate, RenderToImagePartialUpdateFunc partialUpdateCallback, ShouldRenderToImagePartialQueryFunc shouldDoPartialUpdateCallback,
581	const QVariant &payload) const;
582
583	/**
584	Abort query function callback.
585
586	This function type is used for query if the current rendering/text extraction should be cancelled.
587	*/
588	using ShouldAbortQueryFunc = bool (*)(const QVariant & /*closure*/);
589
590	/**
591	Render the page to a QImage using the current
592	\link Document::renderBackend() Document renderer\endlink.
593
594	If \p x = \p y = \p w = \p h = -1, the method will automatically
595	compute the size of the image from the horizontal and vertical
596	resolutions specified in \p xres and \p yres. Otherwise, the
597	method renders only a part of the page, specified by the
598	parameters (\p x, \p y, \p w, \p h) in pixel coordinates. The returned
599	QImage then has size (\p w, \p h), independent of the page
600	size.
601
602	\param x specifies the left x-coordinate of the box, in
603	pixels.
604
605	\param y specifies the top y-coordinate of the box, in
606	pixels.
607
608	\param w specifies the width of the box, in pixels.
609
610	\param h specifies the height of the box, in pixels.
611
612	\param xres horizontal resolution of the graphics device,
613	in dots per inch
614
615	\param yres vertical resolution of the graphics device, in
616	dots per inch
617
618	\param rotate how to rotate the page
619
620	\param partialUpdateCallback callback that will be called to
621	report a partial rendering update
622
623	\param shouldDoPartialUpdateCallback callback that will be called
624	to ask if a partial rendering update is wanted. This exists
625	because doing a partial rendering update needs to copy the image
626	buffer so if it is not wanted it is better skipped early.
627
628	\param shouldAbortRenderCallback callback that will be called
629	to ask if the rendering should be cancelled.
630
631	\param payload opaque structure that will be passed
632	back to partialUpdateCallback, shouldDoPartialUpdateCallback
633	and shouldAbortRenderCallback.
634
635	\warning The parameter (\p x, \p y, \p w, \p h) are not
636	well-tested. Unusual or meaningless parameters may lead to
637	rather unexpected results.
638
639	\returns a QImage of the page, or a null image on failure.
640	*/
641	QImage renderToImage(double xres, double yres, int x, int y, int w, int h, Rotation rotate, RenderToImagePartialUpdateFunc partialUpdateCallback, ShouldRenderToImagePartialQueryFunc shouldDoPartialUpdateCallback,
642	ShouldAbortQueryFunc shouldAbortRenderCallback, const QVariant &payload) const;
643
644	/**
645	Render the page to the specified QPainter using the current
646	\link Document::renderBackend() Document renderer\endlink.
647
648	If \p x = \p y = \p w = \p h = -1, the method will automatically
649	compute the size of the page area from the horizontal and vertical
650	resolutions specified in \p xres and \p yres. Otherwise, the
651	method renders only a part of the page, specified by the
652	parameters (\p x, \p y, \p w, \p h) in pixel coordinates.
653
654	\param painter the painter to paint on
655
656	\param x specifies the left x-coordinate of the box, in
657	pixels.
658
659	\param y specifies the top y-coordinate of the box, in
660	pixels.
661
662	\param w specifies the width of the box, in pixels.
663
664	\param h specifies the height of the box, in pixels.
665
666	\param xres horizontal resolution of the graphics device,
667	in dots per inch
668
669	\param yres vertical resolution of the graphics device, in
670	dots per inch
671
672	\param rotate how to rotate the page
673
674	\param flags additional painter flags
675
676	\warning The parameter (\p x, \p y, \p w, \p h) are not
677	well-tested. Unusual or meaningless parameters may lead to
678	rather unexpected results.
679
680	\returns whether the painting succeeded
681
682	\note This method is only supported for the QPainterOutputDev
683	*/
684	bool renderToPainter(QPainter *painter, double xres = 72.0, double yres = 72.0, int x = -1, int y = -1, int w = -1, int h = -1, Rotation rotate = Rotate0, PainterFlags flags = NoPainterFlags) const;
685
686	/**
687	Get the page thumbnail if it exists.
688
689	\return a QImage of the thumbnail, or a null image
690	if the PDF does not contain one for this page
691	*/
692	QImage thumbnail() const;
693
694	/**
695	Returns the text that is inside a specified rectangle
696
697	\param rect the rectangle specifying the area of interest,
698	with coordinates given in points, i.e., 1/72th of an inch.
699	If rect is null, all text on the page is given
700	**/
701	QString text(const QRectF &rect, TextLayout textLayout) const;
702
703	/**
704	Returns the text that is inside a specified rectangle.
705	The text is returned using the physical layout of the page
706
707	\param rect the rectangle specifying the area of interest,
708	with coordinates given in points, i.e., 1/72th of an inch.
709	If rect is null, all text on the page is given
710	**/
711	QString text(const QRectF &rect) const;
712
713	/**
714	The starting point for a search
715	*/
716	enum SearchDirection
717	{
718	FromTop, ///< Start sorting at the top of the document
719	NextResult, ///< Find the next result, moving "down the page"
720	PreviousResult ///< Find the previous result, moving "up the page"
721	};
722
723	/**
724	The type of search to perform
725	*/
726	enum SearchMode
727	{
728	CaseSensitive, ///< Case differences cause no match in searching
729	CaseInsensitive ///< Case differences are ignored in matching
730	};
731
732	/**
733	Flags to modify the search behaviour
734	*/
735	enum SearchFlag
736	{
737	NoSearchFlags = 0x00000000,
738	IgnoreCase = 0x00000001, ///< Case differences are ignored
739	WholeWords = 0x00000002, ///< Only whole words are matched
740	IgnoreDiacritics = 0x00000004, ///< Diacritic differences (eg. accents, umlauts, diaeresis) are ignored.
741	///< This option will have no effect if the search term contains characters which
742	///< are not pure ascii.
743	AcrossLines = 0x00000008 ///< Allows to match on text spanning from end of a line to the next line.
744	///< It won't match on text spanning more than two lines. Automatically ignores hyphen
745	///< at end of line, and allows whitespace in search term to match on newline. \since 21.05.0
746	};
747	Q_DECLARE_FLAGS(SearchFlags, SearchFlag)
748
749	/**
750	Returns true if the specified text was found.
751
752	\param text the text the search
753	\param rectXXX in all directions is used to return where the text was found, for NextResult and PreviousResult
754	indicates where to continue searching for
755	\param direction in which direction do the search
756	\param flags the flags to consider during matching
757	\param rotate the rotation to apply for the search order
758	**/
759	bool search(const QString &text, double &sLeft, double &sTop, double &sRight, double &sBottom, SearchDirection direction, SearchFlags flags = NoSearchFlags, Rotation rotate = Rotate0) const;
760
761	/**
762	Returns a list of all occurrences of the specified text on the page.
763
764	if SearchFlags::AcrossLines is given in \param flags, then rects may just
765	be parts of the text itself if it's split between multiple lines.
766
767	\param text the text to search
768	\param flags the flags to consider during matching
769	\param rotate the rotation to apply for the search order
770
771	\warning Do not use the returned QRectF as arguments of another search call because of truncation issues if qreal is defined as float.
772	**/
773	QList<QRectF> search(const QString &text, SearchFlags flags = NoSearchFlags, Rotation rotate = Rotate0) const;
774
775	/**
776	Returns a list of text of the page
777
778	This method returns a QList of TextBoxes that contain all
779	the text of the page, with roughly one text word of text
780	per TextBox item.
781
782	For text written in western languages (left-to-right and
783	up-to-down), the QList contains the text in the proper
784	order.
785
786	\warning This method is not tested with Asian scripts
787	*/
788	std::vector<std::unique_ptr<TextBox>> textList(Rotation rotate = Rotate0) const;
789
790	/**
791	Returns a list of text of the page
792
793	This method returns a QList of TextBoxes that contain all
794	the text of the page, with roughly one text word of text
795	per TextBox item.
796
797	For text written in western languages (left-to-right and
798	up-to-down), the QList contains the text in the proper
799	order.
800
801	\param shouldAbortExtractionCallback callback that will be called
802	to ask if the text extraction should be cancelled.
803
804	\param closure opaque structure that will be passed
805	back to shouldAbortExtractionCallback.
806
807	\warning This method is not tested with Asian scripts
808	*/
809	std::vector<std::unique_ptr<TextBox>> textList(Rotation rotate, ShouldAbortQueryFunc shouldAbortExtractionCallback, const QVariant &closure) const;
810
811	/**
812	\return The dimensions (cropbox) of the page, in points (i.e. 1/72th of an inch)
813	*/
814	QSizeF pageSizeF() const;
815
816	/**
817	\return The dimensions (cropbox) of the page, in points (i.e. 1/72th of an inch)
818	*/
819	QSize pageSize() const;
820
821	/**
822	Returns the transition of this page
823
824	\returns a pointer to a PageTransition structure that
825	defines how transition to this page shall be performed.
826
827	\note The PageTransition structure is owned by this page, and will
828	automatically be destroyed when this page class is
829	destroyed.
830	**/
831	PageTransition *transition() const;
832
833	/**
834	Gets the page action specified, or empty unique pointer if there is no action.
835	**/
836	std::unique_ptr<Link> action(PageAction act) const;
837
838	/**
839	Types of orientations that are possible
840	*/
841	enum Orientation
842	{
843	Landscape, ///< Landscape orientation (portrait, with 90 degrees clockwise rotation )
844	Portrait, ///< Normal portrait orientation
845	Seascape, ///< Seascape orientation (portrait, with 270 degrees clockwise rotation)
846	UpsideDown ///< Upside down orientation (portrait, with 180 degrees rotation)
847	};
848
849	/**
850	The orientation of the page
851	*/
852	Orientation orientation() const;
853
854	/**
855	The default CTM
856	*/
857	void defaultCTM(double *CTM, double dpiX, double dpiY, int rotate, bool upsideDown);
858
859	/**
860	Gets the links of the page
861	*/
862	std::vector<std::unique_ptr<Link>> links() const;
863
864	/**
865	Returns the annotations of the page
866
867	\note If you call this method twice, you get different objects
868	pointing to the same annotations (see Annotation).
869	*/
870	std::vector<std::unique_ptr<Annotation>> annotations() const;
871
872	/**
873	Returns the annotations of the page
874
875	\param subtypes the subtypes of annotations you are interested in
876
877	\note If you call this method twice, you get different objects
878	pointing to the same annotations (see Annotation).
879	*/
880	std::vector<std::unique_ptr<Annotation>> annotations(const QSet<Annotation::SubType> &subtypes) const;
881
882	/**
883	Adds an annotation to the page
884
885	\note Ownership of the annotation object stays with the caller, who can
886	delete it at any time.
887	*/
888	void addAnnotation(const Annotation *ann);
889
890	/**
891	Removes an annotation from the page and destroys the annotation object
892
893	\note There mustn't be other Annotation objects pointing this annotation
894	*/
895	void removeAnnotation(const Annotation *ann);
896
897	/**
898	Returns the form fields on the page
899	*/
900	std::vector<std::unique_ptr<FormField>> formFields() const;
901
902	/**
903	Returns the page duration. That is the time, in seconds, that the page
904	should be displayed before the presentation automatically advances to the next page.
905	Returns < 0 if duration is not set.
906	*/
907	double duration() const;
908
909	/**
910	Returns the label of the page, or a null string is the page has no label.
911	**/
912	QString label() const;
913
914	/**
915	Returns the index of the page.
916	**/
917	int index() const;
918
919	private:
920	Q_DISABLE_COPY(Page)
921
922	Page(DocumentData *doc, int index);
923	PageData *m_page;
924	};
925
926	/**
927	\brief Item in the outline of a PDF document
928
929	Represents an item in the outline of PDF document, i.e. a name, an internal or external link and a set of child items.
930	**/
931	class POPPLER_QT6_EXPORT OutlineItem
932	{
933	friend class Document;
934
935	public:
936	/**
937	Constructs a null item, i.e. one that does not represent a valid item in the outline of some PDF document.
938	**/
939	OutlineItem();
940	~OutlineItem();
941
942	OutlineItem(const OutlineItem &other);
943	OutlineItem &operator=(const OutlineItem &other);
944
945	OutlineItem(OutlineItem &&other) noexcept;
946	OutlineItem &operator=(OutlineItem &&other) noexcept;
947
948	/**
949	Indicates whether an item is null, i.e. whether it does not represent a valid item in the outline of some PDF document.
950	**/
951	bool isNull() const;
952
953	/**
954	The name of the item which should be displayed to the user.
955	**/
956	QString name() const;
957
958	/**
959	Indicates whether the item should initially be display in an expanded or collapsed state.
960	**/
961	bool isOpen() const;
962
963	/**
964	The destination referred to by this item.
965
966	\returns a shared pointer to an immutable link destination
967	**/
968	QSharedPointer<const LinkDestination> destination() const;
969
970	/**
971	The external file name of the document to which the \see destination refers
972
973	\returns a string with the external file name or an empty string if there is none
974	*/
975	QString externalFileName() const;
976
977	/**
978	The URI to which the item links
979
980	\returns a string with the URI which this item links or an empty string if there is none
981	**/
982	QString uri() const;
983
984	/**
985	Determines if this item has any child items
986
987	\returns true if there are any child items
988	**/
989	bool hasChildren() const;
990
991	/**
992	Gets the child items of this item
993
994	\returns a vector outline items, empty if there are none
995	**/
996	QVector<OutlineItem> children() const;
997
998	private:
999	explicit OutlineItem(OutlineItemData *data);
1000	OutlineItemData *m_data;
1001	};
1002
1003	/**
1004	\brief PDF document.
1005
1006	The Document class represents a PDF document: its pages, and all the global
1007	properties, metadata, etc.
1008
1009	\section ownership Ownership of the returned objects
1010
1011	All the functions that returns class pointers create new object, and the
1012	responsibility of those is given to the caller.
1013
1014	The only exception is \link Poppler::Page::transition() Page::transition()\endlink.
1015
1016	\section document-loading Loading
1017
1018	To get a Document, you have to load it via the load() & loadFromData()
1019	functions.
1020
1021	In all the functions that have passwords as arguments, they \b must be Latin1
1022	encoded. If you have a password that is a UTF-8 string, you need to use
1023	QString::toLatin1() (or similar) to convert the password first.
1024	If you have a UTF-8 character array, consider converting it to a QString first
1025	(QString::fromUtf8(), or similar) before converting to Latin1 encoding.
1026
1027	\section document-rendering Rendering
1028
1029	To render pages of a document, you have different Document functions to set
1030	various options.
1031
1032	\subsection document-rendering-backend Backends
1033
1034	%Poppler offers a different backends for rendering the pages. Currently
1035	there are two backends (see #RenderBackend), but only the Splash engine works
1036	well and has been tested.
1037
1038	The available rendering backends can be discovered via availableRenderBackends().
1039	The current rendering backend can be changed using setRenderBackend().
1040	Please note that setting a backend not listed in the available ones
1041	will always result in null QImage's.
1042
1043	\section document-cms Color management support
1044
1045	%Poppler, if compiled with this support, provides functions to handle color
1046	profiles.
1047
1048	To know whether the %Poppler version you are using has support for color
1049	management, you can query Poppler::isCmsAvailable(). In case it is not
1050	available, all the color management-related functions will either do nothing
1051	or return null.
1052	*/
1053	class POPPLER_QT6_EXPORT Document
1054	{
1055	friend class Page;
1056	friend class DocumentData;
1057
1058	public:
1059	/**
1060	The page mode
1061	*/
1062	enum PageMode
1063	{
1064	UseNone, ///< No mode - neither document outline nor thumbnail images are visible
1065	UseOutlines, ///< Document outline visible
1066	UseThumbs, ///< Thumbnail images visible
1067	FullScreen, ///< Fullscreen mode (no menubar, windows controls etc)
1068	UseOC, ///< Optional content group panel visible
1069	UseAttach ///< Attachments panel visible
1070	};
1071
1072	/**
1073	The page layout
1074	*/
1075	enum PageLayout
1076	{
1077	NoLayout, ///< Layout not specified
1078	SinglePage, ///< Display a single page
1079	OneColumn, ///< Display a single column of pages
1080	TwoColumnLeft, ///< Display the pages in two columns, with odd-numbered pages on the left
1081	TwoColumnRight, ///< Display the pages in two columns, with odd-numbered pages on the right
1082	TwoPageLeft, ///< Display the pages two at a time, with odd-numbered pages on the left
1083	TwoPageRight ///< Display the pages two at a time, with odd-numbered pages on the right
1084	};
1085
1086	/**
1087	The render backends available
1088	*/
1089	enum RenderBackend
1090	{
1091	SplashBackend, ///< Splash backend
1092	QPainterBackend ///< Qt backend
1093	};
1094
1095	/**
1096	The render hints available
1097	*/
1098	enum RenderHint
1099	{
1100	Antialiasing = 0x00000001, ///< Antialiasing for graphics
1101	TextAntialiasing = 0x00000002, ///< Antialiasing for text
1102	TextHinting = 0x00000004, ///< Hinting for text
1103	TextSlightHinting = 0x00000008, ///< Lighter hinting for text when combined with TextHinting
1104	OverprintPreview = 0x00000010, ///< Overprint preview
1105	ThinLineSolid = 0x00000020, ///< Enhance thin lines solid
1106	ThinLineShape = 0x00000040, ///< Enhance thin lines shape. Wins over ThinLineSolid
1107	IgnorePaperColor = 0x00000080, ///< Do not compose with the paper color
1108	HideAnnotations = 0x00000100 ///< Do not render annotations
1109	};
1110	Q_DECLARE_FLAGS(RenderHints, RenderHint)
1111
1112	/**
1113	Form types
1114	*/
1115	enum FormType
1116	{
1117	NoForm, ///< Document doesn't contain forms
1118	AcroForm, ///< AcroForm
1119	XfaForm ///< Adobe XML Forms Architecture (XFA), currently unsupported
1120	};
1121
1122	/**
1123	Set a color display profile for the current document.
1124
1125	\param outputProfileA is a \c cmsHPROFILE of the LCMS library.
1126
1127	\note This should be called before any rendering happens.
1128
1129	\note It is assumed that poppler takes over the owernship of the corresponding cmsHPROFILE. In particular,
1130	it is no longer the caller's responsibility to close the profile after use.
1131	*/
1132	void setColorDisplayProfile(void *outputProfileA);
1133	/**
1134	Set a color display profile for the current document.
1135
1136	\param name is the name of the display profile to set.
1137
1138	\note This should be called before any rendering happens.
1139	*/
1140	void setColorDisplayProfileName(const QString &name);
1141	/**
1142	Return the current RGB profile.
1143
1144	\return a \c cmsHPROFILE of the LCMS library.
1145
1146	\note The returned profile stays a property of poppler and shall NOT be closed by the user. It's
1147	existence is guaranteed for as long as this instance of the Document class is not deleted.
1148	*/
1149	void *colorRgbProfile() const;
1150	/**
1151	Return the current display profile.
1152
1153	\return a \c cmsHPROFILE of the LCMS library.
1154
1155	\note The returned profile stays a property of poppler and shall NOT be closed by the user. It's
1156	existence is guaranteed for as long as this instance of the Document class is not deleted.
1157	*/
1158	void *colorDisplayProfile() const;
1159
1160	/**
1161	Load the document from a file on disk
1162
1163	\param filePath the name (and path, if required) of the file to load
1164	\param ownerPassword the Latin1-encoded owner password to use in
1165	loading the file
1166	\param userPassword the Latin1-encoded user ("open") password
1167	to use in loading the file
1168
1169	\return the loaded document, or empty unique pointer on error
1170
1171	\warning The returning document may be locked if a password is required
1172	to open the file, and one is not provided (as the userPassword).
1173	*/
1174	static std::unique_ptr<Document> load(const QString &filePath, const QByteArray &ownerPassword = QByteArray(), const QByteArray &userPassword = QByteArray());
1175
1176	/**
1177	Load the document from a device
1178
1179	\param device the device of the data to load
1180	\param ownerPassword the Latin1-encoded owner password to use in
1181	loading the file
1182	\param userPassword the Latin1-encoded user ("open") password
1183	to use in loading the file
1184
1185	\return the loaded document, or empty unique pointer on error
1186
1187	\note if the file is on disk it is recommended to use the other load overload
1188	since it is less resource intensive
1189
1190	\warning The returning document may be locked if a password is required
1191	to open the file, and one is not provided (as the userPassword).
1192	*/
1193	static std::unique_ptr<Document> load(QIODevice *device, const QByteArray &ownerPassword = QByteArray(), const QByteArray &userPassword = QByteArray());
1194
1195	/**
1196	Load the document from memory
1197
1198	\param fileContents the file contents. They are copied so there is no need
1199	to keep the byte array around for the full life time of
1200	the document.
1201	\param ownerPassword the Latin1-encoded owner password to use in
1202	loading the file
1203	\param userPassword the Latin1-encoded user ("open") password
1204	to use in loading the file
1205
1206	\return the loaded document, or empty unique pointer on error
1207
1208	\warning The returning document may be locked if a password is required
1209	to open the file, and one is not provided (as the userPassword).
1210	*/
1211	static std::unique_ptr<Document> loadFromData(const QByteArray &fileContents, const QByteArray &ownerPassword = QByteArray(), const QByteArray &userPassword = QByteArray());
1212
1213	/**
1214	Get a specified Page
1215
1216	Note that this follows the PDF standard of being zero based - if you
1217	want the first page, then you need an index of zero.
1218
1219	This function can return empty unique pointer if for some reason the page can't be properly parsed.
1220
1221	\param index the page number index
1222
1223	\warning The Page object returned by this method internally stores a pointer
1224	to the document that it was created from. This pointer will go stale if you
1225	delete the Document object. Therefore the Document object needs to be kept alive
1226	as long as you want to use the Page object.
1227	*/
1228	std::unique_ptr<Page> page(int index) const;
1229
1230	/**
1231	\overload
1232
1233
1234	The intent is that you can pass in a label like \c "ix" and
1235	get the page with that label (which might be in the table of
1236	contents), or pass in \c "1" and get the page that the user
1237	expects (which might not be the first page, if there is a
1238	title page and a table of contents).
1239
1240	\param label the page label
1241	*/
1242	std::unique_ptr<Page> page(const QString &label) const;
1243
1244	/**
1245	The number of pages in the document
1246	*/
1247	int numPages() const;
1248
1249	/**
1250	The type of mode that should be used by the application
1251	when the document is opened. Note that while this is
1252	called page mode, it is really viewer application mode.
1253	*/
1254	PageMode pageMode() const;
1255
1256	/**
1257	The layout that pages should be shown in when the document
1258	is first opened. This basically describes how pages are
1259	shown relative to each other.
1260	*/
1261	PageLayout pageLayout() const;
1262
1263	/**
1264	The predominant reading order for text as supplied by
1265	the document's viewer preferences.
1266	*/
1267	Qt::LayoutDirection textDirection() const;
1268
1269	/**
1270	Provide the passwords required to unlock the document
1271
1272	\param ownerPassword the Latin1-encoded owner password to use in
1273	loading the file
1274	\param userPassword the Latin1-encoded user ("open") password
1275	to use in loading the file
1276	*/
1277	bool unlock(const QByteArray &ownerPassword, const QByteArray &userPassword);
1278
1279	/**
1280	Determine if the document is locked
1281	*/
1282	bool isLocked() const;
1283
1284	/**
1285	The date associated with the document
1286
1287	You would use this method with something like:
1288	\code
1289	QDateTime created = m_doc->date("CreationDate");
1290	QDateTime modified = m_doc->date("ModDate");
1291	\endcode
1292
1293	The available dates are:
1294	- CreationDate: the date of creation of the document
1295	- ModDate: the date of the last change in the document
1296
1297	\param type the type of date that is required
1298	*/
1299	QDateTime date(const QString &type) const;
1300
1301	/**
1302	Set the Info dict date entry specified by \param key to \param val
1303
1304	\returns true on success, false on failure
1305	*/
1306	bool setDate(const QString &key, const QDateTime &val);
1307
1308	/**
1309	The date of the creation of the document
1310	*/
1311	QDateTime creationDate() const;
1312
1313	/**
1314	Set the creation date of the document to \param val
1315
1316	\returns true on success, false on failure
1317	*/
1318	bool setCreationDate(const QDateTime &val);
1319
1320	/**
1321	The date of the last change in the document
1322	*/
1323	QDateTime modificationDate() const;
1324
1325	/**
1326	Set the modification date of the document to \param val
1327
1328	\returns true on success, false on failure
1329	*/
1330	bool setModificationDate(const QDateTime &val);
1331
1332	/**
1333	Get specified information associated with the document
1334
1335	You would use this method with something like:
1336	\code
1337	QString title = m_doc->info("Title");
1338	QString subject = m_doc->info("Subject");
1339	\endcode
1340
1341	In addition to \c Title and \c Subject, other information that may
1342	be available include \c Author, \c Keywords, \c Creator and \c Producer.
1343
1344	\param type the information that is required
1345
1346	\sa infoKeys() to get a list of the available keys
1347	*/
1348	QString info(const QString &type) const;
1349
1350	/**
1351	Set the value of the document's Info dictionary entry specified by \param key to \param val
1352
1353	\returns true on success, false on failure
1354	*/
1355	bool setInfo(const QString &key, const QString &val);
1356
1357	/**
1358	The title of the document
1359	*/
1360	QString title() const;
1361
1362	/**
1363	Set the title of the document to \param val
1364
1365	\returns true on success, false on failure
1366	*/
1367	bool setTitle(const QString &val);
1368
1369	/**
1370	The author of the document
1371	*/
1372	QString author() const;
1373
1374	/**
1375	Set the author of the document to \param val
1376
1377	\returns true on success, false on failure
1378	*/
1379	bool setAuthor(const QString &val);
1380
1381	/**
1382	The subject of the document
1383	*/
1384	QString subject() const;
1385
1386	/**
1387	Set the subject of the document to \param val
1388
1389	\returns true on success, false on failure
1390	*/
1391	bool setSubject(const QString &val);
1392
1393	/**
1394	The keywords of the document
1395	*/
1396	QString keywords() const;
1397
1398	/**
1399	Set the keywords of the document to \param val
1400
1401	\returns true on success, false on failure
1402	*/
1403	bool setKeywords(const QString &val);
1404
1405	/**
1406	The creator of the document
1407	*/
1408	QString creator() const;
1409
1410	/**
1411	Set the creator of the document to \param val
1412
1413	\returns true on success, false on failure
1414	*/
1415	bool setCreator(const QString &val);
1416
1417	/**
1418	The producer of the document
1419	*/
1420	QString producer() const;
1421
1422	/**
1423	Set the producer of the document to \param val
1424
1425	\returns true on success, false on failure
1426	*/
1427	bool setProducer(const QString &val);
1428
1429	/**
1430	Remove the document's Info dictionary
1431
1432	\returns true on success, false on failure
1433	*/
1434	bool removeInfo();
1435
1436	/**
1437	Obtain a list of the available string information keys.
1438	*/
1439	QStringList infoKeys() const;
1440
1441	/**
1442	Test if the document is encrypted
1443	*/
1444	bool isEncrypted() const;
1445
1446	/**
1447	Test if the document is linearised
1448
1449	In some cases, this is called "fast web view", since it
1450	is mostly an optimisation for viewing over the Web.
1451	*/
1452	bool isLinearized() const;
1453
1454	/**
1455	Test if the permissions on the document allow it to be
1456	printed
1457	*/
1458	bool okToPrint() const;
1459
1460	/**
1461	Test if the permissions on the document allow it to be
1462	printed at high resolution
1463	*/
1464	bool okToPrintHighRes() const;
1465
1466	/**
1467	Test if the permissions on the document allow it to be
1468	changed.
1469
1470	\note depending on the type of change, it may be more
1471	appropriate to check other properties as well.
1472	*/
1473	bool okToChange() const;
1474
1475	/**
1476	Test if the permissions on the document allow the
1477	contents to be copied / extracted
1478	*/
1479	bool okToCopy() const;
1480
1481	/**
1482	Test if the permissions on the document allow annotations
1483	to be added or modified, and interactive form fields (including
1484	signature fields) to be completed.
1485	*/
1486	bool okToAddNotes() const;
1487
1488	/**
1489	Test if the permissions on the document allow interactive
1490	form fields (including signature fields) to be completed.
1491
1492	\note this can be true even if okToAddNotes() is false - this
1493	means that only form completion is permitted.
1494	*/
1495	bool okToFillForm() const;
1496
1497	/**
1498	Test if the permissions on the document allow interactive
1499	form fields (including signature fields) to be set, created and
1500	modified
1501	*/
1502	bool okToCreateFormFields() const;
1503
1504	/**
1505	Test if the permissions on the document allow content extraction
1506	(text and perhaps other content) for accessibility usage (eg for
1507	a screen reader)
1508	*/
1509	bool okToExtractForAccessibility() const;
1510
1511	/**
1512	Test if the permissions on the document allow it to be
1513	"assembled" - insertion, rotation and deletion of pages;
1514	or creation of bookmarks and thumbnail images.
1515
1516	\note this can be true even if okToChange() is false
1517	*/
1518	bool okToAssemble() const;
1519
1520	/** \brief The version specification of a pdf file */
1521	struct PdfVersion
1522	{
1523	int major;
1524	int minor;
1525	};
1526
1527	/**
1528	The version of the PDF specification that the document
1529	conforms to
1530
1531	\since 21.08
1532	*/
1533	PdfVersion getPdfVersion() const;
1534
1535	/**
1536	The fonts within the PDF document.
1537
1538	This is a shorthand for getting all the fonts at once.
1539
1540	\note this can take a very long time to run with a large
1541	document. You may wish to use a FontIterator if you have more
1542	than say 20 pages
1543
1544	\see newFontIterator()
1545	*/
1546	QList<FontInfo> fonts() const;
1547
1548	/**
1549	Creates a new FontIterator object for font scanning.
1550
1551	The new iterator can be used for reading the font information of the
1552	document, reading page by page.
1553
1554	\param startPage the initial page from which start reading fonts
1555
1556	\see fonts()
1557	*/
1558	std::unique_ptr<FontIterator> newFontIterator(int startPage = 0) const;
1559
1560	/**
1561	The font data if the font is an embedded one.
1562	*/
1563	QByteArray fontData(const FontInfo &fi) const;
1564
1565	/**
1566	The documents embedded within the PDF document.
1567
1568	\note there are two types of embedded document - this call
1569	only accesses documents that are embedded at the document level.
1570
1571	\note The ownership of the EmbeddedFile objects remain with the callee.
1572	*/
1573	QList<EmbeddedFile *> embeddedFiles() const;
1574
1575	/**
1576	Whether there are any documents embedded in this PDF document.
1577	*/
1578	bool hasEmbeddedFiles() const;
1579
1580	/**
1581	Gets the outline of the document
1582
1583	\returns a vector of outline items, empty if there are none
1584	**/
1585	QVector<OutlineItem> outline() const;
1586
1587	/**
1588	Tries to resolve the named destination \p name.
1589
1590	\note this operation starts a search through the whole document
1591
1592	\returns a new LinkDestination object if the named destination was
1593	actually found, or empty unique pointer otherwise
1594	*/
1595	std::unique_ptr<LinkDestination> linkDestination(const QString &name);
1596
1597	/**
1598	Sets the paper color
1599
1600	\param color the new paper color
1601	*/
1602	void setPaperColor(const QColor &color);
1603	/**
1604	The paper color
1605
1606	The default color is white.
1607	*/
1608	QColor paperColor() const;
1609
1610	/**
1611	Sets the backend used to render the pages.
1612
1613	\param backend the new rendering backend
1614	*/
1615	void setRenderBackend(RenderBackend backend);
1616	/**
1617	The currently set render backend
1618
1619	The default backend is \ref SplashBackend
1620	*/
1621	RenderBackend renderBackend() const;
1622
1623	/**
1624	The available rendering backends.
1625	*/
1626	static QSet<RenderBackend> availableRenderBackends();
1627
1628	/**
1629	Sets the render \p hint .
1630
1631	\note some hints may not be supported by some rendering backends.
1632
1633	\param on whether the flag should be added or removed.
1634	*/
1635	void setRenderHint(RenderHint hint, bool on = true);
1636	/**
1637	The currently set render hints.
1638	*/
1639	RenderHints renderHints() const;
1640
1641	/**
1642	Gets a new PS converter for this document.
1643	*/
1644	std::unique_ptr<PSConverter> psConverter() const;
1645
1646	/**
1647	Gets a new PDF converter for this document.
1648	*/
1649	std::unique_ptr<PDFConverter> pdfConverter() const;
1650
1651	/**
1652	Gets the metadata stream contents
1653	*/
1654	QString metadata() const;
1655
1656	/**
1657	Test whether this document has "optional content".
1658
1659	Optional content is used to optionally turn on (display)
1660	and turn off (not display) some elements of the document.
1661	The most common use of this is for layers in design
1662	applications, but it can be used for a range of things,
1663	such as not including some content in printing, and
1664	displaying content in the appropriate language.
1665	*/
1666	bool hasOptionalContent() const;
1667
1668	/**
1669	Itemviews model for optional content.
1670
1671	The model is owned by the document.
1672	*/
1673	OptContentModel *optionalContentModel();
1674
1675	/**
1676	Document-level JavaScript scripts.
1677
1678	Returns the list of document level JavaScript scripts to be always
1679	executed before any other script.
1680	*/
1681	QStringList scripts() const;
1682
1683	/**
1684	The PDF identifiers.
1685
1686	\param permanentId an optional pointer to a variable where store the
1687	permanent ID of the document
1688	\param updateId an optional pointer to a variable where store the
1689	update ID of the document
1690
1691	\return whether the document has the IDs
1692	*/
1693	bool getPdfId(QByteArray *permanentId, QByteArray *updateId) const;
1694
1695	/**
1696	Returns the type of forms contained in the document
1697	*/
1698	FormType formType() const;
1699
1700	/**
1701	Returns the calculate order for forms (using their id)
1702	*/
1703	QVector<int> formCalculateOrder() const;
1704
1705	/**
1706	Returns the signatures of this document.
1707
1708	Prefer to use this over getting the signatures for all the pages of the document
1709	since there are documents with signatures that don't belong to a given page
1710	*/
1711	std::vector<std::unique_ptr<FormFieldSignature>> signatures() const;
1712
1713	/**
1714	Returns whether the document's XRef table has been reconstructed or not
1715
1716	\since 21.06
1717	*/
1718	bool xrefWasReconstructed() const;
1719
1720	/**
1721	Sets the document's XRef reconstruction callback, so whenever a XRef table
1722	reconstruction happens the callback will get triggered.
1723
1724	\since 21.06
1725	*/
1726	void setXRefReconstructedCallback(const std::function<void()> &callback);
1727
1728	/**
1729	Destructor.
1730	*/
1731	~Document();
1732
1733	private:
1734	Q_DISABLE_COPY(Document)
1735
1736	DocumentData *m_doc;
1737
1738	explicit Document(DocumentData *dataA);
1739	};
1740
1741	class BaseConverterPrivate;
1742	class PSConverterPrivate;
1743	class PDFConverterPrivate;
1744	/**
1745	\brief Base converter.
1746
1747	This is the base class for the converters.
1748	*/
1749	class POPPLER_QT6_EXPORT BaseConverter
1750	{
1751	friend class Document;
1752
1753	public:
1754	/**
1755	Destructor.
1756	*/
1757	virtual ~BaseConverter();
1758
1759	/** Sets the output file name. You must set this or the output device. */
1760	void setOutputFileName(const QString &outputFileName);
1761
1762	/**
1763	* Sets the output device. You must set this or the output file name.
1764	*/
1765	void setOutputDevice(QIODevice *device);
1766
1767	/**
1768	Does the conversion.
1769
1770	\return whether the conversion succeeded
1771	*/
1772	virtual bool convert() = 0;
1773
1774	enum Error
1775	{
1776	NoError,
1777	FileLockedError,
1778	OpenOutputError,
1779	NotSupportedInputFileError
1780	};
1781
1782	/**
1783	Returns the last error
1784	*/
1785	Error lastError() const;
1786
1787	protected:
1788	/// \cond PRIVATE
1789	explicit BaseConverter(BaseConverterPrivate &dd);
1790	Q_DECLARE_PRIVATE(BaseConverter)
1791	BaseConverterPrivate *d_ptr;
1792	/// \endcond
1793
1794	private:
1795	Q_DISABLE_COPY(BaseConverter)
1796	};
1797
1798	/**
1799	Converts a PDF to PS
1800
1801	Sizes have to be in Points (1/72 inch)
1802
1803	If you are using QPrinter you can get paper size by doing:
1804	\code
1805	QPrinter dummy(QPrinter::PrinterResolution);
1806	dummy.setFullPage(true);
1807	dummy.setPageSize(myPageSize);
1808	width = dummy.width();
1809	height = dummy.height();
1810	\endcode
1811	*/
1812	class POPPLER_QT6_EXPORT PSConverter : public BaseConverter
1813	{
1814	friend class Document;
1815
1816	public:
1817	/**
1818	Options for the PS export.
1819	*/
1820	enum PSOption
1821	{
1822	Printing = 0x00000001, ///< The PS is generated for printing purposes
1823	StrictMargins = 0x00000002,
1824	ForceRasterization = 0x00000004,
1825	PrintToEPS = 0x00000008, ///< Output EPS instead of PS
1826	HideAnnotations = 0x00000010, ///< Don't print annotations
1827	ForceOverprintPreview = 0x00000020 ///< Force rasterized overprint preview during conversion \since 23.09
1828	};
1829	Q_DECLARE_FLAGS(PSOptions, PSOption)
1830
1831	/**
1832	Destructor.
1833	*/
1834	~PSConverter() override;
1835
1836	/** Sets the list of pages to print. Mandatory. */
1837	void setPageList(const QList<int> &pageList);
1838
1839	/**
1840	Sets the title of the PS Document. Optional
1841	*/
1842	void setTitle(const QString &title);
1843
1844	/**
1845	Sets the horizontal DPI. Defaults to 72.0
1846	*/
1847	void setHDPI(double hDPI);
1848
1849	/**
1850	Sets the vertical DPI. Defaults to 72.0
1851	*/
1852	void setVDPI(double vDPI);
1853
1854	/**
1855	Sets the rotate. Defaults to not rotated
1856	*/
1857	void setRotate(int rotate);
1858
1859	/**
1860	Sets the output paper width. Has to be set.
1861	*/
1862	void setPaperWidth(int paperWidth);
1863
1864	/**
1865	Sets the output paper height. Has to be set.
1866	*/
1867	void setPaperHeight(int paperHeight);
1868
1869	/**
1870	Sets the output right margin. Defaults to 0
1871	*/
1872	void setRightMargin(int marginRight);
1873
1874	/**
1875	Sets the output bottom margin. Defaults to 0
1876	*/
1877	void setBottomMargin(int marginBottom);
1878
1879	/**
1880	Sets the output left margin. Defaults to 0
1881	*/
1882	void setLeftMargin(int marginLeft);
1883
1884	/**
1885	Sets the output top margin. Defaults to 0
1886	*/
1887	void setTopMargin(int marginTop);
1888
1889	/**
1890	Defines if margins have to be strictly followed (even if that
1891	means changing aspect ratio), or if the margins can be adapted
1892	to keep aspect ratio.
1893
1894	Defaults to false.
1895	*/
1896	void setStrictMargins(bool strictMargins);
1897
1898	/**
1899	Defines if the page will be rasterized to an image with overprint
1900	preview enabled before printing.
1901
1902	Defaults to false
1903
1904	\since 23.09
1905	*/
1906	void setForceOverprintPreview(bool forceOverprintPreview);
1907
1908	/** Defines if the page will be rasterized to an image before printing. Defaults to false */
1909	void setForceRasterize(bool forceRasterize);
1910
1911	/**
1912	Sets the options for the PS export.
1913	*/
1914	void setPSOptions(PSOptions options);
1915
1916	/**
1917	The currently set options for the PS export.
1918
1919	The default flags are: Printing.
1920	*/
1921	PSOptions psOptions() const;
1922
1923	/**
1924	Sets a function that will be called each time a page is converted.
1925
1926	The payload belongs to the caller.
1927	*/
1928	void setPageConvertedCallback(void (*callback)(int page, void *payload), void *payload);
1929
1930	bool convert() override;
1931
1932	private:
1933	Q_DECLARE_PRIVATE(PSConverter)
1934	Q_DISABLE_COPY(PSConverter)
1935
1936	explicit PSConverter(DocumentData *document);
1937	};
1938
1939	/**
1940	Converts a PDF to PDF (thus saves a copy of the document).
1941	*/
1942	class POPPLER_QT6_EXPORT PDFConverter : public BaseConverter
1943	{
1944	friend class Document;
1945
1946	public:
1947	/**
1948	Options for the PDF export.
1949	*/
1950	enum PDFOption
1951	{
1952	WithChanges = 0x00000001 ///< The changes done to the document are saved as well
1953	};
1954	Q_DECLARE_FLAGS(PDFOptions, PDFOption)
1955
1956	/**
1957	Destructor.
1958	*/
1959	~PDFConverter() override;
1960
1961	/**
1962	Sets the options for the PDF export.
1963	*/
1964	void setPDFOptions(PDFOptions options);
1965	/**
1966	The currently set options for the PDF export.
1967	*/
1968	PDFOptions pdfOptions() const;
1969
1970	/**
1971	* Holds data for a new signature
1972	* - Common Name of cert to sign (aka nickname)
1973	* - password for the cert
1974	* - page where to add the signature
1975	* - rect for the signature annotation
1976	* - text that will be shown inside the rect
1977	* - font size and color
1978	* - border width and color
1979	* - background color
1980	* \since 21.01
1981	*/
1982	class POPPLER_QT6_EXPORT NewSignatureData
1983	{
1984	public:
1985	NewSignatureData();
1986	~NewSignatureData();
1987	NewSignatureData(const NewSignatureData &) = delete;
1988	NewSignatureData &operator=(const NewSignatureData &) = delete;
1989
1990	QString certNickname() const;
1991	void setCertNickname(const QString &certNickname);
1992
1993	QString password() const;
1994	void setPassword(const QString &password);
1995
1996	int page() const;
1997	void setPage(int page);
1998
1999	QRectF boundingRectangle() const;
2000	void setBoundingRectangle(const QRectF &rect);
2001
2002	QString signatureText() const;
2003	void setSignatureText(const QString &text);
2004
2005	/**
2006	* If this text is not empty, the signature representation
2007	* will split in two, with this text on the left and signatureText
2008	* on the right
2009	*
2010	* \since 21.06
2011	*/
2012	QString signatureLeftText() const;
2013	void setSignatureLeftText(const QString &text);
2014
2015	/**
2016	* Signature's property Reason.
2017	*
2018	* Default: an empty string.
2019	*
2020	* \since 21.10
2021	*/
2022	QString reason() const;
2023	void setReason(const QString &reason);
2024
2025	/**
2026	* Signature's property Location.
2027	*
2028	* Default: an empty string.
2029	*
2030	* \since 21.10
2031	*/
2032	QString location() const;
2033	void setLocation(const QString &location);
2034
2035	/**
2036	* Default: 10
2037	*/
2038	double fontSize() const;
2039	void setFontSize(double fontSize);
2040
2041	/**
2042	* Default: 20
2043	*
2044	* \since 21.06
2045	*/
2046	double leftFontSize() const;
2047	void setLeftFontSize(double fontSize);
2048
2049	/**
2050	* Default: red
2051	*/
2052	QColor fontColor() const;
2053	void setFontColor(const QColor &color);
2054
2055	/**
2056	* Default: red
2057	*/
2058	QColor borderColor() const;
2059	void setBorderColor(const QColor &color);
2060
2061	/**
2062	* border width in points
2063	*
2064	* Default: 1.5
2065	*
2066	* \since 21.05
2067	*/
2068	double borderWidth() const;
2069	void setBorderWidth(double width);
2070
2071	/**
2072	* Default: QColor(240, 240, 240)
2073	*/
2074	QColor backgroundColor() const;
2075	void setBackgroundColor(const QColor &color);
2076
2077	/**
2078	* Default: QUuid::createUuid().toString()
2079	*/
2080	QString fieldPartialName() const;
2081	void setFieldPartialName(const QString &name);
2082
2083	/**
2084	* Document owner password (needed if the document that is being signed is password protected)
2085	*
2086	* Default: no password
2087	*
2088	* \since 22.02
2089	*/
2090	QByteArray documentOwnerPassword() const;
2091	void setDocumentOwnerPassword(const QByteArray &password);
2092
2093	/**
2094	* Document user password (needed if the document that is being signed is password protected)
2095	*
2096	* Default: no password
2097	*
2098	* \since 22.02
2099	*/
2100	QByteArray documentUserPassword() const;
2101	void setDocumentUserPassword(const QByteArray &password);
2102
2103	/**
2104	* Filesystem path to an image file to be used as background
2105	* image for the signature annotation widget.
2106	*
2107	* Default: empty
2108	*
2109	* \since 22.02
2110	*/
2111	QString imagePath() const;
2112	void setImagePath(const QString &path);
2113
2114	private:
2115	struct NewSignatureDataPrivate;
2116	NewSignatureDataPrivate *const d;
2117	};
2118
2119	/**
2120	Sign PDF at given Annotation / signature form
2121
2122	\param data new signature data
2123
2124	\return whether the signing succeeded
2125
2126	\since 21.01
2127	*/
2128	bool sign(const NewSignatureData &data);
2129
2130	bool convert() override;
2131
2132	private:
2133	Q_DECLARE_PRIVATE(PDFConverter)
2134	Q_DISABLE_COPY(PDFConverter)
2135
2136	explicit PDFConverter(DocumentData *document);
2137	};
2138
2139	/**
2140	Conversion from PDF date string format to QDateTime
2141	*/
2142	POPPLER_QT6_EXPORT QDateTime convertDate(const char *dateString);
2143
2144	/**
2145	Whether the color management functions are available.
2146	*/
2147	POPPLER_QT6_EXPORT bool isCmsAvailable();
2148
2149	/**
2150	Whether the overprint preview functionality is available.
2151	*/
2152	POPPLER_QT6_EXPORT bool isOverprintPreviewAvailable();
2153
2154	class SoundData;
2155	/**
2156	Container class for a sound file in a PDF document.
2157
2158	A sound can be either External (in that case should be loaded the file
2159	whose url is represented by url() ), or Embedded, and the player has to
2160	play the data contained in data().
2161	*/
2162	class POPPLER_QT6_EXPORT SoundObject
2163	{
2164	public:
2165	/**
2166	The type of sound
2167	*/
2168	enum SoundType
2169	{
2170	External, ///< The real sound file is external
2171	Embedded ///< The sound is contained in the data
2172	};
2173
2174	/**
2175	The encoding format used for the sound
2176	*/
2177	enum SoundEncoding
2178	{
2179	Raw, ///< Raw encoding, with unspecified or unsigned values in the range [ 0, 2^B - 1 ]
2180	Signed, ///< Twos-complement values
2181	muLaw, ///< mu-law-encoded samples
2182	ALaw ///< A-law-encoded samples
2183	};
2184
2185	/** \cond PRIVATE
2186	The caller keeps the ownership of the popplersound argument
2187	*/
2188	explicit SoundObject(Sound *popplersound);
2189	/// \endcond
2190
2191	~SoundObject();
2192
2193	/**
2194	Is the sound embedded (SoundObject::Embedded) or external (SoundObject::External)?
2195	*/
2196	SoundType soundType() const;
2197
2198	/**
2199	The URL of the sound file to be played, in case of SoundObject::External
2200	*/
2201	QString url() const;
2202
2203	/**
2204	The data of the sound, in case of SoundObject::Embedded
2205	*/
2206	QByteArray data() const;
2207
2208	/**
2209	The sampling rate of the sound
2210	*/
2211	double samplingRate() const;
2212
2213	/**
2214	The number of sound channels to use to play the sound
2215	*/
2216	int channels() const;
2217
2218	/**
2219	The number of bits per sample value per channel
2220	*/
2221	int bitsPerSample() const;
2222
2223	/**
2224	The encoding used for the sound
2225	*/
2226	SoundEncoding soundEncoding() const;
2227
2228	private:
2229	Q_DISABLE_COPY(SoundObject)
2230
2231	SoundData *m_soundData;
2232	};
2233
2234	class MovieData;
2235	/**
2236	Container class for a movie object in a PDF document.
2237	*/
2238	class POPPLER_QT6_EXPORT MovieObject
2239	{
2240	friend class AnnotationPrivate;
2241
2242	public:
2243	/**
2244	The play mode for playing the movie
2245	*/
2246	enum PlayMode
2247	{
2248	PlayOnce, ///< Play the movie once, closing the movie controls at the end
2249	PlayOpen, ///< Like PlayOnce, but leaving the controls open
2250	PlayRepeat, ///< Play continuously until stopped
2251	PlayPalindrome ///< Play forward, then backward, then again foward and so on until stopped
2252	};
2253
2254	~MovieObject();
2255
2256	/**
2257	The URL of the movie to be played
2258	*/
2259	QString url() const;
2260
2261	/**
2262	The size of the movie
2263	*/
2264	QSize size() const;
2265
2266	/**
2267	The rotation (either 0, 90, 180, or 270 degrees clockwise) for the movie,
2268	*/
2269	int rotation() const;
2270
2271	/**
2272	Whether show a bar with movie controls
2273	*/
2274	bool showControls() const;
2275
2276	/**
2277	How to play the movie
2278	*/
2279	PlayMode playMode() const;
2280
2281	/**
2282	Returns whether a poster image should be shown if the movie is not playing.
2283	*/
2284	bool showPosterImage() const;
2285
2286	/**
2287	Returns the poster image that should be shown if the movie is not playing.
2288	If the image is null but showImagePoster() returns @c true, the first frame of the movie
2289	should be used as poster image.
2290	*/
2291	QImage posterImage() const;
2292
2293	private:
2294	/// \cond PRIVATE
2295	explicit MovieObject(AnnotMovie *ann);
2296	/// \endcond
2297
2298	Q_DISABLE_COPY(MovieObject)
2299
2300	MovieData *m_movieData;
2301	};
2302
2303	}
2304
2305	Q_DECLARE_OPERATORS_FOR_FLAGS(Poppler::Page::PainterFlags)
2306	Q_DECLARE_OPERATORS_FOR_FLAGS(Poppler::Page::SearchFlags)
2307	Q_DECLARE_OPERATORS_FOR_FLAGS(Poppler::Document::RenderHints)
2308	Q_DECLARE_OPERATORS_FOR_FLAGS(Poppler::PDFConverter::PDFOptions)
2309	Q_DECLARE_OPERATORS_FOR_FLAGS(Poppler::PSConverter::PSOptions)
2310
2311	#endif
2312