annotations.h 43.3 KB
Newer Older
1
2
3
4
5
6
7
8
9
/***************************************************************************
 *   Copyright (C) 2005 by Enrico Ros <eros.kde@email.it>                  *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 ***************************************************************************/

10
11
12
#ifndef _OKULAR_ANNOTATIONS_H_
#define _OKULAR_ANNOTATIONS_H_

Yuri Chornoivan's avatar
Yuri Chornoivan committed
13
14
15
#include <QDateTime>
#include <QDomDocument>
#include <QDomElement>
Albert Astals Cid's avatar
Albert Astals Cid committed
16
17
18
19
#include <QFont>
#include <QLinkedList>
#include <QRect>
#include <QString>
20

21
#include "area.h"
Albert Astals Cid's avatar
Albert Astals Cid committed
22
#include "okularcore_export.h"
23

Albert Astals Cid's avatar
Albert Astals Cid committed
24
25
namespace Okular
{
26
class Action;
Enrico Ros's avatar
Enrico Ros committed
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
37
38
39
40
41
class TextAnnotationPrivate;
class LineAnnotationPrivate;
class GeomAnnotationPrivate;
class HighlightAnnotationPrivate;
class StampAnnotationPrivate;
class InkAnnotationPrivate;
42
class CaretAnnotationPrivate;
43
class FileAttachmentAnnotationPrivate;
44
class SoundAnnotationPrivate;
45
class MovieAnnotationPrivate;
46
47
class ScreenAnnotationPrivate;
class WidgetAnnotationPrivate;
48
class RichMediaAnnotationPrivate;
Enrico Ros's avatar
Enrico Ros committed
49
50

/**
Tobias Koenig's avatar
Tobias Koenig committed
51
 * @short Helper class for (recursive) annotation retrieval/storage.
Enrico Ros's avatar
Enrico Ros committed
52
 */
53
class OKULARCORE_EXPORT AnnotationUtils
Enrico Ros's avatar
Enrico Ros committed
54
{
Albert Astals Cid's avatar
Albert Astals Cid committed
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
public:
    /**
     * Restore an annotation (with revisions if needed) from the dom @p element.
     *
     * Returns a pointer to the complete annotation or 0 if element is invalid.
     */
    static Annotation *createAnnotation(const QDomElement &element);

    /**
     * Saves the @p annotation as a child of @p element taking
     * care of saving all revisions if it has any.
     */
    static void storeAnnotation(const Annotation *annotation, QDomElement &element, QDomDocument &document);

    /**
     * Returns the child element with the given @p name from the direct
     * children of @p parentNode or a null element if not found.
     */
    static QDomElement findChildElement(const QDomNode &parentNode, const QString &name);

    /**
     * Returns the geometry of the given @p annotation scaled by
     * @p scaleX and @p scaleY.
     */
    static QRect annotationGeometry(const Annotation *annotation, double scaleX, double scaleY);
Enrico Ros's avatar
Enrico Ros committed
80
};
81
82
83
84
85

/**
 * @short Annotation struct holds properties shared by all annotations.
 *
 * An Annotation is an object (text note, highlight, sound, popup window, ..)
86
 * contained by a Page in the document.
87
 */
88
class OKULARCORE_EXPORT Annotation
Enrico Ros's avatar
Enrico Ros committed
89
{
90
    /// @cond PRIVATE
91
    friend class AnnotationObjectRect;
92
    friend class Document;
93
    friend class DocumentPrivate;
94
    friend class ObjectRect;
95
    friend class Page;
96
    friend class PagePrivate;
97
    /// @endcond
98

Albert Astals Cid's avatar
Albert Astals Cid committed
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
public:
    /**
     * Describes the type of annotation as defined in PDF standard.
     */
    enum SubType {
        AText = 1,           ///< A textual annotation
        ALine = 2,           ///< A line annotation
        AGeom = 3,           ///< A geometrical annotation
        AHighlight = 4,      ///< A highlight annotation
        AStamp = 5,          ///< A stamp annotation
        AInk = 6,            ///< An ink annotation
        ACaret = 8,          ///< A caret annotation
        AFileAttachment = 9, ///< A file attachment annotation
        ASound = 10,         ///< A sound annotation
        AMovie = 11,         ///< A movie annotation
        AScreen = 12,        ///< A screen annotation
        AWidget = 13,        ///< A widget annotation
        ARichMedia = 14,     ///< A rich media annotation
        A_BASE = 0           ///< The annotation base class
    };

    /**
     * Describes additional properties of an annotation.
     */
    enum Flag {
        Hidden = 1,               ///< Is not shown in the document
        FixedSize = 2,            ///< Has a fixed size
        FixedRotation = 4,        ///< Has a fixed rotation
        DenyPrint = 8,            ///< Cannot be printed
        DenyWrite = 16,           ///< Cannot be changed
        DenyDelete = 32,          ///< Cannot be deleted
        ToggleHidingOnMouse = 64, ///< Can be hidden/shown by mouse click
        External = 128,           ///< Is stored external
        ExternallyDrawn = 256,    ///< Is drawn externally (by the generator which provided it) @since 0.10 (KDE 4.4)
        BeingMoved = 512,         ///< Is being moved (mouse drag and drop). If ExternallyDrawn, the generator must not draw it @since 0.15 (KDE 4.9)
        BeingResized = 1024       ///< Is being resized (mouse drag and drop). If ExternallyDrawn, the generator must not draw it @since 1.1.0
    };

    /**
     * Describes possible line styles for @see ALine annotation.
     */
    enum LineStyle {
        Solid = 1,     ///< A solid line
        Dashed = 2,    ///< A dashed line
        Beveled = 4,   ///< A beveled line
        Inset = 8,     ///< An inset line
        Underline = 16 ///< An underline
    };

    /**
     * Describes possible line effects for @see ALine annotation.
     */
    enum LineEffect {
        NoEffect = 1, ///< No effect
        Cloudy = 2    ///< The cloudy effect
    };

    /**
     * Describes the scope of revision information.
     */
    enum RevisionScope {
        Reply = 1, ///< Belongs to a reply
        Group = 2, ///< Belongs to a group
        Delete = 4 ///< Belongs to a deleted paragraph
    };

    /**
     * Describes the type of revision information.
     */
    enum RevisionType {
        None = 1,       ///< Not specified
        Marked = 2,     ///< Is marked
        Unmarked = 4,   ///< Is unmarked
        Accepted = 8,   ///< Has been accepted
        Rejected = 16,  ///< Was rejected
        Cancelled = 32, ///< Has been cancelled
        Completed = 64  ///< Has been completed
    };

    /**
     * Describes the type of additional actions.
     *
     * @since 0.16 (KDE 4.10)
     */
    enum AdditionalActionType {
        PageOpening,    ///< Performed when the page containing the annotation is opened.
        PageClosing,    ///< Performed when the page containing the annotation is closed.
        CursorEntering, ///< Performed when the cursor enters the annotation's active area @since 1.5
        CursorLeaving,  ///< Performed when the cursor exists the annotation's active area @since 1.5
        MousePressed,   ///< Performed when the mouse button is pressed inside the annotation's active area @since 1.5
        MouseReleased,  ///< Performed when the mouse button is released inside the annotation's active area @since 1.5
        FocusIn,        ///< Performed when the annotation receives the input focus @since 1.5
        FocusOut,       ///< Performed when the annotation loses the input focus @since 1.5
    };

    /**
     * A function to be called when the annotation is destroyed.
     *
     * @warning the function must *not* call any virtual function,
     *          nor subcast.
     *
     * @since 0.7 (KDE 4.1)
     */
    typedef void (*DisposeDataFunction)(const Okular::Annotation *);

    /**
     * Destroys the annotation.
     */
    virtual ~Annotation();

    /**
     * Sets the @p author of the annotation.
     */
    void setAuthor(const QString &author);

    /**
     * Returns the author of the annotation.
     */
    QString author() const;

    /**
     * Sets the @p contents of the annotation.
     */
    void setContents(const QString &contents);

    /**
     * Returns the contents of the annotation.
     */
    QString contents() const;

    /**
     * Sets the unique @p name of the annotation.
     */
    void setUniqueName(const QString &name);

    /**
     * Returns the unique name of the annotation.
     */
    QString uniqueName() const;

    /**
     * Sets the last modification @p date of the annotation.
     *
     * The date must be before or equal to QDateTime::currentDateTime()
     */
    void setModificationDate(const QDateTime &date);

    /**
     * Returns the last modification date of the annotation.
     */
    QDateTime modificationDate() const;

    /**
     * Sets the creation @p date of the annotation.
     *
     * The date must be before or equal to @see modificationDate()
     */
    void setCreationDate(const QDateTime &date);

    /**
     * Returns the creation date of the annotation.
     */
    QDateTime creationDate() const;

    /**
     * Sets the @p flags of the annotation.
     * @see @ref Flag
     */
    void setFlags(int flags);

    /**
     * Returns the flags of the annotation.
     * @see @ref Flag
     */
    int flags() const;

    /**
     * Sets the bounding @p rectangle of the annotation.
     */
    void setBoundingRectangle(const NormalizedRect &rectangle);

    /**
     * Returns the bounding rectangle of the annotation.
     */
    NormalizedRect boundingRectangle() const;

    /**
     * Returns the transformed bounding rectangle of the annotation.
     *
     * This rectangle must be used when showing annotations on screen
     * to have them rotated correctly.
     */
    NormalizedRect transformedBoundingRectangle() const;

    /**
     * Move the annotation by the specified coordinates.
     *
     * @see canBeMoved()
     */
    void translate(const NormalizedPoint &coord);

    /**
     * Adjust the annotation by the specified coordinates.
     * Adds coordinates of @p deltaCoord1 to annotations top left corner,
     * and @p deltaCoord2 to the bottom right.
     *
     * @see canBeResized()
     */
    void adjust(const NormalizedPoint &deltaCoord1, const NormalizedPoint &deltaCoord2);

    /**
     * The Style class contains all information about style of the
     * annotation.
     */
    class OKULARCORE_EXPORT Style
    {
315
316
    public:
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
317
         * Creates a new style.
318
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
319
        Style();
320
321

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
322
         * Destroys the style.
323
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
324
        ~Style();
325

Albert Astals Cid's avatar
Albert Astals Cid committed
326
327
        Style(const Style &other);
        Style &operator=(const Style &other);
328
329

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
330
         * Sets the @p color of the style.
331
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
332
        void setColor(const QColor &color);
333
334

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
335
         * Returns the color of the style.
336
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
337
        QColor color() const;
338
339

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
340
         * Sets the @p opacity of the style.
341
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
342
        void setOpacity(double opacity);
343

344
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
345
         * Returns the opacity of the style.
346
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
347
        double opacity() const;
348

349
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
350
         * Sets the @p width of the style.
351
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
352
        void setWidth(double width);
353

354
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
355
         * Returns the width of the style.
356
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
357
        double width() const;
358
359

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
360
         * Sets the line @p style of the style.
361
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
362
        void setLineStyle(LineStyle style);
363
364

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
365
         * Returns the line style of the style.
366
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
367
        LineStyle lineStyle() const;
368
369

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
370
         * Sets the x-corners of the style.
371
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
372
        void setXCorners(double xCorners);
373
374

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
375
         * Returns the x-corners of the style.
376
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
377
        double xCorners() const;
378
379

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
380
         * Sets the y-corners of the style.
381
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
382
        void setYCorners(double yCorners);
383
384

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
385
         * Returns the y-corners of the style.
386
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
387
        double yCorners() const;
388
389

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
390
         * Sets the @p marks of the style.
391
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
392
        void setMarks(int marks);
393
394

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
395
         * Returns the marks of the style.
396
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
397
        int marks() const;
398
399

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
400
         * Sets the @p spaces of the style.
401
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
402
        void setSpaces(int spaces);
403
404

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
405
         * Returns the spaces of the style.
406
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
407
        int spaces() const;
408
409

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
410
         * Sets the line @p effect of the style.
411
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
412
        void setLineEffect(LineEffect effect);
413
414

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
415
         * Returns the line effect of the style.
416
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
417
        LineEffect lineEffect() const;
418
419

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
420
         * Sets the effect @p intensity of the style.
421
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
422
        void setEffectIntensity(double intensity);
423
424

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
425
         * Returns the effect intensity of the style.
426
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
427
        double effectIntensity() const;
428

Albert Astals Cid's avatar
Albert Astals Cid committed
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
    private:
        class Private;
        Private *const d;
    };

    /**
     * Returns a reference to the style object of the annotation.
     */
    Style &style();

    /**
     * Returns a const reference to the style object of the annotation.
     */
    const Style &style() const;

    /**
     * The Window class contains all information about the popup window
     * of the annotation that is used to edit the content and properties.
     */
    class OKULARCORE_EXPORT Window
    {
    public:
451
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
452
         * Creates a new window.
453
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
454
        Window();
455

456
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
457
         * Destroys the window.
458
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
459
460
461
462
        ~Window();

        Window(const Window &other);
        Window &operator=(const Window &other);
463

464
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
465
         * Sets the @p flags of the window.
466
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
467
        void setFlags(int flags);
468

469
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
470
         * Returns the flags of the window.
471
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
472
        int flags() const;
473
474

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
475
         * Sets the top-left @p point of the window.
476
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
477
        void setTopLeft(const NormalizedPoint &point);
478
479

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
480
         * Returns the top-left point of the window.
481
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
482
        NormalizedPoint topLeft() const;
483
484

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
485
         * Sets the @p width of the window.
486
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
487
        void setWidth(int width);
488
489

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
490
         * Returns the width of the window.
491
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
492
        int width() const;
493
494

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
495
         * Sets the @p height of the window.
496
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
497
        void setHeight(int height);
498
499

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
500
         * Returns the height of the window.
501
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
502
        int height() const;
503
504

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
505
         * Sets the @p title of the window.
506
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
507
        void setTitle(const QString &title);
508
509

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
510
         * Returns the title of the window.
511
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
512
        QString title() const;
513

514
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
515
         * Sets the @p summary of the window.
516
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
517
        void setSummary(const QString &summary);
518
519

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
520
         * Returns the summary of the window.
521
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
522
        QString summary() const;
523

Albert Astals Cid's avatar
Albert Astals Cid committed
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
    private:
        class Private;
        Private *const d;
    };

    /**
     * Returns a reference to the window object of the annotation.
     */
    Window &window();

    /**
     * Returns a const reference to the window object of the annotation.
     */
    const Window &window() const;

    /**
     * The Revision class contains all information about the revision
     * of the annotation.
     */
543
    class OKULARCORE_EXPORT Revision
Albert Astals Cid's avatar
Albert Astals Cid committed
544
545
    {
    public:
546
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
547
         * Creates a new revision.
548
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
549
        Revision();
550

551
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
552
         * Destroys the revision.
553
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
554
555
556
557
        ~Revision();

        Revision(const Revision &other);
        Revision &operator=(const Revision &other);
558

559
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
560
         * Sets the @p annotation the revision belongs to.
561
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
562
        void setAnnotation(Annotation *annotation);
563

564
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
565
         * Returns the annotation the revision belongs to.
566
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
567
        Annotation *annotation() const;
568

569
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
570
571
         * Sets the @p scope of the revision.
         * @see RevisionScope
572
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
573
        void setScope(RevisionScope scope);
574
575

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
576
         * Returns the scope of the revision.
577
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
578
        RevisionScope scope() const;
579

580
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
581
582
         * Sets the @p type of the revision.
         * @see RevisionType
Albert Astals Cid's avatar
Albert Astals Cid committed
583
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
584
        void setType(RevisionType type);
585
586

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
587
         * Returns the type of the revision.
Albert Astals Cid's avatar
Albert Astals Cid committed
588
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
589
        RevisionType type() const;
590

591
    private:
Albert Astals Cid's avatar
Albert Astals Cid committed
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
        class Private;
        Private *const d;
    };

    /**
     * Returns a reference to the revision list of the annotation.
     */
    QLinkedList<Revision> &revisions();

    /**
     * Returns a reference to the revision list of the annotation.
     */
    const QLinkedList<Revision> &revisions() const;

    /**
     * Sets the "native" @p id of the annotation.
     *
     * This is for use of the Generator, that can optionally store an
     * handle (a pointer, an identifier, etc) of the "native" annotation
     * object, if any.
     *
     * @note Okular makes no use of this
     *
     * @since 0.7 (KDE 4.1)
     */
    void setNativeId(const QVariant &id);

    /**
     * Returns the "native" id of the annotation.
     *
     * @since 0.7 (KDE 4.1)
     */
    QVariant nativeId() const;

    /**
     * Sets a function to be called when the annotation is destroyed.
     *
     * @warning the function must *not* call any virtual function,
     *          nor subcast.
     *
     * @since 0.7 (KDE 4.1)
     */
    void setDisposeDataFunction(DisposeDataFunction func);

    /**
     * Returns whether the annotation can be moved.
     *
     * @since 0.7 (KDE 4.1)
     */
    bool canBeMoved() const;

    /**
     * Returns whether the annotation can be resized.
     */
    bool canBeResized() const;

    /**
     * Returns whether the annotation dialog should be open after creation of the annotation or not
     *
     * @since 0.13 (KDE 4.7)
     */
    bool openDialogAfterCreation() const;

    /**
     * Returns the sub type of the annotation.
     */
    virtual SubType subType() const = 0;

    /**
     * Stores the annotation as xml in @p document under the given parent @p node.
     */
    virtual void store(QDomNode &node, QDomDocument &document) const;

    /**
     * Retrieve the QDomNode representing this annotation's properties

     * @since 0.17 (KDE 4.11)
     */
    QDomNode getAnnotationPropertiesDomNode() const;

    /**
     * Sets annotations internal properties according to the contents of @p node
     *
     * @since 0.17 (KDE 4.11)
     */
    void setAnnotationProperties(const QDomNode &node);

protected:
    /// @cond PRIVATE
    Annotation(AnnotationPrivate &dd);
    Annotation(AnnotationPrivate &dd, const QDomNode &description);
    Q_DECLARE_PRIVATE(Annotation)
    AnnotationPrivate *d_ptr;
    /// @endcond

private:
    Q_DISABLE_COPY(Annotation)
689
690
};

691
692
693
694
695
696
697
698
/**
 * @short Native annotation interface
 *
 * Generators can subclass it to provide native annotation support.
 * Generators can use Annotation::setNativeId to store per-annotation data.
 *
 * @since 0.15 (KDE 4.9)
 */
699
class OKULARCORE_EXPORT AnnotationProxy
700
{
Albert Astals Cid's avatar
Albert Astals Cid committed
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
public:
    enum Capability {
        Addition,     ///< Generator can create native annotations
        Modification, ///< Generator can edit native annotations
        Removal       ///< Generator can remove native annotations
    };

    AnnotationProxy();

    /**
     * Destroys the annotation proxy.
     */
    virtual ~AnnotationProxy();

    AnnotationProxy(const AnnotationProxy &) = delete;
    AnnotationProxy &operator=(const AnnotationProxy &) = delete;

    /**
     * Query for the supported capabilities.
     */
    virtual bool supports(Capability capability) const = 0;

    /**
     * Called when a new @p annotation is added to a @p page.
     *
     * @note Only called if supports(Addition) == true
     */
    virtual void notifyAddition(Annotation *annotation, int page) = 0;

    /**
     * Called after an existing @p annotation at a given @p page is modified.
     *
     * Generator can call @p annotation getters to get the new values.
     * @p appearanceChanged tells if a non-visible property was modified
     *
     * @note Only called if supports(Modification) == true
     */
    virtual void notifyModification(const Annotation *annotation, int page, bool appearanceChanged) = 0;

    /**
     * Called when an existing @p annotation at a given @p page is removed.
     *
     * @note Only called if supports(Removal) == true
     */
    virtual void notifyRemoval(Annotation *annotation, int page) = 0;
746
747
};

748
class OKULARCORE_EXPORT TextAnnotation : public Annotation
Tobias Koenig's avatar
Tobias Koenig committed
749
{
Albert Astals Cid's avatar
Albert Astals Cid committed
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
public:
    /**
     * Describes the type of the text.
     */
    enum TextType {
        Linked, ///< The annotation is linked to a text
        InPlace ///< The annotation is located next to the text
    };

    /**
     * Describes the style of the text.
     */
    enum InplaceIntent {
        Unknown,   ///< Unknown style
        Callout,   ///< Callout style
        TypeWriter ///< Type writer style
    };

    /**
     * Creates a new text annotation.
     */
    TextAnnotation();

    /**
     * Creates a new text annotation from the xml @p description
     */
    explicit TextAnnotation(const QDomNode &description);

    /**
     * Destroys the text annotation.
     */
    ~TextAnnotation() override;

    /**
     * Sets the text @p type of the text annotation.
     * @see TextType
     */
    void setTextType(TextType type);

    /**
     * Returns the text type of the text annotation.
     */
    TextType textType() const;

    /**
     * Sets the @p icon of the text annotation.
     */
    void setTextIcon(const QString &icon);

    /**
     * Returns the icon of the text annotation.
     */
    QString textIcon() const;

    /**
     * Sets the @p font of the text annotation.
     */
    void setTextFont(const QFont &font);

    /**
     * Returns the font of the text annotation.
     */
    QFont textFont() const;

    /**
     * Sets the @p color of inplace text.
     *
     * @since 1.6
     */
    void setTextColor(const QColor &color);

    /**
     * Returns the color of inplace text.
     *
     * @since 1.6
     */
    QColor textColor() const;

    /**
     * Sets the inplace @p alignment of the text annotation.
830
     * 0:left, 1:center, 2:right
Albert Astals Cid's avatar
Albert Astals Cid committed
831
832
833
834
835
     */
    void setInplaceAlignment(int alignment);

    /**
     * Returns the inplace alignment of the text annotation.
836
     * 0:left, 1:center, 2:right
Albert Astals Cid's avatar
Albert Astals Cid committed
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
     */
    int inplaceAlignment() const;

    /**
     * Sets the inplace callout @p point at @p index.
     *
     * @p index must be between 0 and 2.
     */
    void setInplaceCallout(const NormalizedPoint &point, int index);

    /**
     * Returns the inplace callout point for @p index.
     *
     * @p index must be between 0 and 2.
     */
    NormalizedPoint inplaceCallout(int index) const;

    /**
     * Returns the transformed (e.g. rotated) inplace callout point for @p index.
     *
     * @p index must be between 0 and 2.
     */
    NormalizedPoint transformedInplaceCallout(int index) const;

    /**
     * Returns the inplace @p intent of the text annotation.
     * @see InplaceIntent
     */
    void setInplaceIntent(InplaceIntent intent);

    /**
     * Returns the inplace intent of the text annotation.
     */
    InplaceIntent inplaceIntent() const;

    /**
     * Returns the sub type of the text annotation.
     */
    SubType subType() const override;

    /**
     * Stores the text annotation as xml in @p document under the given parent @p node.
     */
    void store(QDomNode &node, QDomDocument &document) const override;

private:
    Q_DECLARE_PRIVATE(TextAnnotation)
    Q_DISABLE_COPY(TextAnnotation)
885
886
};

887
class OKULARCORE_EXPORT LineAnnotation : public Annotation
Enrico Ros's avatar
Enrico Ros committed
888
{
Albert Astals Cid's avatar
Albert Astals Cid committed
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
public:
    /**
     * Describes the line ending style.
     */
    enum TermStyle {
        Square,       ///< Using a square
        Circle,       ///< Using a circle
        Diamond,      ///< Using a diamond
        OpenArrow,    ///< Using an open arrow
        ClosedArrow,  ///< Using a closed arrow
        None,         ///< No special ending style
        Butt,         ///< Using a butt ending
        ROpenArrow,   ///< Using an arrow opened at the right side
        RClosedArrow, ///< Using an arrow closed at the right side
        Slash         ///< Using a slash
    };

    /**
     * Describes the line intent.
     */
    enum LineIntent {
        Unknown,     ///< Unknown intent
        Arrow,       ///< Arrow intent
        Dimension,   ///< Dimension intent
        PolygonCloud ///< Polygon cloud intent
    };

    /**
     * Creates a new line annotation.
     */
    LineAnnotation();

    /**
     * Creates a new line annotation from the xml @p description
     */
    explicit LineAnnotation(const QDomNode &description);

    /**
     * Destroys the line annotation.
     */
    ~LineAnnotation() override;

    /**
     * Sets the normalized line @p points of the line annotation.
     */
    void setLinePoints(const QLinkedList<NormalizedPoint> &points);

    /**
     * Returns the normalized line points of the line annotation.
     */
    QLinkedList<NormalizedPoint> linePoints() const;

    /**
     * Returns the transformed (e.g. rotated) normalized line points
     * of the line annotation.
     */
    QLinkedList<NormalizedPoint> transformedLinePoints() const;

    /**
     * Sets the line starting @p style of the line annotation.
     * @see TermStyle
     */
    void setLineStartStyle(TermStyle style);

    /**
     * Returns the line starting style of the line annotation.
     */
    TermStyle lineStartStyle() const;

    /**
     * Sets the line ending @p style of the line annotation.
     * @see TermStyle
     */
    void setLineEndStyle(TermStyle style);

    /**
     * Returns the line ending style of the line annotation.
     */
    TermStyle lineEndStyle() const;

    /**
     * Sets whether the line shall be @p closed.
     */
    void setLineClosed(bool closed);

    /**
     * Returns whether the line shall be closed.
     */
    bool lineClosed() const;

    /**
     * Sets the inner line @p color of the line annotation.
     */
    void setLineInnerColor(const QColor &color);

    /**
     * Returns the inner line color of the line annotation.
     */
    QColor lineInnerColor() const;

    /**
     * Sets the leading forward @p point of the line annotation.
     */
    void setLineLeadingForwardPoint(double point);

    /**
     * Returns the leading forward point of the line annotation.
     */
    double lineLeadingForwardPoint() const;

    /**
     * Sets the leading backward @p point of the line annotation.
     */
    void setLineLeadingBackwardPoint(double point);

    /**
     * Returns the leading backward point of the line annotation.
     */
    double lineLeadingBackwardPoint() const;

    /**
     * Sets whether the caption shall be @p shown.
     */
    void setShowCaption(bool shown);

    /**
     * Returns whether the caption shall be shown.
     */
    bool showCaption() const;

    /**
     * Sets the line @p intent of the line annotation.
     * @see LineIntent
     */
    void setLineIntent(LineIntent intent);

    /**
     * Returns the line intent of the line annotation.
     */
    LineIntent lineIntent() const;

    /**
     * Returns the sub type of the line annotation.
     */
    SubType subType() const override;

    /**
     * Stores the line annotation as xml in @p document under the given parent @p node.
     */
    void store(QDomNode &node, QDomDocument &document) const override;

private:
    Q_DECLARE_PRIVATE(LineAnnotation)
    Q_DISABLE_COPY(LineAnnotation)
1043
1044
};

1045
class OKULARCORE_EXPORT GeomAnnotation : public Annotation
Enrico Ros's avatar
Enrico Ros committed
1046
{
Albert Astals Cid's avatar
Albert Astals Cid committed
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
public:
    // common enums
    enum GeomType {
        InscribedSquare, ///< Draw a square
        InscribedCircle  ///< Draw a circle
    };

    /**
     * Creates a new geometrical annotation.
     */
    GeomAnnotation();

    /**
     * Creates a new geometrical annotation from the xml @p description
     */
    explicit GeomAnnotation(const QDomNode &description);

    /**
     * Destroys the geometrical annotation.
     */
    ~GeomAnnotation() override;

    /**
     * Sets the geometrical @p type of the geometrical annotation.
     * @see GeomType
     */
    void setGeometricalType(GeomType type);

    /**
     * Returns the geometrical type of the geometrical annotation.
     */
    GeomType geometricalType() const;

    /**
     * Sets the inner @p color of the geometrical annotation.
     */
    void setGeometricalInnerColor(const QColor &color);

    /**
     * Returns the inner color of the geometrical annotation.
     */
    QColor geometricalInnerColor() const;

    /**
     * Returns the sub type of the geometrical annotation.
     */
    SubType subType() const override;

    /**
     * Stores the geometrical annotation as xml in @p document
     * under the given parent @p node.
     */
    void store(QDomNode &node, QDomDocument &document) const override;

private:
    Q_DECLARE_PRIVATE(GeomAnnotation)
    Q_DISABLE_COPY(GeomAnnotation)
1104
1105
};

1106
class OKULARCORE_EXPORT HighlightAnnotation : public Annotation
Enrico Ros's avatar
Enrico Ros committed
1107
{
Albert Astals Cid's avatar
Albert Astals Cid committed
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
public:
    /**
     * Describes the highlighting style of the annotation.
     */
    enum HighlightType {
        Highlight, ///< Highlights the text
        Squiggly,  ///< Squiggles the text
        Underline, ///< Underlines the text
        StrikeOut  ///< Strikes out the text
    };

    /**
     * Creates a new highlight annotation.
     */
    HighlightAnnotation();

    /**
     * Creates a new highlight annotation from the xml @p description
     */
    explicit HighlightAnnotation(const QDomNode &description);

    /**
     * Destroys the highlight annotation.
     */
    ~HighlightAnnotation() override;

    /**
     * Sets the @p type of the highlight annotation.
     * @see HighlightType
     */
    void setHighlightType(HighlightType type);

    /**
     * Returns the type of the highlight annotation.
     */
    HighlightType highlightType() const;

    /**
     * @short Describes a highlight quad of a text markup annotation.
     *
     * The Quad is a closed path of 4 NormalizedPoints.
     * Another set of 4 NormalizedPoints can be generated with transform(),
     * e. g. to get highlighting coordinates on a rotated PageViewItem.
     * Additionally, Quad stores some geometry related style attributes.
     *
     * To enable correct rendering of the annotation,
     * the points 0 and 1 must describe the bottom edge of the quad
     * (relative to the text orientation).
     *
     * @see NormalizedPoint
     */
    class OKULARCORE_EXPORT Quad
    {
Tobias Koenig's avatar
Tobias Koenig committed
1161
1162
    public:
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
1163
         * Creates a new quad.
Tobias Koenig's avatar
Tobias Koenig committed
1164
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
1165
        Quad();
Tobias Koenig's avatar
Tobias Koenig committed
1166
1167

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
1168
         * Destroys the quad.
Tobias Koenig's avatar
Tobias Koenig committed
1169
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
1170
        ~Quad();
Tobias Koenig's avatar
Tobias Koenig committed
1171

Albert Astals Cid's avatar
Albert Astals Cid committed
1172
1173
        Quad(const Quad &other);
        Quad &operator=(const Quad &other);
Tobias Koenig's avatar
Tobias Koenig committed
1174
1175

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
1176
         * Sets the normalized @p point at @p index.
1177
         *
Albert Astals Cid's avatar
Albert Astals Cid committed
1178
         * @p index must be between 0 and 3.
Tobias Koenig's avatar
Tobias Koenig committed
1179
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
1180
        void setPoint(const NormalizedPoint &point, int index);
Tobias Koenig's avatar
Tobias Koenig committed
1181
1182

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
1183
1184
1185
         * Returns the normalized point at @p index.
         *
         * @p index must be between 0 and 3.
Tobias Koenig's avatar
Tobias Koenig committed
1186
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
1187
        NormalizedPoint point(int index) const;
Tobias Koenig's avatar
Tobias Koenig committed
1188
1189

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
1190
1191
1192
         * Returns the transformed (e.g. rotated) normalized point at @p index.
         *
         * @p index must be between 0 and 3.
Tobias Koenig's avatar
Tobias Koenig committed
1193
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
1194
        NormalizedPoint transformedPoint(int index) const;
Tobias Koenig's avatar
Tobias Koenig committed
1195
1196

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
1197
         * Sets whether a cap should be used at the start.
Tobias Koenig's avatar
Tobias Koenig committed
1198
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
1199
        void setCapStart(bool value);
1200

Tobias Koenig's avatar
Tobias Koenig committed
1201
        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
1202
         * Returns whether a cap should be used at the start.
Tobias Koenig's avatar
Tobias Koenig committed
1203
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
1204
        bool capStart() const;
Tobias Koenig's avatar
Tobias Koenig committed
1205
1206

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
1207
         * Sets whether a cap should be used at the end.
Tobias Koenig's avatar
Tobias Koenig committed
1208
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
1209
        void setCapEnd(bool value);
Tobias Koenig's avatar
Tobias Koenig committed
1210
1211

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
1212
         * Returns whether a cap should be used at the end.
Tobias Koenig's avatar
Tobias Koenig committed
1213
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
1214
        bool capEnd() const;
Tobias Koenig's avatar
Tobias Koenig committed
1215
1216

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
1217
         * Sets the @p width of the drawing feather.
Tobias Koenig's avatar
Tobias Koenig committed
1218
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
1219
        void setFeather(double width);
Tobias Koenig's avatar
Tobias Koenig committed
1220
1221

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
1222
         * Returns the width of the drawing feather.
Tobias Koenig's avatar
Tobias Koenig committed
1223
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
1224
        double feather() const;
Tobias Koenig's avatar
Tobias Koenig committed
1225
1226

        /**
Albert Astals Cid's avatar
Albert Astals Cid committed
1227
1228
1229
1230
1231
         * Transforms the quad coordinates with the transformation defined
         * by @p matrix.
         *
         * The transformed coordinates will be accessible with transformedPoint().
         * The coordinates returned by point() are not affected.
Tobias Koenig's avatar
Tobias Koenig committed
1232
         */
Albert Astals Cid's avatar
Albert Astals Cid committed
1233
        void transform(const QTransform &matrix);
Tobias Koenig's avatar
Tobias Koenig committed
1234
1235

    private:
Albert Astals Cid's avatar
Albert Astals Cid committed
1236
1237
1238
1239
1240
1241
1242
1243
1244
        class Private;
        Private *const d;
    };

    /**
     * Returns a reference to the quad list of the highlight annotation.
     */
    QList<Quad> &highlightQuads();

1245
1246
1247
1248
1249
1250
    /**
     * Returns a const reference to the quad list of the highlight annotation.
     * @since 20.12
     */
    const QList<Quad> &highlightQuads() const;

Albert Astals Cid's avatar
Albert Astals Cid committed
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
    /**
     * Returns the sub type of the highlight annotation.
     */
    SubType subType() const override;

    /**
     * Stores the highlight annotation as xml in @p document
     * under the given parent @p node.
     */
    void store(QDomNode &node, QDomDocument &document) const override;

private:
    Q_DECLARE_PRIVATE(HighlightAnnotation)
    Q_DISABLE_COPY(HighlightAnnotation)
1265
1266
};

Albert Astals Cid's avatar
Albert Astals Cid committed
1267
class OKULARCORE_EXPORT StampAnnotation : public Annotation
Enrico Ros's avatar
Enrico Ros committed
1268
{
Albert Astals Cid's avatar
Albert Astals Cid committed
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
public:
    /**
     * Creates a new stamp annotation.
     */
    StampAnnotation();

    /**
     * Creates a new stamp annotation from the xml @p description
     */
    explicit StampAnnotation(const QDomNode &description);

    /**
     * Destroys the stamp annotation.
     */
    ~StampAnnotation() override;

    /**
     * Sets the @p name of the icon for the stamp annotation.
     */
    void setStampIconName(const QString &name);

    /**
     * Returns the name of the icon.
     */
    QString stampIconName() const;

    /**
     * Returns the sub type of the stamp annotation.
     */
    SubType subType() const override;

    /**
     * Stores the stamp annotation as xml in @p document
     * under the given parent @p node.
     */
    void store(QDomNode &node, QDomDocument &document) const override;

private:
    Q_DECLARE_PRIVATE(StampAnnotation)
    Q_DISABLE_COPY(StampAnnotation)
};
Tobias Koenig's avatar
Tobias Koenig committed
1310

Albert Astals Cid's avatar
Albert Astals Cid committed
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
class OKULARCORE_EXPORT InkAnnotation : public Annotation
{
public:
    /**
     * Creates a new ink annotation.
     */
    InkAnnotation();

    /**
     * Creates a new ink annotation from the xml @p description
     */
    explicit InkAnnotation(const QDomNode &description);

    /**
     * Destroys the ink annotation.
     */
    ~InkAnnotation() override;

    /**
     * Sets the @p paths of points for the ink annotation.
     */
    void setInkPaths(const QList<QLinkedList<NormalizedPoint>> &paths);

    /**
     * Returns the paths of points of the ink annotation.
     */
    QList<QLinkedList<NormalizedPoint>> inkPaths() const;

    /**
     * Returns the paths of transformed (e.g. rotated) points of
     * the ink annotation.
     */
    QList<QLinkedList<NormalizedPoint>> transformedInkPaths() const;

    /**
     * Returns the sub type of the ink annotation.
     */
    SubType subType() const override;

    /**
     * Stores the ink annotation as xml in @p document
     * under the given parent @p node.
     */
    void store(QDomNode &node, QDomDocument &document) const override;

private:
    Q_DECLARE_PRIVATE(InkAnnotation)
    Q_DISABLE_COPY(InkAnnotation)
1359
1360
};

1361
class OKULARCORE_EXPORT CaretAnnotation : public Annotation
1362
{
Albert Astals Cid's avatar
Albert Astals Cid committed
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
public:
    /**
     * Describes the highlighting style of the annotation.
     */
    enum CaretSymbol {
        None, ///< No symbol to be associated with the text
        P     ///< A 'paragraph' symbol
    };

    /**
     * Creates a new caret annotation.
     */
    CaretAnnotation();

    /**
     * Creates a new caret annotation from the xml @p description
     */
    explicit CaretAnnotation(const QDomNode &description);

    /**
     * Destroys the caret annotation.
     */
    ~CaretAnnotation() override;

    /**
     * Sets the @p symbol for the caret annotation.
     */
    void setCaretSymbol(CaretAnnotation::CaretSymbol symbol);

    /**
     * Returns the symbol of the annotation.
     */
    CaretAnnotation::CaretSymbol caretSymbol() const;

    /**
     * Returns the sub type of the caret annotation.
     */
    SubType subType() const override;

    /**
     * Stores the caret annotation as xml in @p document
     * under the given parent @p node.
     */
    void store(QDomNode &node, QDomDocument &document) const override;

private:
    Q_DECLARE_PRIVATE(CaretAnnotation)
    Q_DISABLE_COPY(CaretAnnotation)
1411
1412
};

1413
class OKULARCORE_EXPORT FileAttachmentAnnotation : public Annotation
1414
{
Albert Astals Cid's avatar
Albert Astals Cid committed
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
public:
    /**
     * Creates a new file attachment annotation.
     */
    FileAttachmentAnnotation();
    /**
     * Creates a new file attachment annotation from the xml @p description
     */
    explicit FileAttachmentAnnotation(const QDomNode &description);
    /**
     * Destroys the file attachment annotation.
     */
    ~FileAttachmentAnnotation() override;

    /**
     * Gets the name of the icon.
     */
    QString fileIconName() const;

    /**
     * Sets the @p iconName of the icon for the file attachment annotation.
     */
    void setFileIconName(const QString &iconName);

    /**
     * Gets the embedded file object.
     */
    EmbeddedFile *embeddedFile() const;

    /**
     * Sets the @p ef representing the embedded file of the file
     * attachment annotation.
     */
    void setEmbeddedFile(EmbeddedFile *ef);

    /**
     * Returns the sub type of the file attachment annotation.
     */
    SubType subType() const override;

    /**
     * Stores the file attachment annotation as xml in @p document
     * under the given parent @p node.
     */
    void store(QDomNode &node, QDomDocument &document) const override;

private:
    Q_DECLARE_PRIVATE(FileAttachmentAnnotation)
    Q_DISABLE_COPY(FileAttachmentAnnotation)
1464
1465
};

1466
1467
1468
1469
/**
 * \short Sound annotation.
 *
 * The sound annotation represents a sound to be played when activated.
Pino Toscano's avatar
apidox    
Pino Toscano committed
1470
1471
 *
 * @since 0.7 (KDE 4.1)
1472
 */
1473
class OKULARCORE_EXPORT SoundAnnotation : public Annotation
1474
{
Albert Astals Cid's avatar
Albert Astals Cid committed
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
public:
    /**
     * Creates a new sound annotation.
     */
    SoundAnnotation();
    /**
     * Creates a new sound annotation from the xml @p description
     */
    explicit SoundAnnotation(const QDomNode &description);
    /**
     * Destroys the sound annotation.
     */
    ~SoundAnnotation() override;

    /**
     * Gets the name of the icon.
     */
    QString soundIconName() const;

    /**
     * Sets the @p iconName of the icon for the sound annotation.
     */
    void setSoundIconName(const QString &iconName);

    /**
     * Gets the sound object.
     */
    Sound *sound() const;

    /**
     * Sets the @p s representing the sound of the file
     * attachment annotation.
     */
    void setSound(Sound *s);

    /**
     * Returns the sub type of the sound annotation.
     */
    SubType subType() const override;

    /**
     * Stores the sound annotation as xml in @p document
     * under the given parent @p node.
     */
    void store(QDomNode &node, QDomDocument &document) const override;

private:
    Q_DECLARE_PRIVATE(SoundAnnotation)
    Q_DISABLE_COPY(SoundAnnotation)
1524
1525
};

1526
1527
1528
1529
1530
1531
1532
/**
 * \short Movie annotation.
 *
 * The movie annotation represents a movie to be played when activated.
 *
 * @since 0.8 (KDE 4.2)
 */
1533
class OKULARCORE_EXPORT MovieAnnotation : public Annotation
1534
{
Albert Astals Cid's avatar
Albert Astals Cid committed
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
public:
    /**
     * Creates a new movie annotation.
     */
    MovieAnnotation();
    /**
     * Creates a new movie annotation from the xml @p description
     */
    explicit MovieAnnotation(const QDomNode &description);
    /**
     * Destroys the movie annotation.
     */
    ~MovieAnnotation() override;
    /**
     * Gets the movie object.
     */
    Movie *movie() const;
    /**
     * Sets the new @p movie object.
     */
    void setMovie(Movie *movie);
    /**
     * Returns the sub type of the movie annotation.
     */
    SubType subType() const override;
    /**
     * Stores the movie annotation as xml in @p document
     * under the given @p parentNode.
     */
    void store(QDomNode &parentNode, QDomDocument &document) const override;

private:
    Q_DECLARE_PRIVATE(MovieAnnotation)
    Q_DISABLE_COPY(MovieAnnotation)
1569
1570
};

1571
1572
1573
1574
1575
1576
1577
1578
/**
 * \short Screen annotation.
 *
 * The screen annotation specifies a region of a page upon which media clips
 * may be played. It also serves as an object from which actions can be triggered.
 *
 * @since 0.16 (KDE 4.10)
 */
1579
class OKULARCORE_EXPORT ScreenAnnotation : public Annotation
1580
{
Albert Astals Cid's avatar
Albert Astals Cid committed
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
public:
    /**
     * Creates a new screen annotation.
     */
    ScreenAnnotation();

    /**
     * Creates a new screen annotation from the xml @p description
     */
    explicit ScreenAnnotation(const QDomNode &description);

    /**
     * Destroys the screen annotation.
     */
    ~ScreenAnnotation() override;

    /**
     * Returns the sub type of the screen annotation.
     */
    SubType subType() const override;

    /**
     * Stores the screen annotation as xml in @p document
     * under the given @p parentNode.
     */
    void store(QDomNode &parentNode, QDomDocument &document) const override;

    /**
     * Sets the @p action that is executed when the annotation is triggered.
     *
     * @since 0.16 (KDE 4.10)
     */
    void setAction(Action *action);

    /**
     * Returns the action that is executed when the annotation is triggered or @c 0 if not action has been defined.
     *
     * @since 0.16 (KDE 4.10)
     */
    Action *action() const;

    /**
     * Sets the additional @p action of the given @p type.
     *
     * @since 0.16 (KDE 4.10)
     */
    void setAdditionalAction(AdditionalActionType type, Action *action);

    /**
     * Returns the additional action of the given @p type or @c 0 if no action has been defined.
     *
     * @since 0.16 (KDE 4.10)
     */
    Action *additionalAction(AdditionalActionType type) const;

private:
    Q_DECLARE_PRIVATE(ScreenAnnotation)
    Q_DISABLE_COPY(ScreenAnnotation)
1639
1640
1641
1642
1643
1644
1645
1646
1647
};

/**
 * \short Widget annotation.
 *
 * The widget annotation represents a widget on a page.
 *
 * @since 0.16 (KDE 4.10)
 */
1648
class OKULARCORE_EXPORT WidgetAnnotation : public Annotation
1649
{
Albert Astals Cid's avatar
Albert Astals Cid committed
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
public:
    /**
     * Creates a new widget annotation.
     */
    WidgetAnnotation();

    /**
     * Creates a new widget annotation from the xml @p description
     */
    explicit WidgetAnnotation(const QDomNode &description);

    /**
     * Destroys the widget annotation.
     */
    ~WidgetAnnotation() override;

    /**
     * Returns the sub type of the widget annotation.
     */
    SubType subType() const override;

    /**
     * Stores the widget annotation as xml in @p document
     * under the given @p parentNode.
     */
    void store(QDomNode &parentNode, QDomDocument &document) const override;

    /**
     * Sets the additional @p action of the given @p type.
     *
     * @since 0.16 (KDE 4.10)
     */
    void setAdditionalAction(AdditionalActionType type, Action *action);

    /**
     * Returns the additional action of the given @p type or @c 0 if no action has been defined.
     *
     * @since 0.16 (KDE 4.10)
     */
    Action *additionalAction(AdditionalActionType type) const;

private: