okular/core/textpage.h

   1 /***************************************************************************
   2  *   Copyright (C) 2005 by Piotr Szymanski <niedakh@gmail.com>             *
   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_TEXTPAGE_H_
  11 #define _OKULAR_TEXTPAGE_H_
  12
  13 #include <QtCore/QList>
  14 #include <QtCore/QString>
  15
  16 #include <okular/core/okular_export.h>
  17 #include <okular/core/global.h>
  18
  19 class QMatrix;
  20
  21 namespace Okular {
  22
  23 class NormalizedRect;
  24 class Page;
  25 class PagePrivate;
  26 class TextPagePrivate;
  27 class TextSelection;
  28 class RegularAreaRect;
  29
  30 /*! @class TextEntity
  31  * @short Abstract textentity of Okular
  32  * @par The context
  33  * A document can provide different forms of information about textual representation
  34  * of its contents. It can include information about positions of every character on the
  35  * page, this is the best possibility.
  36  *
  37  * But also it can provide information only about positions of every word on the page (not the character).
  38  * Furthermore it can provide information only about the position of the whole page's text on the page.
  39  *
  40  * Also some document types have glyphes - sets of characters rendered as one, so in search they should
  41  * appear as a text but are only one character when drawn on screen. We need to allow this.
  42  */
  43 class OKULAR_EXPORT TextEntity
  44 {
  45     public:
  46         typedef QList<TextEntity*> List;
  47
  48         /**
  49          * Creates a new text entity with the given @p text and the
  50          * given @p area.
  51          */
  52         TextEntity( const QString &text, NormalizedRect *area );
  53
  54         /**
  55          * Destroys the text entity.
  56          */
  57         ~TextEntity();
  58
  59         /**
  60          * Returns the text of the text entity.
  61          */
  62         QString text() const;
  63
  64         /**
  65          * Returns the bounding area of the text entity.
  66          */
  67         NormalizedRect* area() const;
  68
  69         /**
  70          * Returns the transformed area of the text entity.
  71          */
  72         NormalizedRect transformedArea(const QMatrix &matrix) const;
  73
  74     private:
  75         QString m_text;
  76         NormalizedRect* m_area;
  77
  78         class Private;
  79         const Private *d;
  80
  81         Q_DISABLE_COPY( TextEntity )
  82 };
  83
  84 /**
  85  * The TextPage class represents the text of a page by
  86  * providing @see TextEntity items for every word/character of
  87  * the page.
  88  */
  89 class OKULAR_EXPORT TextPage
  90 {
  91     /// @cond PRIVATE
  92     friend class Page;
  93     friend class PagePrivate;
  94     /// @endcond
  95
  96     public:
  97         /**
  98          * Creates a new text page.
  99          */
 100         TextPage();
 101
 102         /**
 103          * Creates a new text page with the given @p words.
 104          */
 105         TextPage( const TextEntity::List &words );
 106
 107         /**
 108          * Destroys the text page.
 109          */
 110         ~TextPage();
 111
 112         /**
 113          * Appends the given @p text with the given @p area as new
 114          * @ref TextEntity to the page.
 115          */
 116         void append( const QString &text, NormalizedRect *area );
 117
 118         /**
 119          * Returns the bounding rect of the text which matches the following criteria
 120          * or 0 if the search is not successful.
 121          *
 122          * @param id An unique id for this search.
 123          * @param text The search text.
 124          * @param direction The direction of the search (@ref SearchDirection)
 125          * @param caseSensitivity If Qt::CaseSensitive, the search is case sensitive; otherwise
 126          *                        the search is case insensitive.
 127          * @param lastRect If 0 the search starts at the beginning of the page, otherwise
 128          *                 right/below the coordinates of the the given rect.
 129          */
 130         RegularAreaRect* findText( int id, const QString &text, SearchDirection direction,
 131                                    Qt::CaseSensitivity caseSensitivity, const RegularAreaRect *lastRect );
 132
 133         /**
 134          * Text extraction function.
 135          *
 136          * Returns:
 137          * - a null string if @p rect is a valid pointer to a null area
 138          * - the whole page text if @p rect is a null pointer
 139          * - the text which is included by rectangular area @p rect otherwise
 140          */
 141         QString text( const RegularAreaRect *rect = 0 ) const;
 142
 143         /**
 144          * Returns the rectangular area of the given @p selection.
 145          */
 146         RegularAreaRect *textArea( TextSelection *selection ) const;
 147
 148     private:
 149         TextPagePrivate* const d;
 150
 151         Q_DISABLE_COPY( TextPage )
 152 };
 153
 154 }
 155
 156 #endif