Poppler Qt5  0.74.0
Classes | Public Types | Public Member Functions | List of all members
Poppler::Annotation Class Referenceabstract

#include <poppler-annotation.h>

Inheritance diagram for Poppler::Annotation:
Inheritance graph
[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:

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

Member Enumeration Documentation

◆ 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

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

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: