From 8bac4d1e43ce9a4c66fddc8430d7bed2d9aabba1 Mon Sep 17 00:00:00 2001 From: Fabio D'Urso Date: Tue, 25 Jun 2013 20:09:00 +0200 Subject: qt5: Some documentation about annotations * Removed incorrect hint "Use uniqueName to test for Annotation equality": uniqueNames are optional and we don't actually guarantee uniqueness * Added "How to add annotations" and "FixedRotation flag specifics" sections in the Annotation class page * Added links from enum Annotation::SubType items to actual subclasses * Added documentation for annotation flags that are known to work * Added "see also" links between annotation flag and boundary setters/getters * Added warning on Annotation::setPopup to tell that it's currently not implemented --- qt5/src/poppler-annotation.h | 143 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 135 insertions(+), 8 deletions(-) diff --git a/qt5/src/poppler-annotation.h b/qt5/src/poppler-annotation.h index 19f6bd0e..afdca33c 100644 --- a/qt5/src/poppler-annotation.h +++ b/qt5/src/poppler-annotation.h @@ -5,7 +5,7 @@ * Copyright (C) 2010, Philip Lorenz * Copyright (C) 2012, Tobias Koenig * Copyright (C) 2012, Guillermo A. Amaral B. - * Copyright (C) 2012, Fabio D'Urso + * Copyright (C) 2012, 2013 Fabio D'Urso * Copyright (C) 2013, Anthony Granger * Adapting code from * Copyright (C) 2004 by Enrico Ros @@ -102,7 +102,71 @@ class POPPLER_QT5_EXPORT AnnotationUtils * contained by a Page in the document. * * \warning Different Annotation objects might point to the same annotation. - * Use uniqueName to test for Annotation equality + * + * \section annotCreation How to add annotations + * + * Create an Annotation object of the desired subclass (for example + * TextAnnotation) and set its properties: + * @code + * 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!"); + * @endcode + * \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 + * \ref req for instructions) and add the annotation: + * @code + * Poppler::Page* mypage = ...; + * mypage->addAnnotation(myann); + * @endcode + * + * You can keep on editing the annotation after it has been added to the page: + * @code + * myann->setContents("World, hello!"); // Let's change text... + * myann->setAuthor("Your name here"); // ...and set an author too + * @endcode + * + * When you're done with editing the annotation, you must destroy the Annotation + * object: + * @code + * delete myann; + * @endcode + * + * Use the PDFConverter class to save the modified document. + * + * \section annotFixedRotation 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 \ref 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 Qt4 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. */ class POPPLER_QT5_EXPORT Annotation { @@ -112,12 +176,50 @@ class POPPLER_QT5_EXPORT Annotation public: // enum definitions + /** + * Annotation subclasses + * + * \sa subType() + */ // WARNING!!! oKular uses that very same values so if you change them notify the author! - 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 /** \since 0.20 */, AWidget = 13 /** \since 0.22 */, A_BASE = 0 }; - enum Flag { Hidden = 1, FixedSize = 2, FixedRotation = 4, DenyPrint = 8, - DenyWrite = 16, DenyDelete = 32, ToggleHidingOnMouse = 64, External = 128 }; + enum SubType + { + AText = 1, ///< TextAnnotation + ALine = 2, ///< LineAnnotation + AGeom = 3, ///< GeomAnnotation + AHighlight = 4, ///< HighlightAnnotation + AStamp = 5, ///< StampAnnotation + AInk = 6, ///< InkAnnotation + ALink = 7, ///< LinkAnnotation + ACaret = 8, ///< CaretAnnotation + AFileAttachment = 9, ///< FileAttachmentAnnotation + ASound = 10, ///< SoundAnnotation + AMovie = 11, ///< MovieAnnotation + AScreen = 12, ///< ScreenAnnotation \since 0.20 + AWidget = 13, ///< WidgetAnnotation \since 0.22 + A_BASE = 0 + }; + + /** + * Annotation flags + * + * They can be OR'd together (e.g. Annotation::FixedRotation | Annotation::DenyPrint). + * + * \sa flags(), setFlags(int) + */ + // NOTE: Only flags that are known to work are documented + enum Flag + { + Hidden = 1, ///< Do not display or print the annotation + FixedSize = 2, + FixedRotation = 4, ///< Do not rotate the annotation according to page orientation and rendering rotation \warning Extra care is needed with this flag: see \ref annotFixedRotation + DenyPrint = 8, ///< Do not print the annotation + DenyWrite = 16, + DenyDelete = 32, + ToggleHidingOnMouse = 64, + External = 128 + }; + enum LineStyle { Solid = 1, Dashed = 2, Beveled = 4, Inset = 8, Underline = 16 }; enum LineEffect { NoEffect = 1, Cloudy = 2}; enum RevScope { Root = 0 /** \since 0.20 */, Reply = 1, Group = 2, Delete = 4 }; @@ -152,10 +254,35 @@ class POPPLER_QT5_EXPORT Annotation QDateTime creationDate() const; void setCreationDate( const QDateTime &date ); + /** + * Returns this annotation's flags + * + * \sa Flag, setFlags(int) + */ int flags() const; + /** + * Sets this annotation's flags + * + * \sa Flag, flags(), \ref annotFixedRotation + */ void setFlags( int flags ); + /** + * Returns this annotation's boundary rectangle in normalized coordinates + * + * \sa setBoundary(const QRectF&) + */ QRectF boundary() const; + /** + * 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. + * + * \sa boundary(), \ref annotFixedRotation + */ void setBoundary( const QRectF &boundary ); /** @@ -241,7 +368,7 @@ class POPPLER_QT5_EXPORT Annotation /// \since 0.20 Popup popup() const; - /// \since 0.20 + /// \warning Currently does nothing \since 0.20 void setPopup( const Popup& popup ); /// \since 0.20 -- cgit v1.2.3