Poppler::Annotation Class Reference

#include <poppler-annotation.h>

Inheritance diagram for Poppler::Annotation:

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
std::unique_ptr< AnnotationAppearance >	annotationAppearance () const
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	setAnnotationAppearance (const AnnotationAppearance &annotationAppearance)
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

annotationAppearance()

std::unique_ptr< AnnotationAppearance > Poppler::Annotation::annotationAppearance

(

)

const

Returns the current appearance stream of this annotation.

Since

21.10.0

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

setAnnotationAppearance()

void Poppler::Annotation::setAnnotationAppearance

(

const AnnotationAppearance &

annotationAppearance

)

Sets the annotation's appearance stream with the annotationAppearance.

Since

21.10.0

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

subType()

virtual SubType Poppler::Annotation::subType ( ) const

pure virtual

The type of the annotation.

Implemented in Poppler::TextAnnotation, Poppler::LineAnnotation, Poppler::GeomAnnotation, Poppler::HighlightAnnotation, Poppler::StampAnnotation, Poppler::InkAnnotation, Poppler::LinkAnnotation, Poppler::CaretAnnotation, Poppler::FileAttachmentAnnotation, Poppler::SoundAnnotation, Poppler::MovieAnnotation, Poppler::ScreenAnnotation, Poppler::WidgetAnnotation, and Poppler::RichMediaAnnotation.

---

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

• poppler-annotation.h