okular/core/page.h

   1 /***************************************************************************
   2  *   Copyright (C) 2004 by Enrico Ros <eros.kde@email.it>                  *
   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_PAGE_H_
  11 #define _OKULAR_PAGE_H_
  12
  13 #include <QtCore/QLinkedList>
  14
  15 #include <okular/core/okular_export.h>
  16 #include <okular/core/area.h>
  17 #include <okular/core/global.h>
  18
  19 class QPixmap;
  20
  21 class PagePainter;
  22
  23 namespace Okular {
  24
  25 class Annotation;
  26 class Document;
  27 class DocumentPrivate;
  28 class FormField;
  29 class PagePrivate;
  30 class PageTransition;
  31 class SourceReference;
  32 class TextPage;
  33 class TextSelection;
  34
  35 /**
  36  * @short Collector for all the data belonging to a page.
  37  *
  38  * The Page class contains pixmaps (referenced using observers id as key),
  39  * a search page (a class used internally for retrieving text), rect classes
  40  * (that describe links or other active areas in the current page) and more.
  41  *
  42  * All coordinates are normalized to the page, so {x,y} are valid in [0,1]
  43  * range as long as NormalizedRect components.
  44  *
  45  * Note: The class takes ownership of all objects.
  46  */
  47 class OKULAR_EXPORT Page
  48 {
  49     public:
  50         /**
  51          * An action to be executed when particular events happen.
  52          */
  53         enum PageAction
  54         {
  55             Opening,       ///< An action to be executed when the page is "opened".
  56             Closing        ///< An action to be executed when the page is "closed".
  57         };
  58
  59         /**
  60          * Creates a new page.
  61          *
  62          * @param number The number of the page in the document.
  63          * @param width The width of the page.
  64          * @param height The height of the page.
  65          * @param orientation The orientation of the page
  66          */
  67         Page( uint number, double width, double height, Rotation orientation );
  68
  69         /**
  70          * Destroys the page.
  71          */
  72         ~Page();
  73
  74         /**
  75          * Returns the number of the page in the document.
  76          */
  77         int number() const;
  78
  79         /**
  80          * Returns the orientation of the page as defined by the document.
  81          */
  82         Rotation orientation() const;
  83
  84         /**
  85          * Returns the rotation of the page as defined by the user.
  86          */
  87         Rotation rotation() const;
  88
  89         /**
  90          * Returns the total orientation which is the original orientation plus
  91          * the user defined rotation.
  92          */
  93         Rotation totalOrientation() const;
  94
  95         /**
  96          * Returns the width of the page.
  97          */
  98         double width() const;
  99
 100         /**
 101          * Returns the height of the page.
 102          */
 103         double height() const;
 104
 105         /**
 106          * Returns the ration (height / width) of the page.
 107          */
 108         double ratio() const;
 109
 110         /**
 111          * Returns the bounding box of the page content in normalized [0,1] coordinates,
 112          * in terms of the upright orientation (Rotation0).
 113          * If it has not been computed yet, returns the full page (i.e., (0, 0, 1, 1)).
 114          * Note that the bounding box may be null if the page is blank.
 115          *
 116          * @since 0.7 (KDE 4.1)
 117          */
 118         NormalizedRect boundingBox() const;
 119
 120         /**
 121          * Returns whether the bounding box of the page has been computed.
 122          * Note that even if the bounding box is computed, it may be null if the page is blank.
 123          *
 124          * @since 0.7 (KDE 4.1)
 125          */
 126         bool isBoundingBoxKnown() const;
 127
 128         /**
 129          * Sets the bounding box of the page content in normalized [0,1] coordinates,
 130          * in terms of the upright orientation (Rotation0).
 131          * (This does not inform the document's observers, call Document::SetPageBoundingBox
 132          * instead if you want that.)
 133          *
 134          * @since 0.7 (KDE 4.1)
 135          */
 136         void setBoundingBox( const NormalizedRect& bbox );
 137
 138         /**
 139          * Returns whether the page has a pixmap of size @p width x @p height
 140          * for the observer with given @p id.
 141          */
 142         bool hasPixmap( int id, int width = -1, int height = -1 ) const;
 143
 144         /**
 145          * Returns whether the page provides a text page (@ref TextPage).
 146          */
 147         bool hasTextPage() const;
 148
 149         /**
 150          * Returns whether the page has an object rect which includes the point (@p x, @p y)
 151          * at scale (@p xScale, @p yScale).
 152          */
 153         bool hasObjectRect( double x, double y, double xScale, double yScale ) const;
 154
 155         /**
 156          * Returns whether the page provides highlighting for the observer with the
 157          * given @p id.
 158          */
 159         bool hasHighlights( int id = -1 ) const;
 160
 161         /**
 162          * Returns whether the page provides a transition effect.
 163          */
 164         bool hasTransition() const;
 165
 166         /**
 167          * Returns whether the page provides annotations.
 168          */
 169         bool hasAnnotations() const;
 170
 171         /**
 172          * Returns the bounding rect of the text which matches the following criteria
 173          * or 0 if the search is not successful.
 174          *
 175          * @param id An unique id for this search.
 176          * @param text The search text.
 177          * @param direction The direction of the search (@ref SearchDirection)
 178          * @param caseSensitivity If Qt::CaseSensitive, the search is case sensitive; otherwise
 179          *                        the search is case insensitive.
 180          * @param lastRect If 0 (default) the search starts at the beginning of the page, otherwise
 181          *                 right/below the coordinates of the the given rect.
 182          */
 183         RegularAreaRect* findText( int id, const QString & text, SearchDirection direction,
 184                                    Qt::CaseSensitivity caseSensitivity, const RegularAreaRect * lastRect=0) const;
 185
 186         /**
 187          * Returns the page text (or part of it).
 188          * @see TextPage::text()
 189          */
 190         QString text( const RegularAreaRect * rect = 0 ) const;
 191
 192         /**
 193          * Returns the rectangular area of the given @p selection.
 194          */
 195         RegularAreaRect * textArea( TextSelection *selection ) const;
 196
 197         /**
 198          * Returns the object rect of the given @p type which is at point (@p x, @p y) at scale (@p xScale, @p yScale).
 199          */
 200         const ObjectRect * objectRect( ObjectRect::ObjectType type, double x, double y, double xScale, double yScale ) const;
 201
 202         /**
 203          * Returns the transition effect of the page or 0 if no transition
 204          * effect is set (see hasTransition()).
 205          */
 206         const PageTransition * transition() const;
 207
 208         /**
 209          * Returns the list of annotations of the page.
 210          */
 211         QLinkedList< Annotation* > annotations() const;
 212
 213         /**
 214          * Returns the @ref Action object which is associated with the given page @p action
 215          * or 0 if no page action is set.
 216          */
 217         const Action * pageAction( PageAction action ) const;
 218
 219         /**
 220          * Returns the list of FormField of the page.
 221          */
 222         QLinkedList< FormField * > formFields() const;
 223
 224         /**
 225          * Sets the @p pixmap for the observer with the given @p id.
 226          */
 227         void setPixmap( int id, QPixmap *pixmap );
 228
 229         /**
 230          * Sets the @p text page.
 231          */
 232         void setTextPage( TextPage * text );
 233
 234         /**
 235          * Sets the list of object @p rects of the page.
 236          */
 237         void setObjectRects( const QLinkedList< ObjectRect * > & rects );
 238
 239         /**
 240          * Sets the list of source reference objects @p rects.
 241          */
 242         void setSourceReferences( const QLinkedList< SourceRefObjectRect * > & rects );
 243
 244         /**
 245          * Sets the duration of the page to @p seconds when displayed in presentation mode.
 246          *
 247          * Setting a negative number disables the duration.
 248          */
 249         void setDuration( double seconds );
 250
 251         /**
 252          * Returns the duration in seconds of the page when displayed in presentation mode.
 253          *
 254          * A negative number means that no time is set.
 255          */
 256         double duration() const;
 257
 258         /**
 259          * Sets the labels for the page to @p label .
 260          */
 261         void setLabel( const QString& label );
 262
 263         /**
 264          * Returns the label of the page, or a null string if not set.
 265          */
 266         QString label() const;
 267
 268         /**
 269          * Returns the current text selection.
 270          */
 271         const RegularAreaRect * textSelection() const;
 272
 273         /**
 274          * Returns the color of the current text selection, or an invalid color
 275          * if no text selection has been set.
 276          */
 277         QColor textSelectionColor() const;
 278
 279         /**
 280          * Adds a new @p annotation to the page.
 281          */
 282         void addAnnotation( Annotation * annotation );
 283
 284         /**
 285          * Removes the @p annotation from the page.
 286          */
 287         bool removeAnnotation( Annotation * annotation );
 288
 289         /**
 290          * Sets the page @p transition effect.
 291          */
 292         void setTransition( PageTransition * transition );
 293
 294         /**
 295          * Sets the @p link object for the given page @p action.
 296          */
 297         void setPageAction( PageAction action, Action * link );
 298
 299         /**
 300          * Sets @p fields as list of FormField of the page.
 301          */
 302         void setFormFields( const QLinkedList< FormField * >& fields );
 303
 304         /**
 305          * Deletes the pixmap for the observer with the given @p id.
 306          */
 307         void deletePixmap( int id );
 308
 309         /**
 310          * Deletes all pixmaps of the page.
 311          */
 312         void deletePixmaps();
 313
 314         /**
 315          * Deletes all object rects of the page.
 316          */
 317         void deleteRects();
 318
 319         /**
 320          * Deletes all source reference objects of the page.
 321          */
 322         void deleteSourceReferences();
 323
 324         /**
 325          * Deletes all annotations of the page.
 326          */
 327         void deleteAnnotations();
 328
 329     private:
 330         PagePrivate* const d;
 331         /// @cond PRIVATE
 332         friend class PagePrivate;
 333         friend class Document;
 334         friend class DocumentPrivate;
 335
 336         /**
 337          * To improve performance PagePainter accesses the following
 338          * member variables directly.
 339          */
 340         friend class ::PagePainter;
 341         /// @endcond
 342
 343         const QPixmap * _o_nearestPixmap( int, int, int ) const;
 344
 345         QLinkedList< ObjectRect* > m_rects;
 346         QLinkedList< HighlightAreaRect* > m_highlights;
 347         QLinkedList< Annotation* > m_annotations;
 348
 349         Q_DISABLE_COPY( Page )
 350 };
 351
 352 }
 353
 354 #endif