2004-12-10 16:04:45 +00:00
/***************************************************************************
2005-11-18 20:48:01 +00:00
* Copyright ( C ) 2004 - 5 by Enrico Ros < eros . kde @ email . it > *
2006-05-08 20:12:04 +00:00
* Copyright ( C ) 2005 by Piotr Szymanski < niedakh @ gmail . com > *
2008-08-01 20:26:22 +00:00
* Copyright ( C ) 2008 by Albert Astals Cid < aacid @ kde . org > *
2017-10-03 07:29:18 +00:00
* Copyright ( C ) 2017 Klarälvdalens Datakonsult AB , a KDAB Group *
* company , info @ kdab . com . Work sponsored by the *
* LiMux project of the city of Munich *
2004-12-10 16:04:45 +00:00
* *
* This program is free software ; you can redistribute it and / or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation ; either version 2 of the License , or *
* ( at your option ) any later version . *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
2006-09-21 08:45:36 +00:00
# ifndef _OKULAR_GENERATOR_H_
# define _OKULAR_GENERATOR_H_
2004-12-10 16:04:45 +00:00
2014-05-09 17:56:16 +00:00
# include "document.h"
2011-06-01 08:31:44 +00:00
# include "fontinfo.h"
# include "global.h"
2014-10-27 21:35:06 +00:00
# include "okularcore_export.h"
2011-06-01 08:31:44 +00:00
# include "pagesize.h"
2005-07-15 18:20:57 +00:00
2018-08-31 09:23:45 +00:00
# include <QList>
# include <QObject>
# include <QSharedDataPointer>
# include <QSizeF>
# include <QString>
# include <QVariant>
# include <QVector>
2006-09-21 08:45:36 +00:00
2020-07-08 11:54:37 +00:00
# include <KPluginFactory>
2014-09-11 13:18:05 +00:00
# include <QMimeType>
2006-09-21 08:45:36 +00:00
2015-11-28 19:24:41 +00:00
# define OKULAR_EXPORT_PLUGIN(classname, json) \
static_assert ( json [ 0 ] ! = ' \0 ' , " arg2 must be a string literal " ) ; \
2019-01-06 23:50:21 +00:00
K_PLUGIN_CLASS_WITH_JSON ( classname , json )
2007-01-03 14:30:48 +00:00
2008-08-01 20:26:22 +00:00
class QByteArray ;
2007-09-15 11:35:53 +00:00
class QMutex ;
2007-10-15 23:01:27 +00:00
class QPrinter ;
2014-08-13 09:54:49 +00:00
class QIcon ;
2006-09-21 08:45:36 +00:00
namespace Okular
{
2016-11-26 15:00:02 +00:00
class BackendOpaqueAction ;
2019-06-04 05:12:42 +00:00
class DocumentFonts ;
2006-12-28 16:45:50 +00:00
class DocumentInfo ;
2013-02-24 21:58:53 +00:00
class DocumentObserver ;
2006-12-28 16:45:50 +00:00
class DocumentSynopsis ;
class EmbeddedFile ;
2007-04-12 20:43:37 +00:00
class ExportFormatPrivate ;
2008-08-01 20:26:22 +00:00
class FontInfo ;
2007-04-20 17:17:44 +00:00
class GeneratorPrivate ;
2006-09-21 08:45:36 +00:00
class Page ;
class PixmapRequest ;
2007-09-30 21:44:31 +00:00
class PixmapRequestPrivate ;
2006-10-23 23:03:02 +00:00
class TextPage ;
2018-02-01 18:42:37 +00:00
class TextRequest ;
class TextRequestPrivate ;
2008-05-18 23:06:21 +00:00
class NormalizedRect ;
2004-12-10 16:04:45 +00:00
2007-01-04 15:22:28 +00:00
/* Note: on contents generation and asynchronous queries.
2018-11-14 19:12:15 +00:00
* Many observers may want to request data synchronously or asynchronously .
2005-01-18 16:43:36 +00:00
* - Sync requests . These should be done in - place .
2004-12-21 12:38:52 +00:00
* - Async request must be done in real background . That usually means a
* thread , such as QThread derived classes .
* Once contents are available , they must be immediately stored in the
2006-09-21 08:45:36 +00:00
* Page they refer to , and a signal is emitted as soon as storing
2004-12-21 12:38:52 +00:00
* ( even for sync or async queries ) has been done .
*/
2006-10-25 15:35:53 +00:00
/**
* @ short Defines an entry for the export menu
*
* This class encapsulates information about an export format .
2007-01-02 19:05:49 +00:00
* Every Generator can support 0 or more export formats which can be
2007-01-13 22:55:00 +00:00
* queried with @ ref Generator : : exportFormats ( ) .
2006-10-25 15:35:53 +00:00
*/
2014-10-27 21:35:06 +00:00
class OKULARCORE_EXPORT ExportFormat
2006-10-25 15:35:53 +00:00
{
2006-10-25 17:43:15 +00:00
public :
typedef QList < ExportFormat > List ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Creates an empty export format .
2007-03-10 20:51:50 +00:00
*
* @ see isNull ( )
2006-10-25 17:43:15 +00:00
*/
ExportFormat ( ) ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Creates a new export format .
*
* @ param description The i18n ' ed description of the format .
* @ param mimeType The supported mime type of the format .
*/
2014-09-11 13:18:05 +00:00
ExportFormat ( const QString & description , const QMimeType & mimeType ) ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Creates a new export format .
*
* @ param icon The icon used in the GUI for this format .
* @ param description The i18n ' ed description of the format .
* @ param mimeType The supported mime type of the format .
*/
2014-09-11 13:18:05 +00:00
ExportFormat ( const QIcon & icon , const QString & description , const QMimeType & mimeType ) ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Destroys the export format .
*/
~ ExportFormat ( ) ;
2020-07-10 22:15:05 +00:00
2007-01-02 19:05:49 +00:00
/**
* @ internal
*/
2006-10-25 17:43:15 +00:00
ExportFormat ( const ExportFormat & other ) ;
2020-07-10 22:15:05 +00:00
2007-01-02 19:05:49 +00:00
/**
* @ internal
*/
2006-10-25 17:43:15 +00:00
ExportFormat & operator = ( const ExportFormat & other ) ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Returns the description of the format .
*/
QString description ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Returns the mime type of the format .
*/
2014-09-11 13:18:05 +00:00
QMimeType mimeType ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Returns the icon for GUI representations of the format .
*/
2014-08-13 09:54:49 +00:00
QIcon icon ( ) const ;
2020-07-10 22:15:05 +00:00
2007-03-10 20:51:50 +00:00
/**
* Returns whether the export format is null / valid .
*
* An ExportFormat is null if the mimetype is not valid or the
* description is empty , or both .
*/
bool isNull ( ) const ;
2020-07-10 22:15:05 +00:00
2007-03-10 21:32:09 +00:00
/**
2007-04-21 11:09:41 +00:00
* Type of standard export format .
2007-03-10 21:32:09 +00:00
*/
2007-04-21 11:09:41 +00:00
enum StandardExportFormat {
PlainText , ///< Plain text
2008-08-07 13:45:43 +00:00
PDF , ///< PDF, aka Portable Document Format
2008-09-01 12:00:50 +00:00
OpenDocumentText , ///< OpenDocument Text format @since 0.8 (KDE 4.2)
HTML ///< OpenDocument Text format @since 0.8 (KDE 4.2)
2007-04-21 11:09:41 +00:00
} ;
2020-07-10 22:15:05 +00:00
2007-04-21 11:09:41 +00:00
/**
* Builds a standard format for the specified @ p type .
*/
static ExportFormat standardFormat ( StandardExportFormat type ) ;
2020-07-10 22:15:05 +00:00
2007-04-12 20:43:37 +00:00
bool operator = = ( const ExportFormat & other ) const ;
2020-07-10 22:15:05 +00:00
2007-04-12 20:43:37 +00:00
bool operator ! = ( const ExportFormat & other ) const ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
private :
2007-09-01 22:48:28 +00:00
/// @cond PRIVATE
2007-04-12 20:43:37 +00:00
friend class ExportFormatPrivate ;
2007-09-01 22:48:28 +00:00
/// @endcond
2007-04-12 20:43:37 +00:00
QSharedDataPointer < ExportFormatPrivate > d ;
2006-10-25 15:35:53 +00:00
} ;
2004-12-10 16:04:45 +00:00
/**
* @ short [ Abstract Class ] The information generator .
*
2007-01-20 14:51:43 +00:00
* Most of class members are virtuals and some of them pure virtual . The pure
* virtuals provide the minimal functionalities for a Generator , that is being
* able to generate QPixmap for the Page ' s of the Document .
2004-12-10 16:04:45 +00:00
*
2007-01-20 14:51:43 +00:00
* Implementing the other functions will make the Generator able to provide
* more contents and / or functionalities ( like text extraction ) .
*
* Generation / query is requested by the Document class only , and that
* class stores the resulting data into Page s . The data will then be
* displayed by the GUI components ( PageView , ThumbnailList , etc . . ) .
*
* @ see PrintInterface , ConfigInterface , GuiInterface
2004-12-10 16:04:45 +00:00
*/
2014-10-27 21:35:06 +00:00
class OKULARCORE_EXPORT Generator : public QObject
2004-12-10 16:04:45 +00:00
{
2007-09-01 22:48:28 +00:00
/// @cond PRIVATE
2007-01-31 18:31:19 +00:00
friend class PixmapGenerationThread ;
friend class TextPageGenerationThread ;
2007-09-01 22:48:28 +00:00
/// @endcond
2007-01-31 18:31:19 +00:00
2006-06-10 12:59:09 +00:00
Q_OBJECT
2004-12-10 16:04:45 +00:00
public :
2007-01-20 14:51:43 +00:00
/**
* Describe the possible optional features that a Generator can
* provide .
*/
2007-01-12 22:49:14 +00:00
enum GeneratorFeature {
2019-02-07 06:13:11 +00:00
Threaded , ///< Whether the Generator supports asynchronous generation of pictures or text pages
2007-01-17 11:58:20 +00:00
TextExtraction , ///< Whether the Generator can extract text from the document in the form of TextPage's
2007-01-17 18:02:53 +00:00
ReadRawData , ///< Whether the Generator can read a document directly from its raw data.
2007-07-07 20:35:01 +00:00
FontInfo , ///< Whether the Generator can provide information about the fonts used in the document
2007-11-26 21:43:54 +00:00
PageSizes , ///< Whether the Generator can change the size of the document pages.
PrintNative , ///< Whether the Generator supports native cross-platform printing (QPainter-based).
PrintPostscript , ///< Whether the Generator supports postscript-based file printing.
2012-11-10 16:00:09 +00:00
PrintToFile , ///< Whether the Generator supports export to PDF & PS through the Print Dialog
2014-05-09 22:53:39 +00:00
TiledRendering , ///< Whether the Generator can render tiles @since 0.16 (KDE 4.10)
2018-02-01 18:42:37 +00:00
SwapBackingFile , ///< Whether the Generator can hot-swap the file it's reading from @since 1.3
SupportsCancelling ///< Whether the Generator can cancel requests @since 1.4
2007-01-12 22:49:14 +00:00
} ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
2006-10-22 11:25:08 +00:00
* Creates a new generator .
2006-10-20 16:51:46 +00:00
*/
2018-09-01 08:25:57 +00:00
explicit Generator ( QObject * parent = nullptr , const QVariantList & args = QVariantList ( ) ) ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
* Destroys the generator .
*/
2019-12-18 11:51:13 +00:00
~ Generator ( ) override ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
* Loads the document with the given @ p fileName and fills the
* @ p pagesVector with the parsed pages .
*
2014-05-09 17:56:16 +00:00
* @ note If you implement the WithPassword variants you don ' t need to implement this one
*
2006-10-20 16:51:46 +00:00
* @ returns true on success , false otherwise .
*/
2014-05-09 17:56:16 +00:00
virtual bool loadDocument ( const QString & fileName , QVector < Page * > & pagesVector ) ;
2020-07-10 22:15:05 +00:00
2007-01-12 22:49:14 +00:00
/**
* Loads the document from the raw data @ p fileData and fills the
* @ p pagesVector with the parsed pages .
*
2014-05-09 17:56:16 +00:00
* @ note If you implement the WithPassword variants you don ' t need to implement this one
*
2007-01-12 22:49:14 +00:00
* @ note the Generator has to have the feature @ ref ReadRawData enabled
*
* @ returns true on success , false otherwise .
*/
virtual bool loadDocumentFromData ( const QByteArray & fileData , QVector < Page * > & pagesVector ) ;
2020-07-10 22:15:05 +00:00
2014-05-09 17:56:16 +00:00
/**
* Loads the document with the given @ p fileName and @ p password and fills the
* @ p pagesVector with the parsed pages .
*
* @ note Do not implement this if your format doesn ' t support passwords , it ' ll cleanly call loadDocument ( )
*
2014-05-09 22:56:57 +00:00
* @ since 0.20 ( KDE 4.14 )
*
2014-05-09 17:56:16 +00:00
* @ returns a LoadResult defining the result of the operation
*/
virtual Document : : OpenResult loadDocumentWithPassword ( const QString & fileName , QVector < Page * > & pagesVector , const QString & password ) ;
2020-07-10 22:15:05 +00:00
2014-05-09 17:56:16 +00:00
/**
* Loads the document from the raw data @ p fileData and @ p password and fills the
* @ p pagesVector with the parsed pages .
*
* @ note Do not implement this if your format doesn ' t support passwords , it ' ll cleanly call loadDocumentFromData ( )
*
* @ note the Generator has to have the feature @ ref ReadRawData enabled
*
2014-05-09 22:56:57 +00:00
* @ since 0.20 ( KDE 4.14 )
*
2014-05-09 17:56:16 +00:00
* @ returns a LoadResult defining the result of the operation
*/
virtual Document : : OpenResult loadDocumentFromDataWithPassword ( const QByteArray & fileData , QVector < Page * > & pagesVector , const QString & password ) ;
2020-07-10 22:15:05 +00:00
2017-10-26 07:47:18 +00:00
/**
* Describes the result of an swap file operation .
*
* @ since 1.3
*/
enum SwapBackingFileResult {
SwapBackingFileError , //< The document could not be swapped
SwapBackingFileNoOp , //< The document was swapped and nothing needs to be done
SwapBackingFileReloadInternalData //< The document was swapped and internal data (forms, annotations, etc) needs to be reloaded
} ;
2020-07-10 22:15:05 +00:00
2014-05-09 22:53:39 +00:00
/**
* Changes the path of the file we are reading from . The new path must
* point to a copy of the same document .
*
* @ note the Generator has to have the feature @ ref SwapBackingFile enabled
*
2017-10-26 07:47:18 +00:00
* @ since 1.3
2014-05-09 22:53:39 +00:00
*/
2017-11-15 10:20:25 +00:00
virtual SwapBackingFileResult swapBackingFile ( const QString & newFileName , QVector < Okular : : Page * > & newPagesVector ) ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
* This method is called when the document is closed and not used
* any longer .
*
* @ returns true on success , false otherwise .
*/
2007-10-08 16:46:51 +00:00
bool closeDocument ( ) ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
2007-01-24 15:06:45 +00:00
* This method returns whether the generator is ready to
* handle a new pixmap request .
2006-10-20 16:51:46 +00:00
*/
2007-01-31 18:31:19 +00:00
virtual bool canGeneratePixmap ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
2007-01-24 15:06:45 +00:00
* This method can be called to trigger the generation of
* a new pixmap as described by @ p request .
2006-10-20 16:51:46 +00:00
*/
2007-01-31 18:31:19 +00:00
virtual void generatePixmap ( PixmapRequest * request ) ;
2020-07-10 22:15:05 +00:00
2007-01-24 18:27:54 +00:00
/**
* This method returns whether the generator is ready to
* handle a new text page request .
*/
2007-01-31 18:31:19 +00:00
virtual bool canGenerateTextPage ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
2007-01-24 15:06:45 +00:00
* This method can be called to trigger the generation of
* a text page for the given @ p page .
2007-01-31 21:10:00 +00:00
*
2018-02-01 18:42:37 +00:00
* The generation is done in the calling thread .
2007-01-31 21:10:00 +00:00
*
2007-01-24 15:06:45 +00:00
* @ see TextPage
2006-10-20 16:51:46 +00:00
*/
2018-02-01 18:42:37 +00:00
void generateTextPage ( Page * page ) ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
2014-05-11 09:17:49 +00:00
* Returns the general information object of the document .
2014-09-09 09:44:33 +00:00
*
* Changed signature in okular version 0.21
2006-10-20 16:51:46 +00:00
*/
2014-05-11 09:17:49 +00:00
virtual DocumentInfo generateDocumentInfo ( const QSet < DocumentInfo : : Key > & keys ) const ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
* Returns the ' table of content ' object of the document or 0 if
* no table of content is available .
*/
virtual const DocumentSynopsis * generateDocumentSynopsis ( ) ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
2018-10-18 19:04:49 +00:00
* Returns the ' list of embedded fonts ' object of the specified \ p page
2007-07-07 20:35:01 +00:00
* of the document .
*
2007-12-28 17:06:43 +00:00
* \ param page a page of the document , starting from 0 - - 1 indicates all
2007-07-07 20:35:01 +00:00
* the other fonts
2006-10-20 16:51:46 +00:00
*/
2007-07-07 20:35:01 +00:00
virtual FontInfo : : List fontsForPage ( int page ) ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
* Returns the ' list of embedded files ' object of the document or 0 if
* no list of embedded files is available .
*/
virtual const QList < EmbeddedFile * > * embeddedFiles ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
* This enum identifies the metric of the page size .
*/
enum PageSizeMetric {
2007-01-02 17:45:32 +00:00
None , ///< The page size is not defined in a physical metric.
2014-01-13 00:15:55 +00:00
Points , ///< The page size is given in 1/72 inches.
Pixels ///< The page size is given in screen pixels @since 0.19 (KDE 4.13)
2006-10-20 16:51:46 +00:00
} ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
2007-01-13 22:55:00 +00:00
* This method returns the metric of the page size . Default is @ ref None .
2006-10-20 16:51:46 +00:00
*/
virtual PageSizeMetric pagesSizeMetric ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
2018-11-20 17:43:11 +00:00
* Returns whether the given @ p action is allowed in the document .
2019-02-07 06:13:11 +00:00
* @ see @ ref Okular : : Permission
2006-10-20 16:51:46 +00:00
*/
2007-03-10 23:59:11 +00:00
virtual bool isAllowed ( Permission action ) const ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
* This method is called when the orientation has been changed by the user .
*/
2007-01-05 17:09:47 +00:00
virtual void rotationChanged ( Rotation orientation , Rotation oldOrientation ) ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
2007-01-05 23:12:06 +00:00
* Returns the list of supported page sizes .
2006-10-20 16:51:46 +00:00
*/
2007-01-05 23:12:06 +00:00
virtual PageSize : : List pageSizes ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
2007-01-05 23:12:06 +00:00
* This method is called when the page size has been changed by the user .
2006-10-20 16:51:46 +00:00
*/
2007-01-05 23:12:06 +00:00
virtual void pageSizeChanged ( const PageSize & pageSize , const PageSize & oldPageSize ) ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
* This method is called to print the document to the given @ p printer .
*/
2007-10-15 23:01:27 +00:00
virtual bool print ( QPrinter & printer ) ;
2020-07-10 22:15:05 +00:00
2010-04-14 23:07:27 +00:00
/**
* Possible print errors
* @ since 0.11 ( KDE 4.5 )
*/
enum PrintError {
NoPrintError , ///< There was no print error
UnknownPrintError ,
TemporaryFileOpenPrintError ,
FileConversionPrintError ,
PrintingProcessCrashPrintError ,
PrintingProcessStartPrintError ,
PrintToFilePrintError ,
InvalidPrinterStatePrintError ,
UnableToFindFilePrintError ,
NoFileToPrintError ,
2014-01-12 18:16:04 +00:00
NoBinaryToPrintError ,
InvalidPageSizePrintError ///< @since 0.18.2 (KDE 4.12.2)
2010-04-14 23:07:27 +00:00
} ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
* This method returns the meta data of the given @ p key with the given @ p option
* of the document .
*/
2006-10-28 19:18:36 +00:00
virtual QVariant metaData ( const QString & key , const QVariant & option ) const ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
* Returns the list of additional supported export formats .
*/
2006-10-25 15:35:53 +00:00
virtual ExportFormat : : List exportFormats ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
2006-10-25 15:35:53 +00:00
* This method is called to export the document in the given @ p format and save it
* under the given @ p fileName . The format must be one of the supported export formats .
2006-10-20 16:51:46 +00:00
*/
2006-10-25 15:35:53 +00:00
virtual bool exportTo ( const QString & fileName , const ExportFormat & format ) ;
2020-07-10 22:15:05 +00:00
2014-05-10 13:31:59 +00:00
/**
* This method is called to know which wallet data should be used for the given file name .
* Unless you have very special requirements to where wallet data should be stored you
* don ' t need to reimplement this method .
*/
virtual void walletDataForFile ( const QString & fileName , QString * walletName , QString * walletFolder , QString * walletKey ) const ;
2020-07-10 22:15:05 +00:00
2007-01-12 22:49:14 +00:00
/**
* Query for the specified @ p feature .
*/
2007-01-26 16:35:30 +00:00
bool hasFeature ( GeneratorFeature feature ) const ;
2020-07-10 22:15:05 +00:00
2014-01-13 00:15:55 +00:00
/**
* Update DPI of the generator
*
* @ since 0.19 ( KDE 4.13 )
*/
2020-02-20 17:45:46 +00:00
void setDPI ( const QSizeF & dpi ) ; // TODO remove the & when we do a BIC change elsewhere
2020-07-10 22:15:05 +00:00
2015-05-27 13:56:56 +00:00
/**
* Returns the ' layers model ' object of the document or NULL if
* layers model is not available .
2015-09-14 23:38:09 +00:00
*
* @ since 0.24
2015-05-27 13:56:56 +00:00
*/
virtual QAbstractItemModel * layersModel ( ) const ;
2020-07-10 22:15:05 +00:00
2016-11-26 15:00:02 +00:00
/**
* Calls the backend to execute an BackendOpaqueAction
*/
virtual void opaqueAction ( const BackendOpaqueAction * action ) ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
Q_SIGNALS :
/**
2006-12-28 16:58:56 +00:00
* This signal should be emitted whenever an error occurred in the generator .
2006-10-20 16:51:46 +00:00
*
* @ param message The message which should be shown to the user .
* @ param duration The time that the message should be shown to the user .
*/
void error ( const QString & message , int duration ) ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
* This signal should be emitted whenever the user should be warned .
*
* @ param message The message which should be shown to the user .
* @ param duration The time that the message should be shown to the user .
*/
void warning ( const QString & message , int duration ) ;
2020-07-10 22:15:05 +00:00
2006-10-20 16:51:46 +00:00
/**
* This signal should be emitted whenever the user should be noticed .
*
* @ param message The message which should be shown to the user .
* @ param duration The time that the message should be shown to the user .
*/
void notice ( const QString & message , int duration ) ;
2020-07-10 22:15:05 +00:00
2005-11-04 11:59:51 +00:00
protected :
2006-10-20 16:51:46 +00:00
/**
2007-01-13 22:55:00 +00:00
* This method must be called when the pixmap request triggered by generatePixmap ( )
2006-10-20 16:51:46 +00:00
* has been finished .
*/
2007-01-29 08:17:45 +00:00
void signalPixmapRequestDone ( PixmapRequest * request ) ;
2020-07-10 22:15:05 +00:00
2008-05-04 15:10:32 +00:00
/**
* This method must be called when a text generation has been finished .
*/
void signalTextGenerationDone ( Page * page , TextPage * textPage ) ;
2020-07-10 22:15:05 +00:00
2007-10-08 16:46:51 +00:00
/**
* This method is called when the document is closed and not used
* any longer .
*
* @ returns true on success , false otherwise .
*/
virtual bool doCloseDocument ( ) = 0 ;
2020-07-10 22:15:05 +00:00
2007-01-24 15:06:45 +00:00
/**
2007-01-31 18:31:19 +00:00
* Returns the image of the page as specified in
* the passed pixmap @ p request .
*
2018-02-01 18:42:37 +00:00
* Must return a null image if the request was cancelled and the generator supports cancelling
*
2007-01-31 18:31:19 +00:00
* @ warning this method may be executed in its own separated thread if the
* @ ref Threaded is enabled !
2007-01-24 18:27:54 +00:00
*/
2019-12-20 15:40:59 +00:00
virtual QImage image ( PixmapRequest * request ) ;
2020-07-10 22:15:05 +00:00
2007-01-24 15:06:45 +00:00
/**
2018-02-01 18:42:37 +00:00
* Returns the text page for the given @ p request .
*
* Must return a null pointer if the request was cancelled and the generator supports cancelling
2007-01-24 15:06:45 +00:00
*
2007-01-31 18:31:19 +00:00
* @ warning this method may be executed in its own separated thread if the
* @ ref Threaded is enabled !
2018-02-01 18:42:37 +00:00
*
* @ since 1.4
2007-01-24 15:06:45 +00:00
*/
2018-02-01 18:42:37 +00:00
virtual TextPage * textPage ( TextRequest * request ) ;
2020-07-10 22:15:05 +00:00
2006-10-22 11:25:08 +00:00
/**
* Returns a pointer to the document .
*/
2007-03-17 12:11:41 +00:00
const Document * document ( ) const ;
2020-07-10 22:15:05 +00:00
2007-01-26 16:35:30 +00:00
/**
* Toggle the @ p feature .
*/
void setFeature ( GeneratorFeature feature , bool on = true ) ;
2020-07-10 22:15:05 +00:00
2017-03-02 20:04:59 +00:00
/**
* Internal document setting
*/
enum DocumentMetaDataKey {
2017-03-02 21:23:41 +00:00
PaperColorMetaData , ///< Returns (QColor) the paper color if set in Settings or the default color (white) if option is true (otherwise returns a non initialized QColor)
TextAntialiasMetaData , ///< Returns (bool) text antialias from Settings (option is not used)
GraphicsAntialiasMetaData , ///< Returns (bool)graphic antialias from Settings (option is not used)
TextHintingMetaData ///< Returns (bool)text hinting from Settings (option is not used)
2017-03-02 20:04:59 +00:00
} ;
2020-07-10 22:15:05 +00:00
2017-03-02 20:04:59 +00:00
/**
* Request a meta data of the Document , if available , like an internal
* setting .
*
* @ since 1.1
*/
2017-03-02 21:45:45 +00:00
QVariant documentMetaData ( const DocumentMetaDataKey key , const QVariant & option = QVariant ( ) ) const ;
2020-07-10 22:15:05 +00:00
2007-09-14 22:16:00 +00:00
/**
* Request a meta data of the Document , if available , like an internal
* setting .
*/
2017-03-02 20:04:59 +00:00
OKULARCORE_DEPRECATED QVariant documentMetaData ( const QString & key , const QVariant & option = QVariant ( ) ) const ;
2020-07-10 22:15:05 +00:00
2007-09-15 11:35:53 +00:00
/**
* Return the pointer to a mutex the generator can use freely .
*/
QMutex * userMutex ( ) const ;
2020-07-10 22:15:05 +00:00
2008-05-18 23:06:21 +00:00
/**
* Set the bounding box of a page after the page has already been handed
* to the Document . Call this instead of Page : : setBoundingBox ( ) to ensure
* that all observers are notified .
*
* @ since 0.7 ( KDE 4.1 )
*/
void updatePageBoundingBox ( int page , const NormalizedRect & boundingBox ) ;
2020-07-10 22:15:05 +00:00
2014-01-13 00:15:55 +00:00
/**
* Returns DPI , previously set via setDPI ( )
* @ since 0.19 ( KDE 4.13 )
*/
QSizeF dpi ( ) const ;
2020-07-10 22:15:05 +00:00
2008-08-01 20:26:22 +00:00
protected Q_SLOTS :
/**
* Gets the font data for the given font
*
* @ since 0.8 ( KDE 4.1 )
*/
2020-07-11 05:50:05 +00:00
// TODO Make it return a QByteArray and be virtual when a BIC change happens somewhere else
2008-08-01 20:26:22 +00:00
void requestFontData ( const Okular : : FontInfo & font , QByteArray * data ) ;
2020-07-10 22:15:05 +00:00
2017-10-03 07:29:18 +00:00
/**
* This method can be called to trigger a partial pixmap update for the given request
* Make sure you call it in a way it ' s executed in the main thread .
* @ since 1.3
*/
void signalPartialPixmapRequest ( Okular : : PixmapRequest * request , const QImage & image ) ;
2020-07-10 22:15:05 +00:00
2007-09-14 13:31:55 +00:00
protected :
2020-02-20 11:41:37 +00:00
/**
* Returns the last print error in case print ( ) failed
* @ since 0.11 ( KDE 4.5 )
*/
// TODO Make print() return a PrintError instead of bool and remove this function when a BIC change happens somewhere else
Q_INVOKABLE Okular : : Generator : : PrintError printError ( ) const ;
2020-07-10 22:15:05 +00:00
2007-09-01 22:48:28 +00:00
/// @cond PRIVATE
2014-09-17 21:52:14 +00:00
Generator ( GeneratorPrivate & dd , QObject * parent , const QVariantList & args ) ;
2007-09-14 13:31:55 +00:00
Q_DECLARE_PRIVATE ( Generator )
GeneratorPrivate * d_ptr ;
2020-07-10 22:15:05 +00:00
2007-04-20 17:26:04 +00:00
friend class Document ;
2008-11-09 12:40:05 +00:00
friend class DocumentPrivate ;
2007-09-01 22:48:28 +00:00
/// @endcond PRIVATE
2020-07-10 22:15:05 +00:00
2007-09-14 13:31:55 +00:00
private :
Q_DISABLE_COPY ( Generator )
2004-12-22 18:21:36 +00:00
} ;
/**
* @ short Describes a pixmap type request .
*/
2014-10-27 21:35:06 +00:00
class OKULARCORE_EXPORT PixmapRequest
2006-07-01 22:17:53 +00:00
{
2006-10-25 17:43:15 +00:00
friend class Document ;
2007-09-30 21:44:31 +00:00
friend class DocumentPrivate ;
2006-10-25 17:43:15 +00:00
public :
2013-02-24 21:58:53 +00:00
enum PixmapRequestFeature { NoFeature = 0 , Asynchronous = 1 , Preload = 2 } ;
Q_DECLARE_FLAGS ( PixmapRequestFeatures , PixmapRequestFeature )
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Creates a new pixmap request .
*
2013-02-24 21:58:53 +00:00
* @ param observer The observer .
2006-10-25 17:43:15 +00:00
* @ param pageNumber The page number .
* @ param width The width of the page .
* @ param height The height of the page .
* @ param priority The priority of the request .
2013-02-24 21:58:53 +00:00
* @ param features The features of generation .
2006-10-25 17:43:15 +00:00
*/
2013-02-24 21:58:53 +00:00
PixmapRequest ( DocumentObserver * observer , int pageNumber , int width , int height , int priority , PixmapRequestFeatures features ) ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Destroys the pixmap request .
*/
~ PixmapRequest ( ) ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
2013-02-24 21:58:53 +00:00
* Returns the observer of the request .
2006-10-25 17:43:15 +00:00
*/
2013-02-24 21:58:53 +00:00
DocumentObserver * observer ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Returns the page number of the request .
*/
int pageNumber ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Returns the page width of the requested pixmap .
*/
int width ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Returns the page height of the requested pixmap .
*/
int height ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Returns the priority ( less it better , 0 is maximum ) of the
* request .
*/
int priority ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Returns whether the generation should be done synchronous or
* asynchronous .
*
* If asynchronous , the pixmap is created in a thread and the observer
* is notified when the job is done .
*/
bool asynchronous ( ) const ;
2020-07-10 22:15:05 +00:00
2013-02-24 21:58:53 +00:00
/**
* Returns whether the generation request is for a page that is not important
* i . e . it ' s just for speeding up future rendering
*/
bool preload ( ) const ;
2020-07-10 22:15:05 +00:00
2006-10-25 17:43:15 +00:00
/**
* Returns a pointer to the page where the pixmap shall be generated for .
*/
Page * page ( ) const ;
2020-07-10 22:15:05 +00:00
2012-08-19 23:31:32 +00:00
/**
2012-08-24 16:32:39 +00:00
* Sets whether the generator should render only the given normalized
* rect or the entire page
2012-11-10 14:50:12 +00:00
*
* @ since 0.16 ( KDE 4.10 )
2012-08-24 16:32:39 +00:00
*/
void setTile ( bool tile ) ;
2020-07-10 22:15:05 +00:00
2012-08-24 16:32:39 +00:00
/**
* Returns whether the generator should render just the region given by
* normalizedRect ( ) or the entire page .
2012-11-10 14:50:12 +00:00
*
* @ since 0.16 ( KDE 4.10 )
2012-08-24 16:32:39 +00:00
*/
bool isTile ( ) const ;
2020-07-10 22:15:05 +00:00
2012-08-24 16:32:39 +00:00
/**
* Sets the region of the page to request .
2012-11-10 14:50:12 +00:00
*
* @ since 0.16 ( KDE 4.10 )
2012-08-19 23:31:32 +00:00
*/
2012-07-08 16:52:00 +00:00
void setNormalizedRect ( const NormalizedRect & rect ) ;
2020-07-10 22:15:05 +00:00
2012-08-19 23:31:32 +00:00
/**
2012-08-24 16:32:39 +00:00
* Returns the normalized region of the page to request .
2012-11-10 14:50:12 +00:00
*
* @ since 0.16 ( KDE 4.10 )
2012-08-19 23:31:32 +00:00
*/
2012-11-10 17:30:01 +00:00
const NormalizedRect & normalizedRect ( ) const ;
2020-07-10 22:15:05 +00:00
2017-10-03 07:29:18 +00:00
/**
* Sets whether the request should report back updates if possible
*
* @ since 1.3
*/
void setPartialUpdatesWanted ( bool partialUpdatesWanted ) ;
2020-07-10 22:15:05 +00:00
2017-10-03 07:29:18 +00:00
/**
* Should the request report back updates if possible ?
*
* @ since 1.3
*/
bool partialUpdatesWanted ( ) const ;
2020-07-10 22:15:05 +00:00
2018-02-01 18:42:37 +00:00
/**
* Should the request be aborted if possible ?
*
* @ since 1.4
*/
bool shouldAbortRender ( ) const ;
2020-07-10 22:15:05 +00:00
2007-09-15 13:16:30 +00:00
private :
Q_DISABLE_COPY ( PixmapRequest )
2020-07-10 22:15:05 +00:00
2007-09-30 21:44:31 +00:00
friend class PixmapRequestPrivate ;
PixmapRequestPrivate * const d ;
2006-07-01 22:17:53 +00:00
} ;
2018-02-01 18:42:37 +00:00
/**
* @ short Describes a text request .
*
* @ since 1.4
*/
class OKULARCORE_EXPORT TextRequest
{
public :
/**
* Creates a new text request .
*/
2018-09-01 08:25:57 +00:00
explicit TextRequest ( Page * page ) ;
2020-07-10 22:15:05 +00:00
2018-02-01 18:42:37 +00:00
TextRequest ( ) ;
2020-07-10 22:15:05 +00:00
2018-02-01 18:42:37 +00:00
/**
* Destroys the pixmap request .
*/
~ TextRequest ( ) ;
2020-07-10 22:15:05 +00:00
2018-02-01 18:42:37 +00:00
/**
* Returns a pointer to the page where the pixmap shall be generated for .
*/
Page * page ( ) const ;
2020-07-10 22:15:05 +00:00
2018-02-01 18:42:37 +00:00
/**
* Should the request be aborted if possible ?
*/
bool shouldAbortExtraction ( ) const ;
2020-07-10 22:15:05 +00:00
2018-02-01 18:42:37 +00:00
private :
Q_DISABLE_COPY ( TextRequest )
2020-07-10 22:15:05 +00:00
2018-02-01 18:42:37 +00:00
friend TextRequestPrivate ;
TextRequestPrivate * const d ;
} ;
2006-09-21 08:45:36 +00:00
}
2010-04-14 23:33:14 +00:00
Q_DECLARE_METATYPE ( Okular : : Generator : : PrintError )
2017-10-03 07:29:18 +00:00
Q_DECLARE_METATYPE ( Okular : : PixmapRequest * )
2010-04-14 23:33:14 +00:00
2014-08-10 12:42:51 +00:00
# define OkularGeneratorInterface_iid "org.kde.okular.Generator"
Q_DECLARE_INTERFACE ( Okular : : Generator , OkularGeneratorInterface_iid )
2007-07-30 23:58:04 +00:00
# ifndef QT_NO_DEBUG_STREAM
2014-10-27 21:35:06 +00:00
OKULARCORE_EXPORT QDebug operator < < ( QDebug str , const Okular : : PixmapRequest & req ) ;
2007-07-30 23:58:04 +00:00
# endif
2006-10-22 13:34:47 +00:00
2004-12-10 16:04:45 +00:00
# endif
2010-04-14 23:07:27 +00:00
/* kate: replace-tabs on; indent-width 4; */