okular/core/generator.h

   1 /***************************************************************************
   2  *   Copyright (C) 2004-5 by Enrico Ros <eros.kde@email.it>                *
   3  *   Copyright (C) 2005   by Piotr Szymanski <niedakh@gmail.com>           *
   4  *   Copyright (C) 2008   by Albert Astals Cid <aacid@kde.org>             *
   5  *                                                                         *
   6  *   This program is free software; you can redistribute it and/or modify  *
   7  *   it under the terms of the GNU General Public License as published by  *
   8  *   the Free Software Foundation; either version 2 of the License, or     *
   9  *   (at your option) any later version.                                   *
  10  ***************************************************************************/
  11
  12 #ifndef _OKULAR_GENERATOR_H_
  13 #define _OKULAR_GENERATOR_H_
  14
  15 #include <okular/core/okular_export.h>
  16 #include <okular/core/fontinfo.h>
  17 #include <okular/core/global.h>
  18 #include <okular/core/pagesize.h>
  19
  20 #include <QtCore/QList>
  21 #include <QtCore/QObject>
  22 #include <QtCore/QSharedDataPointer>
  23 #include <QtCore/QString>
  24 #include <QtCore/QVariant>
  25 #include <QtCore/QVector>
  26
  27 #include <kmimetype.h>
  28 #include <kpluginfactory.h>
  29
  30 #define OKULAR_EXPORT_PLUGIN( classname, aboutdata ) \
  31     K_PLUGIN_FACTORY( classname ## Factory, registerPlugin< classname >(); ) \
  32     K_EXPORT_PLUGIN( classname ## Factory( aboutdata ) )
  33
  34 class QByteArray;
  35 class QMutex;
  36 class QPrinter;
  37 class QPrintDialog;
  38 class KIcon;
  39
  40 namespace Okular {
  41
  42 class Document;
  43 class DocumentFonts;
  44 class DocumentInfo;
  45 class DocumentSynopsis;
  46 class EmbeddedFile;
  47 class ExportFormatPrivate;
  48 class FontInfo;
  49 class GeneratorPrivate;
  50 class Page;
  51 class PixmapRequest;
  52 class PixmapRequestPrivate;
  53 class TextPage;
  54 class NormalizedRect;
  55
  56 /* Note: on contents generation and asynchronous queries.
  57  * Many observers may want to request data syncronously or asynchronously.
  58  * - Sync requests. These should be done in-place.
  59  * - Async request must be done in real background. That usually means a
  60  *   thread, such as QThread derived classes.
  61  * Once contents are available, they must be immediately stored in the
  62  * Page they refer to, and a signal is emitted as soon as storing
  63  * (even for sync or async queries) has been done.
  64  */
  65
  66 /**
  67  * @short Defines an entry for the export menu
  68  *
  69  * This class encapsulates information about an export format.
  70  * Every Generator can support 0 or more export formats which can be
  71  * queried with @ref Generator::exportFormats().
  72  */
  73 class OKULAR_EXPORT ExportFormat
  74 {
  75     public:
  76         typedef QList<ExportFormat> List;
  77
  78         /**
  79          * Creates an empty export format.
  80          *
  81          * @see isNull()
  82          */
  83         ExportFormat();
  84
  85         /**
  86          * Creates a new export format.
  87          *
  88          * @param description The i18n'ed description of the format.
  89          * @param mimeType The supported mime type of the format.
  90          */
  91         ExportFormat( const QString &description, const KMimeType::Ptr &mimeType );
  92
  93         /**
  94          * Creates a new export format.
  95          *
  96          * @param icon The icon used in the GUI for this format.
  97          * @param description The i18n'ed description of the format.
  98          * @param mimeType The supported mime type of the format.
  99          */
 100         ExportFormat( const KIcon &icon, const QString &description, const KMimeType::Ptr &mimeType );
 101
 102         /**
 103          * Destroys the export format.
 104          */
 105         ~ExportFormat();
 106
 107         /**
 108          * @internal
 109          */
 110         ExportFormat( const ExportFormat &other );
 111
 112         /**
 113          * @internal
 114          */
 115         ExportFormat& operator=( const ExportFormat &other );
 116
 117         /**
 118          * Returns the description of the format.
 119          */
 120         QString description() const;
 121
 122         /**
 123          * Returns the mime type of the format.
 124          */
 125         KMimeType::Ptr mimeType() const;
 126
 127         /**
 128          * Returns the icon for GUI representations of the format.
 129          */
 130         KIcon icon() const;
 131
 132         /**
 133          * Returns whether the export format is null/valid.
 134          *
 135          * An ExportFormat is null if the mimetype is not valid or the
 136          * description is empty, or both.
 137          */
 138         bool isNull() const;
 139
 140         /**
 141          * Type of standard export format.
 142          */
 143         enum StandardExportFormat
 144         {
 145             PlainText,         ///< Plain text
 146             PDF,               ///< PDF, aka Portable Document Format
 147             OpenDocumentText,  ///< OpenDocument Text format @since 0.8 (KDE 4.2)
 148             HTML   ///< OpenDocument Text format @since 0.8 (KDE 4.2)
 149         };
 150
 151         /**
 152          * Builds a standard format for the specified @p type .
 153          */
 154         static ExportFormat standardFormat( StandardExportFormat type );
 155
 156         bool operator==( const ExportFormat &other ) const;
 157
 158         bool operator!=( const ExportFormat &other ) const;
 159
 160     private:
 161         /// @cond PRIVATE
 162         friend class ExportFormatPrivate;
 163         /// @endcond
 164         QSharedDataPointer<ExportFormatPrivate> d;
 165 };
 166
 167 /**
 168  * @short [Abstract Class] The information generator.
 169  *
 170  * Most of class members are virtuals and some of them pure virtual. The pure
 171  * virtuals provide the minimal functionalities for a Generator, that is being
 172  * able to generate QPixmap for the Page 's of the Document.
 173  *
 174  * Implementing the other functions will make the Generator able to provide
 175  * more contents and/or functionalities (like text extraction).
 176  *
 177  * Generation/query is requested by the Document class only, and that
 178  * class stores the resulting data into Page s. The data will then be
 179  * displayed by the GUI components (PageView, ThumbnailList, etc..).
 180  *
 181  * @see PrintInterface, ConfigInterface, GuiInterface
 182  */
 183 class OKULAR_EXPORT Generator : public QObject
 184 {
 185     /// @cond PRIVATE
 186     friend class PixmapGenerationThread;
 187     friend class TextPageGenerationThread;
 188     /// @endcond
 189
 190     Q_OBJECT
 191
 192     public:
 193         /**
 194          * Describe the possible optional features that a Generator can
 195          * provide.
 196          */
 197         enum GeneratorFeature
 198         {
 199             Threaded,
 200             TextExtraction,    ///< Whether the Generator can extract text from the document in the form of TextPage's
 201             ReadRawData,       ///< Whether the Generator can read a document directly from its raw data.
 202             FontInfo,          ///< Whether the Generator can provide information about the fonts used in the document
 203             PageSizes,         ///< Whether the Generator can change the size of the document pages.
 204             PrintNative,       ///< Whether the Generator supports native cross-platform printing (QPainter-based).
 205             PrintPostscript,   ///< Whether the Generator supports postscript-based file printing.
 206             PrintToFile        ///< Whether the Generator supports export to PDF & PS through the Print Dialog
 207         };
 208
 209         /**
 210          * Creates a new generator.
 211          */
 212         Generator( QObject *parent, const QVariantList &args );
 213
 214         /**
 215          * Destroys the generator.
 216          */
 217         virtual ~Generator();
 218
 219         /**
 220          * Loads the document with the given @p fileName and fills the
 221          * @p pagesVector with the parsed pages.
 222          *
 223          * @returns true on success, false otherwise.
 224          */
 225         virtual bool loadDocument( const QString & fileName, QVector< Page * > & pagesVector ) = 0;
 226
 227         /**
 228          * Loads the document from the raw data @p fileData and fills the
 229          * @p pagesVector with the parsed pages.
 230          *
 231          * @note the Generator has to have the feature @ref ReadRawData enabled
 232          *
 233          * @returns true on success, false otherwise.
 234          */
 235         virtual bool loadDocumentFromData( const QByteArray & fileData, QVector< Page * > & pagesVector );
 236
 237         /**
 238          * This method is called when the document is closed and not used
 239          * any longer.
 240          *
 241          * @returns true on success, false otherwise.
 242          */
 243         bool closeDocument();
 244
 245         /**
 246          * This method returns whether the generator is ready to
 247          * handle a new pixmap request.
 248          */
 249         virtual bool canGeneratePixmap() const;
 250
 251         /**
 252          * This method can be called to trigger the generation of
 253          * a new pixmap as described by @p request.
 254          */
 255         virtual void generatePixmap( PixmapRequest * request );
 256
 257         /**
 258          * This method returns whether the generator is ready to
 259          * handle a new text page request.
 260          */
 261         virtual bool canGenerateTextPage() const;
 262
 263         /**
 264          * This method can be called to trigger the generation of
 265          * a text page for the given @p page.
 266          *
 267          * The generation is done synchronous or asynchronous, depending
 268          * on the @p type parameter and the capabilities of the
 269          * generator (e.g. multithreading).
 270          *
 271          * @see TextPage
 272          */
 273         virtual void generateTextPage( Page * page );
 274
 275         /**
 276          * Returns the general information object of the document or 0 if
 277          * no information are available.
 278          */
 279         virtual const DocumentInfo * generateDocumentInfo();
 280
 281         /**
 282          * Returns the 'table of content' object of the document or 0 if
 283          * no table of content is available.
 284          */
 285         virtual const DocumentSynopsis * generateDocumentSynopsis();
 286
 287         /**
 288          * Returns the 'list of embedded fonts' object of the specified \page
 289          * of the document.
 290          *
 291          * \param page a page of the document, starting from 0 - -1 indicates all
 292          * the other fonts
 293          */
 294         virtual FontInfo::List fontsForPage( int page );
 295
 296         /**
 297          * Returns the 'list of embedded files' object of the document or 0 if
 298          * no list of embedded files is available.
 299          */
 300         virtual const QList<EmbeddedFile*> * embeddedFiles() const;
 301
 302         /**
 303          * This enum identifies the metric of the page size.
 304          */
 305         enum PageSizeMetric
 306         {
 307           None,   ///< The page size is not defined in a physical metric.
 308           Points  ///< The page size is given in 1/72 inches.
 309         };
 310
 311         /**
 312          * This method returns the metric of the page size. Default is @ref None.
 313          */
 314         virtual PageSizeMetric pagesSizeMetric() const;
 315
 316         /**
 317          * This method returns whether given @p action (@ref Permission) is
 318          * allowed in this document.
 319          */
 320         virtual bool isAllowed( Permission action ) const;
 321
 322         /**
 323          * This method is called when the orientation has been changed by the user.
 324          */
 325         virtual void rotationChanged( Rotation orientation, Rotation oldOrientation );
 326
 327         /**
 328          * Returns the list of supported page sizes.
 329          */
 330         virtual PageSize::List pageSizes() const;
 331
 332         /**
 333          * This method is called when the page size has been changed by the user.
 334          */
 335         virtual void pageSizeChanged( const PageSize &pageSize, const PageSize &oldPageSize );
 336
 337         /**
 338          * This method is called to print the document to the given @p printer.
 339          */
 340         virtual bool print( QPrinter &printer );
 341
 342         /**
 343          * This method returns the meta data of the given @p key with the given @p option
 344          * of the document.
 345          */
 346         virtual QVariant metaData( const QString &key, const QVariant &option ) const;
 347
 348         /**
 349          * Returns the list of additional supported export formats.
 350          */
 351         virtual ExportFormat::List exportFormats() const;
 352
 353         /**
 354          * This method is called to export the document in the given @p format and save it
 355          * under the given @p fileName. The format must be one of the supported export formats.
 356          */
 357         virtual bool exportTo( const QString &fileName, const ExportFormat &format );
 358
 359         /**
 360          * Query for the specified @p feature.
 361          */
 362         bool hasFeature( GeneratorFeature feature ) const;
 363
 364     Q_SIGNALS:
 365         /**
 366          * This signal should be emitted whenever an error occurred in the generator.
 367          *
 368          * @param message The message which should be shown to the user.
 369          * @param duration The time that the message should be shown to the user.
 370          */
 371         void error( const QString &message, int duration );
 372
 373         /**
 374          * This signal should be emitted whenever the user should be warned.
 375          *
 376          * @param message The message which should be shown to the user.
 377          * @param duration The time that the message should be shown to the user.
 378          */
 379         void warning( const QString &message, int duration );
 380
 381         /**
 382          * This signal should be emitted whenever the user should be noticed.
 383          *
 384          * @param message The message which should be shown to the user.
 385          * @param duration The time that the message should be shown to the user.
 386          */
 387         void notice( const QString &message, int duration );
 388
 389     protected:
 390         /**
 391          * This method must be called when the pixmap request triggered by generatePixmap()
 392          * has been finished.
 393          */
 394         void signalPixmapRequestDone( PixmapRequest * request );
 395
 396         /**
 397          * This method must be called when a text generation has been finished.
 398          */
 399         void signalTextGenerationDone( Page *page, TextPage *textPage );
 400
 401         /**
 402          * This method is called when the document is closed and not used
 403          * any longer.
 404          *
 405          * @returns true on success, false otherwise.
 406          */
 407         virtual bool doCloseDocument() = 0;
 408
 409         /**
 410          * Returns the image of the page as specified in
 411          * the passed pixmap @p request.
 412          *
 413          * @warning this method may be executed in its own separated thread if the
 414          * @ref Threaded is enabled!
 415          */
 416         virtual QImage image( PixmapRequest *page );
 417
 418         /**
 419          * Returns the text page for the given @p page.
 420          *
 421          * @warning this method may be executed in its own separated thread if the
 422          * @ref Threaded is enabled!
 423          */
 424         virtual TextPage* textPage( Page *page );
 425
 426         /**
 427          * Returns a pointer to the document.
 428          */
 429         const Document * document() const;
 430
 431         /**
 432          * Toggle the @p feature .
 433          */
 434         void setFeature( GeneratorFeature feature, bool on = true );
 435
 436         /**
 437          * Request a meta data of the Document, if available, like an internal
 438          * setting.
 439          */
 440         QVariant documentMetaData( const QString &key, const QVariant &option = QVariant() ) const;
 441
 442         /**
 443          * Return the pointer to a mutex the generator can use freely.
 444          */
 445         QMutex* userMutex() const;
 446
 447         /**
 448          * Set the bounding box of a page after the page has already been handed
 449          * to the Document. Call this instead of Page::setBoundingBox() to ensure
 450          * that all observers are notified.
 451          *
 452          * @since 0.7 (KDE 4.1)
 453          */
 454         void updatePageBoundingBox( int page, const NormalizedRect & boundingBox );
 455
 456     protected Q_SLOTS:
 457         /**
 458          * Gets the font data for the given font
 459          *
 460          * @since 0.8 (KDE 4.1)
 461          */
 462         void requestFontData(const Okular::FontInfo &font, QByteArray *data);
 463
 464     protected:
 465         /// @cond PRIVATE
 466         Generator( GeneratorPrivate &dd, QObject *parent, const QVariantList &args );
 467         Q_DECLARE_PRIVATE( Generator )
 468         GeneratorPrivate *d_ptr;
 469
 470         friend class Document;
 471         /// @endcond PRIVATE
 472
 473     private:
 474         Q_DISABLE_COPY( Generator )
 475
 476         Q_PRIVATE_SLOT( d_func(), void pixmapGenerationFinished() )
 477         Q_PRIVATE_SLOT( d_func(), void textpageGenerationFinished() )
 478 };
 479
 480 /**
 481  * @short Describes a pixmap type request.
 482  */
 483 class OKULAR_EXPORT PixmapRequest
 484 {
 485     friend class Document;
 486     friend class DocumentPrivate;
 487
 488     public:
 489         /**
 490          * Creates a new pixmap request.
 491          *
 492          * @param id The observer id.
 493          * @param pageNumber The page number.
 494          * @param width The width of the page.
 495          * @param height The height of the page.
 496          * @param priority The priority of the request.
 497          * @param asynchronous The mode of generation.
 498          */
 499         PixmapRequest( int id, int pageNumber, int width, int height, int priority, bool asynchronous );
 500
 501         /**
 502          * Destroys the pixmap request.
 503          */
 504         ~PixmapRequest();
 505
 506         /**
 507          * Returns the observer id of the request.
 508          */
 509         int id() const;
 510
 511         /**
 512          * Returns the page number of the request.
 513          */
 514         int pageNumber() const;
 515
 516         /**
 517          * Returns the page width of the requested pixmap.
 518          */
 519         int width() const;
 520
 521         /**
 522          * Returns the page height of the requested pixmap.
 523          */
 524         int height() const;
 525
 526         /**
 527          * Returns the priority (less it better, 0 is maximum) of the
 528          * request.
 529          */
 530         int priority() const;
 531
 532         /**
 533          * Returns whether the generation should be done synchronous or
 534          * asynchronous.
 535          *
 536          * If asynchronous, the pixmap is created in a thread and the observer
 537          * is notified when the job is done.
 538          */
 539         bool asynchronous() const;
 540
 541         /**
 542          * Returns a pointer to the page where the pixmap shall be generated for.
 543          */
 544         Page *page() const;
 545
 546     private:
 547         Q_DISABLE_COPY( PixmapRequest )
 548
 549         friend class PixmapRequestPrivate;
 550         PixmapRequestPrivate* const d;
 551 };
 552
 553 }
 554
 555 #ifndef QT_NO_DEBUG_STREAM
 556 OKULAR_EXPORT QDebug operator<<( QDebug str, const Okular::PixmapRequest &req );
 557 #endif
 558
 559 #endif