Okular

textdocumentgenerator.h
1 /*
2  SPDX-FileCopyrightText: 2007 Tobias Koenig <[email protected]>
3 
4  SPDX-License-Identifier: GPL-2.0-or-later
5 */
6 
7 #ifndef _OKULAR_TEXTDOCUMENTGENERATOR_H_
8 #define _OKULAR_TEXTDOCUMENTGENERATOR_H_
9 
10 #include "okularcore_export.h"
11 
12 #include "../interfaces/configinterface.h"
13 #include "document.h"
14 #include "generator.h"
15 #include "textdocumentsettings.h"
16 
17 class QTextBlock;
18 class QTextDocument;
19 
20 namespace Okular
21 {
22 class TextDocumentConverterPrivate;
23 class TextDocumentGenerator;
24 class TextDocumentGeneratorPrivate;
25 
26 class OKULARCORE_EXPORT TextDocumentConverter : public QObject
27 {
28  Q_OBJECT
29 
30  friend class TextDocumentGenerator;
31  friend class TextDocumentGeneratorPrivate;
32 
33 public:
34  /**
35  * Creates a new generic converter.
36  */
37  TextDocumentConverter();
38 
39  /**
40  * Destroys the generic converter.
41  */
42  ~TextDocumentConverter() override;
43 
44  /**
45  * Returns the generated QTextDocument object. The caller takes ownership of the QTextDocument
46  *
47  * @note there is no need to implement this one if you implement convertWithPassword
48  */
49  virtual QTextDocument *convert(const QString &fileName);
50 
51  /**
52  * Returns the generated QTextDocument object.
53  */
54  virtual Document::OpenResult convertWithPassword(const QString &fileName, const QString &password);
55 
56  /**
57  * Returns the generated QTextDocument object. Will be null if convert didn't succeed
58  */
59  QTextDocument *document();
60 
61 Q_SIGNALS:
62  /**
63  * Adds a new link object which is located between cursorBegin and
64  * cursorEnd to the generator.
65  */
66  void addAction(Okular::Action *link, int cursorBegin, int cursorEnd);
67 
68  /**
69  * Adds a new annotation object which is located between cursorBegin and
70  * cursorEnd to the generator.
71  */
72  void addAnnotation(Okular::Annotation *annotation, int cursorBegin, int cursorEnd);
73 
74  /**
75  * Adds a new title at the given level which is located as position to the generator.
76  */
77  void addTitle(int level, const QString &title, const QTextBlock &position);
78 
79  /**
80  * Adds a set of meta data to the generator.
81  */
82  void addMetaData(const QString &key, const QString &value, const QString &title); // clazy:exclude=overloaded-signal
83 
84  // TODO When we can do a BIC change rename one of the two addMetaData functions (or see if we can kill one)
85  /**
86  * Adds a set of meta data to the generator.
87  *
88  * @since 0.7 (KDE 4.1)
89  */
90  void addMetaData(DocumentInfo::Key key, const QString &value); // clazy:exclude=overloaded-signal
91 
92  /**
93  * This signal should be emitted whenever an error occurred in the converter.
94  *
95  * @param message The message which should be shown to the user.
96  * @param duration The time that the message should be shown to the user.
97  */
98  void error(const QString &message, int duration);
99 
100  /**
101  * This signal should be emitted whenever the user should be warned.
102  *
103  * @param message The message which should be shown to the user.
104  * @param duration The time that the message should be shown to the user.
105  */
106  void warning(const QString &message, int duration);
107 
108  /**
109  * This signal should be emitted whenever the user should be noticed.
110  *
111  * @param message The message which should be shown to the user.
112  * @param duration The time that the message should be shown to the user.
113  */
114  void notice(const QString &message, int duration);
115 
116 protected:
117  /**
118  * Sets the converted QTextDocument object.
119  */
120  void setDocument(QTextDocument *document);
121 
122  /**
123  * This method can be used to calculate the viewport for a given text block.
124  *
125  * @note This method should be called at the end of the conversion, because it
126  * triggers QTextDocument to do the layout calculation.
127  */
128  DocumentViewport calculateViewport(QTextDocument *document, const QTextBlock &block);
129 
130  /**
131  * Returns the generator that owns this converter.
132  *
133  * @note May be null if the converter was not created for a generator.
134  *
135  * @since 0.7 (KDE 4.1)
136  */
137  TextDocumentGenerator *generator() const;
138 
139 private:
140  TextDocumentConverterPrivate *d_ptr;
141  Q_DECLARE_PRIVATE(TextDocumentConverter)
142  Q_DISABLE_COPY(TextDocumentConverter)
143 };
144 
145 /**
146  * @brief QTextDocument-based Generator
147  *
148  * This generator provides a document in the form of a QTextDocument object,
149  * parsed using a specialized TextDocumentConverter.
150  */
151 class OKULARCORE_EXPORT TextDocumentGenerator : public Generator, public Okular::ConfigInterface
152 {
153  /// @cond PRIVATE
154  friend class TextDocumentConverter;
155  /// @endcond
156 
157  Q_OBJECT
158  Q_INTERFACES(Okular::ConfigInterface)
159 
160 public:
161  /**
162  * Creates a new generator that uses the specified @p converter.
163  *
164  * @param converter The text document converter.
165  * @param configName - see Okular::TextDocumentSettings
166  * @param parent The parent object.
167  * @param args The arguments.
168  *
169  * @note the generator will take ownership of the converter, so you
170  * don't have to delete it yourself
171  * @since 0.17 (KDE 4.11)
172  */
173  TextDocumentGenerator(TextDocumentConverter *converter, const QString &configName, QObject *parent, const QVariantList &args);
174 
175  ~TextDocumentGenerator() override;
176 
177  // [INHERITED] load a document and fill up the pagesVector
178  Document::OpenResult loadDocumentWithPassword(const QString &fileName, QVector<Okular::Page *> &pagesVector, const QString &password) override;
179 
180  // [INHERITED] perform actions on document / pages
181  bool canGeneratePixmap() const override;
182  void generatePixmap(Okular::PixmapRequest *request) override;
183 
184  // [INHERITED] print document using already configured QPrinter
185  bool print(QPrinter &printer) override;
186 
187  // [INHERITED] text exporting
188  Okular::ExportFormat::List exportFormats() const override;
189  bool exportTo(const QString &fileName, const Okular::ExportFormat &format) override;
190 
191  // [INHERITED] config interface
192  /// By default checks if the default font has changed or not
193  bool reparseConfig() override;
194  /// Does nothing by default. You need to reimplement it in your generator
195  void addPages(KConfigDialog *dlg) override;
196 
197  /**
198  * Config skeleton for TextDocumentSettingsWidget
199  *
200  * You must use new construtor to initialize TextDocumentSettings,
201  * that contain @p configName .
202  *
203  * @since 0.17 (KDE 4.11)
204  */
205  TextDocumentSettings *generalSettings();
206 
207  Okular::DocumentInfo generateDocumentInfo(const QSet<DocumentInfo::Key> &keys) const override;
208  const Okular::DocumentSynopsis *generateDocumentSynopsis() override;
209 
210 protected:
211  bool doCloseDocument() override;
212  Okular::TextPage *textPage(Okular::TextRequest *request) override;
213 
214  /* @since 1.8 */
215  TextDocumentConverter *converter();
216 
217  /* @since 1.8 */
218  void setTextDocument(QTextDocument *textDocument);
219 
220 private:
221  Q_DECLARE_PRIVATE(TextDocumentGenerator)
222  Q_DISABLE_COPY(TextDocumentGenerator)
223 };
224 
225 }
226 
227 #endif
T convert(const QVariant &value)
Represents the textual information of a Page.
Definition: textpage.h:105
Describes a text request.
Definition: generator.h:782
global.h
Definition: action.h:16
Key
The list of predefined keys.
Definition: document.h:82
OpenResult
Describes the result of an open document operation.
Definition: document.h:209
Abstract interface for configuration control.
void error(QWidget *parent, const QString &text, const QString &caption=QString(), Options options=Notify)
Encapsulates data that describes an action.
Definition: action.h:40
The DocumentInfo structure can be filled in by generators to display metadata about the currently ope...
Definition: document.h:74
QTextDocument-based Generator.
Defines an entry for the export menu.
Definition: generator.h:78
Annotation struct holds properties shared by all annotations.
Definition: annotations.h:96
A DOM tree that describes the Table of Contents.
Definition: document.h:1382
Describes a pixmap type request.
Definition: generator.h:634
[Abstract Class] The information generator.
Definition: generator.h:187
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Nov 28 2021 22:32:38 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.