Okular

annotations.h
1 /***************************************************************************
2  * Copyright (C) 2005 by Enrico Ros <[email protected]> *
3  * *
4  * This program is free software; you can redistribute it and/or modify *
5  * it under the terms of the GNU General Public License as published by *
6  * the Free Software Foundation; either version 2 of the License, or *
7  * (at your option) any later version. *
8  ***************************************************************************/
9 
10 #ifndef _OKULAR_ANNOTATIONS_H_
11 #define _OKULAR_ANNOTATIONS_H_
12 
13 #include <QString>
14 #include <QDateTime>
15 #include <QLinkedList>
16 #include <QRect>
17 #include <QFont>
18 #include <QDomDocument>
19 #include <QDomElement>
20 
21 #include "okularcore_export.h"
22 #include "area.h"
23 
24 namespace Okular {
25 
26 class Action;
27 class Annotation;
28 class AnnotationObjectRect;
29 class AnnotationPrivate;
30 class Document;
31 class EmbeddedFile;
32 class Page;
33 class PagePrivate;
34 class Sound;
35 class Movie;
36 class TextAnnotationPrivate;
37 class LineAnnotationPrivate;
38 class GeomAnnotationPrivate;
39 class HighlightAnnotationPrivate;
40 class StampAnnotationPrivate;
41 class InkAnnotationPrivate;
42 class CaretAnnotationPrivate;
43 class FileAttachmentAnnotationPrivate;
44 class SoundAnnotationPrivate;
45 class MovieAnnotationPrivate;
46 class ScreenAnnotationPrivate;
47 class WidgetAnnotationPrivate;
48 class RichMediaAnnotationPrivate;
49 
53 class OKULARCORE_EXPORT AnnotationUtils
54 {
55  public:
61  static Annotation * createAnnotation( const QDomElement & element );
62 
67  static void storeAnnotation( const Annotation * annotation,
68  QDomElement & element, QDomDocument & document );
69 
74  static QDomElement findChildElement( const QDomNode & parentNode,
75  const QString & name );
76 
81  static QRect annotationGeometry( const Annotation * annotation,
82  double scaleX, double scaleY );
83 };
84 
91 class OKULARCORE_EXPORT Annotation
92 {
94  friend class AnnotationObjectRect;
95  friend class Document;
96  friend class DocumentPrivate;
97  friend class ObjectRect;
98  friend class Page;
99  friend class PagePrivate;
101 
102  public:
106  enum SubType
107  {
108  AText = 1,
109  ALine = 2,
110  AGeom = 3,
111  AHighlight = 4,
112  AStamp = 5,
113  AInk = 6,
114  ACaret = 8,
115  AFileAttachment = 9,
116  ASound = 10,
117  AMovie = 11,
118  AScreen = 12,
119  AWidget = 13,
120  ARichMedia = 14,
121  A_BASE = 0
122  };
123 
127  enum Flag
128  {
129  Hidden = 1,
130  FixedSize = 2,
131  FixedRotation = 4,
132  DenyPrint = 8,
133  DenyWrite = 16,
134  DenyDelete = 32,
135  ToggleHidingOnMouse = 64,
136  External = 128,
137  ExternallyDrawn = 256,
138  BeingMoved = 512,
139  BeingResized = 1024
140  };
141 
146  {
147  Solid = 1,
148  Dashed = 2,
149  Beveled = 4,
150  Inset = 8,
151  Underline = 16
152  };
153 
158  {
159  NoEffect = 1,
160  Cloudy = 2
161  };
162 
167  {
168  Reply = 1,
169  Group = 2,
170  Delete = 4
171  };
172 
177  {
178  None = 1,
179  Marked = 2,
180  Unmarked = 4,
181  Accepted = 8,
182  Rejected = 16,
183  Cancelled = 32,
184  Completed = 64
185  };
186 
193  {
202  };
203 
212  typedef void ( * DisposeDataFunction )( const Okular::Annotation * );
213 
217  virtual ~Annotation();
218 
222  void setAuthor( const QString &author );
223 
227  QString author() const;
228 
232  void setContents( const QString &contents );
233 
237  QString contents() const;
238 
242  void setUniqueName( const QString &name );
243 
247  QString uniqueName() const;
248 
254  void setModificationDate( const QDateTime &date );
255 
259  QDateTime modificationDate() const;
260 
266  void setCreationDate( const QDateTime &date );
267 
271  QDateTime creationDate() const;
272 
277  void setFlags( int flags );
278 
283  int flags() const;
284 
288  void setBoundingRectangle( const NormalizedRect &rectangle );
289 
293  NormalizedRect boundingRectangle() const;
294 
301  NormalizedRect transformedBoundingRectangle() const;
302 
308  void translate( const NormalizedPoint &coord );
309 
317  void adjust( const NormalizedPoint & deltaCoord1, const NormalizedPoint & deltaCoord2 );
318 
323  class OKULARCORE_EXPORT Style
324  {
325  public:
329  Style();
330 
334  ~Style();
335 
336  Style( const Style &other );
337  Style& operator=( const Style &other );
338 
342  void setColor( const QColor &color );
343 
347  QColor color() const;
348 
352  void setOpacity( double opacity );
353 
357  double opacity() const;
358 
362  void setWidth( double width );
363 
367  double width() const;
368 
372  void setLineStyle( LineStyle style );
373 
377  LineStyle lineStyle() const;
378 
382  void setXCorners( double xCorners );
383 
387  double xCorners() const;
388 
392  void setYCorners( double yCorners );
393 
397  double yCorners() const;
398 
402  void setMarks( int marks );
403 
407  int marks() const;
408 
412  void setSpaces( int spaces );
413 
417  int spaces() const;
418 
422  void setLineEffect( LineEffect effect );
423 
427  LineEffect lineEffect() const;
428 
432  void setEffectIntensity( double intensity );
433 
437  double effectIntensity() const;
438 
439  private:
440  class Private;
441  Private* const d;
442  };
443 
447  Style & style();
448 
452  const Style & style() const;
453 
458  class OKULARCORE_EXPORT Window
459  {
460  public:
464  Window();
465 
469  ~Window();
470 
471  Window( const Window &other );
472  Window& operator=( const Window &other );
473 
477  void setFlags( int flags );
478 
482  int flags() const;
483 
487  void setTopLeft( const NormalizedPoint &point );
488 
492  NormalizedPoint topLeft() const;
493 
497  void setWidth( int width );
498 
502  int width() const;
503 
507  void setHeight( int height );
508 
512  int height() const;
513 
517  void setTitle( const QString &title );
518 
522  QString title() const;
523 
527  void setSummary( const QString &summary );
528 
532  QString summary() const;
533 
534  private:
535  class Private;
536  Private* const d;
537  };
538 
542  Window & window();
543 
547  const Window & window() const;
548 
553  class Revision
554  {
555  public:
559  Revision();
560 
564  ~Revision();
565 
566  Revision( const Revision &other );
567  Revision& operator=( const Revision &other );
568 
572  void setAnnotation( Annotation *annotation );
573 
577  Annotation *annotation() const;
578 
583  void setScope( RevisionScope scope );
584 
588  RevisionScope scope() const;
589 
594  void setType( RevisionType type );
595 
599  RevisionType type() const;
600 
601  private:
602  class Private;
603  Private* const d;
604  };
605 
609  QLinkedList< Revision > & revisions();
610 
614  const QLinkedList< Revision > & revisions() const;
615 
627  void setNativeId( const QVariant &id );
628 
634  QVariant nativeId() const;
635 
644  void setDisposeDataFunction( DisposeDataFunction func );
645 
651  bool canBeMoved() const;
652 
656  bool canBeResized() const;
657 
663  bool openDialogAfterCreation() const;
664 
668  virtual SubType subType() const = 0;
669 
673  virtual void store( QDomNode & node, QDomDocument & document ) const;
674 
680  QDomNode getAnnotationPropertiesDomNode() const;
681 
687  void setAnnotationProperties( const QDomNode & node );
688 
689  protected:
691  Annotation( AnnotationPrivate &dd );
692  Annotation( AnnotationPrivate &dd, const QDomNode &description );
693  Q_DECLARE_PRIVATE( Annotation )
694  AnnotationPrivate *d_ptr;
696 
697  private:
698  Q_DISABLE_COPY( Annotation )
699 };
700 
709 class OKULARCORE_EXPORT AnnotationProxy
710 {
711  public:
713  {
716  Removal
717  };
718 
719  AnnotationProxy();
720 
724  virtual ~AnnotationProxy();
725 
726  AnnotationProxy(const AnnotationProxy &) = delete;
727  AnnotationProxy &operator=(const AnnotationProxy &) = delete;
728 
732  virtual bool supports( Capability capability ) const = 0;
733 
739  virtual void notifyAddition( Annotation *annotation, int page ) = 0;
740 
749  virtual void notifyModification( const Annotation *annotation, int page, bool appearanceChanged ) = 0;
750 
756  virtual void notifyRemoval( Annotation *annotation, int page ) = 0;
757 };
758 
759 class OKULARCORE_EXPORT TextAnnotation : public Annotation
760 {
761  public:
765  enum TextType
766  {
767  Linked,
768  InPlace
769  };
770 
774  enum InplaceIntent
775  {
776  Unknown,
777  Callout,
778  TypeWriter
779  };
780 
784  TextAnnotation();
785 
789  explicit TextAnnotation( const QDomNode &description );
790 
794  ~TextAnnotation() override;
795 
800  void setTextType( TextType type );
801 
805  TextType textType() const;
806 
810  void setTextIcon( const QString &icon );
811 
815  QString textIcon() const;
816 
820  void setTextFont( const QFont &font );
821 
825  QFont textFont() const;
826 
832  void setTextColor( const QColor &color );
833 
839  QColor textColor() const;
840 
844  void setInplaceAlignment( int alignment );
845 
849  int inplaceAlignment() const;
850 
856  void setInplaceCallout( const NormalizedPoint &point, int index );
857 
863  NormalizedPoint inplaceCallout( int index ) const;
864 
870  NormalizedPoint transformedInplaceCallout( int index ) const;
871 
876  void setInplaceIntent( InplaceIntent intent );
877 
881  InplaceIntent inplaceIntent() const;
882 
886  SubType subType() const override;
887 
891  void store( QDomNode &node, QDomDocument &document ) const override;
892 
893  private:
894  Q_DECLARE_PRIVATE( TextAnnotation )
895  Q_DISABLE_COPY( TextAnnotation )
896 };
897 
898 class OKULARCORE_EXPORT LineAnnotation : public Annotation
899 {
900  public:
904  enum TermStyle
905  {
906  Square,
907  Circle,
908  Diamond,
909  OpenArrow,
910  ClosedArrow,
911  None,
912  Butt,
913  ROpenArrow,
914  RClosedArrow,
915  Slash
916  };
917 
921  enum LineIntent
922  {
923  Unknown,
924  Arrow,
925  Dimension,
926  PolygonCloud
927  };
928 
932  LineAnnotation();
933 
937  explicit LineAnnotation( const QDomNode &description );
938 
942  ~LineAnnotation() override;
943 
947  void setLinePoints( const QLinkedList<NormalizedPoint> &points );
948 
952  QLinkedList<NormalizedPoint> linePoints() const;
953 
958  QLinkedList<NormalizedPoint> transformedLinePoints() const;
959 
964  void setLineStartStyle( TermStyle style );
965 
969  TermStyle lineStartStyle() const;
970 
975  void setLineEndStyle( TermStyle style );
976 
980  TermStyle lineEndStyle() const;
981 
985  void setLineClosed( bool closed );
986 
990  bool lineClosed() const;
991 
995  void setLineInnerColor( const QColor &color );
996 
1000  QColor lineInnerColor() const;
1001 
1005  void setLineLeadingForwardPoint( double point );
1006 
1010  double lineLeadingForwardPoint() const;
1011 
1015  void setLineLeadingBackwardPoint( double point );
1016 
1020  double lineLeadingBackwardPoint() const;
1021 
1025  void setShowCaption( bool shown );
1026 
1030  bool showCaption() const;
1031 
1036  void setLineIntent( LineIntent intent );
1037 
1041  LineIntent lineIntent() const;
1042 
1046  SubType subType() const override;
1047 
1051  void store( QDomNode &node, QDomDocument &document ) const override;
1052 
1053  private:
1054  Q_DECLARE_PRIVATE( LineAnnotation )
1055  Q_DISABLE_COPY( LineAnnotation )
1056 };
1057 
1058 class OKULARCORE_EXPORT GeomAnnotation : public Annotation
1059 {
1060  public:
1061  // common enums
1062  enum GeomType
1063  {
1064  InscribedSquare,
1065  InscribedCircle
1066  };
1067 
1071  GeomAnnotation();
1072 
1076  explicit GeomAnnotation( const QDomNode &description );
1077 
1081  ~GeomAnnotation() override;
1082 
1087  void setGeometricalType( GeomType type );
1088 
1092  GeomType geometricalType() const;
1093 
1097  void setGeometricalInnerColor( const QColor &color );
1098 
1102  QColor geometricalInnerColor() const;
1103 
1107  SubType subType() const override;
1108 
1113  void store( QDomNode &node, QDomDocument &document ) const override;
1114 
1115  private:
1116  Q_DECLARE_PRIVATE( GeomAnnotation )
1117  Q_DISABLE_COPY( GeomAnnotation )
1118 };
1119 
1120 class OKULARCORE_EXPORT HighlightAnnotation : public Annotation
1121 {
1122  public:
1126  enum HighlightType
1127  {
1128  Highlight,
1129  Squiggly,
1130  Underline,
1131  StrikeOut
1132  };
1133 
1137  HighlightAnnotation();
1138 
1142  explicit HighlightAnnotation( const QDomNode &description );
1143 
1147  ~HighlightAnnotation() override;
1148 
1153  void setHighlightType( HighlightType type );
1154 
1158  HighlightType highlightType() const;
1159 
1174  class OKULARCORE_EXPORT Quad
1175  {
1176  public:
1180  Quad();
1181 
1185  ~Quad();
1186 
1187  Quad( const Quad &other );
1188  Quad& operator=( const Quad &other );
1189 
1195  void setPoint( const NormalizedPoint &point, int index );
1196 
1202  NormalizedPoint point( int index ) const;
1203 
1209  NormalizedPoint transformedPoint( int index ) const;
1210 
1214  void setCapStart( bool value );
1215 
1219  bool capStart() const;
1220 
1224  void setCapEnd( bool value );
1225 
1229  bool capEnd() const;
1230 
1234  void setFeather( double width );
1235 
1239  double feather() const;
1240 
1248  void transform( const QTransform &matrix );
1249 
1250  private:
1251  class Private;
1252  Private* const d;
1253  };
1254 
1258  QList< Quad > & highlightQuads();
1259 
1263  SubType subType() const override;
1264 
1269  void store( QDomNode &node, QDomDocument &document ) const override;
1270 
1271  private:
1272  Q_DECLARE_PRIVATE( HighlightAnnotation )
1273  Q_DISABLE_COPY( HighlightAnnotation )
1274 };
1275 
1276 class OKULARCORE_EXPORT StampAnnotation : public Annotation
1277 {
1278  public:
1282  StampAnnotation();
1283 
1287  explicit StampAnnotation( const QDomNode &description );
1288 
1292  ~StampAnnotation() override;
1293 
1297  void setStampIconName( const QString &name );
1298 
1302  QString stampIconName() const;
1303 
1307  SubType subType() const override;
1308 
1313  void store( QDomNode &node, QDomDocument &document ) const override;
1314 
1315  private:
1316  Q_DECLARE_PRIVATE( StampAnnotation )
1317  Q_DISABLE_COPY( StampAnnotation )
1318 };
1319 
1320 class OKULARCORE_EXPORT InkAnnotation : public Annotation
1321 {
1322  public:
1326  InkAnnotation();
1327 
1331  explicit InkAnnotation( const QDomNode &description );
1332 
1336  ~InkAnnotation() override;
1337 
1341  void setInkPaths( const QList< QLinkedList<NormalizedPoint> > &paths );
1342 
1346  QList< QLinkedList<NormalizedPoint> > inkPaths() const;
1347 
1352  QList< QLinkedList<NormalizedPoint> > transformedInkPaths() const;
1353 
1357  SubType subType() const override;
1358 
1363  void store( QDomNode &node, QDomDocument &document ) const override;
1364 
1365  private:
1366  Q_DECLARE_PRIVATE( InkAnnotation )
1367  Q_DISABLE_COPY( InkAnnotation )
1368 };
1369 
1370 class OKULARCORE_EXPORT CaretAnnotation : public Annotation
1371 {
1372  public:
1376  enum CaretSymbol
1377  {
1378  None,
1379  P
1380  };
1381 
1385  CaretAnnotation();
1386 
1390  explicit CaretAnnotation( const QDomNode &description );
1391 
1395  ~CaretAnnotation() override;
1396 
1400  void setCaretSymbol( CaretAnnotation::CaretSymbol symbol );
1401 
1405  CaretAnnotation::CaretSymbol caretSymbol() const;
1406 
1410  SubType subType() const override;
1411 
1416  void store( QDomNode &node, QDomDocument &document ) const override;
1417 
1418  private:
1419  Q_DECLARE_PRIVATE( CaretAnnotation )
1420  Q_DISABLE_COPY( CaretAnnotation )
1421 };
1422 
1423 class OKULARCORE_EXPORT FileAttachmentAnnotation : public Annotation
1424 {
1425  public:
1429  FileAttachmentAnnotation();
1433  explicit FileAttachmentAnnotation( const QDomNode &description );
1437  ~FileAttachmentAnnotation() override;
1438 
1442  QString fileIconName() const;
1443 
1447  void setFileIconName( const QString &iconName );
1448 
1452  EmbeddedFile* embeddedFile() const;
1453 
1458  void setEmbeddedFile( EmbeddedFile *ef );
1459 
1463  SubType subType() const override;
1464 
1469  void store( QDomNode &node, QDomDocument &document ) const override;
1470 
1471  private:
1472  Q_DECLARE_PRIVATE( FileAttachmentAnnotation )
1473  Q_DISABLE_COPY( FileAttachmentAnnotation )
1474 };
1475 
1483 class OKULARCORE_EXPORT SoundAnnotation : public Annotation
1484 {
1485  public:
1489  SoundAnnotation();
1493  explicit SoundAnnotation( const QDomNode &description );
1497  ~SoundAnnotation() override;
1498 
1502  QString soundIconName() const;
1503 
1507  void setSoundIconName( const QString &iconName );
1508 
1512  Sound* sound() const;
1513 
1518  void setSound( Sound *s );
1519 
1523  SubType subType() const override;
1524 
1529  void store( QDomNode &node, QDomDocument &document ) const override;
1530 
1531  private:
1532  Q_DECLARE_PRIVATE( SoundAnnotation )
1533  Q_DISABLE_COPY( SoundAnnotation )
1534 };
1535 
1543 class OKULARCORE_EXPORT MovieAnnotation : public Annotation
1544 {
1545  public:
1549  MovieAnnotation();
1553  explicit MovieAnnotation( const QDomNode &description );
1557  ~MovieAnnotation() override;
1561  Movie* movie() const;
1565  void setMovie( Movie *movie );
1569  SubType subType() const override;
1574  void store( QDomNode &parentNode, QDomDocument &document ) const override;
1575 
1576  private:
1577  Q_DECLARE_PRIVATE( MovieAnnotation )
1578  Q_DISABLE_COPY( MovieAnnotation )
1579 };
1580 
1589 class OKULARCORE_EXPORT ScreenAnnotation : public Annotation
1590 {
1591  public:
1595  ScreenAnnotation();
1596 
1600  explicit ScreenAnnotation( const QDomNode &description );
1601 
1605  ~ScreenAnnotation() override;
1606 
1610  SubType subType() const override;
1611 
1616  void store( QDomNode &parentNode, QDomDocument &document ) const override;
1617 
1623  void setAction( Action *action );
1624 
1630  Action* action() const;
1631 
1637  void setAdditionalAction( AdditionalActionType type, Action *action );
1638 
1644  Action* additionalAction( AdditionalActionType type ) const;
1645 
1646  private:
1647  Q_DECLARE_PRIVATE( ScreenAnnotation )
1648  Q_DISABLE_COPY( ScreenAnnotation )
1649 };
1650 
1658 class OKULARCORE_EXPORT WidgetAnnotation : public Annotation
1659 {
1660  public:
1664  WidgetAnnotation();
1665 
1669  explicit WidgetAnnotation( const QDomNode &description );
1670 
1674  ~WidgetAnnotation() override;
1675 
1679  SubType subType() const override;
1680 
1685  void store( QDomNode &parentNode, QDomDocument &document ) const override;
1686 
1692  void setAdditionalAction( AdditionalActionType type, Action *action );
1693 
1699  Action* additionalAction( AdditionalActionType type ) const;
1700 
1701  private:
1702  Q_DECLARE_PRIVATE( WidgetAnnotation )
1703  Q_DISABLE_COPY( WidgetAnnotation )
1704 };
1705 
1713 class OKULARCORE_EXPORT RichMediaAnnotation : public Annotation
1714 {
1715  public:
1720 
1724  explicit RichMediaAnnotation( const QDomNode &description );
1725 
1729  ~RichMediaAnnotation() override;
1730 
1734  SubType subType() const override;
1735 
1740  void store( QDomNode &parentNode, QDomDocument &document ) const override;
1741 
1745  Movie* movie() const;
1746 
1750  void setMovie( Movie *movie );
1751 
1755  void setEmbeddedFile( EmbeddedFile *embeddedFile );
1756 
1760  EmbeddedFile* embeddedFile() const;
1761 
1762  private:
1763  Q_DECLARE_PRIVATE( RichMediaAnnotation )
1764  Q_DISABLE_COPY( RichMediaAnnotation )
1765 };
1766 
1767 }
1768 
1769 #endif
Performed when the cursor enters the annotation&#39;s active area.
Definition: annotations.h:196
NormalizedPoint is a helper class which stores the coordinates of a normalized point.
Definition: area.h:119
The Revision class contains all information about the revision of the annotation. ...
Definition: annotations.h:553
Performed when the cursor exists the annotation&#39;s active area.
Definition: annotations.h:197
time_t date() const
Performed when the annotation loses the input focus.
Definition: annotations.h:201
A NormalizedRect is a rectangle which can be defined by two NormalizedPoints.
Definition: area.h:192
Native annotation interface.
Definition: annotations.h:709
global.h
Definition: action.h:19
An embedded file into the document.
Definition: document.h:1400
The Window class contains all information about the popup window of the annotation that is used to ed...
Definition: annotations.h:458
RevisionType
Describes the type of revision information.
Definition: annotations.h:176
SubType
Describes the type of annotation as defined in PDF standard.
Definition: annotations.h:106
This class describes the object rectangle for an annotation.
Definition: area.h:553
Performed when the page containing the annotation is opened.
Definition: annotations.h:194
Sound annotation.
Definition: annotations.h:1483
Performed when the mouse button is pressed inside the annotation&#39;s active area.
Definition: annotations.h:198
Generator can edit native annotations.
Definition: annotations.h:715
An area with normalized coordinates that contains a reference to an object.
Definition: area.h:454
Performed when the mouse button is released inside the annotation&#39;s active area.
Definition: annotations.h:199
RichMedia annotation.
Definition: annotations.h:1713
Performed when the annotation receives the input focus.
Definition: annotations.h:200
The Document.
Definition: document.h:192
Collector for all the data belonging to a page.
Definition: page.h:52
RevisionScope
Describes the scope of revision information.
Definition: annotations.h:166
Contains information about a sound object.
Definition: sound.h:26
AdditionalActionType
Describes the type of additional actions.
Definition: annotations.h:192
Encapsulates data that describes an action.
Definition: action.h:43
Movie annotation.
Definition: annotations.h:1543
Annotation struct holds properties shared by all annotations.
Definition: annotations.h:91
Performed when the page containing the annotation is closed.
Definition: annotations.h:195
LineStyle
Describes possible line styles for.
Definition: annotations.h:145
Helper class for (recursive) annotation retrieval/storage.
Definition: annotations.h:53
The Style class contains all information about style of the annotation.
Definition: annotations.h:323
Generator can create native annotations.
Definition: annotations.h:714
Screen annotation.
Definition: annotations.h:1589
LineEffect
Describes possible line effects for.
Definition: annotations.h:157
Flag
Describes additional properties of an annotation.
Definition: annotations.h:127
Describes a highlight quad of a text markup annotation.
Definition: annotations.h:1174
Widget annotation.
Definition: annotations.h:1658
Contains information about a movie object.
Definition: movie.h:28
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Sun May 24 2020 22:48:59 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.