#include <poppler-annotation.h>

Inheritance diagram for Poppler::Annotation:

[legend]

Classes
class	Popup

class	Style

Public Types
enum	AdditionalActionType { CursorEnteringAction, CursorLeavingAction, MousePressedAction, MouseReleasedAction, FocusInAction, FocusOutAction, PageOpeningAction, PageClosingAction, PageVisibleAction, PageInvisibleAction }

enum	Flag { Hidden = 1, FixedSize = 2, FixedRotation = 4, DenyPrint = 8, DenyWrite = 16, DenyDelete = 32, ToggleHidingOnMouse = 64, External = 128 }

enum	LineEffect { NoEffect = 1, Cloudy = 2 }

enum	LineStyle { Solid = 1, Dashed = 2, Beveled = 4, Inset = 8, Underline = 16 }

enum	RevScope { Root = 0, Reply = 1, Group = 2, Delete = 4 }

enum	RevType { None = 1, Marked = 2, Unmarked = 4, Accepted = 8, Rejected = 16, Cancelled = 32, Completed = 64 }

enum	SubType { AText = 1, ALine = 2, AGeom = 3, AHighlight = 4, AStamp = 5, AInk = 6, ALink = 7, ACaret = 8, AFileAttachment = 9, ASound = 10, AMovie = 11, AScreen = 12, AWidget = 13, ARichMedia = 14, A_BASE = 0 }

Public Member Functions
QString	author () const

QRectF	boundary () const

QString	contents () const

QDateTime	creationDate () const

int	flags () const

QDateTime	modificationDate () const

Popup	popup () const

QList< Annotation * >	revisions () const

RevScope	revisionScope () const

RevType	revisionType () const

void	setAuthor (const QString &author)

void	setBoundary (const QRectF &boundary)

void	setContents (const QString &contents)

void	setCreationDate (const QDateTime &date)

void	setFlags (int flags)

void	setModificationDate (const QDateTime &date)

void	setPopup (const Popup &popup)

void	setStyle (const Style &style)

void	setUniqueName (const QString &uniqueName)

Style	style () const

virtual SubType	subType () const =0

QString	uniqueName () const

virtual	~Annotation ()

Detailed Description

Annotation class holding properties shared by all annotations.

An Annotation is an object (text note, highlight, sound, popup window, ..) contained by a Page in the document.

Warning: Different Annotation objects might point to the same annotation.

How to add annotations

Create an Annotation object of the desired subclass (for example TextAnnotation) and set its properties:

Poppler::TextAnnotation* myann = new Poppler::TextAnnotation(Poppler::TextAnnotation::InPlace);
myann->setBoundary(QRectF(0.1, 0.1, 0.2, 0.2)); // normalized coordinates: (0,0) is top-left, (1,1) is bottom-right
myann->setContents("Hello, world!");

Note: Always set a boundary rectangle, or nothing will be shown!

Obtain a pointer to the Page where you want to add the annotation (refer to How to use the Poppler Qt5 interface library in three easy steps for instructions) and add the annotation:

Poppler::Page* mypage = ...;

mypage->addAnnotation(myann);

You can keep on editing the annotation after it has been added to the page:

myann->setContents("World, hello!"); // Let's change text...

myann->setAuthor("Your name here"); // ...and set an author too

When you're done with editing the annotation, you must destroy the Annotation object:

delete myann;

Use the PDFConverter class to save the modified document.

FixedRotation flag specifics

According to the PDF specification, annotations whose Annotation::FixedRotation flag is set must always be shown in their original orientation, no matter what the current rendering rotation or the page's Page::orientation() values are. In comparison with regular annotations, such annotations should therefore be transformed by an extra rotation at rendering time to "undo" such context-related rotations, which is equal to -(rendering_rotation + page_orientation). The rotation pivot is the top-left corner of the boundary rectangle.

In practice, Poppler's Page::renderToImage only "unrotates" the page orientation, and does not unrotate the rendering rotation. This ensures consistent renderings at different Page::Rotation values: annotations are always positioned as if they were being positioned at the default page orientation.

Just like regular annotations, Poppler Qt5 exposes normalized coordinates relative to the page's default orientation. However, behind the scenes, the coordinate system is different and Poppler transparently transforms each shape. If you never call either Annotation::setFlags or Annotation::setBoundary, you don't need to worry about this; but if you do call them, then you need to adhere to the following rules:

