KDE 3.5 API Reference kviewshell
DocumentRenderer Class Reference
loads and renders documents More...
#include <documentRenderer.h>
Detailed Description
loads and renders documentsThis abstract class is one of the two core classes that must be implemented by all authors who write plugins for the kviewshell programm. It is responsible for document loading and rendering. As a minimum, the setFile() and drawPage() must be reimplemented.
This documentation mentiones only the methods and members that are important for authors of plugins. For full documentation, consult the header file documentRenderer.h.
- Warning:
- Future versions of kviewshell will use threading to keep the GUI responsive while pages are rendered. As a result, IT IS ABSOLUTELY NECESSARY that your implementation is THREAD-SAFE, if not, this can result in infrequent and very hard-to-find crashes of your programm. Use the member mutex to make your implemetation thread-safe.
Definition at line 51 of file documentRenderer.h.
Constructor & Destructor Documentation
| DocumentRenderer::DocumentRenderer | ( | QWidget * | parent | ) |
| DocumentRenderer::~DocumentRenderer | ( | ) | [virtual] |
Definition at line 28 of file documentRenderer.cpp.
Member Function Documentation
| void DocumentRenderer::clear | ( | ) | [virtual] |
clearing the document renderer
This method clears the renderer, so that it represents an empty document. The standard implementation doe the following:
- sets 'numPages' to zero
- clears the pageSizes and the anchorList
- sets _isModified to 'false'
Most authors of kviewshell-plugins will probably want to re-implement this to clear internal data structures of their implementations.
- Warning:
- Future versions of kviewshell will use threading to keep the GUI responsive while pages are rendered. As a result, IT IS ABSOLUTELY NECESSARY that your implementation is THREAD-SAFE, if not, this can result in infrequent and very hard-to-find crashes of your programm. Use the member mutex to make your implemetation thread-safe.
Definition at line 37 of file documentRenderer.cpp.
| void DocumentRenderer::documentIsChanged | ( | ) | [signal] |
signals that the document is changed
This signal can be emitted if the document or status of this class changed internally so that all associated widgets should be repainted. This could be emitted, e.g. if pages are removed from a document, or if some preferences change that have some direct influence on the way the document is rendered.
When this signal is emitted, the whole GUI setup is re-computed, and all widgets are re-drawn. This can take considerable time.
| virtual void DocumentRenderer::drawPage | ( | double | resolution, | |
| RenderedDocumentPage * | page | |||
| ) | [pure virtual] |
rendering of documents
This purely virtual method is the most important method in the DocumentRenderer class. It must be re-implemented by authors who want to write plugins for the kviewshell program. The purpose of this method is to render a graphical representation into a documentPage structure. More specifically, the implementation needs to
- call the documentPage::clear() on *page
and the do all of the following, in no particular order
- obtain the pointer to the QPaintDevice from the documentPage using the documentPage::getPaintDevice() method and draw a graphical representation of the page number page->getPageNumber() into the QPaintDevice, using the given resolution. If the member accessibilityBackground is true, the accessibilityBackgroundColor should be used for a background color, if possible. Otherwise, white should be used, if possible. If you need to compute the size of the page in pixel, do this as follows: Don't use page->height() or page->width() to calculate the sizes ---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.
SimplePageSize psize = pageSizes[page->getPageNumber() - 1]; if (psize.isValid()) { int width_in_pixel = resolution * psize.width().getLength_in_inch(); int height_in_pixel = resolution * psize.height().getLength_in_inch(); <...> }
- if your document contains hyperlinks, fill the documentPage::hyperLinkList with HyperLinks, using pixel coordinates for the coordinates in the Hyperlink::box member of the Hyperlink. The Hyperlink::baseline member of the Hyperlink can be ignored. The linkText member of the Hyperlink should either be an absolute URL ("http://www.kde.org"), or be of the form "#anch", where the string "anch" is contained in the anchorList.
- if your plugin supports full-text information, fill documentPage::textLinkList with HyperLinks, using pixel coordinates for the coordinates in the Hyperlink::box and Hyperlink::baseline members of the Hyperlink. The entries in the documentPage::textLinkList should have a natural ordering, "first text first" (left-to-right, up-to-down for western languages, right-to-left for hebrew, etc.). This is important so that text selection with the mouse works properly, and only continuous blocks of text can be selected.
- Note:
- This method is often called in a paintEvent, so that care must be taken to return as soon as possible. No user interaction should be done during the execution.
If your plugin supports full-text information, you probably want to re-implement the method supportsTextSearch() below.
- Warning:
- As mentioned above, 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.
The signal documentIsChanged() must not be emitted while the method runs.
Future versions of kviewshell will use threading to keep the GUI responsive while pages are rendered. As a result, IT IS ABSOLUTELY NECESSARY that your implementation is THREAD-SAFE, if not, this can result in infrequent and very hard-to-find crashes of your programm. Use the member mutex to make your implemetation thread-safe.
- Parameters:
-
resolution this argument contains the resolution of the display device. In principle. In fact, kviewshell implements zooming by using values that are not exactly the resolution of the display, but multiplied with the zoom factor. Bottom line: the DocumentRenderer should act as if this field indeed contains resolution of the display device. page pointer to a documentPage structure that this method rendered into.
Implemented in EmptyRenderer, and DjVuRenderer.
| void DocumentRenderer::drawThumbnail | ( | double | resolution, | |
| RenderedDocumentPage * | page | |||
| ) | [virtual] |
rendering of documents at thumbnail size
This method is used to draw thumbnails. The standared implementations just calls 'drawPage' to do the job. Reimplement this if the used fileformat has embedded thumbnails.
- Warning:
- Future versions of kviewshell will use threading to keep the GUI responsive while pages are rendered. As a result, IT IS ABSOLUTELY NECESSARY that your implementation is THREAD-SAFE, if not, this can result in infrequent and very hard-to-find crashes of your programm. Use the member mutex to make your implemetation thread-safe.
Definition at line 74 of file documentRenderer.cpp.
Definition at line 120 of file documentRenderer.cpp.
Definition at line 165 of file documentRenderer.h.
| void DocumentRenderer::getText | ( | RenderedDocumentPage * | page | ) | [virtual] |
quick extraction of text information
This method returns the textinformation of the current page if available. It is only called when the page pixmap is not of interest, so it is possible to implement it much more efficiently then the drawPage() method.
The default implementation just calls drawPage().
- Warning:
- Future versions of kviewshell will use threading to keep the GUI responsive while pages are rendered. As a result, IT IS ABSOLUTELY NECESSARY that your implementation is THREAD-SAFE, if not, this can result in infrequent and very hard-to-find crashes of your programm. Use the member mutex to make your implemetation thread-safe.
- Parameters:
-
page pointer to a documentPage structure that this method rendered into.
Reimplemented in DjVuRenderer.
Definition at line 82 of file documentRenderer.cpp.
| bool DocumentRenderer::hasSpecifiedPageSizes | ( | ) | const [inline] |
Definition at line 178 of file documentRenderer.h.
| bool DocumentRenderer::isEmpty | ( | ) | const [inline] |
Definition at line 155 of file documentRenderer.h.
| bool DocumentRenderer::isModified | ( | ) | const [inline] |
Definition at line 158 of file documentRenderer.h.
| bool DocumentRenderer::isValidFile | ( | const QString & | fileName | ) | const [virtual] |
Definition at line 88 of file documentRenderer.cpp.
Definition at line 94 of file documentRenderer.cpp.
| void DocumentRenderer::setAccessibleBackground | ( | bool | accessibleMode, | |
| const QColor & | background = QColor(255, 255, 255) | |||
| ) |
Definition at line 49 of file documentRenderer.cpp.
| virtual bool DocumentRenderer::setFile | ( | const QString & | fname, | |
| const KURL & | base | |||
| ) | [pure virtual] |
loading of files
This is a purely virtual method that must be re-implemented. It is called when a file should be loaded. The implementation must then do the following
- initialize internal data structures so the document pointed to by 'fname' can be rendered quickly. It is not necessary actually load the file; if the implementation choses to load only parts of a large file and leave the rest on the disc, this is perfectly fine.
- return 'true' on success and 'false' on failure. Before 'false' is returned, the method clear() should be called
When the method returns 'true', it is expected that
- the member _isModified is set to 'false'
- the member 'numPages' is either set to 0 if the document is empty, or else to the number of page in the document
- the vector pageSizes *must* either be empty (e.g. if your file format does not specify a page size), or must be of size totalPages(), and contain the sizes of all pages in the document.
- the anchorList is filled with data; it is perfectly fine to leave the anchorList empty, if your file format does not support anchors, or if your document doesn't contain any.
- the list 'bookmarks' is filled with data; it is perfectly fine to leave this list empty, if your file format does not support bookmarks or if your document doesn't contain any.
- the method drawPage() works
- Note:
- It is perfectly possible that setFile() is called several times in a row, with the same or with different filenames.
- Warning:
- The signal documentIsChanged() must not be emitted while the method runs.
Future versions of kviewshell will use threading to keep the GUI responsive while pages are rendered. As a result, IT IS ABSOLUTELY NECESSARY that your implementation is THREAD-SAFE, if not, this can result in infrequent and very hard-to-find crashes of your programm. Use the member mutex to make your implemetation thread-safe.
- Parameters:
-
fname name of the file to open. It is not guaranteed that the file exists, that it is a file, or that it is readable. base original URL of the file that was opened.
- Returns:
- 'true' on success and 'false' on failure. Even after this method returns 'false' the class must act reasonably, i.e. by clear()ing the document
Implemented in EmptyRenderer, and DjVuRenderer.
| void DocumentRenderer::setStatusBarText | ( | const QString & | ) | [signal] |
sets text in the statusbar
This signal is emitted when the renderer needs to inform the user via the status bar. Since the status bar is not always visible, and since the duration that the message is shown is not quite specified, this should not be used for important information.
| SimplePageSize DocumentRenderer::sizeOfPage | ( | const PageNumber & | page | ) |
Definition at line 58 of file documentRenderer.cpp.
| virtual bool DocumentRenderer::supportsTextSearch | ( | ) | const [inline, virtual] |
Flag to indicate if full text is supported.
If your implementation of the drawPage() method supports full-text information and writes to the documentPage::textLinkList, this method should be re-implemented to return 'true'. The text-search and text-selection utilities will then be enabled in the GUI.
The default implementation returns 'false'.
Reimplemented in DjVuRenderer.
Definition at line 316 of file documentRenderer.h.
| PageNumber DocumentRenderer::totalPages | ( | ) | const [inline] |
Definition at line 163 of file documentRenderer.h.
Member Data Documentation
bool DocumentRenderer::_isModified [protected] |
Flag if document is modified.
This flag indicates if the document was modified after it was loaded. It is set to 'false' in the constructor, in the clear() and setFile() method. It can be set to 'true' be methods that modify the document (e.g. the deletePages() method of the djvu implementation of this class).
Definition at line 475 of file documentRenderer.h.
bool DocumentRenderer::accessibilityBackground [protected] |
specifies if accessibilityBackgroundColor should be used
If true, the drawPage() and drawThumbnail() methods should use accessibilityBackgroundColor as the backgroundcolor of the pages.
Definition at line 457 of file documentRenderer.h.
QColor DocumentRenderer::accessibilityBackgroundColor [protected] |
background color, to be used for visibly impaired users
If accessibilityBackground is true, the drawPage() and drawThumbnail() methods should use this color as the backgroundcolor of the pages.
Definition at line 465 of file documentRenderer.h.
QMap<QString, Anchor> DocumentRenderer::anchorList [protected] |
map of anchors in a document.
This map contains the anchors that are contained in the document. The values in this map are set by the setFile() method, and cleared by the constructor and the clear() method.
Definition at line 442 of file documentRenderer.h.
QPtrList<Bookmark> DocumentRenderer::bookmarks [protected] |
bookmarks
This (ordered!) list contains the bookmarks that are contained in the document. The values in this vector are set by the setFile() method, and cleared by the constructor and the clear() method.
Definition at line 431 of file documentRenderer.h.
QMutex DocumentRenderer::mutex [protected] |
mutex used to make method thread-safe
This is a recursive mutex that must be used to make the public methods of this class thread-safe. Future versions of kviewshell will use threading to keep the GUI responsive while pages are rendered. As a result, IT IS ABSOLUTELY NECESSARY that your implementation is THREAD-SAFE, if not, this can result in infrequent and very hard-to-find crashes of your programm.
Definition at line 392 of file documentRenderer.h.
Q_UINT16 DocumentRenderer::numPages [protected] |
QValueVector<SimplePageSize> DocumentRenderer::pageSizes [protected] |
page sizes
This vector contains the size of every page in the document. To accomodate for file format that do not specify a page size, it is explicitly allowed that this vector is empty, or that entries are invalid page sizes. The values in this vector are set by the setFile() method.
- Note:
- if the document does not specify page sizes, this vector should --for performance reasons-- be empty, and not set to a large number of invalid page sizes.
Definition at line 420 of file documentRenderer.h.
QGuardedPtr<QWidget> DocumentRenderer::parentWidget [protected] |
pointer to the parent widget
This pointer can be used by implementations e.g. to display error messages. This pointer can well be zero.
Definition at line 449 of file documentRenderer.h.
The documentation for this class was generated from the following files:
