annotations.h

Go to the documentation of this file.

/***************************************************************************
 *   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.                                   *
 ***************************************************************************/

#ifndef _OKULAR_ANNOTATIONS_H_
#define _OKULAR_ANNOTATIONS_H_

#include <QtCore/QString>
#include <QtCore/QDateTime>
#include <QtCore/QLinkedList>
#include <QtCore/QRect>
#include <QtGui/QFont>
#include <QtXml/QDomDocument>
#include <QtXml/QDomElement>

#include "okular_export.h"
#include "area.h"

namespace Okular {

class Action;
class Annotation;
class AnnotationObjectRect;
class AnnotationPrivate;
class Document;
class EmbeddedFile;
class Page;
class PagePrivate;
class Sound;
class Movie;
class TextAnnotationPrivate;
class LineAnnotationPrivate;
class GeomAnnotationPrivate;
class HighlightAnnotationPrivate;
class StampAnnotationPrivate;
class InkAnnotationPrivate;
class CaretAnnotationPrivate;
class FileAttachmentAnnotationPrivate;
class SoundAnnotationPrivate;
class MovieAnnotationPrivate;
class ScreenAnnotationPrivate;
class WidgetAnnotationPrivate;

class OKULAR_EXPORT AnnotationUtils
{
    public:
        static Annotation * createAnnotation( const QDomElement & element );

        static void storeAnnotation( const Annotation * annotation,
                                     QDomElement & element, QDomDocument & document );

        static QDomElement findChildElement( const QDomNode & parentNode,
                                             const QString & name );

        static QRect annotationGeometry( const Annotation * annotation,
                                         double scaleX, double scaleY );
};

class OKULAR_EXPORT Annotation
{
    friend class AnnotationObjectRect;
    friend class Document;
    friend class DocumentPrivate;
    friend class ObjectRect;
    friend class Page;
    friend class PagePrivate;

    public:
        enum SubType
        {
            AText = 1,      
            ALine = 2,      
            AGeom = 3,      
            AHighlight = 4, 
            AStamp = 5,     
            AInk = 6,       
            ACaret = 8,     
            AFileAttachment = 9, 
            ASound = 10,    
            AMovie = 11,    
            AScreen = 12,   
            AWidget = 13,   
            A_BASE = 0      
        };

        enum Flag
        {
            Hidden = 1,               
            FixedSize = 2,            
            FixedRotation = 4,        
            DenyPrint = 8,            
            DenyWrite = 16,           
            DenyDelete = 32,          
            ToggleHidingOnMouse = 64, 
            External = 128,           
            ExternallyDrawn = 256,    
            BeingMoved = 512          
        };

        enum LineStyle
        {
            Solid = 1,      
            Dashed = 2,     
            Beveled = 4,    
            Inset = 8,      
            Underline = 16  
        };

        enum LineEffect
        {
            NoEffect = 1,  
            Cloudy = 2     
        };

        enum RevisionScope
        {
            Reply = 1,  
            Group = 2,  
            Delete = 4  
        };

        enum RevisionType
        {
            None = 1,        
            Marked = 2,      
            Unmarked = 4,    
            Accepted = 8,    
            Rejected = 16,   
            Cancelled = 32,  
            Completed = 64   
        };

        enum AdditionalActionType
        {
            PageOpening, 
            PageClosing  
        };

        typedef void ( * DisposeDataFunction )( const Okular::Annotation * );

        virtual ~Annotation();

        void setAuthor( const QString &author );

        QString author() const;

        void setContents( const QString &contents );

        QString contents() const;

        void setUniqueName( const QString &name );

        QString uniqueName() const;

        void setModificationDate( const QDateTime &date );

        QDateTime modificationDate() const;

        void setCreationDate( const QDateTime &date );

        QDateTime creationDate() const;

        void setFlags( int flags );

        int flags() const;

        void setBoundingRectangle( const NormalizedRect &rectangle );

        NormalizedRect boundingRectangle() const;

        NormalizedRect transformedBoundingRectangle() const;

        void translate( const NormalizedPoint &coord );

        class OKULAR_EXPORT Style
        {
            public:
                Style();

                ~Style();

                Style( const Style &other );
                Style& operator=( const Style &other );

                void setColor( const QColor &color );

                QColor color() const;

                void setOpacity( double opacity );

                double opacity() const;

                void setWidth( double width );

                double width() const;

                void setLineStyle( LineStyle style );

                LineStyle lineStyle() const;

                void setXCorners( double xCorners );

                double xCorners() const;

                void setYCorners( double yCorners );

                double yCorners() const;

                void setMarks( int marks );

                int marks() const;

                void setSpaces( int spaces );

                int spaces() const;

                void setLineEffect( LineEffect effect );

                LineEffect lineEffect() const;

                void setEffectIntensity( double intensity );

                double effectIntensity() const;

            private:
                class Private;
                Private* const d;
        };

        Style & style();

        const Style & style() const;

        class OKULAR_EXPORT Window
        {
            public:
                Window();

                ~Window();

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

                void setFlags( int flags );

                int flags() const;

                void setTopLeft( const NormalizedPoint &point );

                NormalizedPoint topLeft() const;

                void setWidth( int width );

                int width() const;

                void setHeight( int height );

                int height() const;

                void setTitle( const QString &title );

                QString title() const;

                void setSummary( const QString &summary );

                QString summary() const;

            private:
                class Private;
                Private* const d;
        };

        Window & window();

        const Window & window() const;

        class Revision
        {
            public:
                Revision();

                ~Revision();

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

                void setAnnotation( Annotation *annotation );

                Annotation *annotation() const;

                void setScope( RevisionScope scope );

                RevisionScope scope() const;

                void setType( RevisionType type );

                RevisionType type() const;

            private:
                class Private;
                Private* const d;
        };

        QLinkedList< Revision > & revisions();

        const QLinkedList< Revision > & revisions() const;

        void setNativeId( const QVariant &id );

        QVariant nativeId() const;

        void setDisposeDataFunction( DisposeDataFunction func );

        bool canBeMoved() const;

        bool openDialogAfterCreation() const;

        virtual SubType subType() const = 0;

        virtual void store( QDomNode & node, QDomDocument & document ) const;

        QDomNode getAnnotationPropertiesDomNode() const;

        void setAnnotationProperties( const QDomNode & node );

    protected:
        Annotation( AnnotationPrivate &dd );
        Annotation( AnnotationPrivate &dd, const QDomNode &description );
        Q_DECLARE_PRIVATE( Annotation )
        AnnotationPrivate *d_ptr;

    private:
        Q_DISABLE_COPY( Annotation )
};

class OKULAR_EXPORT AnnotationProxy
{
    public:
        enum Capability
        {
            Addition,       
            Modification,   
            Removal         
        };

        virtual ~AnnotationProxy();

        virtual bool supports( Capability capability ) const = 0;

        virtual void notifyAddition( Annotation *annotation, int page ) = 0;

        virtual void notifyModification( const Annotation *annotation, int page, bool appearanceChanged ) = 0;

        virtual void notifyRemoval( Annotation *annotation, int page ) = 0;
};

class OKULAR_EXPORT TextAnnotation : public Annotation
{
    public:
        enum TextType
        {
            Linked,  
            InPlace  
        };

        enum InplaceIntent
        {
            Unknown,    
            Callout,    
            TypeWriter  
        };

        TextAnnotation();

        TextAnnotation( const QDomNode &description );

        ~TextAnnotation();

        void setTextType( TextType type );

        TextType textType() const;

        void setTextIcon( const QString &icon );

        QString textIcon() const;

        void setTextFont( const QFont &font );

        QFont textFont() const;

        void setInplaceAlignment( int alignment );

