You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdegraphics/kviewshell/renderedDocumentPage.h

242 lines
8.3 KiB

// -*- C++ -*-
//
// Class: documentPage
//
// Widget for displaying TeX DVI files.
// Part of KDVI- A previewer for TeX DVI files.
//
// (C) 2004-2005 Stefan Kebekus. Distributed under the GPL.
#ifndef _rendereddocumentpage_h_
#define _rendereddocumentpage_h_
#include "pageNumber.h"
#include <tqobject.h>
#include <tqstring.h>
#include <tqvaluevector.h>
class Hyperlink;
class TQPainter;
class TQRect;
class TQRegion;
class TextBox;
class TextSelection;
/** @short Represents a page in a document, contains the page's graphical
representation and resolution-dependent information.
This abstract class represents a page in a document. Its
implementations contain graphical representations of document pages,
and resolution-dependent information. The most important members are
- the page number
- a vector that contains hyperlinks
- a vector for source hyperlinks; this vector is currently used by
KDVI only, and is therefore not documented much here.
- a vector that contains the document text together with
information about the position of the text on the page. This
information is used in kviewshell e.g. for selecting text with the
mouse or for the "export as text..." functionality
- the implementations of the documentPage will also contain a
TQPaintDevice, onto which the graphical representation of the page
is rendered. This could for instance be a TQPixmap, if the page is
to be displayed on a computer screen, or a TQPrinter for printing.
The kviewshell program uses the documentPage class in the
following manner: first, it is constructed, the page number is
invalid. The page number is then set to a reasonable value using
the setPageNumber() method. After this, the
documentRenderer.drawPage() method of an implementation of the
documentRenderer is used to render a graphical representation into
the TQPaintDevice at a given resolution, and to fill the
(source-)hyperlink and text vectors, which are also
resolution-dependent. After the data has been used, the
documentPage is clear()ed, perhaps a new page number set, and
documentRenderer.drawPage() is used again.
@author Stefan Kebekus <kebekus@kde.org>
@version 1.0.0
*/
class RenderedDocumentPage : public QObject
{
Q_OBJECT
public:
/** \brief Default constructor
The default constructor constructs a RenderedDocumentPage whose pageNumber
is invalid. It sets the member 'isEmpty' to 'true'.
*/
RenderedDocumentPage();
virtual ~RenderedDocumentPage();
/** \brief Set page number
This method sets the number of the page that this instance
represents. A value of '0' means that this class does not represent
any page ('invalid page'). This method also calls clear().
*/
void setPageNumber(const PageNumber& pagenr);
/** \brief Get page number
@returns The number of the page that this instance represents.
*/
PageNumber getPageNumber() const {return pageNr;}
/** \brief Get paint device
This method is used for instance by the documentRenderer.drawPage()
method to draw on the page. It returns a pointer to a TQPainter (in
most implementation a painter on either a TQPixmap, or a
TQPrinter). The pointer returned points to an active TQPainter and is
valid as long as *this RenderedDocumentPage exists. The pointer
returned must not be deleted nor should TQPainter::end() be
called. Instead, the method returnPainter() must be called as soon
as drawing is finished.
In short, to draw on a renderedDocumentPage, you do the following:
@code
RenderedDocumentPage rdp;
TQPainter *paint = rdp.getPainter()
if (paint != 0) {
<Do some painting, don't call paint->end() >
rdp.returnPainter(paint);
}
@endcode
@warning Before the pointer has been returned by the returnPainter()
method, all subsequent calls to getPainter() will return undefined
results. Do not delete a renderedDocumentPage when you still hold a
pointer. Call returnPainter() first.
@returns A pointer to a TQPainter (in most implementation a painter
on either a TQPixmap, or a TQPrinter), or NULL, if painting is not
possible. The TQPainter object is owned by the RenderedDocumentPage.
*/
virtual TQPainter *getPainter() = 0;
/** \brief Returns a pointer to the paint device.
See the documentation to the getPainter() method for an explanation
@see getPainter
@warning Returning a pointer twice, or returning arbitrary pointers
will lead to a segfault.
@param pt a pointer to a TQPainter, as returned by the getPainter()
method
*/
virtual void returnPainter(TQPainter *pt) = 0;
/** \brief Returns the size of the page in pixel. */
virtual TQSize size() = 0;
/** \brief Returns the width of the page in pixel.
@warning If you are implementing DocumentRenderer::drawPage(), it
may be tempting to compute the image size in pixel, using
page->height() and page->width(). DON'T DO THAT. KViewShell uses
transformations e.g. to rotate the page, and sets the argument
'resolution' accordingly; these changes are not reflected in
page->height() and page->width(). Similar problems occur if
KViewShell required a shrunken version of the page, e.g. to print
multiple pages on one sheet of paper. See the documentation of
DocumentRenderer::drawPage() to learn how to compute the sizes
properly.
*/
virtual int width() {return size().width(); }
/** \brief Returns the height of the page in pixel.
@warning If you are implementing DocumentRenderer::drawPage(), it
may be tempting to compute the image size in pixel, using
page->height() and page->width(). DON'T DO THAT. KViewShell uses
transformations e.g. to rotate the page, and sets the argument
'resolution' accordingly; these changes are not reflected in
page->height() and page->width(). Similar problems occur if
KViewShell required a shrunken version of the page, e.g. to print
multiple pages on one sheet of paper. See the documentation of
DocumentRenderer::drawPage() to learn how to compute the sizes
properly.
*/
virtual int height() {return size().height(); }
/** \brief Text contained in the document page
This vector contains the document text together with information
about the position of the text on the page. This information is
generated by the documentRenderer.drawPage() method. It is used in
kviewshell e.g. for selecting text with the mouse or for the "export
as text..." functionality.
*/
TQValueVector<TextBox> textBoxList;
/** \brief Calculates the text selected by the given rectangle. */
TextSelection select(const TQRect&);
/** \brief Selects the character which lies at the given point. */
TextSelection select(const TQPoint&);
TQRegion selectedRegion(const TextSelection& selection);
/** Finds the first occurence of str starting by the current index.
If the text is found a corresponding TextSelection is returned.
If the text is not found a empty selection is returned. */
TextSelection find(const TQString& str, int index = 0, bool caseSensitive = true);
/** Finds the first occurence of str starting by the current index searching backwards.
If the text is found a corresponding TextSelection is returned.
If the text is not found a empty selection is returned.
If index < 0 start the search at the end of the page. */
TextSelection findRev(const TQString& str, int index = 0, bool cs = true);
/** \brief Hyperlinks on the document page
This vector contains the hyperlinks that appear on the page. This
information is generated by the documentRenderer.drawPage()
method. It is used in kviewshell so users can use the mouse to
navigate in the document through hyperlinks.
*/
TQValueVector<Hyperlink> hyperLinkList;
// set to 'false' in the constructor, set to 'true' by the renderer,
// if something really has been rendered
bool isEmpty;
/** \brief Clears the data structures
Clears the contents of the class, but leaves pageNumber intact. For
performance reasons, it does not free the memory for the
QValueVectors so that lengthy re-allocations won't be necessary
later.
*/
virtual void clear();
private:
/** \brief Page number
Number of the page that this instance represents a value of '0'
means that this class does not represent any page.
*/
PageNumber pageNr;
TQString pageText;
};
#endif