Poppler Qt5 24.11.0
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
Poppler::Document Class Reference

#include <poppler-qt5.h>

Classes

struct  PdfVersion
 

Public Types

enum  DocumentAdditionalActionsType {
  CloseDocument , SaveDocumentStart , SaveDocumentFinish , PrintDocumentStart ,
  PrintDocumentFinish
}
 
enum  FormType { NoForm , AcroForm , XfaForm }
 
enum  PageLayout {
  NoLayout , SinglePage , OneColumn , TwoColumnLeft ,
  TwoColumnRight , TwoPageLeft , TwoPageRight
}
 
enum  PageMode {
  UseNone , UseOutlines , UseThumbs , FullScreen ,
  UseOC , UseAttach
}
 
enum  RenderBackend { SplashBackend , ArthurBackend , QPainterBackend = ArthurBackend }
 
enum  RenderHint {
  Antialiasing = 0x00000001 , TextAntialiasing = 0x00000002 , TextHinting = 0x00000004 , TextSlightHinting = 0x00000008 ,
  OverprintPreview = 0x00000010 , ThinLineSolid = 0x00000020 , ThinLineShape = 0x00000040 , IgnorePaperColor = 0x00000080 ,
  HideAnnotations = 0x00000100
}
 

Public Member Functions

LinkadditionalAction (DocumentAdditionalActionsType type) const
 
void applyResetFormsLink (const LinkResetForm &link)
 
QString author () const
 
void * colorDisplayProfile () const
 
void * colorRgbProfile () const
 
QDateTime creationDate () const
 
QString creator () const
 
QDateTime date (const QString &type) const
 
QList< EmbeddedFile * > embeddedFiles () const
 
QByteArray fontData (const FontInfo &fi) const
 
QList< FontInfofonts () const
 
QVector< int > formCalculateOrder () const
 
FormType formType () const
 
bool getPdfId (QByteArray *permanentId, QByteArray *updateId) const
 
PdfVersion getPdfVersion () const
 
void getPdfVersion (int *major, int *minor) const
 
bool hasEmbeddedFiles () const
 
bool hasOptionalContent () const
 
QString info (const QString &type) const
 
QStringList infoKeys () const
 
bool isEncrypted () const
 
bool isLinearized () const
 
bool isLocked () const
 
QString keywords () const
 
LinkDestinationlinkDestination (const QString &name)
 
QString metadata () const
 
QDateTime modificationDate () const
 
FontIteratornewFontIterator (int startPage=0) const
 
int numPages () const
 
bool okToAddNotes () const
 
bool okToAssemble () const
 
bool okToChange () const
 
bool okToCopy () const
 
bool okToCreateFormFields () const
 
bool okToExtractForAccessibility () const
 
bool okToFillForm () const
 
bool okToPrint () const
 
bool okToPrintHighRes () const
 
OptContentModeloptionalContentModel ()
 
QVector< OutlineItemoutline () const
 
Pagepage (const QString &label) const
 
Pagepage (int index) const
 
PageLayout pageLayout () const
 
PageMode pageMode () const
 
QColor paperColor () const
 
PDFConverterpdfConverter () const
 
QString producer () const
 
PSConverterpsConverter () const
 
bool removeInfo ()
 
RenderBackend renderBackend () const
 
RenderHints renderHints () const
 
QStringList scripts () const
 
bool setAuthor (const QString &val)
 
void setColorDisplayProfile (void *outputProfileA)
 
void setColorDisplayProfileName (const QString &name)
 
bool setCreationDate (const QDateTime &val)
 
bool setCreator (const QString &val)
 
bool setDate (const QString &key, const QDateTime &val)
 
bool setInfo (const QString &key, const QString &val)
 
bool setKeywords (const QString &val)
 
bool setModificationDate (const QDateTime &val)
 
void setPaperColor (const QColor &color)
 
bool setProducer (const QString &val)
 
void setRenderBackend (RenderBackend backend)
 
void setRenderHint (RenderHint hint, bool on=true)
 
bool setSubject (const QString &val)
 
bool setTitle (const QString &val)
 
void setXRefReconstructedCallback (const std::function< void()> &callback)
 
