Handling PDF: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Doc Links)
 
(14 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Cleanup | reason=Auto-imported from ExpressionEngine.}}
{{Ambox|text=TODO: Tips for implementing a custom interactive viewer, using Qt and the PDF parsing and rendering libraries mentioned above}}
 
{{LangSwitch}}
__TOC__
[[Category:Developing_with_Qt]]
[[Category:Developing_with_Qt]]
= Handling PDF =
This page discusses various available options for working with [http://en.wikipedia.org/wiki/Portable_Document_Format Portable Document Format (PDF)] [en.wikipedia.org] documents in your Qt application. Please also read the general considerations outlined on the [[Handling_Document_Formats | Handling Document Formats]] page.
This page discusses various available options for working with [http://en.wikipedia.org/wiki/Portable_Document_Format Portable Document Format (PDF)] [en.wikipedia.org] documents in your Qt application. Please also read the general considerations outlined on the [[Handling_Document_Formats | Handling Document Formats]] page.
'' <pre style="background-color: #E6E6FA">Note that this information is collaboratively collected by the community, with no promise
of completeness or correctness. In particular, use your own research and judgment
when evaluating third-party libraries or tools! </pre> ''


== Reading / Writing ==
== Reading / Writing ==
Line 15: Line 9:
=== Using QPrinter ===
=== Using QPrinter ===


For <span style="color:#800080">  creating</span> PDF documents from scratch, you can use Qt's built-in print support which also allows "printing" to PDF files. To do so you can set up a [http://doc.qt.io/qt-5/qprinter.html QPrinter] instance like this: <code>QPrinter printer(QPrinter::HighResolution);
For <span style="color:#800080">  creating</span> PDF documents from scratch, you can use Qt's built-in print support which also allows "printing" to PDF files. To do so you can set up a {{DocLink|QPrinter}} instance like this: <code>QPrinter printer(QPrinter::HighResolution);
printer.setOutputFormat(QPrinter::PdfFormat);
printer.setOutputFormat(QPrinter::PdfFormat);
printer.setOutputFileName("path/to/file.pdf");</code> Since QPrinter inherits [http://doc.qt.io/qt-5/qpaintdevice.html QPaintDevice], anything that supports outputting graphical content to a QPaintDevice (or has convenience API for printing with QPrinter) can thus be used for generating PDFs:
printer.setOutputFileName("path/to/file.pdf");</code> Since QPrinter inherits {{DocLink|QPaintDevice}}, anything that supports outputting graphical content to a QPaintDevice (or has convenience API for printing with QPrinter) can thus be used for generating PDFs:


* '''''manual QPainter painting'''''
* '''''manual QPainter painting'''''
The most basic (but not necessarily simplest) way of creating PDF documents with QPrinter is by manually painting the document's content with Qt's [http://doc.qt.io/qt-5/qtdesigner-arthurplugin-example.html Arthur paint system].
The most basic (but not necessarily simplest) way of creating PDF documents with QPrinter is by manually painting the document's content with Qt's {{DocLink|QtDesigner-ArthurPlugin-Example||Arthur paint system}}.
Just pass the QPrinter object as a reference to the constructor of [http://doc.qt.io/qt-5/paintsystem.html QPainter] (or, alternatively, to [http://doc.qt.io/qt-4.8/qpainter.html#begin QPainter::begin] for an already existing QPainter) and then perform any painting operations with that QPainter instance like you usually would (with intermittent calls to [http://doc.qt.io/qt-4.8/qprinter.html#newPage QPrinter::newPage] whenever you want to move on to the next PDF page).
Just pass the QPrinter object as a reference to the constructor of {{DocLink|PaintSystem.html||QPainter}} (or, alternatively, to {{DocLink|QPainter|begin|QPainter::begin()}} for an already existing QPainter) and then perform any painting operations with that QPainter instance like you usually would (with intermittent calls to {{DocLink|QPrinter|newPage|QPrinter::newPage()}} whenever you want to move on to the next PDF page).


* '''''Scribe'''''
* '''''Scribe'''''
For a more high-level API for creating structured rich-text documents, use Qt's Scribe framework (see [[Handling_Document_Formats | Handling Document Formats]]). You can export the whole document or a part of it to PDF with [http://doc.qt.io/qt-4.8/qtextdocument.html#print QTextDocument::print] or [http://doc.qt.io/qt-4.8/qtextedit.html#print QTextEdit::print](again, using a QPrinter object set up as shown above).
For a more high-level API for creating structured rich-text documents, use Qt's Scribe framework (see [[Handling Document Formats]]), which is based on a cursor interface that mimics the behavior of a cursor in a text editor. You can export the whole document with {{DocLink|QTextDocument|print|QTextDocument::print()}}, or a part of it with {{DocLink|QTextEdit|print|QTextEdit::print()}} (see [[Exporting a document to PDF]] for more details).


* '''''Graphics View'''''
* '''''Graphics View'''''
Qt's [http://doc.qt.io/qt-4.8/graphicsview.html Graphics View framework] can be a more suitable alternative for creating PDF documents with content that is mainly based on arbitrarily positioned and transformed 2D graphical items rather than continuous flowed rich text.
Qt's {{DocLink|GraphicsView||Graphics View framework}} can be a more suitable alternative for creating PDF documents with content that is mainly based on arbitrarily positioned and transformed 2D graphical items rather than continuous flowed rich text.
To export the content of a graphics scene or view (or a part of it) to PDF, you need to manually initialize a QPainter configured to paint on a PDF-creating QPrinter (as described above), and pass it to [http://doc.qt.io/qt-4.8/qgraphicsscene.html#render QGraphicsScene::render] or [http://doc.qt.io/qt-4.8/qgraphicsview.html#render QGraphicsView::render].
To export the content of a graphics scene or view (or a part of it) to PDF, you need to manually initialize a QPainter configured to paint on a PDF-creating QPrinter (as described above), and pass it to {{DocLink|QGraphicsScene|render|QGraphicsScene::render()}} or {{DocLink|QGraphicsView|render|QGraphicsView::render()}}.


=== Using third-party libraries ===
=== Using third-party libraries ===
Line 97: Line 91:


== Rendering ==
== Rendering ==
=== Using QtPDF ===
The QtPDF module is a wrapper around PDFium which supports rendering, navigating pages, bookmarks, links, document metadata, search, text selection and copying to the clipboard.  It includes an image plugin so that most image-viewing applications can view PDF files too (however most of those do not have multi-frame image support, so they will only render the first page).  At this point, more of the feature set is complete for Qt Quick applications than for widget-based ones; but both are possible.  It was introduced as a Qt Labs module in [http://blog.qt.io/blog/2017/01/30/new-qtpdf-qtlabs-module/ this blog post].  Since then, Qt Quick support has been added; and now the source code lives in the qtwebengine repository.  It is supported on all platforms that support Qt WebEngine, plus iOS.  You can build it using [[QtPDF Build Instructions|these instructions]].  Binary builds are also provided via Marketplace:  https://marketplace.qt.io/products/qtpdf  It's available under GPL, LGPL and commercial licenses.


=== Using third-party libraries/tools ===
=== Using third-party libraries/tools ===
Line 112: Line 110:
|-
|-
| [http://freedesktop.org/wiki/Software/poppler '''poppler-qt4'''] [freedesktop.org]
| [http://freedesktop.org/wiki/Software/poppler '''poppler-qt4'''] [freedesktop.org]
| C++/Qt
| pages, …?
| QImage
| Win, Mac?, Linux, …
| GPL v2 <span style="color:Navy"> [strong copyleft] </span>
|-
| [http://freedesktop.org/wiki/Software/poppler '''poppler-qt5'''] [freedesktop.org]
| C++/Qt
| C++/Qt
| pages, …?
| pages, …?
Line 127: Line 132:


Alternatively, the task can be delegated to existing command-line tools:
Alternatively, the task can be delegated to existing command-line tools:


{| class="wikitable"
{| class="wikitable"
Line 153: Line 157:


== Interactive Viewing ==
== Interactive Viewing ==
=== Using QtPDF ===
The [[QtPDF_Build_Instructions|QtPDF module]] includes example PDF viewers which can be adapted and incorporated into Qt Quick or widget-based applications.


=== Calling an external viewer application ===
=== Calling an external viewer application ===
Line 194: Line 201:
| AxAcroPDFLib.AxAcroPDF
| AxAcroPDFLib.AxAcroPDF
| Win, Mac, Linux, …
| Win, Mac, Linux, …
| <span style="color:Navy"> freeware </span> ''(for commercial redistribution see [http://www.adobe.com/products/reader/distribution.html)_ here] [adobe.com]) ''
| <span style="color:Navy"> freeware </span> ''(for commercial redistribution see [http://www.adobe.com/products/reader/distribution.html here]) [adobe.com])''
|}
|}


Line 215: Line 222:
| nppdf
| nppdf
| Win, Mac, (Linux)¹, …  
| Win, Mac, (Linux)¹, …  
| <span style="color:Navy"> freeware </span>''(for commercial redistribution see [http://www.adobe.com/products/reader/distribution.html)_ here]''
| <span style="color:Navy"> freeware </span>''(for commercial redistribution see [http://www.adobe.com/products/reader/distribution.html here] [adobe.com])''
|}
|}


Line 229: Line 236:
! style="text-align:left;"| license
! style="text-align:left;"| license
|-
|-
| [http://www.devmachines.com/products/qtitanmultimedia-overview.html '''QtitanMultimedia'''] [devmachines.com  
| [http://www.devmachines.com/products/qtitanmultimedia-overview.html '''QtitanMultimedia'''] [devmachines.com]
| QWidget
| QWidget
| Adobe Reader, …
| Adobe Reader, …
Line 235: Line 242:
| <span style="color:Navy"> commercial </span>
| <span style="color:Navy"> commercial </span>
|}
|}
=== Implementing a custom viewer ===
<pre style="background-color: Moccasin"> TODO: Tips for implementing a custom interactive viewer, using Qt and the PDF parsing and rendering libraries mentioned above</pre>


== See Also ==
== See Also ==


* [[Handling_Document_Formats | Handling Document Formats]]
* [[Handling Document Formats]]
** ''other "text document" formats:''
* [[Handling HTML]]
*** [[Handling_HTML | HTML]]
* [[Handling Microsoft Excel file format]]
*** [[Handling_RTF | RTF]]
*** [[Handling_Microsoft_Word_(file_format) | Microsoft Word]]
*** [[Handling_OpenDocument_Text | OpenDocument Text]]

Latest revision as of 13:41, 28 May 2020

TODO: Tips for implementing a custom interactive viewer, using Qt and the PDF parsing and rendering libraries mentioned above

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

This page discusses various available options for working with Portable Document Format (PDF) [en.wikipedia.org] documents in your Qt application. Please also read the general considerations outlined on the Handling Document Formats page.

Reading / Writing

Using QPrinter

For creating PDF documents from scratch, you can use Qt's built-in print support which also allows "printing" to PDF files. To do so you can set up a QPrinter instance like this: 

QPrinter printer(QPrinter::HighResolution);
printer.setOutputFormat(QPrinter::PdfFormat);
printer.setOutputFileName("path/to/file.pdf");

Since QPrinter inherits QPaintDevice, anything that supports outputting graphical content to a QPaintDevice (or has convenience API for printing with QPrinter) can thus be used for generating PDFs:

  • manual QPainter painting

The most basic (but not necessarily simplest) way of creating PDF documents with QPrinter is by manually painting the document's content with Qt's Arthur paint system. Just pass the QPrinter object as a reference to the constructor of QPainter (or, alternatively, to QPainter::begin() for an already existing QPainter) and then perform any painting operations with that QPainter instance like you usually would (with intermittent calls to QPrinter::newPage() whenever you want to move on to the next PDF page).

  • Scribe

For a more high-level API for creating structured rich-text documents, use Qt's Scribe framework (see Handling Document Formats), which is based on a cursor interface that mimics the behavior of a cursor in a text editor. You can export the whole document with QTextDocument::print(), or a part of it with QTextEdit::print() (see Exporting a document to PDF for more details).

  • Graphics View

Qt's Graphics View framework can be a more suitable alternative for creating PDF documents with content that is mainly based on arbitrarily positioned and transformed 2D graphical items rather than continuous flowed rich text. To export the content of a graphics scene or view (or a part of it) to PDF, you need to manually initialize a QPainter configured to paint on a PDF-creating QPrinter (as described above), and pass it to QGraphicsScene::render() or QGraphicsView::render().

Using third-party libraries

If you need more control over the output when creating PDF documents, or you need to parse existing PDF documents (anything from extracting specific information to assembling a full in-memory document object tree) and maybe even modify their structure or content before writing them back to disk, refer to third-party PDF reading/writing libraries:

API parsing modifying creating platforms license
poppler-qt4 [freedesktop.org] C+/Qt yes ? ? Win, Mac?, Linux, … GPL v2+ [strong copyleft]
Hummus [pdfhummus.com] C++ yes yes yes Win, Mac, Linux Apache 2.0 [permissive]
PoDoFo [podofo.sourceforge.net] C++ yes yes yes Win, Mac, Linux LGPL [weak copyleft]

Using batch conversion tools

If all else fails, there is always the option of using an existing tool to automatically convert between PDF files and a more manageable format, and let your Qt application read/write that format instead. The conversion tool could be bundled with your application or specified as a prerequisite, and controlled via QProcess. Some possibilities are:


executable names .pdf to: … to .pdf platforms license
poppler-utils [freedesktop.org] pdftotext, pdftocairo, pdftohtml .txt .svg .html … - Win, Mac?, Linux, … GPL v2+ [strong copyleft]
Inkscape [inkscape.org] inkscape .svg … .svg … Win, Mac, Linux, … GPL v2 [strong copyleft]

Rendering

Using QtPDF

The QtPDF module is a wrapper around PDFium which supports rendering, navigating pages, bookmarks, links, document metadata, search, text selection and copying to the clipboard. It includes an image plugin so that most image-viewing applications can view PDF files too (however most of those do not have multi-frame image support, so they will only render the first page). At this point, more of the feature set is complete for Qt Quick applications than for widget-based ones; but both are possible. It was introduced as a Qt Labs module in this blog post. Since then, Qt Quick support has been added; and now the source code lives in the qtwebengine repository. It is supported on all platforms that support Qt WebEngine, plus iOS. You can build it using these instructions. Binary builds are also provided via Marketplace: https://marketplace.qt.io/products/qtpdf It's available under GPL, LGPL and commercial licenses.

Using third-party libraries/tools

For rendering pages or elements from existing PDF documents to image files or in-memory pixmaps (useful e.g. for thumbnail generation or implementing custom viewers), third-party libraries can be used:


API can render output to platforms license
poppler-qt4 [freedesktop.org] C++/Qt pages, …? QImage Win, Mac?, Linux, … GPL v2 [strong copyleft]
poppler-qt5 [freedesktop.org] C++/Qt pages, …? QImage Win, Mac?, Linux, … GPL v2 [strong copyleft]
muPDF [mupdf.com] C pages RGBA byte array Win, Mac, Linux, … GPL v3+ [strong copyleft]; or commercial

Alternatively, the task can be delegated to existing command-line tools:

executable names can render output to platforms license
poppler-utils [freedesktop.org] pdftocairo, pdftoppm, pdfimages pages, image elements .png .jpg .svg .ppm … Win, Mac?, Linux, … GPL v2+ [strong copyleft]
muPDF [mupdf.com] pdfdraw pages .png, .ppm, .pgm, .pam, .pbm Win, Mac, Linux, … GPL v3+ [strong copyleft]; or commercial

Interactive Viewing

Using QtPDF

The QtPDF module includes example PDF viewers which can be adapted and incorporated into Qt Quick or widget-based applications.

Calling an external viewer application

If your application merely needs to let the user view/read certain PDF documents on demand, displaying them within the UI of the application itself might not be necessary, and delegating the task to an existing viewer application can be a viable option.

Many users have already chosen and installed a stand-alone PDF viewer according to their personal preferences, so simply letting the operating system open the PDF file with whatever it considers the default viewer for such files, might be the easiest (and potentially most user-friendly) choice. To do so, simply pass the PDF file's URL to QDesktopServices::openUrl. If you're downloading the file from the Internet, store it on disk using QTemporaryFile first, since not all viewers can handle remote URLs.

Using a third-party Qt widget

The following widgets provide native PDF viewing for Qt applications:

class name platforms license
XpdfWidget/Qt [glyphandcog.com] XpdfWidget Win, Mac, Linux, … commercial

Embedding a third-party ActiveX control

If you are exclusively targeting the Windows platform, you can embed an existing ActiveX component for viewing PDFs in your Qt applications by instantiating it as a QAxWidget (see Qt's ActiveX Framework).

The following PDF viewers provide such an ActiveX control:

DLL file ActiveX control name platforms license
Adobe Reader [get.adobe.com] Acropdf.dll AxAcroPDFLib.AxAcroPDF Win, Mac, Linux, … freeware (for commercial redistribution see here) [adobe.com])

In the case of the Adobe Reader control, opening a PDF file is done with: 

dynamicCall("LoadFile(const QString)", pathToFile)

Embedding a third-party browser plugin

A more cross-platform technology for embedding reusable components is the NPAPI [en.wikipedia.org] browser plugin architecture- which Qt's WebKit-based browser framework happens to support. You'll need to set up a simple HTML page containing appropriate embed>…</embed> tags, and let a QWebView display it (with QWebSettings::PluginsEnabled.

The following applications provide a reusable NPAPI plugin for viewing PDF:

plugin name platforms license
Adobe Reader [get.adobe.com] nppdf Win, Mac, (Linux)¹, … freeware (for commercial redistribution see here [adobe.com])

¹While in theory it should work on all Desktop platforms, application developers have "reported problems":/forums/viewthread/14055 in trying to get it to work with Qt Webkit on Linux.

As an alternative to using QWebView for running the plugin, it is possible to use a third-party solution that allows embedding NPAPI plugins in a Qt application without the overhead of a full web browser instance:

component type has special convenience API for platforms license
QtitanMultimedia [devmachines.com] QWidget Adobe Reader, … Win, Linux commercial

See Also

Retrieved from "https://wiki.qt.io/index.php?title=Handling_PDF&oldid=37043"