        int inplaceAlignment() const;

        void setInplaceCallout( const NormalizedPoint &point, int index );

        NormalizedPoint inplaceCallout( int index ) const;

        NormalizedPoint transformedInplaceCallout( int index ) const;

        void setInplaceIntent( InplaceIntent intent );

        InplaceIntent inplaceIntent() const;

        SubType subType() const;

        void store( QDomNode &node, QDomDocument &document ) const;

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

class OKULAR_EXPORT LineAnnotation : public Annotation
{
    public:
        enum TermStyle
        {
            Square,         
            Circle,         
            Diamond,        
            OpenArrow,      
            ClosedArrow,    
            None,           
            Butt,           
            ROpenArrow,     
            RClosedArrow,   
            Slash           
        };

        enum LineIntent
        {
            Unknown,        
            Arrow,          
            Dimension,      
            PolygonCloud    
        };

        LineAnnotation();

        explicit LineAnnotation( const QDomNode &description );

        ~LineAnnotation();

        void setLinePoints( const QLinkedList<NormalizedPoint> &points );

        QLinkedList<NormalizedPoint> linePoints() const;

        QLinkedList<NormalizedPoint> transformedLinePoints() const;

        void setLineStartStyle( TermStyle style );

        TermStyle lineStartStyle() const;

        void setLineEndStyle( TermStyle style );

        TermStyle lineEndStyle() const;

        void setLineClosed( bool closed );

        bool lineClosed() const;

        void setLineInnerColor( const QColor &color );

        QColor lineInnerColor() const;

        void setLineLeadingForwardPoint( double point );

        double lineLeadingForwardPoint() const;

        void setLineLeadingBackwardPoint( double point );

        double lineLeadingBackwardPoint() const;

        void setShowCaption( bool shown );

        bool showCaption() const;

        void setLineIntent( LineIntent intent );

        LineIntent lineIntent() const;

        SubType subType() const;

        void store( QDomNode &node, QDomDocument &document ) const;

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

class OKULAR_EXPORT GeomAnnotation : public Annotation
{
    public:
        // common enums
        enum GeomType
        {
            InscribedSquare,  
            InscribedCircle   
        };

        GeomAnnotation();

        GeomAnnotation( const QDomNode &description );

        ~GeomAnnotation();

        void setGeometricalType( GeomType type );

        GeomType geometricalType() const;

        void setGeometricalInnerColor( const QColor &color );

        QColor geometricalInnerColor() const;

        SubType subType() const;

        void store( QDomNode &node, QDomDocument &document ) const;

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

class OKULAR_EXPORT HighlightAnnotation : public Annotation
{
    public:
        enum HighlightType
        {
            Highlight,  
            Squiggly,   
            Underline,  
            StrikeOut   
        };

        HighlightAnnotation();

        explicit HighlightAnnotation( const QDomNode &description );

        ~HighlightAnnotation();

        void setHighlightType( HighlightType type );

        HighlightType highlightType() const;

        class OKULAR_EXPORT Quad
        {
            public:
                Quad();

                ~Quad();

                Quad( const Quad &other );
                Quad& operator=( const Quad &other );

                void setPoint( const NormalizedPoint &point, int index );

                NormalizedPoint point( int index ) const;

                NormalizedPoint transformedPoint( int index ) const;

                void setCapStart( bool value );

                bool capStart() const;

                void setCapEnd( bool value );

                bool capEnd() const;

                void setFeather( double width );

                double feather() const;

                void transform( const QTransform &matrix );

            private:
                class Private;
                Private* const d;
        };

        QList< Quad > & highlightQuads();

        SubType subType() const;

        void store( QDomNode &node, QDomDocument &document ) const;

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

class OKULAR_EXPORT StampAnnotation : public Annotation
{
    public:
        StampAnnotation();

        explicit StampAnnotation( const QDomNode &description );

        ~StampAnnotation();