QVector< FormFieldSignature * > signatures () const
 
QString subject () const
 
Qt::LayoutDirection textDirection () const
 
QString title () const
 
QDomDocument * toc () const
 
bool unlock (const QByteArray &ownerPassword, const QByteArray &userPassword)
 
bool xrefWasReconstructed () const
 
 ~Document ()
 

Static Public Member Functions

static QSet< RenderBackendavailableRenderBackends ()
 
static Documentload (const QString &filePath, const QByteArray &ownerPassword=QByteArray(), const QByteArray &userPassword=QByteArray())
 
static Documentload (QIODevice *device, const QByteArray &ownerPassword=QByteArray(), const QByteArray &userPassword=QByteArray())
 
static DocumentloadFromData (const QByteArray &fileContents, const QByteArray &ownerPassword=QByteArray(), const QByteArray &userPassword=QByteArray())
 

Detailed Description

PDF document.

The Document class represents a PDF document: its pages, and all the global properties, metadata, etc.

Ownership of the returned objects

All the functions that returns class pointers create new object, and the responsibility of those is given to the callee.

The only exception is Page::transition().

Loading

To get a Document, you have to load it via the load() & loadFromData() functions.

In all the functions that have passwords as arguments, they must be Latin1 encoded. If you have a password that is a UTF-8 string, you need to use QString::toLatin1() (or similar) to convert the password first. If you have a UTF-8 character array, consider converting it to a QString first (QString::fromUtf8(), or similar) before converting to Latin1 encoding.

Rendering

To render pages of a document, you have different Document functions to set various options.

Backends

Poppler offers a different backends for rendering the pages. Currently there are two backends (see RenderBackend), but only the Splash engine works well and has been tested.

The available rendering backends can be discovered via availableRenderBackends(). The current rendering backend can be changed using setRenderBackend(). Please note that setting a backend not listed in the available ones will always result in null QImage's.

Color management support

Poppler, if compiled with this support, provides functions to handle color profiles.

To know whether the Poppler version you are using has support for color management, you can query Poppler::isCmsAvailable(). In case it is not available, all the color management-related functions will either do nothing or return null.

Member Enumeration Documentation

◆ DocumentAdditionalActionsType

Describes the flags for additional document actions i.e.

for executing document scripts at different events. This flag is used by additionalAction method to return the particular Link.

Since
24.07
Enumerator
CloseDocument 

Performed before closing the document.

SaveDocumentStart 

Performed before saving the document.

SaveDocumentFinish 

Performed after saving the document.

PrintDocumentStart 

Performed before printing the document.

PrintDocumentFinish 

Performed after printing the document.

◆ FormType

Form types.

Since
0.22
Enumerator
NoForm 

Document doesn't contain forms.

AcroForm 

AcroForm.

XfaForm 

Adobe XML Forms Architecture (XFA), currently unsupported.

◆ PageLayout

The page layout.

Enumerator
NoLayout 

Layout not specified.

SinglePage 

Display a single page.

OneColumn 

Display a single column of pages.

TwoColumnLeft 

Display the pages in two columns, with odd-numbered pages on the left.

TwoColumnRight 

Display the pages in two columns, with odd-numbered pages on the right.

TwoPageLeft 

Display the pages two at a time, with odd-numbered pages on the left.

TwoPageRight 

Display the pages two at a time, with odd-numbered pages on the right.

◆ PageMode

The page mode.

Enumerator
UseNone 

No mode - neither document outline nor thumbnail images are visible.

UseOutlines 

Document outline visible.

UseThumbs 

Thumbnail images visible.

FullScreen 

Fullscreen mode (no menubar, windows controls etc)

UseOC 

Optional content group panel visible.

UseAttach 

Attachments panel visible.

◆ RenderBackend

The render backends available.

Since
0.6
Enumerator
SplashBackend 

Splash backend.

ArthurBackend 
Deprecated:
The old name of the QPainter backend
QPainterBackend 
Since
20.11

◆ RenderHint

The render hints available.

Since
0.6
Enumerator
Antialiasing 

Antialiasing for graphics.

