RenderedDocumentPage Class Reference

Represents a page in a document, contains the page's graphical representation and resolution-dependent information. More...

#include <renderedDocumentPage.h>

Inheritance diagram for RenderedDocumentPage:

[legend]

List of all members.


Public Member Functions
virtual void	clear ()
TextSelection	find (const QString &str, int index=0, bool caseSensitive=true)
TextSelection	findRev (const QString &str, int index=0, bool cs=true)
PageNumber	getPageNumber () const
virtual QPainter *	getPainter ()=0
virtual int	height ()
	RenderedDocumentPage ()
virtual void	returnPainter (QPainter *pt)=0
TextSelection	select (const QPoint &)
TextSelection	select (const QRect &)
QRegion	selectedRegion (const TextSelection &selection)
void	setPageNumber (const PageNumber &pagenr)
virtual QSize	size ()=0
virtual int	width ()
virtual	~RenderedDocumentPage ()
Public Attributes
QValueVector< Hyperlink >	hyperLinkList
bool	isEmpty
QValueVector< TextBox >	textBoxList

Detailed Description

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 QPaintDevice, onto which the graphical representation of the page is rendered. This could for instance be a QPixmap, if the page is to be displayed on a computer screen, or a QPrinter 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 QPaintDevice 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

Definition at line 67 of file renderedDocumentPage.h.

Constructor & Destructor Documentation

RenderedDocumentPage::RenderedDocumentPage ( )

Default constructor.

The default constructor constructs a RenderedDocumentPage whose pageNumber is invalid. It sets the member 'isEmpty' to 'true'.

Definition at line 19 of file renderedDocumentPage.cpp.

RenderedDocumentPage::~RenderedDocumentPage ( ) [virtual]

Definition at line 28 of file renderedDocumentPage.cpp.

Member Function Documentation

void RenderedDocumentPage::clear ( void ) [virtual]

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.

Definition at line 41 of file renderedDocumentPage.cpp.

TextSelection RenderedDocumentPage::find	(	const QString &	str,
		int	index = `0`,
		bool	caseSensitive = `true`
	)

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.

Definition at line 219 of file renderedDocumentPage.cpp.

TextSelection RenderedDocumentPage::findRev	(	const QString &	str,
		int	index = `0`,
		bool	cs = `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.

Definition at line 294 of file renderedDocumentPage.cpp.

PageNumber RenderedDocumentPage::getPageNumber ( ) const [inline]

Get page number.

Returns:: The number of the page that this instance represents.

Definition at line 93 of file renderedDocumentPage.h.

virtual QPainter* RenderedDocumentPage::getPainter ( ) [pure virtual]

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 QPainter (in most implementation a painter on either a QPixmap, or a QPrinter). The pointer returned points to an active QPainter and is valid as long as *this RenderedDocumentPage exists. The pointer returned must not be deleted nor should QPainter::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:

  RenderedDocumentPage rdp;

  QPainter *paint = rdp.getPainter()
  if (paint != 0) {
  
    <Do some painting, don't call paint->end() >
  
    rdp.returnPainter(paint);
  }

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 QPainter (in most implementation a painter on either a QPixmap, or a QPrinter), or NULL, if painting is not possible. The QPainter object is owned by the RenderedDocumentPage.

Implemented in RenderedDocumentPagePixmap, and RenderedDocumentPagePrinter.

virtual int RenderedDocumentPage::height ( ) [inline, virtual]

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.

Reimplemented in RenderedDocumentPagePixmap.

Definition at line 176 of file renderedDocumentPage.h.

virtual void RenderedDocumentPage::returnPainter ( QPainter * pt ) [pure virtual]

Returns a pointer to the paint device.

See the documentation to the getPainter() method for an explanation

See also:: getPainter

Warning:: Returning a pointer twice, or returning arbitrary pointers will lead to a segfault.

Parameters:

pt

a pointer to a QPainter, as returned by the getPainter() method

Implemented in RenderedDocumentPagePixmap, and RenderedDocumentPagePrinter.

TextSelection RenderedDocumentPage::select ( const QPoint & point )

Selects the character which lies at the given point.

Definition at line 190 of file renderedDocumentPage.cpp.

TextSelection RenderedDocumentPage::select ( const QRect & selectedRectangle )

Calculates the text selected by the given rectangle.

Definition at line 156 of file renderedDocumentPage.cpp.

QRegion RenderedDocumentPage::selectedRegion ( const TextSelection & selection )

Definition at line 55 of file renderedDocumentPage.cpp.

void RenderedDocumentPage::setPageNumber ( const PageNumber & pagenr )

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

Definition at line 34 of file renderedDocumentPage.cpp.

virtual QSize RenderedDocumentPage::size ( ) [pure virtual]

Returns the size of the page in pixel.

Implemented in RenderedDocumentPagePixmap, and RenderedDocumentPagePrinter.

virtual int RenderedDocumentPage::width ( ) [inline, virtual]

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.

Reimplemented in RenderedDocumentPagePixmap.

Definition at line 161 of file renderedDocumentPage.h.

Member Data Documentation

QValueVector<Hyperlink> RenderedDocumentPage::hyperLinkList

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.

Definition at line 214 of file renderedDocumentPage.h.

bool RenderedDocumentPage::isEmpty

Definition at line 218 of file renderedDocumentPage.h.

QValueVector<TextBox> RenderedDocumentPage::textBoxList

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.

Definition at line 186 of file renderedDocumentPage.h.

The documentation for this class was generated from the following files:

kviewshell

RenderedDocumentPage Class Reference

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

kviewshell

API Reference