Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdegraphics@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 650 insertions, 0 deletions

diff --git a/kviewshell/kmultipage.h b/kviewshell/kmultipage.h
new file mode 100644
index 00000000..7f24a809
--- /dev/null
+++ b/kviewshell/kmultipage.h
@@ -0,0 +1,650 @@
+// -*- C++ -*-
+#ifndef _KMULTIPAGE_H
+#define _KMULTIPAGE_H
+
+#include "pageView.h"
+#include "documentPageCache.h"
+#include "documentRenderer.h"
+#include "history.h"
+#include "kmultipageInterface.h"
+#include "marklist.h"
+
+#include <kparts/part.h>
+#include <qtimer.h>
+
+class Anchor;
+class DocumentWidget;
+class KConfigDialog;
+class KPrintDialogPage_PageOptions;
+class KPrinter;
+class PageView;
+class QPainter;
+class QSplitter;
+class QToolBox;
+class simplePageSize;
+class TableOfContents;
+class PageNumber;
+class SearchWidget;
+
+
+/** \brief This class provides plugin-specific GUI elements for kviewshell plugins
+
+@author Wilfried Huss, Stefan Kebekus
+
+ */
+
+// TODO remove virtual inheritance for KDE 4. It's the reason for the strange DCOPObject construction
+class KMultiPage : public KParts::ReadOnlyPart, virtual public kmultipageInterface
+{
+  Q_OBJECT
+
+public:
+  KMultiPage(QWidget *parentWidget, const char *widgetName, QObject *parent, const char *name);
+  virtual ~KMultiPage();
+
+  /* returns the scrollview used for the display */
+  virtual QWidget* mainWidget() {return _scrollView;}
+
+  /* Methods which are associated with the DCOP functionality of the
+     kmultipage. This method returns the file name (not the URL) of
+     the currently loaded file. */
+  QString name_of_current_file();
+
+  /* Methods which are associated with the DCOP functionality of the
+     kmultipage. This method can be implemented by the multipage,
+     e.g. to jump to a certain location. */
+  virtual ASYNC  jumpToReference(const QString& /*reference*/);
+
+  /* Methods which are associated with the DCOP functionality of the
+     kmultipage. This method checks if a given file is loaded. */
+  bool   is_file_loaded(const QString& filename);
+
+  /* Opens file and sets URL
+
+     This method does the same as openFile, but sets the m_url of the
+     kmultipage. This can be important, for the following reason:
+     assume that a DVI is or DJVU-file is located on a web server at
+     baseURL=http://www.x.x/x.dvi The file may refer to external
+     graphic files using relative links.
+
+     The file is downloaded by the kviewpart to a temporary file on
+     the hard disk, say /tmp/t.dvi. The kviewpart would then call this
+     method with filename=/tmp/t.dvi and baseURL=http://www.x.x/x.dvi,
+     so the DVI-renderer knows to interpret the link to t.jpg as
+     http://www.x.x/t.jpg, and will download the file from there.
+
+     @warning This method is virtual only for technical reasons. Do
+     not re-implement this method
+
+     @returns true on success, false on failure
+  */
+  virtual bool openURL(const QString &filename, const KURL &base_url);
+
+  /** Prints a document
+
+  This method prints a document. The default implementation offers
+  fairly good printer support, but printing with the default
+  implementation is usually quite slow as tremendous amounts of data
+  needs to be transferred to the printer. To limit the data sent to
+  the printer, this default implementation prints only at low
+  resolution and produces mediocre quality. This method can (and
+  should) therefore be re-implemented if you have good code to convert
+  your document to PostScript.
+
+  Example: If your document consists of a single A4 page that contains
+  a DJVU image of 30KB, then the default implementation would render
+  the image in 600dpi, i.e. in about 7000x5000 pixel, and then send
+  this huge graphics uncompressed to the printer. A smart
+  implementation, on the other hand, would send the DJVU-file directly
+  to the printer, together with a DJVU decoder, which is implemented
+  in PostScript and uses only a few KB of memory, making for less than
+  40KB of data sent to the printer.
+
+  If you decide to re-implement this method, you need to decide if
+  your implementation will support the options offered by the "page
+  size & placement" tab of the print dialog. If these options are set,
+  pages that are smaller/larger than the printer's paper size will be
+  shrunk/enlarged and optionally centered on the paper.
+
+  If your implementation does not support the options, the following
+  code should be used:
+  @code
+  // Obtain a fully initialized KPrinter structure, and disable all
+  // entries in the "Page Size & Placement" tab of the printer dialog.
+  KPrinter *printer = getPrinter(false);
+  // Abort with an error message if no KPrinter could be initialized
+  if (printer == 0) {
+    kdError(4300) << "KPrinter not available" << endl;
+    return;
+  }
+
+  // Show the printer options dialog. Return immediately if the user
+  // aborts.
+  if (!printer->setup(parentWdg, i18n("Print %1").arg(m_file.section('/', -1)) )) {
+    delete printer;
+    return;
+  }
+
+  ...  <Produce a PostScript file, with filename, say, tmpPSFile. You
+  can use all the features that KPrinter has to offer. Note that
+  printer->pageList() gives a list of pages to be printed, where "1"
+  denotes the first page, "2" the second, etc.> ...
+
+  printer->printFiles( QStringList(tmpPSFile), true );
+  delete printer;
+  @endcode
+
+  If your implementation does support the options, code must be
+  provided to support the KPrinter options
+  "kde-kviewshell-shrinkpage", "kde-kviewshell-expandpage",
+  "kde-kviewshell-centerpage" and "kde-kviewshell-rotatepage". It is
+  important to note that "kde-kviewshell-rotatepage" and
+  "kde-kviewshell-centerpage" should by default treated as "true",
+  while the other options should be "false" by default. The following
+  code sees to that:
+  @code
+  // Obtain a fully initialized KPrinter structure, and enable all
+  // entries in the "Page Size & Placement" tab of the printer dialog.
+  KPrinter *printer = getPrinter(true);
+  // Abort with an error message if no KPrinter could be initialized
+  if (printer == 0) {
+    kdError(4300) << "KPrinter not available" << endl;
+    return;
+  }
+
+  // Show the printer options dialog. Return immediately if the user
+  // aborts.
+  if (!printer->setup(parentWdg, i18n("Print %1").arg(m_file.section('/', -1)) )) {
+    delete printer;
+    return;
+  }
+
+  if (printer->option( "kde-kviewshell-shrinkpage" ) == "true")
+    <Shrink some pages to paper size, where necessary>
+  if (printer->option( "kde-kviewshell-expandpage" ) == "true")
+    <Expand some pages to paper size, where necessary>
+  if (printer->option( "kde-kviewshell-centerpage" ) != "false") 
+    <Center pages on paper>
+  if (printer->option( "kde-kviewshell-rotatepage" ) != "false") 
+    <rotate pages by 90 deg. counterclockwise, if paper orientation is different from pages orientation>
+
+  ...  <Produce a PostScript file, with filename, say, tmpPSFile. You
+  can use all the features that KPrinter has to offer. Note that
+  printer->pageList() gives a list of pages to be printed, where "1"
+  denotes the first page, "2" the second, etc.> ...
+
+  printer->printFiles( QStringList(tmpPSFile), true ); 
+  delete printer;
+  @endcode 
+
+  For more information, see the default implementation in the source
+  file kmultipage.cpp. You might also look at the documentation to
+  getPrinter().
+  */
+  virtual void print();
+
+
+  /* Returns true if the document specifies page sizes, and false
+     otherwise. NOTE: the information returned by this method is not
+     always 100% reliable. Although unlikely, it is theoretically
+     possible that this method returns 'true', but still some of the
+     sizes returned by sizeOfPage() are invalid. */
+  virtual bool hasSpecifiedPageSizes() const {return renderer && renderer->hasSpecifiedPageSizes();}
+
+  /* This methos is similar to openFile(). It is used when the "Watch
+     file" option is activated, and the file has changed on disk. It
+     differs from openFile() in two aspects: first, the file is
+     checked for validity with DVIRenderer.isValidFile(m_file) if the
+     file is invalid, a timer event is used to call the method again
+     after a brief pause. Secondly, when the GUI is updated, the
+     implementation does not jump to the first page, but tries to keep
+     the current page. */
+  virtual void reload();
+
+// Interface definition start ------------------------------------------------
+
+  /** list of supported file formats, for saving
+      
+  This member must return the list of supported file formats for
+  saving. These strings returned must be in the format explained in
+  the documentation to KFileDialog::setFilter(), e.g. ""*.cpp *.cxx
+  *.c++|C++ Source Files". The use of mimetype-filters is allowed, but
+  discouraged. Among other penalties, if a multipage gives a
+  mimetype-filter, e.g. "application/x-dvi", the open file dialog in
+  kviewshell will not allow the user to see and select compressed
+  dvi-files.
+  */
+  virtual QStringList fileFormats() const = 0;
+
+  /// closes a file
+  virtual bool closeURL();
+
+  /* sets a zoom factor. The multipage implementation might refuse to
+   use a given zoom factor, even if it falls within the bounds given
+   by the constants MinZoom and MaxZoom which are defined in
+   zoomlimits.h. In that case, the multipage implementation chooses a
+   different zomm factor. The implementation returns the factor which
+   has actually been used. A default implementation is provided. */
+  virtual double setZoom(double z);
+  
+  /** reads in settings. Reimplementations must call this. */
+  virtual void readSettings();
+  
+  /** writes settings. Reimplementations must call this. */
+  virtual void writeSettings();
+  
+  /** Flag to indicate that this implementation has support for textserach and selection */
+  virtual bool supportsTextSearch() const { return getRenderer() && getRenderer()->supportsTextSearch(); }
+
+  /** Flag to indicate the document was modified since last saved
+
+      KMultiPage implementations that offer functionality that
+      modifies the document (e.g. remove or insert pages) must
+      re-implement this method to return 
+
+      @returns 'true' if the document was modified since it was last
+      saved
+  */
+  virtual bool isModified() const {return false;}
+
+  /* Returns the number of the first (i.e. top-left) page in the
+     display. Such a number cannot be reasonably assigned
+     (e.g. because the current document is empty, or because no
+     document has been loaded yet), the method returns "invalid page",
+     i.e. 0. */
+  virtual PageNumber currentPageNumber();
+
+  /* Returns the number of pages in the currently loaded document or
+     0, if no document is loaded or if the document is empty */
+  PageNumber numberOfPages() const {return renderer.isNull() ? (PageNumber)0 : renderer->totalPages();}
+
+  /* List of pages selected in the sidebar
+
+      @returns a list with the numbers of the currently selected
+      pages. */
+  virtual QValueList<int> selectedPages() {return markList()->selectedPages();}
+
+  virtual History* history() { return &document_history; }
+
+  /** Add pages to the KViewshell's central preferences dialog
+
+      This method can be re-implemented to add documenttype specific
+      configuration pages to the central preferences dialog. The
+      documentation to KConfigDialog explains how to do that.
+
+      The default implementation does nothing.
+
+      @param configDialog a pointer to the KConfigDialog the dialog to
+      add pages to
+  */
+  virtual void addConfigDialogs(KConfigDialog* configDialog) { Q_UNUSED(configDialog); }
+
+
+  /* These methods calculate the Zoomfactor needed to fit the pages
+     into the current viewport. Note that the return value need *not*
+     be within the limits defined in "zoomLimits.h". If they are not,
+     this indicates that fitting to width or height is currently not
+     possible (e.g. because no document is loaded). The return value
+     should then be ignored and any operation that relies on the
+     return value should be aborted. */
+  virtual double calculateFitToWidthZoomValue();
+  virtual double calculateFitToHeightZoomValue();
+
+  /* Returns the number of columns into which the widgets are aligned. */
+  virtual Q_UINT8 getNrColumns() const { return _scrollView->getNrColumns(); }
+  virtual Q_UINT8 getNrRows() const { return _scrollView->getNrRows(); }
+
+  virtual bool overviewMode() const { return _scrollView->overviewMode(); }
+
+  // =========== Interface definition ends
+
+  /* ---------------------------------------------------------------------
+     The following methods export functions of the DocumentPageCache which
+     are currently needed by KViewPart. TODO: Clean this up again without
+     directly linking DocumentPageCache to the KViewPart. */
+
+  /* Returns the size of page 'page'. If the document does not
+      specify a size (which happens, e.g., for some DVI-files), then
+      the userPreferredSize is returned. */
+  virtual SimplePageSize sizeOfPage(const PageNumber& page = 1) const { return pageCache->sizeOfPage(page); }
+  
+public slots:
+  /* Sets the userPreferredSize, which is explained below */
+  virtual void setUserPreferredSize(const SimplePageSize& t) { pageCache->setUserPreferredSize(t); }
+  virtual void setUseDocumentSpecifiedSize(bool b) { pageCache->setUseDocumentSpecifiedSize(b); }
+  // --------------------------------------------------------------------
+
+protected:
+  /** Update GUI after loading or closing of a file
+
+      This method is called by openFile() when a new file was loaded,
+      and by closeURL() when a file is closed so that the kmultipage
+      implementation can update its own GUI, enable/disable actions,
+      prepare info texts, etc. At the time the method is executed, the
+      file has already been loaded into the renderer using
+      renderer.setFile(), or closed using renderer.clear() and the
+      standard KMultiPage GUI is set up. The filename can be accessed
+      via m_file.
+
+      The default implementation does nothing.
+
+      @param success the return value of renderer.setFile() which
+      indicates if the file could be successfully loaded by the
+      renderer, or not. Note that setFile() is called even if the
+      renderer returned 'false', so that the implemtation can then
+      disable menu items, etc. */
+  virtual void setFile(bool success);
+
+  /* Creates new instances of DocumentWidget. If you need special
+     functionality and reimplement the DocumentWidget class, then you
+     should also reimplement this method to ensure that your new
+     DocumentWidgets will be used. This function is also the right
+     place to connect to signals emitted by DocumentWidget. */
+  virtual DocumentWidget* createDocumentWidget();
+
+  /* Used to enable/disable KActions of multiPage implementations.
+     enableActions(true) should be called whenever a file is
+     successfully loaded.  enableActions(false) is called when the
+     file is closed. */
+  virtual void enableActions(bool);
+
+  /* Initializes all data structures that need to know the renderer.
+     This function must be called in the constructor of multipage
+     implementations. */
+  void setRenderer(DocumentRenderer*);
+
+  /** This function creates the page cache. If a multipage implementation needs
+     additional functionaly from the cache overwrite this function to create a
+     subclass of DocumentPageCache.
+     @warning This function is called by the constructor, never call it explicitly.
+  */
+  virtual void initializePageCache();
+
+  /* Returns a pointer to the renderer. */
+  virtual QGuardedPtr<DocumentRenderer> getRenderer() const { return renderer; }
+
+  PageView* scrollView() { return _scrollView; }
+
+  MarkList* markList() { return _markList; }
+
+  // The next two functions are used for the autozoom feature
+  // TODO optimize (the calculation of the widest page needs to be done only once
+  // per document, not everytime calculateFitToWidthZoomValue() is called)
+  PageNumber widestPage() const;
+
+  // TODO Generalize this for more than 2 columns
+  double zoomForWidthColumns(unsigned int viewportWidth) const;
+
+public slots:
+  virtual void doSelectAll();
+
+  virtual void clearSelection();
+
+  virtual void copyText();
+
+  /** Exports the document to a plain text file. */
+  virtual void doExportText();
+
+  /* Shows the "text search" dialog, if text search is supported by
+     the renderer. Otherwise, the method returns immediately. */
+  virtual void showFindTextDialog();
+
+
+  /* This method may be called after the text search dialog
+     'findDialog' has been set up, and the user has entered a search
+     phrase. The method searches for the next occurence of the text,
+     starting from the beginning of the current page, or after the
+     currently selected text, if there is any. */
+  virtual void findNextText();
+
+  /* This method may be called after the text search dialog
+     'findDialog' has been set up, and the user has entered a search
+     phrase. The method searches for the next occurence of the text,
+     starting from the end of the current page, or before the
+     currently selected text, if there is any. */
+  virtual void findPrevText();
+
+  /** Opens a file requestor and starts a basic copy KIO-Job. A
+      multipage implementation that wishes to offer saving in various
+      formats must re-implement this slot. */
+  virtual void slotSave();
+
+  /* The standard implementation just calls slotSave. */
+  virtual void slotSave_defaultFilename();
+
+  /* Initialize/Update PageWidgets, thumbnail list and bookmark list
+
+  This slot is called after a document was loaded, when the
+  document was modified (e.g. when pages were deleted), or the
+  rendering mode is changed (e.g. when a different accessibility
+  viewmode is selected). The following is done
+
+  - The page cache is cleared
+
+  - all page widgets as well as the thumbnails are updated.
+  */
+  void renderModeChanged();
+
+  /* Empties the page cache and --as the name suggests-- repaints all
+     visible widgets. */
+  void repaintAllVisibleWidgets();
+
+  /* Tells the multipage if scrollbars should be used. */
+  virtual void slotShowScrollbars(bool);
+
+  /* Show or hide the sidebar widget. */
+  virtual void slotShowSidebar(bool);
+
+  /* Show or hide thumbnails. */
+  virtual void slotShowThumbnails(bool);
+
+  /* Used internally. */
+  void slotIOJobFinished ( KIO::Job *job );
+
+  /* Switches to fullscreen mode and back. */
+  virtual void slotSetFullPage(bool fullpage);
+
+  virtual void setViewMode(int);
+
+  /* Is called if settings are changed in the configuration dialog.
+     If this method is reimplemented in a child class, it needs to be
+     called from there. */
+  virtual void preferencesChanged();
+
+  /* Page Navigation. */
+  virtual bool gotoPage(const PageNumber& page);
+  virtual void gotoPage(const Anchor& a);
+
+  virtual void prevPage();
+  virtual void nextPage();
+  virtual void firstPage();
+  virtual void lastPage();
+
+  virtual void scrollUp();
+  virtual void scrollDown();
+  virtual void scrollLeft();
+  virtual void scrollRight();
+
+  virtual void scrollUpPage();
+  virtual void scrollDownPage();
+  virtual void scrollLeftPage();
+  virtual void scrollRightPage();
+
+  virtual void readUp();
+  virtual void readDown();
+
+  virtual void doGoBack();
+  virtual void doGoForward();
+
+  /* Scrolls the main scrollview by deltaInPixel (positive values
+     scroll DOWN). If the user tries to scroll past the beginning or
+     the end of a page, then the method either returns without doing
+     anything (if the current page is the first or last page, resp, or
+     if the method is called within 200ms after the beg. or end of the
+     page was reached), or goes the the next/previous page. The delay
+     makes it a little easier for the user to scroll with the mouse
+     wheel or the keyboard without involuntarily moving to another
+     page. */
+  virtual void scroll(Q_INT32 deltaInPixel);
+
+  virtual void slotEnableMoveTool(bool enable);
+
+protected slots:
+  virtual bool gotoPage(const PageNumber& page, int y, bool isLink = true);
+
+  /* Make the selection visible */
+  void gotoPage(const TextSelection&);
+
+private slots:
+   void         handleLocalLink(const QString &linkText);
+
+signals:
+  /** Emitted with argument "true" when the move tool is selected, and
+      with argument "false" if selection tool is selected. */
+  void enableMoveTool(bool enable);
+
+  /* Emitted when a page has been selected in the MarkList. */
+  void selected(const PageNumber& pageNumber);
+
+  /* Emitted to indicate the number of pages in the file and the
+     current page. The receiver will not change or update the display,
+     nor call the gotoPage()-method. */
+  void pageInfo(int nr, int currpg);
+
+  void askingToCheckActions();
+
+  /* emitted when a new preview is available */
+  void previewChanged(bool previewAvailable);
+
+  void viewModeChanged();
+
+  /* Emitted when the zoom of the pageview changes. */
+  void zoomChanged();
+
+  void zoomOut();
+  void zoomIn();
+
+  /* Emitted it the status of the text selection changes. */
+  void textSelected(bool);
+
+  void searchEnabled(bool);
+
+// Interface definition end --------------------------------------------------
+
+public slots:
+  virtual void generateDocumentWidgets(const PageNumber& startPage = PageNumber::invalidPage);
+
+ protected slots:
+  /* This is the slot where mouseWheel events are processed that come
+     from the multipage/scrollview. This method calles scroll, a
+     delta-value of 120 (i.e. one notch on a standard wheel mouse)
+     scrolls by two 'lines'. */
+  void wheelEvent(QWheelEvent *);
+
+protected:
+  /** Allocates and initializes a KPrinter structure
+
+  This method is used in implementations of the print() method. See
+  the documentation of print() for more information and for example
+  code.  This method allocates and initializes a KPrinter
+  structure. The list of pages marked in the sidebar is already set in
+  the "kde-range" option in the KPrinter structure. In this option "1"
+  means: first page of the document, "2" the second, etc.
+  
+  @param enablePageSizeFeatures Enables or diables the entries in the
+  "Page Size & Placement" tab of the print dialog.
+
+  @returns a pointer to a KPrinter, or 0 if no KPrinter could be
+  allocated.
+
+  @warning The KPrinter allocated is owned by the caller must be
+  deleted before the KMultiPage is deleted. Otherwise, a segfault will
+  occur.
+  */
+  KPrinter *getPrinter(bool enablePageSizeFeatures=true);
+
+
+  /** Pointer to the parent widget 
+
+  This pointer is automatically set by the constructor.
+  */
+  QGuardedPtr<QWidget> parentWdg;
+
+  QPtrVector<DocumentWidget> widgetList;
+
+  History document_history;
+
+  /* Variable which is used internally by the method
+     currentPageNumber() to provide 'lazy' page numbers. */
+  PageNumber lastCurrentPage;
+
+  /* The pageCache caches already drawn "documentPages" and invokes
+     the renderer if the needed page is not available in the cache. */
+  DocumentPageCache* pageCache;
+
+private slots:
+  void setCurrentPageNumber(const PageNumber&);
+  void updateWidgetSize(const PageNumber&);
+
+  /* Interrupts a search if one is currently performed, otherwise
+     hide the search panel */
+  void stopSearch();
+
+private:
+  /* For internal use by the reload()-method. See the comments in
+     kmultipage.cpp, right before the timerEvent function. */
+  int  timer_id;
+
+  /* For internal use the reload()-method. This is a dreadful
+     hack. The problem we adress with this timer event is the
+     following: the kviewshell has a KDirWatch object which looks at
+     the DVI file and calls reload() when the object has changed. That
+     works very nicely in principle, but in practise, when TeX runs
+     for several seconds over a complicated file, this does not work
+     at all. First, most of the time, while TeX is still writing, the
+     file is invalid. Thus, reload() is very often called when the DVI
+     file is bad. We solve this problem by checking the file first. If
+     the file is bad, we do not reload. Second, when the file finally
+     becomes good, it very often happens that KDirWatch does not
+     notify us anymore. Whether this is a bug or a side effect of a
+     feature of KDirWatch, I dare not say. We remedy that problem by
+     using a timer: when reload() was called on a bad file, we
+     automatically come back (via the timerEvent() function) every
+     second and check if the file became good. If so, we stop the
+     timer. It may well happen that KDirWatch calls us several times
+     while we are waiting for the file to become good, but that does
+     not do any harm. */
+  void timerEvent( QTimerEvent *e );
+
+  /* This method opens a file and sets up the GUI when the file is
+     loaded. It calls setFile() so that implementations of kmultipage
+     can  update their own GUI. DO NOT REIMPLEMENT THIS METHOD. */
+  bool openFile();
+
+  /* Is set by setRenderer. */
+  QGuardedPtr<DocumentRenderer> renderer;
+
+  PageView *_scrollView;
+  SearchWidget* searchWidget;
+  QToolBox* sideBar;
+
+  MarkList* _markList;
+  TableOfContents* tableOfContents;
+
+  QSplitter* splitterWidget;
+
+  /* This timer is used to implement a brief delay when the user
+     scrolls past the beginning or the end of the page before a the
+     program moves to a new page. That way, it is a little easier for
+     the user to scroll with the mouse wheel or the keyboard without
+     involuntarily moving to another page. The timer is used in the
+     scroll() method. */
+  QTimer changePageDelayTimer;
+
+  // This is set to true while a text search is performed.
+  // If set to false the search is interrupted.
+  bool searchInProgress;
+};
+
+
+#endif