        void setStampIconName( const QString &name );

        QString stampIconName() const;

        SubType subType() const;

        void store( QDomNode &node, QDomDocument &document ) const;

    private:
        Q_DECLARE_PRIVATE( StampAnnotation )
        Q_DISABLE_COPY( StampAnnotation )
};

class OKULAR_EXPORT InkAnnotation : public Annotation
{
    public:
        InkAnnotation();

        InkAnnotation( const QDomNode &description );

        ~InkAnnotation();

        void setInkPaths( const QList< QLinkedList<NormalizedPoint> > &paths );

        QList< QLinkedList<NormalizedPoint> > inkPaths() const;

        QList< QLinkedList<NormalizedPoint> > transformedInkPaths() const;

        SubType subType() const;

        void store( QDomNode &node, QDomDocument &document ) const;

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

class OKULAR_EXPORT CaretAnnotation : public Annotation
{
    public:
        enum CaretSymbol
        {
            None,       
            P           
        };

        CaretAnnotation();

        explicit CaretAnnotation( const QDomNode &description );

        ~CaretAnnotation();

        void setCaretSymbol( CaretAnnotation::CaretSymbol symbol );

        CaretAnnotation::CaretSymbol caretSymbol() const;

        SubType subType() const;

        void store( QDomNode &node, QDomDocument &document ) const;

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

class OKULAR_EXPORT FileAttachmentAnnotation : public Annotation
{
    public:
        FileAttachmentAnnotation();
        explicit FileAttachmentAnnotation( const QDomNode &description );
        virtual ~FileAttachmentAnnotation();

        QString fileIconName() const;

        void setFileIconName( const QString &name );

        EmbeddedFile* embeddedFile() const;

        void setEmbeddedFile( EmbeddedFile *object );

        SubType subType() const;

        void store( QDomNode &node, QDomDocument &document ) const;

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

class OKULAR_EXPORT SoundAnnotation : public Annotation
{
    public:
        SoundAnnotation();
        SoundAnnotation( const QDomNode &description );
        virtual ~SoundAnnotation();

        QString soundIconName() const;

        void setSoundIconName( const QString &name );

        Sound* sound() const;

        void setSound( Sound *object );

        SubType subType() const;

        void store( QDomNode &node, QDomDocument &document ) const;

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

class OKULAR_EXPORT MovieAnnotation : public Annotation
{
    public:
        MovieAnnotation();
        MovieAnnotation( const QDomNode &description );
        virtual ~MovieAnnotation();
        Movie* movie() const;
        void setMovie( Movie *movie );
        SubType subType() const;
        void store( QDomNode &parentNode, QDomDocument &document ) const;

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

class OKULAR_EXPORT ScreenAnnotation : public Annotation
{
    public:
        ScreenAnnotation();

        ScreenAnnotation( const QDomNode &description );

        virtual ~ScreenAnnotation();

        SubType subType() const;

        void store( QDomNode &parentNode, QDomDocument &document ) const;

        void setAction( Action *action );

        Action* action() const;

        void setAdditionalAction( AdditionalActionType type, Action *action );

        Action* additionalAction( AdditionalActionType type ) const;

    private:
        Q_DECLARE_PRIVATE( ScreenAnnotation )
        Q_DISABLE_COPY( ScreenAnnotation )
};

class OKULAR_EXPORT WidgetAnnotation : public Annotation
{
    public:
        WidgetAnnotation();

        WidgetAnnotation( const QDomNode &description );

        virtual ~WidgetAnnotation();

        SubType subType() const;

        void store( QDomNode &parentNode, QDomDocument &document ) const;

        void setAdditionalAction( AdditionalActionType type, Action *action );

        Action* additionalAction( AdditionalActionType type ) const;

    private:
        Q_DECLARE_PRIVATE( WidgetAnnotation )
        Q_DISABLE_COPY( WidgetAnnotation )
};

}

#endif