• Skip to content
• Skip to link menu

KDE 3.5 API Reference

• KDE API Reference
• API Reference

• Sitemap
• Contact Us

 

kviewshell

kmultipage.h

Go to the documentation of this file.

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


// 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);

  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 ------------------------------------------------

  virtual QStringList fileFormats() const = 0;

  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);
  
  virtual void readSettings();
  
  virtual void writeSettings();
  
  virtual bool supportsTextSearch() const { return getRenderer() && getRenderer()->supportsTextSearch(); }

  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; }

  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:
  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*);

  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();

  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();

  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:
  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:
  KPrinter *getPrinter(bool enablePageSizeFeatures=true);


  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

kviewshell

Skip menu "kviewshell"

• Main Page
• Namespace List
• Class Hierarchy
• Alphabetical List
• Class List
• File List
• Namespace Members
• Class Members

API Reference

Skip menu "API Reference"

• kviewshell

Generated for API Reference by doxygen 1.5.9
This website is maintained by Adriaan de Groot and Allen Winter.
KDE^® and the K Desktop Environment^® logo are registered trademarks of KDE e.V. | Legal