- MERGE KPDF 3.5 CHANGES

svn path=/trunk/playground/graphics/oKular/kpdf/; revision=477586

COPYING

@@ -2,7 +2,7 @@
 		       Version 2, June 1991
 
  Copyright (C) 1989, 1991 Free Software Foundation, Inc.
-               51 Franklin Steet, Fifth Floor, Boston, MA 02110-1301  USA
+               51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 
@@ -305,7 +305,7 @@ the "copyright" line and a pointer to where the full notice is found.
 
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
-    Foundation, Inc., 51 Franklin Steet, Fifth Floor, Boston, MA 02110-1301, USA.
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
 Also add information on how to contact you by electronic and paper mail.
 

TODO

@@ -27,6 +27,7 @@ More items (first items will enter 'In progress list' first):
 -> popup context menu when using right button in selection mode (BR99315)
 -> pageview: add scrollbar marks for bookmarks (like kate)
 -> evaluate changing KPDFLink to KPDFAction
+-> evaluate changing KPDFLinkMovie to KPDFLinkResource (any kind)
 -> evaluate completely handling links internally instead of asking xpdf structs
 -> pageview: change document viewport after mouse scrolling ended (not every scroll frame)
    this will give better mvc consistancy
@@ -88,8 +89,8 @@ More items (first items will enter 'In progress list' first):
 -> presentation: implement missing transitions (6/11 done)
 -> presentation: add a red pencil that creates ink annotations (author: i18n(author-presentation)))
 -> presentation: save a flag (to the xml) to open a pdf in presentation mode
--> presentation: link following (now possible with uniform links) (BR98388)
 -> presentation: wheel not visible on black. gradient appreciated on lighter backgrounds.
+-> presentation: 2 pages per view, for users reading ebooks with wide screens.
 -> splash(xpdf): check lack of smoothness at low resolutions and antialiasing (BR94231)
 -> kfile-plugins/pdf: provide internal support and rewrite that plugin (drops xpdf dependancy from kdegraphics) (by ktech)
 -> goto 'logical' page (usually differs from pdf's page) (req. by Luca Burrelli)
@@ -111,6 +112,7 @@ Icons needed:
 - COMMON (here in ToolBox): Toc, Annotations
 
 Done (newest features come first):
+-> ADD: presentation: link following (BR98388)
 -> ADD: add ebook-friendly alignment option, better layouting (BR100341)
 -> FIX: random crash when closing kpdf with kapp->quit() (don't use Settings:: in destructors)
 -> FIX: implement links for starting end exiting from presentation mode (pdf FullScreen, Close actions)

conf/dlggeneral.ui

@@ -132,7 +132,7 @@
                                     <cstring>kcfg_WatchFile</cstring>
                                 </property>
                                 <property name="text">
-                                    <string>&amp;Watch File</string>
+                                    <string>&amp;Watch file</string>
                                 </property>
                             </widget>
                             <widget class="QCheckBox">

conf/settings.kcfgc

-ClassName=Settings
+ClassName=KpdfSettings
 File=oKular.kcfg
 Mutators=true
 Singleton=true

configure.in.bot

@@ -5,6 +5,15 @@ if test -z "$FREETYPE_CONFIG"; then
   echo ""
 fi
 
+if test x$FREETYPE_VERSION != x; then
+  if test $FREETYPE_VERSION -lt 9008003; then
+    echo ""
+    echo "You're are using freetype older than 2.1.10, it is not mandatory"
+    echo "to use 2.1.10 but kpdf improves its rendering in some pdf with it"
+    echo ""
+  fi
+fi
+
 if test -z "$XFT_LIBS"; then
   echo ""
   echo "You're missing XFT development libs."
@@ -18,3 +27,4 @@ if test "$HAVE_LIBJPEG" = "no"; then
   echo "KPDF will not be build without them"
   echo ""
 fi
+

configure.in.in

@@ -7,8 +7,8 @@ KDE_FIND_PATH(freetype-config, FREETYPE_CONFIG, [${prefix}/bin ${exec_prefix}/bi
 ])
 
 if test -n "$FREETYPE_CONFIG"; then
-  vers=`$FREETYPE_CONFIG --version 2>/dev/null | sed -e 's/libfreetype //' | awk 'BEGIN { FS = "."; } { printf "%d", ($1 * 1000 + $2) * 1000 + $3;}'`
-  if test -n "$vers" && test "$vers" -ge 9000000; then
+  FREETYPE_VERSION=`$FREETYPE_CONFIG --version 2>/dev/null | sed -e 's/libfreetype //' | awk 'BEGIN { FS = "."; } { printf "%d", ($1 * 1000 + $2) * 1000 + $3;}'`
+  if test -n "$FREETYPE_VERSION" && test "$FREETYPE_VERSION" -ge 9000000; then
     LIBFREETYPE_LIBS="`$FREETYPE_CONFIG --libs`"
     LIBFREETYPE_RPATH=
     for args in $LIBFREETYPE_LIBS; do
@@ -19,12 +19,6 @@ if test -n "$FREETYPE_CONFIG"; then
     LIBFREETYPE_RPATH=`echo $LIBFREETYPE_RPATH | sed -e "s/-L/-R/g"`
     LIBFREETYPE_CFLAGS="`$FREETYPE_CONFIG --cflags`"
     AC_DEFINE_UNQUOTED(HAVE_FREETYPE, 1, [Defines if your system has the freetype library])
-    if test -n "$vers" && test "$vers" -le 9005003; then
-	    AC_DEFINE_UNQUOTED(HAVE_FREETYPE_217_OR_OLDER, 1, [Defines if your system has the freetype library 2.1.7 or older])
-    else
-	    AC_DEFINE_UNQUOTED(HAVE_FREETYPE_217_OR_OLDER, 0, [Defines if your system has the freetype library 2.1.7 or older])
-    fi
-	    
   else
     AC_MSG_WARN([You need at least libfreetype 2.0.5])
     DO_NOT_COMPILE="$DO_NOT_COMPILE kpdf"
@@ -33,6 +27,7 @@ else
   DO_NOT_COMPILE="$DO_NOT_COMPILE kpdf"
 fi
 
+AC_SUBST(FREETYPE_VERSION)
 AC_SUBST(LIBFREETYPE_LIBS)
 AC_SUBST(LIBFREETYPE_CFLAGS)
 AC_SUBST(LIBFREETYPE_RPATH)
@@ -119,3 +114,9 @@ AC_ARG_ENABLE(force-kpdf-drm,
 , AC_DEFINE(KPDF_FORCE_DRM, 0, [Defines if force the use DRM in kpdf])
 )
 
+KDE_CHECK_COMPILER_FLAG([fno-regmove], SUPPORTS_NOREGMOVE=true, SUPPORTS_NOREGMOVE=false)
+if test "x$SUPPORTS_NOREGMOVE" = xtrue; then
+       NOREGMOVE="-fno-regmove"
+fi
+AC_SUBST(NOREGMOVE)
+

core/document.cpp

@@ -25,7 +25,6 @@
 #include <kmessagebox.h>
 #include <kapplication.h>
 #include <kuserprofile.h>
-#include <kmimetype.h>
 #include <krun.h>
 #include <kstandarddirs.h>
 #include <klibloader.h>
@@ -132,7 +131,7 @@ KPDFDocument::~KPDFDocument()
 }
 
 
-bool KPDFDocument::openDocument( const QString & docFile, const KURL & url )
+bool KPDFDocument::openDocument( const QString & docFile, const KURL & url, const KMimeType::Ptr &mime )
 {
     // docFile is always local so we can use QFile on it
     QFile fileReadTest( docFile );
@@ -149,8 +148,6 @@ bool KPDFDocument::openDocument( const QString & docFile, const KURL & url )
     fileReadTest.close();
     d->xmlFileName = locateLocal( "data", fn );
 
-    // create the generator based on the file's mimetype
-    KMimeType::Ptr mime = KMimeType::findByPath( docFile );
     if (mime.count()<=0)
 	return false;
     
@@ -167,7 +164,7 @@ bool KPDFDocument::openDocument( const QString & docFile, const KURL & url )
     int hRank=0;
 
     // best ranked offer search
-    if (offers.count() > 1 && Settings::chooseGenerators() )
+    if (offers.count() > 1 && KpdfSettings::chooseGenerators() )
     {
         ChooseEngineDialog * choose = new ChooseEngineDialog (0,0);
         int count=offers.count();
@@ -380,17 +377,25 @@ void KPDFDocument::addObserver( DocumentObserver * pObserver )
     }
 }
 
-void KPDFDocument::slotOrientation( int orientation )
+void KPDFDocument::notifyObservers (NotifyRequest * request)
 {
-    if (generator->supportsRotation())
+    switch (request->type)
     {
-        generator->setOrientation(pages_vector,orientation);
-        foreachObserver( notifySetup( pages_vector, true ) );
-        kdDebug() << "Oreint: " << orientation << endl;
+        case DocumentObserver::Setup:
+            foreachObserver( notifySetup( pages_vector, request->toggle ) );
+            break;
+        case DocumentObserver::Viewport:
+            foreachObserver( notifyViewportChanged( request->toggle ) );
+            break;
+        case DocumentObserver::Page:
+            foreachObserver( notifyPageChanged( request->page, request->flags ) );
+            break;
+        case DocumentObserver::Contents:
+            foreachObserver( notifyContentsCleared( request->flags ) );
+            break;
     }
 }
 
-
 void KPDFDocument::removeObserver( DocumentObserver * pObserver )
 {
     // remove observer from the map. it won't receive notifications anymore
@@ -445,7 +450,7 @@ void KPDFDocument::reparseConfig()
     }
 
     // free memory if in 'low' profile
-    if ( Settings::memoryLevel() == Settings::EnumMemoryLevel::Low &&
+    if ( KpdfSettings::memoryLevel() == KpdfSettings::EnumMemoryLevel::Low &&
          !d->allocatedPixmapsFifo.isEmpty() && !pages_vector.isEmpty() )
         cleanupPixmapMemory();
 }
@@ -564,7 +569,7 @@ void KPDFDocument::requestPixmaps( const QValueList< PixmapRequest * > & request
     }
 
     // 2. [ADD TO STACK] add requests to stack
-    bool threadingDisabled = !Settings::enableThreading();
+    bool threadingDisabled = !KpdfSettings::enableThreading();
     QValueList< PixmapRequest * >::const_iterator rIt = requests.begin(), rEnd = requests.end();
     for ( ; rIt != rEnd; ++rIt )
     {
@@ -854,7 +859,7 @@ bool KPDFDocument::searchText( int searchID, const QString & text, bool fromStar
             {
                 if ( currentPage >= pageCount )
                 {
-                    if ( noDialogs || KMessageBox::questionYesNo(0, i18n("End of document reached.\nContinue from the beginning?")) == KMessageBox::Yes )
+                    if ( noDialogs || KMessageBox::questionYesNo(0, i18n("End of document reached.\nContinue from the beginning?"), QString::null, KStdGuiItem::cont(), KStdGuiItem::cancel()) == KMessageBox::Yes )
                         currentPage = 0;
                     else
                         break;
@@ -1150,7 +1155,7 @@ void KPDFDocument::processLink( const KPDFLink * link )
                     setNextViewport();
                     break;
                 case KPDFLinkAction::Quit:
-                    kapp->quit();
+                    emit quit();
                     break;
                 case KPDFLinkAction::Presentation:
                     emit linkPresentation();
@@ -1164,6 +1169,9 @@ void KPDFDocument::processLink( const KPDFLink * link )
                 case KPDFLinkAction::GoToPage:
                     emit linkGoToPage();
                     break;
+                case KPDFLinkAction::Close:
+                    emit close();
+                    break;
             }
             } break;
 
@@ -1298,18 +1306,18 @@ void KPDFDocument::cleanupPixmapMemory( int /*sure? bytesOffset*/ )
     // [MEM] choose memory parameters based on configuration profile
     int clipValue = -1;
     int memoryToFree = -1;
-    switch ( Settings::memoryLevel() )
+    switch ( KpdfSettings::memoryLevel() )
     {
-        case Settings::EnumMemoryLevel::Low:
+        case KpdfSettings::EnumMemoryLevel::Low:
             memoryToFree = d->allocatedPixmapsTotalMemory;
             break;
 
-        case Settings::EnumMemoryLevel::Normal:
+        case KpdfSettings::EnumMemoryLevel::Normal:
             memoryToFree = d->allocatedPixmapsTotalMemory - getTotalMemory() / 3;
             clipValue = (d->allocatedPixmapsTotalMemory - getFreeMemory()) / 2;
             break;
 
-        case Settings::EnumMemoryLevel::Aggressive:
+        case KpdfSettings::EnumMemoryLevel::Aggressive:
             clipValue = (d->allocatedPixmapsTotalMemory - getFreeMemory()) / 2;
             break;
     }
@@ -1578,11 +1586,20 @@ void KPDFDocument::saveDocumentInfo() const
 void KPDFDocument::slotTimedMemoryCheck()
 {
     // [MEM] clean memory (for 'free mem dependant' profiles only)
-    if ( Settings::memoryLevel() != Settings::EnumMemoryLevel::Low &&
+    if ( KpdfSettings::memoryLevel() != KpdfSettings::EnumMemoryLevel::Low &&
          d->allocatedPixmapsTotalMemory > 1024*1024 )
         cleanupPixmapMemory();
 }
 
+void KPDFDocument::slotOrientation( int orientation )
+{
+    if (generator->supportsRotation())
+    {
+        generator->setOrientation(pages_vector,orientation);
+        foreachObserver( notifySetup( pages_vector, true ) );
+        kdDebug() << "Oreint: " << orientation << endl;
+    }
+}
 
 /** DocumentViewport **/
 

core/document.h

@@ -16,6 +16,7 @@
 #include <qstring.h>
 #include <qdom.h>
 #include <qdict.h>
+#include <kmimetype.h>
 
 class KPDFPage;
 class KPDFLink;
@@ -31,7 +32,7 @@ class KPrinter;
 class KURL;
 class KActionCollection;
 class QToolBox;
-
+class NotifyRequest;
 
 /**
  * @short The Document. Heart of everything. Actions take place here.
@@ -57,13 +58,16 @@ class KPDFDocument : public QObject
         KPDFDocument( QDict<Generator> * genList );
         ~KPDFDocument();
 
+        // communication with the part
+
         // document handling
-        bool openDocument( const QString & docFile, const KURL & url );
+        bool openDocument( const QString & docFile, const KURL & url, const KMimeType::Ptr &mime );
         void closeDocument();
 
-        // misc methods
+        // observer stuff
         void addObserver( DocumentObserver * pObserver );
         void removeObserver( DocumentObserver * pObserver );
+        void notifyObservers (NotifyRequest * request);
         void reparseConfig();
 
         // enum definitions
@@ -114,11 +118,14 @@ class KPDFDocument : public QObject
         bool handleEvent (QEvent * event);
         // notifications sent by generator
         void requestDone( PixmapRequest * request );
+//         inline pagesVector() { return pages_vector; };
 
     public slots:
         void slotOrientation( int orientation );
 
     signals:
+        void close();
+        void quit();
         void linkFind();
         void linkGoToPage();
         void linkPresentation();

core/generator.h

@@ -54,6 +54,14 @@ class Generator : public QObject
         // load a document and fill up the pagesVector
         virtual bool loadDocument( const QString & fileName, QValueVector< KPDFPage * > & pagesVector ) = 0;
 
+        // page contents generation
+        virtual bool canGeneratePixmap( bool async ) = 0;
+        virtual void generatePixmap( PixmapRequest * request ) = 0;
+
+        // can generate a KPDFText Page
+        virtual bool canGenerateTextPage() { return false; };
+        virtual void generateSyncTextPage( KPDFPage * /*page*/ ) {;};
+
         // Document description and Table of contents
         virtual const DocumentInfo * generateDocumentInfo() { return 0L; }
         virtual const DocumentSynopsis * generateDocumentSynopsis() { return 0L; }
@@ -62,28 +70,25 @@ class Generator : public QObject
         // DRM handling
         virtual bool isAllowed( int /*Document::Permisison(s)*/ ) { return true; }
 
-        // page contents generation
-        virtual bool canGeneratePixmap( bool async ) = 0;
-        virtual void generatePixmap( PixmapRequest * request ) = 0;
-
-        // can generate a KPDFText Page
-        virtual bool canGenerateTextPage() = 0;
-        virtual void generateSyncTextPage( KPDFPage * page ) = 0;
         // gui stuff
-        virtual QString getXMLFile() = 0;
+        virtual QString getXMLFile() { return QString::null; } ;
         virtual void setupGUI(KActionCollection  * /*ac*/ , QToolBox * /*tBox*/ ) {;};
         virtual void freeGUI( ) {;};
         // capability querying
+
         // provides internal search 
-        virtual bool supportsSearching() = 0;
-        virtual bool prefersInternalSearching() = 0;
-        virtual bool supportsRotation() = 0;
+        virtual bool supportsSearching() { return false; };
+        virtual bool prefersInternalSearching() { return false; };
+
+        // rotation
+        virtual bool supportsRotation() { return false; };
+        virtual void setOrientation(QValueVector<KPDFPage*> & /*pagesVector*/, int /*orientation*/) { ; };
 
         // internal search and gettext
-        virtual RegularAreaRect * findText( const QString & text, SearchDir dir, const bool strictCase,
-                    const RegularAreaRect * lastRect, KPDFPage * page) = 0;
-        virtual QString* getText( const RegularAreaRect * area, KPDFPage * page ) = 0;
-        virtual void setOrientation(QValueVector<KPDFPage*> & pagesVector, int orientation) = 0;
+        virtual RegularAreaRect * findText( const QString & /*text*/, SearchDir /*dir*/, const bool /*strictCase*/,
+                    const RegularAreaRect * /*lastRect*/, KPDFPage * /*page*/) { return 0L; };
+        virtual QString* getText( const RegularAreaRect * /*area*/, KPDFPage * /*page*/ ) { return 0L; }
+
         // may come useful later
         //virtual bool hasFonts() const = 0;
 
@@ -97,6 +102,15 @@ class Generator : public QObject
         // tell generator to re-parse configuration and return true if something changed
         virtual bool reparseConfig() { return false; }
 
+        // add support for settings
+        virtual void addPages( KConfigDialog* /*dlg*/ ) {;};
+//         virtual void setConfigurationPointer( KConfigDialog* /*dlg*/) { ; } ;
+
+        // capture events
+        // return false if you don't wish kpdf to use its event handlers
+        // in the pageview after your handling (use with caution)
+        virtual bool handleEvent (QEvent * /*event*/ ) { return true; } ;
+
         void setDocument( KPDFDocument * doc ) { m_document=doc; };
 
         /** 'signals' to send events the KPDFDocument **/
@@ -106,31 +120,15 @@ class Generator : public QObject
         /** constructor: takes the Document as a parameter **/
         Generator( KPDFDocument * doc ) : m_document( doc ) {};
 
-        // add support for settings
-        virtual void addPages( KConfigDialog* /*dlg*/) { ; } ;
-
-        // capture events
-        // return false if you don't wish kpdf to use its event handlers
-        // in the pageview after your handling (use with caution)
-        virtual bool handleEvent (QEvent * /*event*/ ) { return true; } ;
-
-        // podner if not making separate handlers for every event type (clutters the api though)
-        /*virtual bool mouseEvent ( QMouseEvent* event ) { return false; };
-        virtual bool wheelEvent ( QWheelEvent* event ) { return false; };
-        virtual bool keyEvent ( QKeyEvent* event ) { return false; };
-        virtual bool resizeEvent ( QResizeEvent* event ) { return false; };
-        virtual bool dragEnterEvent ( QDragEnterEvent* event ) { return false; };
-        virtual bool dropEvent ( QDropEvent* event ) { return false; };
-        virtual bool paintEvent ( QKeyEvent* event ) { return false; };*/
-
     signals:
         void error(QString & string, int duration);
         void warning(QString & string, int duration);
         void notice(QString & string, int duration);
 
+    protected:
+        KPDFDocument * m_document;
     private:
         Generator();
-        KPDFDocument * m_document;
 };
 
 /**

core/link.h

@@ -93,7 +93,7 @@ class KPDFLinkAction : public KPDFLink
     public:
         // define types of actions
         enum ActionType { PageFirst, PagePrev, PageNext, PageLast, HistoryBack, HistoryForward,
-                          Quit, Presentation, EndPresentation, Find, GoToPage };
+                          Quit, Presentation, EndPresentation, Find, GoToPage, Close };
 
         // query for action type
         ActionType actionType() const { return m_type; }

core/observer.h

@@ -46,6 +46,7 @@ class DocumentObserver
 
         // commands from the Document to all observers
         enum ChangedFlags { Pixmap = 1, Bookmark = 2, Highlights = 4, Annotations = 8 };
+        enum NotifyType { Setup = 1, Viewport = 2, Page = 4, Contents = 8 };
         virtual void notifySetup( const QValueVector< KPDFPage * > & /*pages*/, bool /*documentChanged*/ ) {};
         virtual void notifyViewportChanged( bool /*smoothMove*/ ) {};
         virtual void notifyPageChanged( int /*pageNumber*/, int /*changedFlags*/ ) {};
@@ -55,4 +56,18 @@ class DocumentObserver
         virtual bool canUnloadPixmap( int /*pageNum*/ ) { return true; }
 };
 