Whenever you toggle the Annotation::FixedRotation flag, you must set again the boundary rectangle first, and then you must set again any other geometry-related property.
Whenever you modify the boundary rectangle of an annotation whose Annotation::FixedRotation flag is set, you must set again any other geometry-related property.

These two rules are necessary to make Poppler's transparent coordinate conversion work properly.

Member Enumeration Documentation

◆ AdditionalActionType

enum Poppler::Annotation::AdditionalActionType

Describes the flags from an annotations 'AA' dictionary.

This flag is used by the additionalAction() method for ScreenAnnotation and WidgetAnnotation.

Since: 0.22

Enumerator
CursorEnteringAction	Performed when the cursor enters the annotation's active area.
CursorLeavingAction	Performed when the cursor exists the annotation's active area.
MousePressedAction	Performed when the mouse button is pressed inside the annotation's active area.
MouseReleasedAction	Performed when the mouse button is released inside the annotation's active area.
FocusInAction	Performed when the annotation receives the input focus.
FocusOutAction	Performed when the annotation loses the input focus.
PageOpeningAction	Performed when the page containing the annotation is opened.
PageClosingAction	Performed when the page containing the annotation is closed.
PageVisibleAction	Performed when the page containing the annotation becomes visible.
PageInvisibleAction	Performed when the page containing the annotation becomes invisible.

◆ Flag

enum Poppler::Annotation::Flag

Annotation flags.

They can be OR'd together (e.g. Annotation::FixedRotation | Annotation::DenyPrint).

See also: flags(), setFlags(int)

Enumerator

Hidden

Do not display or print the annotation.

FixedRotation

Do not rotate the annotation according to page orientation and rendering rotation.

Warning: Extra care is needed with this flag: see FixedRotation flag specifics

DenyPrint

Do not print the annotation.

◆ SubType

enum Poppler::Annotation::SubType

Annotation subclasses.

See also: subType()

Enumerator
AText	TextAnnotation.
ALine	LineAnnotation.
AGeom	GeomAnnotation.
AHighlight	HighlightAnnotation.
AStamp	StampAnnotation.
AInk	InkAnnotation.
ALink	LinkAnnotation.
ACaret	CaretAnnotation.
AFileAttachment	FileAttachmentAnnotation.
ASound	SoundAnnotation.
AMovie	MovieAnnotation.
AScreen	ScreenAnnotation. Since 0.20
AWidget	WidgetAnnotation. Since 0.22
ARichMedia	RichMediaAnnotation. Since 0.36

Member Function Documentation

◆ boundary()

QRectF Poppler::Annotation::boundary ( ) const

Returns this annotation's boundary rectangle in normalized coordinates.

See also: setBoundary(const QRectF&)

◆ flags()

int Poppler::Annotation::flags ( ) const

Returns this annotation's flags.

See also: Flag, setFlags(int)

◆ popup()

Popup Poppler::Annotation::popup ( ) const

Since: 0.20

◆ revisions()

QList<Annotation*> Poppler::Annotation::revisions ( ) const

Returns the revisions of this annotation.

Note: The caller owns the returned annotations and they should be deleted when no longer required.

Since: 0.20

◆ revisionScope()

RevScope Poppler::Annotation::revisionScope ( ) const

Since: 0.20

◆ revisionType()

RevType Poppler::Annotation::revisionType ( ) const

Since: 0.20

◆ setBoundary()

void Poppler::Annotation::setBoundary ( const QRectF & boundary )

Sets this annotation's boundary rectangle.

The boundary rectangle is the smallest rectangle that contains the annotation.

Warning: This property is mandatory: you must always set this.

See also: boundary(), FixedRotation flag specifics

◆ setFlags()

void Poppler::Annotation::setFlags ( int flags )

Sets this annotation's flags.

See also: Flag, flags(), FixedRotation flag specifics

◆ setPopup()

void Poppler::Annotation::setPopup ( const Popup & popup )

Warning: Currently does nothing

Since: 0.20

◆ setStyle()

void Poppler::Annotation::setStyle ( const Style & style )

Since: 0.20

◆ setUniqueName()

void Poppler::Annotation::setUniqueName ( const QString & uniqueName )

Sets a new unique name for the annotation.

Note: no check of the new uniqueName is done

◆ style()

Style Poppler::Annotation::style ( ) const

Since: 0.20

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

poppler-annotation.h

Classes

Public Types

Public Member Functions