TextAntialiasing 

Antialiasing for text.

TextHinting 

Hinting for text.

Since
0.12.1
TextSlightHinting 

Lighter hinting for text when combined with TextHinting.

Since
0.18
OverprintPreview 

Overprint preview.

Since
0.22
ThinLineSolid 

Enhance thin lines solid.

Since
0.24
ThinLineShape 

Enhance thin lines shape. Wins over ThinLineSolid.

Since
0.24
IgnorePaperColor 

Do not compose with the paper color.

Since
0.35
HideAnnotations 

Do not render annotations.

Since
0.60

Member Function Documentation

◆ additionalAction()

Link * Poppler::Document::additionalAction ( DocumentAdditionalActionsType  type) const

Returns the additional action of the given type for the document or 0 if no action has been defined.

Since
24.07

◆ applyResetFormsLink()

void Poppler::Document::applyResetFormsLink ( const LinkResetForm link)

Resets the form with the details contained in the link.

Since
24.07

◆ availableRenderBackends()

static QSet< RenderBackend > Poppler::Document::availableRenderBackends ( )
static

The available rendering backends.

Since
0.6

◆ colorDisplayProfile()

void * Poppler::Document::colorDisplayProfile ( ) const

Return the current display profile.

Returns
a cmsHPROFILE of the LCMS library.
Note
The returned profile stays a property of poppler and shall NOT be closed by the user. It's existence is guaranteed for as long as this instance of the Document class is not deleted.
Since
0.12

◆ colorRgbProfile()

void * Poppler::Document::colorRgbProfile ( ) const

Return the current RGB profile.

Returns
a cmsHPROFILE of the LCMS library.
Note
The returned profile stays a property of poppler and shall NOT be closed by the user. It's existence is guaranteed for as long as this instance of the Document class is not deleted.
Since
0.12

◆ date()

QDateTime Poppler::Document::date ( const QString &  type) const
   The date associated with the document

   You would use this method with something like:
   \code

QDateTime created = m_doc->date("CreationDate"); QDateTime modified = m_doc->date("ModDate");

The available dates are:

  • CreationDate: the date of creation of the document
  • ModDate: the date of the last change in the document
Parameters
typethe type of date that is required

◆ embeddedFiles()

QList< EmbeddedFile * > Poppler::Document::embeddedFiles ( ) const

The documents embedded within the PDF document.

Note
there are two types of embedded document - this call only accesses documents that are embedded at the document level.

◆ fontData()

QByteArray Poppler::Document::fontData ( const FontInfo fi) const

The font data if the font is an embedded one.

Since
0.10

◆ fonts()

QList< FontInfo > Poppler::Document::fonts ( ) const

The fonts within the PDF document.

This is a shorthand for getting all the fonts at once.

Note
this can take a very long time to run with a large document. You may wish to use a FontIterator if you have more than say 20 pages
See also
newFontIterator()

◆ formCalculateOrder()

QVector< int > Poppler::Document::formCalculateOrder ( ) const

Returns the calculate order for forms (using their id)

Since
0.53

◆ formType()

FormType Poppler::Document::formType ( ) const

Returns the type of forms contained in the document.

Since
0.22

◆ getPdfId()

bool Poppler::Document::getPdfId ( QByteArray *  permanentId,
QByteArray *  updateId 
) const

The PDF identifiers.

Parameters
permanentIdan optional pointer to a variable where store the permanent ID of the document
updateIdan optional pointer to a variable where store the update ID of the document
Returns
whether the document has the IDs
Since
0.16

◆ getPdfVersion() [1/2]

PdfVersion Poppler::Document::getPdfVersion ( ) const

The version of the PDF specification that the document conforms to.

Since
21.08

◆ getPdfVersion() [2/2]

void Poppler::Document::getPdfVersion ( int *  major,
int *  minor 
) const

The version of the PDF specification that the document conforms to.

Parameters
majoran optional pointer to a variable where store the "major" number of the version
minoran optional pointer to a variable where store the "minor" number of the version
Deprecated:
Will be removed in the Qt6 interface. Use the method returning a PdfVersion object instead!
Since
0.12

