mirror of
https://invent.kde.org/graphics/okular
synced 2024-08-27 11:40:07 +00:00
865 lines
29 KiB
Plaintext
865 lines
29 KiB
Plaintext
/**
|
|
\mainpage Okular, the unified document viewer
|
|
|
|
\section okular_overview Overview
|
|
|
|
- \ref okular_history
|
|
- \ref okular_design
|
|
- \ref okular_generators
|
|
- <a href="http://www.okular.org">Website</a>
|
|
|
|
\authors Tobias König <tokoe@kde.org>
|
|
|
|
\licenses \lgpl
|
|
|
|
\page okular_history Historical background
|
|
|
|
Okular is the successor of <a href="http://kpdf.kde.org">kpdf</a>, the PDF viewer in KDE 3.
|
|
kpdf was refactored and extended in a Google Summer of Code project to support not only
|
|
viewing PDF but also other types of document, e.g. PostScript files, images and many more.
|
|
|
|
\page okular_design The Design of Okular
|
|
|
|
To support a wide range of document formats, Okular was designed in a modular way, so you
|
|
have the following components:
|
|
|
|
\li \ref Shell
|
|
\li \ref Part
|
|
\li \ref Okular::Document Class
|
|
\li \ref Okular::Generator
|
|
|
|
The shell is the application which is started by the user as standalone application and
|
|
which embedds the part. The part contains all GUI elements of Okular, for example the
|
|
content list, the bookmark manager, menus and the graphical view of the document class.
|
|
The document class is an abstract presentation of the document content. It contains information
|
|
about every page of the document, its size, orientation etc.
|
|
|
|
But somehow the document class must retrieve these information from the various types of documents.
|
|
This is the task of the Generators. Generators are plugins which are loaded at runtime and which
|
|
have the knowledge about the internal structure of the different document types.
|
|
They extract the needed information from the documents, convert the data into a common format and
|
|
pass them to the document class.
|
|
|
|
Currently Generators for the following document types are available:
|
|
|
|
\li Portable Document Format (PDF)
|
|
\li PostScript
|
|
\li Device Independent Format (DVI)
|
|
\li DeJaVu Format
|
|
\li Comic Books
|
|
\li Images (JPEG, PNG, GIF, and many more)
|
|
\li TIFF Image Format
|
|
\li FictionBook Format
|
|
\li Plucker Format
|
|
\li OpenDocument Text Format
|
|
\li Microsofts CHM Format
|
|
\li Microsofts XML Document Format
|
|
|
|
Now the questions is how can these various formats be represented in a unified way?
|
|
Okular provides features like rotation, text search and extraction, zooming and many more, so how
|
|
does it match with the different capabilities of the formats?
|
|
|
|
\section okular_design_basics Basics of Generators
|
|
|
|
Lets start with the smallest commonness of all document formats:
|
|
|
|
\li they have pages (one ore more) of a given size
|
|
\li pages can be represented as pictures
|
|
|
|
So the first thing every Generator must support is to return the number of pages of a document.
|
|
Furthermore it must be able to return the picture of a page at a requested size.
|
|
|
|
For vector based document formats (e.g. PDF or PostScript) the Generators can render the page for
|
|
the requested size, for static documents formats (e.g. images), the Generator must scale the
|
|
content according to the requested size, so when you zoom a page in Okular, the Generators are
|
|
just asked to return the page for the zoomed size.
|
|
|
|
When the document class has retrieved the page pictures from the Generators, it can do further
|
|
image manipulation on it, for example rotating them or applying fancy effects.
|
|
|
|
\section okular_design_text_support Generators with Text support
|
|
|
|
Some document formats however support more functionality than just representing a page as an image.
|
|
PDF, PostScript, DVI and DeJaVu for example contains a machine readable representation of the
|
|
included text. For those document formats Okular provides additional features like text search,
|
|
text extraction and text selection.
|
|
|
|
How is that supported by the Generators?
|
|
|
|
To access the text from the documents the generators must extract it somehow and make it available
|
|
to the document class. However for the text selection feature the document class must also know <em>where</em>
|
|
the extracted text is located on the page. For a zoom factor of 100% the absolute position of
|
|
the text in the document can be used, however for larger or smaller zoom factors the position
|
|
must be recalculated. To make this calculation as easy as possible, the Generators return an
|
|
abstract represtentation (\ref Okular::TextPage) of the text which includes every character together
|
|
with its <em>normalized</em> position. Normalized means that the width and height of the page is
|
|
in the range of 0 to 1, so a character in the middle of the page is at x=0.5 and y=0.5.
|
|
|
|
So when you want to know where this character is located on the page which is zoomed at 300%, you just
|
|
multiply the position by 3 * page width (and page height) and get the absolute position for this zoom level.
|
|
|
|
This abstract text representation also allows an easy rotation of the coordinates, so that text selection
|
|
is available on rotated pages as well.
|
|
|
|
\section okular_design_meta_information Meta Information
|
|
|
|
Most documents have additional meta information:
|
|
|
|
\li Name of the author
|
|
\li Date of creation
|
|
\li Version number
|
|
\li Table of Content
|
|
\li Bookmarks
|
|
\li Annotations
|
|
|
|
These information can be retrieved by the generator as well and will be shown by Okular.
|
|
|
|
\page okular_generators How to implement a Generator
|
|
|
|
The power of Okular is its extensibility by Generator plugins. This section will describe how to
|
|
implement your own plugin for a new document type.
|
|
|
|
\li \ref okular_generators_basic
|
|
\li \ref okular_generators_with_text
|
|
\li \ref okular_generators_threaded
|
|
\li \ref okular_generators_extended
|
|
|
|
\section okular_generators_basic A Basic Generator
|
|
|
|
To provide a short overview and don't reimplementing an existing generator we'll work on a Generator
|
|
for the Magic document format, a non existing, pure virtual format :)
|
|
|
|
Lets assume we have some helper class (MagicDocument) which provides the following functionality for this
|
|
document format:
|
|
|
|
\li Loading a document
|
|
\li Retrieving number of pages
|
|
\li Returning a fixed size picture representation of a page
|
|
|
|
The class API looks like this
|
|
|
|
\code
|
|
class MagicDocument
|
|
{
|
|
public:
|
|
MagicDocument();
|
|
~MagicDocument();
|
|
|
|
bool loadDocument( const QString &fileName );
|
|
|
|
int numberOfPages() const;
|
|
|
|
QSize pageSize( int pageNumber ) const;
|
|
|
|
QImage pictureOfPage( int pageNumber ) const;
|
|
|
|
private:
|
|
...
|
|
};
|
|
\endcode
|
|
|
|
The methods should be self explaining, loadDocument() loads a document file and returns false on error,
|
|
numberOfPages() returns the number of pages, pageSize() returns the size of the page and pictureOfPage()
|
|
returns the picture representation of the page.
|
|
|
|
Our first version of our Generator is a basic one which just provides page pictures to the document class.
|
|
|
|
The API of the Generator looks like the following:
|
|
|
|
\code
|
|
#include "magicdocument.h"
|
|
|
|
#include <okular/core/generator.h>
|
|
|
|
class MagicGenerator : public Okular::Generator
|
|
{
|
|
public:
|
|
MagicGenerator( QObject *parent, const QVariantList &args );
|
|
~MagicGenerator();
|
|
|
|
bool loadDocument( const QString &fileName, QVector<Okular::Page*> &pages );
|
|
|
|
bool canGeneratePixmap() const;
|
|
void generatePixmap( Okular::PixmapRequest *request );
|
|
|
|
protected:
|
|
bool doCloseDocument();
|
|
|
|
private:
|
|
MagicDocument mMagicDocument;
|
|
};
|
|
\endcode
|
|
|
|
The implementation of the Generator looks like this:
|
|
|
|
\code
|
|
#include <okular/core/page.h>
|
|
|
|
#include "magicgenerator.h"
|
|
|
|
static KAboutData createAboutData()
|
|
{
|
|
KAboutData aboutData(...);
|
|
// fill the about data
|
|
return aboutData;
|
|
}
|
|
|
|
OKULAR_EXPORT_PLUGIN(MagicGenerator, createAboutData())
|
|
|
|
MagicGenerator::MagicGenerator( QObject *parent, const QVariantList &args )
|
|
: Okular::Generator( parent, args )
|
|
{
|
|
}
|
|
|
|
MagicGenerator::~MagicGenerator()
|
|
{
|
|
}
|
|
|
|
bool MagicGenerator::loadDocument( const QString &fileName, QVector<Okular::Page*> &pages )
|
|
{
|
|
if ( !mMagicDocument.loadDocument( fileName ) ) {
|
|
emit error( i18n( "Unable to load document" ), -1 );
|
|
return false;
|
|
}
|
|
|
|
pagesVector.resize( mMagicDocument.numberOfPages() );
|
|
|
|
for ( int i = 0; i < mMagicDocument.numberOfPages(); ++i ) {
|
|
const QSize size = mMagicDocument.pageSize( i );
|
|
|
|
Okular::Page * page = new Okular::Page( i, size.width(), size.height(), Okular::Rotation0 );
|
|
pages[ i ] = page;
|
|
}
|
|
|
|
return true;
|
|
}
|
|
|
|
bool MagicGenerator::doCloseDocument()
|
|
{
|
|
return true;
|
|
}
|
|
|
|
bool MagicGenerator::canGeneratePixmap() const
|
|
{
|
|
return true;
|
|
}
|
|
|
|
void MagicGenerator::generatePixmap( Okular::PixmapRequest *request )
|
|
{
|
|
QImage image = mMagicDocument.pictureOfPage( request->pageNumber() );
|
|
|
|
image = image.scaled( request->width(), request->height(), Qt::IgnoreAspectRatio, Qt::SmoothTransformation );
|
|
|
|
request->page()->setPixmap( request->id(), new QPixmap( QPixmap::fromImage( image ) ) );
|
|
|
|
signalPixmapRequestDone( request );
|
|
}
|
|
|
|
\endcode
|
|
|
|
As you can see implementing a basic Generator is quite easy. The loadDocument() method opens the document file
|
|
and extracts the number of pages. For every page in the document it adds an Okular::Page object to the pages vector
|
|
which is passed in as method argument. Each page is initialized with its page number, width, height and initial rotation.
|
|
These page objects will be stored in the document object and act as a container for the picture representation
|
|
of the pages. This code is the same for nearly every Generator. On an failure the error() signal can be emitted
|
|
to inform the user about the issue. This code is the same for nearly every Generator.
|
|
|
|
In the doCloseDocument() method you should close the document and free all resources you have allocated in openDocument().
|
|
|
|
Now we come to the picture creation methods. The canGeneratorPixmap() method returns whether the Generator is currently
|
|
able to handle a new pixmap generation request. For a simple Generator like our one that's always the case as it works
|
|
linear, however a multithreaded Generator might return <em>false</em> here if it is still waiting for one of its working
|
|
threads to finish. In this case the document class will try to request the pixmap later again.
|
|
|
|
The generatePixmap() method does the actual fetching of the picture for a page. The page number, requested width and
|
|
height of the page is encapsulated in the passed Okular::PixmapRequest object.
|
|
So the task of the Generator is to create a pixmap of the requested page in the requested size and then store this
|
|
pixmap in the Okular::Page object which is associated with the page request.
|
|
When this task is finished, the Generator has to call signalPixmapRequestDone() with the page request object
|
|
as argument. This extra call is needed to allow the Generator to use signals and slots internally and create the
|
|
pixmap asynchronously.
|
|
|
|
So now you have the code of a working Okular Generator, the next step is to tell Okular about the new plugin.
|
|
Like in other places in KDE that is done by .desktop files, which are installed to the services directory.
|
|
|
|
Every Generator needs 3 .desktop files:
|
|
|
|
\li libokularGenerator_<name>.desktop
|
|
\li okularApplication_<name>.desktop
|
|
\li okular<name>.desktop
|
|
|
|
where <name> should be the name of the document format. So for our Magic Document Generator we
|
|
create the following 3 files:
|
|
|
|
\li libokularGenerator_magic.desktop
|
|
\li okularApplication_magic.desktop
|
|
\li okularMagic.desktop
|
|
|
|
with the following content:
|
|
|
|
\verbatim
|
|
[Desktop Entry]
|
|
Encoding=UTF-8
|
|
Type=Service
|
|
Name=Magic Document
|
|
Comment=Magic Document backend for okular
|
|
ServiceTypes=okular/Generator
|
|
MimeType=application/x-magic;
|
|
X-KDE-Library=okularGenerator_magic
|
|
X-KDE-Priority=1
|
|
X-KDE-okularAPIVersion=1
|
|
X-KDE-okularHasInternalSettings=false
|
|
\endverbatim
|
|
|
|
The first 6 fields are standard .desktop entries, the fields afterwards have a special meaning to Okular
|
|
|
|
\li <b>ServiceType</b> Must be 'okular/Generator' for all Okular Generator Plugins
|
|
\li <b>MimeType</b> The mimetype or list of mimetypes of the supported document format(s)
|
|
\li <b>X-KDE-Library</b> The name of the plugin library
|
|
\li <b>X-KDE-Priority</b> When multiple Generators for the same mimetype exists, the one with the highest priority is used
|
|
\li <b>X-KDE-okularAPIVersion</b> The version of the Generator Plugin API ('1' currently)
|
|
\li <b>X-KDE-okularHasInternalSettings</b> Is 'true' when the Generator provides configuration dialogs
|
|
|
|
The second .desktop file has the following content:
|
|
|
|
\verbatim
|
|
[Desktop Entry]
|
|
Encoding=UTF-8
|
|
MimeType=application/x-magic;
|
|
Terminal=false
|
|
Name=okular
|
|
GenericName=Document Viewer
|
|
Exec=okular %U %i -caption "%c"
|
|
Icon=okular
|
|
Type=Application
|
|
InitialPreference=7
|
|
Categories=Qt;KDE;Graphics;Viewer;
|
|
NoDisplay=true
|
|
\endverbatim
|
|
|
|
You can use the file as it is, you just have to adapt the mimetype. This file is needed to allow Okular
|
|
to handle multiple mimetypes.
|
|
|
|
The third .desktop file looks like this:
|
|
|
|
\verbatim
|
|
[Desktop Entry]
|
|
Encoding=UTF-8
|
|
Icon=okular
|
|
Name=okular
|
|
ServiceTypes=KParts/ReadOnlyPart
|
|
X-KDE-Library=libokularpart
|
|
Type=Service
|
|
MimeType=application/x-magic;
|
|
\endverbatim
|
|
|
|
You can use the file as it is as well, you just have to adapt the mimetype. This file is needed to allow
|
|
the Okular part to handle multiple mimetypes.
|
|
|
|
The last piece you need for a complete Generator is a CMakeLists.txt which compiles and installs the
|
|
Generator. Our CMakeLists.txt looks like the following:
|
|
|
|
\verbatim
|
|
macro_optional_find_package(Okular)
|
|
|
|
include_directories( ${OKULAR_INCLUDE_DIR} ${KDE4_INCLUDE_DIR} ${QT_INCLUDES} )
|
|
|
|
########### next target ###############
|
|
|
|
set( okularGenerator_magic_SRCS generator_magic.cpp )
|
|
|
|
kde4_add_plugin( okularGenerator_magic ${okularGenerator_magic_SRCS} )
|
|
|
|
target_link_libraries( okularGenerator_magic ${OKULAR_LIBRARIES} ${KDE4_KDEUI_LIBS} )
|
|
|
|
install( TARGETS okularGenerator_magic DESTINATION ${PLUGIN_INSTALL_DIR} )
|
|
|
|
########### install files ###############
|
|
|
|
install( FILES libokularGenerator_magic.desktop okularMagic.desktop DESTINATION ${SERVICES_INSTALL_DIR} )
|
|
install( FILES okularApplication_magic.desktop DESTINATION ${XDG_APPS_DIR} )
|
|
\endverbatim
|
|
|
|
The macro_optional_find_package(Okular) call is required to make the ${OKULAR_INCLUDE_DIR} and ${OKULAR_LIBRARIES}
|
|
variables available.
|
|
|
|
Now you can compile the Generator plugin and install it. After a restart of Okular the new plugin is available
|
|
and you can open Magic documents.
|
|
|
|
\section okular_generators_with_text A Generator with TextPage support
|
|
|
|
In this section we want to extend our Generator to support text search, text extraction and selection
|
|
as well. As mentioned in \ref okular_design_text_support, the Generator must provide an Okular::TextPage
|
|
object for every page which contains readable text.
|
|
|
|
Since we use the helper class MagicDocument to read the data from the document we have to extend it first,
|
|
so the new API looks as the following:
|
|
|
|
\code
|
|
class MagicDocument
|
|
{
|
|
public:
|
|
MagicDocument();
|
|
~MagicDocument();
|
|
|
|
bool loadDocument( const QString &fileName );
|
|
|
|
int numberOfPages() const;
|
|
|
|
QSize pageSize( int pageNumber ) const;
|
|
|
|
QImage pictureOfPage( int pageNumber ) const;
|
|
|
|
class TextInfo
|
|
{
|
|
public:
|
|
typedef QList<TextInfo> List;
|
|
|
|
QChar character;
|
|
qreal xPos;
|
|
qreal yPos;
|
|
qreal width;
|
|
qreal height;
|
|
};
|
|
|
|
TextInfo::List textOfPage( int pageNumber );
|
|
|
|
private:
|
|
...
|
|
};
|
|
\endcode
|
|
|
|
MagicDocument has the new internal class TextInfo now, which contains a character and
|
|
its absolute position on a page. Furthermore MagicDocument provides a method textOfPage()
|
|
which returns a list of all TextInfo objects for a page.
|
|
|
|
That's really an optimistic API, in reality it is sometimes quite hard to find out
|
|
the position of single characters in a document format.
|
|
|
|
With the extension of our helper class we can continue on extending our Generator now:
|
|
|
|
\code
|
|
#include "magicdocument.h"
|
|
|
|
#include <okular/core/generator.h>
|
|
|
|
class MagicGenerator : public Okular::Generator
|
|
{
|
|
public:
|
|
MagicGenerator( QObject *parent, const QVariantList &args );
|
|
~MagicGenerator();
|
|
|
|
bool loadDocument( const QString &fileName, QVector<Okular::Page*> &pages );
|
|
|
|
bool canGeneratePixmap() const;
|
|
void generatePixmap( Okular::PixmapRequest *request );
|
|
|
|
virtual bool canGenerateTextPage() const;
|
|
virtual void generateTextPage( Okular::Page *page, enum Okular::GenerationType type = Okular::Synchronous );
|
|
|
|
protected:
|
|
bool doCloseDocument();
|
|
|
|
private:
|
|
MagicDocument mMagicDocument;
|
|
};
|
|
\endcode
|
|
|
|
We have extended the MagicGenerator class by two methods canGenerateTextPage() and generateTextPage().
|
|
The first method is equal to canGeneratePixmap(), it returns whether the Generator is currently able to
|
|
handle a new text page generation request. For linear Generators that should be always the case, however
|
|
when the generation is done in a separated worker thread, this method might return <em>false</em>.
|
|
In this case the document class will try to request the text page later again.
|
|
|
|
The second method will generate the Okular::TextPage object for the passed page. Depending on the capabilities
|
|
of the Generator and the passed <em>type</em> parameter that is done synchronously or asynchronously.
|
|
|
|
Let us take a look at the implementation of these methods in our MagicGenerator:
|
|
|
|
\code
|
|
#include <okular/core/textpage.h>
|
|
|
|
...
|
|
|
|
MagicGenerator::MagicGenerator( QObject *parent, const QVariantList &args )
|
|
: Okular::Generator( parent, args )
|
|
{
|
|
setFeature( TextExtraction );
|
|
}
|
|
|
|
bool MagicGenerator::canGenerateTextPage() const
|
|
{
|
|
return true;
|
|
}
|
|
|
|
void MagicGenerator::generateTextPage( Okular::Page *page, enum Okular::GenerationType )
|
|
{
|
|
MagicDocument::TextInfo::List characters = mMagicDocument.textOfPage( page->number() );
|
|
if ( characters.isEmpty() )
|
|
return;
|
|
|
|
Okular::TextPage *textPage = new Okular::TextPage;
|
|
for ( int i = 0; i < characters.count(); ++i ) {
|
|
qreal left = characters[ i ].xPos / page->width();
|
|
qreal top = characters[ i ].yPos / page->height();
|
|
qreal right = (characters[ i ].xPos + characters[ i ].width) / page->width();
|
|
qreal bottom = (characters[ i ].yPos + characters[ i ].height) / page->height();
|
|
|
|
textPage->append( characters[ i ].character,
|
|
new Okular::NormalizedRect( left, top, right, bottom ) );
|
|
}
|
|
|
|
page->setTextPage( textPage );
|
|
}
|
|
\endcode
|
|
|
|
As you can see the generateTextPage method just iterates over the list of characters returned
|
|
by our MagicDocument helper class and adds the character and its normalized bounding rect to
|
|
the Okular::TextPage object. At the end the text page is assigned to the page. We don't pay
|
|
attention to the GenerationType parameter here, if your Generator want to use threads, it should
|
|
check here whether the request shall be done asynchronously or synchronously and start the generation
|
|
according to that. Additionally we have to tell the Okular::Generator base class that we support
|
|
text handling by setting this flag in the constructor.
|
|
|
|
In this state we can now search, select and extract text from Magic documents.
|
|
|
|
\section okular_generators_threaded A Generator with Thread support
|
|
|
|
Sometimes it makes sense to do the generation of page pictures or text pages asynchronously to
|
|
improve performance and don't blocking the user interface. This can be done in two ways, either
|
|
by using signals and slots or by using threads. Both have there pros and cons:
|
|
|
|
<ul>
|
|
<li><b>Signals and Slots</b></li>
|
|
<ul>
|
|
<li>Pro: Can be used with backend libraries which are not thread safe</li>
|
|
<li>Con: Sometime difficult to implement</li>
|
|
</ul>
|
|
<li><b>Threads</b></li>
|
|
<ul>
|
|
<li>Pro: Easy to implement as you can make synchronous calls to the backend libraries</li>
|
|
<li>Con: Backend libraries must be thread safe and you must prevent race conditions by using mutexes</li>
|
|
</ul>
|
|
</ul>
|
|
|
|
The signal and slots approach can be achieved with a normal Generator by calling Okular::Generator::signalPixmapRequestDone()
|
|
from a slot after pixmap generation has been finished.
|
|
|
|
When using threads you should use a slightly different API, which hides most of the thread usage, to make
|
|
implementing as easy as possible.
|
|
|
|
Let's assume the pictureOfPage() and textOfPage methods in our MagicDocument helper class are thread safe,
|
|
so we can use them in a multithreaded environment.
|
|
So nothing prevents us from changing the MagicGenerator to use threads for better performance.
|
|
|
|
The new MagicGenerator API looks like the following:
|
|
|
|
\code
|
|
#include "magicdocument.h"
|
|
|
|
#include <okular/core/generator.h>
|
|
|
|
class MagicGenerator : public Okular::Generator
|
|
{
|
|
public:
|
|
MagicGenerator( QObject *parent, const QVariantList &args );
|
|
~MagicGenerator();
|
|
|
|
bool loadDocument( const QString &fileName, QVector<Okular::Page*> &pages );
|
|
|
|
protected:
|
|
bool doCloseDocument();
|
|
|
|
virtual QImage image( Okular::PixmapRequest *request );
|
|
|
|
virtual Okular::TextPage* textPage( Okular::Page *page );
|
|
|
|
private:
|
|
MagicDocument mMagicDocument;
|
|
};
|
|
\endcode
|
|
|
|
As you can see the canGeneratePixmap() generatePixmap(), canGenerateTextPage() and generateTextPage() methods have
|
|
been removed and replaced by the image() and textPage() methods.
|
|
|
|
Before explaining why, we'll take a look at the implementation:
|
|
|
|
\code
|
|
|
|
MagicGenerator::MagicGenerator( QObject *parent, const QVariantList &args )
|
|
: Okular::Generator( parent, args )
|
|
{
|
|
setFeature( TextExtraction );
|
|
setFeature( Threaded );
|
|
}
|
|
|
|
QImage MagicGenerator::image( Okular::PixmapRequest *request )
|
|
{
|
|
QImage image = mMagicDocument.pictureOfPage( request->pageNumber() );
|
|
|
|
return image.scaled( request->width(), request->height(), Qt::IgnoreAspectRatio, Qt::SmoothTransformation );
|
|
}
|
|
|
|
Okular::TextPage* textPage( Okular::Page *page )
|
|
{
|
|
MagicDocument::TextInfo::List characters = mMagicDocument.textOfPage( page->number() );
|
|
if ( characters.isEmpty() )
|
|
return 0;
|
|
|
|
Okular::TextPage *textPage = new Okular::TextPage;
|
|
for ( int i = 0; i < characters.count(); ++i ) {
|
|
qreal left = characters[ i ].xPos / page->width();
|
|
qreal top = characters[ i ].yPos / page->height();
|
|
qreal right = (characters[ i ].xPos + characters[ i ].width) / page->width();
|
|
qreal bottom = (characters[ i ].yPos + characters[ i ].height) / page->height();
|
|
|
|
textPage->append( characters[ i ].character,
|
|
new Okular::NormalizedRect( left, top, right, bottom ) );
|
|
}
|
|
|
|
return textPage;
|
|
}
|
|
\endcode
|
|
|
|
So the first obviously thing is that both methods return a value instead of modifying the page directly.
|
|
The reason for this is that both methods are executed in its own thread, so the code executed in them can
|
|
block as long as it wants, it won't block the GUI anyway. Additionally we have to tell the Okular::Generator
|
|
base class that we can handle threads by setting the flag in the constructor.
|
|
|
|
With only a small change we made our MagicGenerator multithreaded now!
|
|
|
|
\section okular_generators_extended An Extended Generator
|
|
|
|
Now we want to create a new generator with some additional functionality:
|
|
|
|
\li Support for document information (author, creation date etc.)
|
|
\li Support for a table of content
|
|
\li Support for printing the document
|
|
\li Support for exporting the document as text
|
|
|
|
The new Generator shall be able to handle HTML documents. We choose this format as example, because
|
|
we can use QTextDocument to load, render and print a HTML page, so a lot of code can be reused.
|
|
|
|
The API of our HTMLGenerator looks like the following:
|
|
|
|
\code
|
|
#include <QtGui/QTextDocument>
|
|
|
|
#include <okular/core/generator.h>
|
|
|
|
class HTMLGenerator : public Okular::Generator
|
|
{
|
|
public:
|
|
HTMLGenerator( QObject *parent, const QVariantList &args );
|
|
~HTMLGenerator();
|
|
|
|
bool loadDocument( const QString &fileName, QVector<Okular::Page*> &pages );
|
|
|
|
bool canGeneratePixmap() const;
|
|
void generatePixmap( Okular::PixmapRequest *request );
|
|
|
|
virtual const Okular::DocumentInfo* generateDocumentInfo();
|
|
|
|
virtual const Okular::DocumentSynopsis* generateDocumentSynopsis();
|
|
|
|
virtual bool print( KPrinter &printer );
|
|
|
|
virtual Okular::ExportFormat::List exportFormats() const;
|
|
|
|
virtual bool exportTo( const QString &fileName, const Okular::ExportFormat &format );
|
|
|
|
protected:
|
|
bool doCloseDocument();
|
|
|
|
private:
|
|
QTextDocument *mTextDocument;
|
|
Okular::DocumentInfo mDocumentInfo;
|
|
Okular::DocumentSynopsis mDocumentSynopsis;
|
|
};
|
|
\endcode
|
|
|
|
The Generator doesn't support text search and selection, as the code would be quite complex, we'll show
|
|
how to do it in the next chapter \ref okular_generators_textdocument anyway.
|
|
|
|
As you can see we have 5 new methods in the class:
|
|
|
|
\li <b>generateDocumentInfo()</b> Creates an Okular::DocumentInfo (which is infact a QDomDocument)
|
|
which contains document information like author, creation time etc.
|
|
\li <b>generateDocumentSynopsis()</b> Creates an Okular::DocumentSynopsis (which is a QDomDocument as well)
|
|
which contains the table of content.
|
|
\li <b>print()</b> Prints the document to the passed printer.
|
|
\li <b>exportFormats()</b> Returns the supported export formats.
|
|
\li <b>exportTo()</b> Exports the document to the given file in the given format.
|
|
|
|
Now that you know what the methods are supposed to do, let's take a look at the implementation:
|
|
|
|
\code
|
|
#include <QtCore/QFile>
|
|
#include <QtGui/QAbstractTextDocumentLayout>
|
|
|
|
#include <kprinter.h>
|
|
|
|
#include <okular/core/document.h>
|
|
#include <okular/core/page.h>
|
|
|
|
#include "htmlgenerator.h"
|
|
|
|
static KAboutData createAboutData()
|
|
{
|
|
KAboutData aboutData(...);
|
|
// fill the about data
|
|
return aboutData;
|
|
}
|
|
|
|
OKULAR_EXPORT_PLUGIN(HTMLGenerator, createAboutData())
|
|
|
|
HTMLGenerator::HTMLGenerator( QObject *parent, const QVariantList &args )
|
|
: Okular::Generator( parent, args ),
|
|
mTextDocument( 0 )
|
|
{
|
|
}
|
|
|
|
HTMLGenerator::~HTMLGenerator()
|
|
{
|
|
delete mTextDocument;
|
|
}
|
|
|
|
bool HTMLGenerator::loadDocument( const QString &fileName, QVector<Okular::Page*> &pages )
|
|
{
|
|
QFile file( fileName );
|
|
if ( !file.open( QIODevice::ReadOnly ) ) {
|
|
emit error( i18n( "Unable to open file" ), -1 );
|
|
return false;
|
|
}
|
|
|
|
const QString data = QString::fromUtf8( file.readAll() );
|
|
|
|
file.close();
|
|
|
|
mTextDocument = new QTextDocument;
|
|
mTextDocument->setHtml( data );
|
|
mTextDocument->setPageSize( QSizeF( 600, 800 ) );
|
|
|
|
pages.resize( mTextDocument->pageCount() );
|
|
|
|
for ( int i = 0; i < mTextDocument->pageCount(); ++i ) {
|
|
Okular::Page * page = new Okular::Page( i, 600, 800, Okular::Rotation0 );
|
|
pages[ i ] = page;
|
|
}
|
|
|
|
mDocumentInfo.set( "author", "Tobias Koenig", i18n( "Author" ) );
|
|
mDocumentInfo.set( "title", "The Art of Okular Plugin Development", i18n( "Title" ) );
|
|
|
|
Okular::DocumentViewport viewport = ... // get the viewport of the chapter
|
|
|
|
QDomElement item = mDocumentSynopsis.createElement( "Chapter 1" );
|
|
item.setAttribute( "Viewport", viewport.toString() );
|
|
mDocumentSynopsis.appendChild( item );
|
|
|
|
viewport = ... // get the viewport of the subchapter
|
|
|
|
QDomElement childItem = mDocumentSynopsis.createElement( "SubChapter 1.1" );
|
|
childItem.setAttribute( "Viewport", viewport.toString() );
|
|
item.appendChild( childItem );
|
|
|
|
return true;
|
|
}
|
|
|
|
bool HTMLGenerator::doCloseDocument()
|
|
{
|
|
delete mTextDocument;
|
|
mTextDocument = 0;
|
|
|
|
return true;
|
|
}
|
|
|
|
bool HTMLGenerator::canGeneratePixmap() const
|
|
{
|
|
return true;
|
|
}
|
|
|
|
void HTMLGenerator::generatePixmap( Okular::PixmapRequest *request )
|
|
{
|
|
QPixmap *pixmap = new QPixmap( request->width(), request->height() );
|
|
pixmap->fill( Qt::white );
|
|
|
|
QPainter p;
|
|
p.begin( pixmap );
|
|
|
|
qreal width = request->width();
|
|
qreal height = request->height();
|
|
|
|
p.scale( width / 600, height / 800 );
|
|
|
|
const QRect rect( 0, request->pageNumber() * 800, 600, 800 );
|
|
p.translate( QPoint( 0, request->pageNumber() * -800 ) );
|
|
d->mDocument->drawContents( &p, rect );
|
|
p.end();
|
|
|
|
request->page()->setPixmap( request->id(), pixmap );
|
|
|
|
signalPixmapRequestDone( request );
|
|
}
|
|
|
|
const Okular::DocumentInfo* HTMLGenerator::generateDocumentInfo()
|
|
{
|
|
return &mDocumentInfo;
|
|
}
|
|
|
|
const Okular::DocumentSynopsis* HTMLGenerator::generateDocumentSynopsis()
|
|
{
|
|
if ( !mDocumentSynopsis.hasChildNodes() )
|
|
return 0;
|
|
else
|
|
return &mDocumentSynopsis;
|
|
}
|
|
|
|
bool HTMLGenerator::print( KPrinter &printer )
|
|
{
|
|
QPainter p( &printer );
|
|
|
|
for ( int i = 0; i < mTextDocument->pageCount(); ++i ) {
|
|
if ( i != 0 )
|
|
printer.newPage();
|
|
|
|
QRect rect( 0, i * 800, 600, 800 );
|
|
p.translate( QPoint( 0, i * -800 ) );
|
|
mTextDocument->drawContents( &p, rect );
|
|
}
|
|
}
|
|
|
|
Okular::ExportFormat::List HTMLGenerator::exportFormats() const
|
|
{
|
|
return Okular::ExportFormat::standardFormat( Okular::ExportFormat::PlainText );
|
|
}
|
|
|
|
bool HTMLGenerator::exportTo( const QString &fileName, const Okular::ExportFormat &format )
|
|
{
|
|
QFile file( fileName );
|
|
if ( !fileName.open( QIODevice::WriteOnly ) ) {
|
|
emit error( i18n( "Unable to open file" ), -1 );
|
|
return false;
|
|
}
|
|
|
|
if ( format.mimeType()->name() == QLatin1String( "text/plain" ) )
|
|
file.writeBlock( mTextDocument->toPlainText().toUtf8() );
|
|
|
|
file.close();
|
|
|
|
return true;
|
|
}
|
|
\endcode
|
|
|
|
Let's take a closer look at the single methods. In the loadDocument() method we try to open the
|
|
passed file name and read all the content into the QTextDocument object. By calling
|
|
QTextDocument::setPageSize(), the whole document is divided into pages of the given size.
|
|
In the next step we create Okular::Page objects for every page in the QTextDocument and fill
|
|
the pages vector with them.
|
|
|
|
Afterwards we fill our Okular::DocumentInfo object with data. Since extracting the HTML meta data
|
|
would need a lot of code we work with static data here. [to be continued]
|
|
*/
|
|
|
|
// DOXYGEN_EXCLUDE = conf generators shell ui
|
|
// DOXYGEN_FILE_PATTERNS = core/*.h *.dox
|