+struct NotifyRequest
+{
+    DocumentObserver::NotifyType type;
+    bool toggle;
+    int page;
+    int flags;
+    NotifyRequest (DocumentObserver::NotifyType t, bool to=false)
+        : type(t), toggle(to) { ; };
+    NotifyRequest (DocumentObserver::NotifyType t, int p, int f)
+        : type(t), page(p), flags (f) { ; };
+    NotifyRequest (DocumentObserver::NotifyType t, int p)
+        : type(t), page(p) { ; };
+};
+
 #endif

core/textpage.cpp

@@ -119,7 +119,7 @@ RegularAreaRect* KPDFTextPage::findTextInternal(const QString &query, bool forwa
         if (query.mid(j,1)==" " && wasEol )
         {
             // lets match newline as a space
-            //kdDebug(1223) << "Matched, space after eol " << endl;
+            kdDebug(1223) << "Matched, space after eol " << endl;
             j++;
             queryLeft--;
             // since we dont really need to increment this after this
@@ -132,7 +132,7 @@ RegularAreaRect* KPDFTextPage::findTextInternal(const QString &query, bool forwa
             dontIncrement=false;
             int min=QMIN(queryLeft,len);
             len=str.length();
-            //kdDebug(1223) << str.left(min) << " : " << query.mid(j,min) << endl;
+            kdDebug(1223) << str.left(min) << " : " << query.mid(j,min) << endl;
             // we have equal (or less then) area of the query left as the lengt of the current 
             // entity
 
@@ -148,7 +148,7 @@ RegularAreaRect* KPDFTextPage::findTextInternal(const QString &query, bool forwa
                     haveMatch=false;
                     delete ret;
                     ret=new RegularAreaRect;
-                   // kdDebug(1223) << "\tNotmatched" << endl;
+                    kdDebug(1223) << "\tNotmatched" << endl;
                     j=0;
                     queryLeft=query.length();
             }
@@ -160,7 +160,7 @@ RegularAreaRect* KPDFTextPage::findTextInternal(const QString &query, bool forwa
                     // we matched
                     // substract the length of the current entity from 
                     // the left length of the query
-                  //  kdDebug(1223) << "\tMatched" << endl;
+                    kdDebug(1223) << "\tMatched" << endl;
                     haveMatch=true;
                     ret->append( (*it)->area );
                     j+=min;
@@ -168,8 +168,8 @@ RegularAreaRect* KPDFTextPage::findTextInternal(const QString &query, bool forwa
             }
         }
         wasEol=(*it)->eol;
-        /*if (wasEol)
-            kdDebug(1223) << "\t\tENDOFLINE"  << endl;*/
+        if (wasEol)
+            kdDebug(1223) << "\t\tENDOFLINE"  << endl;
         if (haveMatch && queryLeft==0 && j==query.length())
         {
 //            RegularAreaRect::ConstIterator i=ret->begin(), end=ret->end;

core/textpage.h

@@ -15,29 +15,41 @@
 #include <qstringlist.h>
 #include "area.h"
 
+/*! @enum SearchDir
+ *  The enum holding the direction of searching.
+ *! @enum SearchDir FromTop
+ *  Searching from top of the page, next result is to be found,
+ *  there was no earlier search result.
+ *! @enum SearchDir NextRes
+ *  Searching for the next result on the page, earlier result should be 
+ *  located so we search from the last result not from the beginning of the 
+ *  page.
+ *! @enum SearchDir PrevRes
+ *  Searching for the previous result on the page, earlier result should be 
+ *  located so we search from the last result not from the beginning of the 
+ *  page.
+ */
 typedef enum SearchDir{ FromTop, NextRes, PrevRes };
 
-/*
- * @short Abstractet Entity of KPDF
- * The idea:
- * Document can provide one of the following information about text areas
- * 1.) provide information for every character  (best)
-
+/*! @struct  KPDFTextEntity
+ * @short Abstract textentity of KPDF
+ * @par The context
+ * A document can provide different forms of information about textual representation
+ * of its contents. It can include information about positions of every character on the 
+ * page, this is the best possibility. 
+ * 
+ * But also it can provide information only about positions of every word on the page (not the character). 
+ * Furthermore it can provide information only about the position of the whole page's text on the page.
  * 
- * 2.) provide information for every word 
- * We will use type Word for this kind of entity. It will store the 
- * word and should be followed by a type glyph which will contain some 
- * punctuation marks.
- 
- 
- * 3.) provide information for every textline
+ * Also some document types have glyphes - sets of characters rendered as one, so in search they should 
+ * appear as a text but are only one character when drawn on screen. We need to allow this.
+ * @par The idea
+ * We need several
  */
 
 struct KPDFTextEntity
 {
-// not sure used now might be useful in the future
-//    typedef enum Type{ Glyph, Word, Line };
-//    Type type;
+    // 
     QString txt;
     NormalizedRect* area;
     double baseline;