◆ hasOptionalContent()

bool Poppler::Document::hasOptionalContent ( ) const

Test whether this document has "optional content".

Optional content is used to optionally turn on (display) and turn off (not display) some elements of the document. The most common use of this is for layers in design applications, but it can be used for a range of things, such as not including some content in printing, and displaying content in the appropriate language.

Since
0.8

◆ info()

QString Poppler::Document::info ( const QString &  type) const
   Get specified information associated with the document

   You would use this method with something like:
   \code

QString title = m_doc->info("Title"); QString subject = m_doc->info("Subject");

In addition to Title and Subject, other information that may be available include Author, Keywords, Creator and Producer.

Parameters
typethe information that is required
See also
infoKeys() to get a list of the available keys

◆ isLinearized()

bool Poppler::Document::isLinearized ( ) const

Test if the document is linearised.

In some cases, this is called "fast web view", since it is mostly an optimisation for viewing over the Web.

◆ linkDestination()

LinkDestination * Poppler::Document::linkDestination ( const QString &  name)

Tries to resolve the named destination name.

Note
this operation starts a search through the whole document
Returns
a new LinkDestination object if the named destination was actually found, or NULL otherwise

◆ load() [1/2]

static Document * Poppler::Document::load ( const QString &  filePath,
const QByteArray &  ownerPassword = QByteArray(),
const QByteArray &  userPassword = QByteArray() 
)
static

Load the document from a file on disk.

Parameters
filePaththe name (and path, if required) of the file to load
ownerPasswordthe Latin1-encoded owner password to use in loading the file
userPasswordthe Latin1-encoded user ("open") password to use in loading the file
Returns
the loaded document, or NULL on error
Note
The caller owns the pointer to Document, and this should be deleted when no longer required.
Warning
The returning document may be locked if a password is required to open the file, and one is not provided (as the userPassword).

◆ load() [2/2]

static Document * Poppler::Document::load ( QIODevice *  device,
const QByteArray &  ownerPassword = QByteArray(),
const QByteArray &  userPassword = QByteArray() 
)
static

Load the document from a device.

Parameters
devicethe device of the data to load
ownerPasswordthe Latin1-encoded owner password to use in loading the file
userPasswordthe Latin1-encoded user ("open") password to use in loading the file
Returns
the loaded document, or NULL on error
Note
The caller owns the pointer to Document, and this should be deleted when no longer required.
The ownership of the device stays with the caller.
if the file is on disk it is recommended to use the other load overload since it is less resource intensive
Warning
The returning document may be locked if a password is required to open the file, and one is not provided (as the userPassword).
Since
0.85

◆ loadFromData()

static Document * Poppler::Document::loadFromData ( const QByteArray &  fileContents,
const QByteArray &  ownerPassword = QByteArray(),
const QByteArray &  userPassword = QByteArray() 
)
static

Load the document from memory.

Parameters
fileContentsthe file contents. They are copied so there is no need to keep the byte array around for the full life time of the document.
ownerPasswordthe Latin1-encoded owner password to use in loading the file
userPasswordthe Latin1-encoded user ("open") password to use in loading the file
Returns
the loaded document, or NULL on error
Note
The caller owns the pointer to Document, and this should be deleted when no longer required.
Warning
The returning document may be locked if a password is required to open the file, and one is not provided (as the userPassword).
Since
0.6

◆ metadata()

QString Poppler::Document::metadata ( ) const

Gets the metadata stream contents.

Since
0.6

◆ newFontIterator()

FontIterator * Poppler::Document::newFontIterator ( int  startPage = 0) const

Creates a new FontIterator object for font scanning.

The new iterator can be used for reading the font information of the document, reading page by page.

The caller is responsible for the returned object, ie it should freed it when no more useful.

Parameters
startPagethe initial page from which start reading fonts
See also
fonts()
Since
0.12

◆ okToAssemble()

bool Poppler::Document::okToAssemble ( ) const

Test if the permissions on the document allow it to be "assembled" - insertion, rotation and deletion of pages; or creation of bookmarks and thumbnail images.

Note
this can be true even if okToChange() is false

◆ okToChange()

bool Poppler::Document::okToChange ( ) const

Test if the permissions on the document allow it to be changed.

Note
depending on the type of change, it may be more appropriate to check other properties as well.

◆ okToFillForm()

bool Poppler::Document::okToFillForm ( ) const

Test if the permissions on the document allow interactive form fields (including signature fields) to be completed.

Note
this can be true even if okToAddNotes() is false - this means that only form completion is permitted.

◆ optionalContentModel()

OptContentModel * Poppler::Document::optionalContentModel ( )

Itemviews model for optional content.

The model is owned by the document.

Since
0.8

◆ outline()

QVector< OutlineItem > Poppler::Document::outline ( ) const

Gets the outline of the document.

Returns
a vector of outline items, empty if there are none
Since
0.74

◆ page() [1/2]

Page * Poppler::Document::page ( const QString &  label) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

The intent is that you can pass in a label like "ix" and get the page with that label (which might be in the table of contents), or pass in "1" and get the page that the user expects (which might not be the first page, if there is a title page and a table of contents).

Parameters
labelthe page label

◆ page() [2/2]

Page * Poppler::Document::page ( int  index) const

Get a specified Page.

Note that this follows the PDF standard of being zero based - if you want the first page, then you need an index of zero.

The caller gets the ownership of the returned object.

This function can return nullptr if for some reason the page can't be properly parsed.

Parameters
indexthe page number index
Warning
The Page object returned by this method internally stores a pointer to the document that it was created from. This pointer will go stale if you delete the Document object. Therefore the Document object needs to be kept alive as long as you want to use the Page object.

◆ pageLayout()

PageLayout Poppler::Document::pageLayout ( ) const

The layout that pages should be shown in when the document is first opened.

This basically describes how pages are shown relative to each other.

◆ pageMode()

PageMode Poppler::Document::pageMode ( ) const

The type of mode that should be used by the application when the document is opened.

Note that while this is called page mode, it is really viewer application mode.

◆ paperColor()

QColor Poppler::Document::paperColor ( ) const

The paper color.

The default color is white.

◆ pdfConverter()

PDFConverter * Poppler::Document::pdfConverter ( ) const

Gets a new PDF converter for this document.

The caller gets the ownership of the returned converter.

Since
0.8

◆ psConverter()

PSConverter * Poppler::Document::psConverter ( ) const

Gets a new PS converter for this document.

The caller gets the ownership of the returned converter.

Since
0.6

◆ removeInfo()

bool Poppler::Document::removeInfo ( )

Remove the document's Info dictionary.

Returns
true on success, false on failure

◆ renderBackend()

RenderBackend Poppler::Document::renderBackend ( ) const

The currently set render backend.

The default backend is SplashBackend

Since
0.6

◆ renderHints()

RenderHints Poppler::Document::renderHints ( ) const

The currently set render hints.

Since
0.6

◆ scripts()

QStringList Poppler::Document::scripts ( ) const

Document-level JavaScript scripts.

Returns the list of document level JavaScript scripts to be always executed before any other script.

Since
0.10

◆ setAuthor()

bool Poppler::Document::setAuthor ( const QString &  val)

Set the author of the document to.

Parameters
val
Returns
true on success, false on failure

◆ setColorDisplayProfile()

void Poppler::Document::setColorDisplayProfile ( void *  outputProfileA)

Set a color display profile for the current document.

Parameters
outputProfileAis a cmsHPROFILE of the LCMS library.
Note
This should be called before any rendering happens.
It is assumed that poppler takes over the owernship of the corresponding cmsHPROFILE. In particular, it is no longer the caller's responsibility to close the profile after use.
Since
0.12

◆ setColorDisplayProfileName()

void Poppler::Document::setColorDisplayProfileName ( const QString &  name)

Set a color display profile for the current document.

Parameters
nameis the name of the display profile to set.
Note
This should be called before any rendering happens.
Since
0.12

◆ setCreationDate()

bool Poppler::Document::setCreationDate ( const QDateTime &  val)

Set the creation date of the document to.

Parameters
val
Returns
true on success, false on failure

◆ setCreator()

bool Poppler::Document::setCreator ( const QString &  val)

Set the creator of the document to.

Parameters
val
Returns
true on success, false on failure

◆ setDate()

bool Poppler::Document::setDate ( const QString &  key,
const QDateTime &  val 
)

Set the Info dict date entry specified by.

Parameters
keyto
val
Returns
true on success, false on failure

◆ setInfo()

bool Poppler::Document::setInfo ( const QString &  key,
const QString &  val 
)

Set the value of the document's Info dictionary entry specified by.

Parameters
keyto
val
Returns
true on success, false on failure

◆ setKeywords()

bool Poppler::Document::setKeywords ( const QString &  val)

Set the keywords of the document to.

Parameters
val
Returns
true on success, false on failure

◆ setModificationDate()

bool Poppler::Document::setModificationDate ( const QDateTime &  val)

Set the modification date of the document to.

Parameters
val
Returns
true on success, false on failure

◆ setPaperColor()

void Poppler::Document::setPaperColor ( const QColor &  color)

Sets the paper color.

Parameters
colorthe new paper color

◆ setProducer()

bool Poppler::Document::setProducer ( const QString &  val)

Set the producer of the document to.

Parameters
val
Returns
true on success, false on failure

◆ setRenderBackend()

void Poppler::Document::setRenderBackend ( RenderBackend  backend)

Sets the backend used to render the pages.

Parameters
backendthe new rendering backend
Since
0.6

◆ setRenderHint()

void Poppler::Document::setRenderHint ( RenderHint  hint,
bool  on = true 
)

Sets the render hint .

Note
some hints may not be supported by some rendering backends.
Parameters
onwhether the flag should be added or removed.
Since
0.6

◆ setSubject()

bool Poppler::Document::setSubject ( const QString &  val)

Set the subject of the document to.

Parameters
val
Returns
true on success, false on failure

◆ setTitle()

bool Poppler::Document::setTitle ( const QString &  val)

Set the title of the document to.

Parameters
val
Returns
true on success, false on failure

◆ setXRefReconstructedCallback()

void Poppler::Document::setXRefReconstructedCallback ( const std::function< void()> &  callback)

Sets the document's XRef reconstruction callback, so whenever a XRef table reconstruction happens the callback will get triggered.

Since
21.06

◆ signatures()

QVector< FormFieldSignature * > Poppler::Document::signatures ( ) const

Returns the signatures of this document.

Prefer to use this over getting the signatures for all the pages of the document since there are documents with signatures that don't belong to a given page

Since
0.88

◆ textDirection()

Qt::LayoutDirection Poppler::Document::textDirection ( ) const

The predominant reading order for text as supplied by the document's viewer preferences.

Since
0.26

◆ toc()

QDomDocument * Poppler::Document::toc ( ) const

Gets the table of contents (TOC) of the Document.

The caller is responsible for the returned object.

In the tree the tag name is the 'screen' name of the entry. A tag can have attributes. Here follows the list of tag attributes with meaning:

  • Destination: A string description of the referred destination
  • DestinationName: A 'named reference' to the viewport
  • ExternalFileName: A link to a external filename
  • Open: A bool value that tells whether the subbranch of the item is open or not

Resolving the final destination for each item can be done in the following way:

  • first, checking for 'Destination': if not empty, then a LinkDestination can be constructed straight with it
  • as second step, if the 'DestinationName' is not empty, then the destination can be resolved using linkDestination()

Note also that if 'ExternalFileName' is not emtpy, then the destination refers to that document (and not to the current one).

Returns
the TOC, or NULL if the Document does not have one

◆ unlock()

bool Poppler::Document::unlock ( const QByteArray &  ownerPassword,
const QByteArray &  userPassword 
)

Provide the passwords required to unlock the document.

Parameters
ownerPasswordthe Latin1-encoded owner password to use in loading the file
userPasswordthe Latin1-encoded user ("open") password to use in loading the file

◆ xrefWasReconstructed()

bool Poppler::Document::xrefWasReconstructed ( ) const

Returns whether the document's XRef table has been reconstructed or not.

Since
21.06

The documentation for this class was generated from the following file: