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  * @since 0.7 (KDE 4.1)
83  */
84  void addMetaData(DocumentInfo::Key key, const QString &value);
85 
86  /**
87  * This signal should be emitted whenever an error occurred in the converter.
88  *
89  * @param message The message which should be shown to the user.
90  * @param duration The time that the message should be shown to the user.
91  */
92  void error(const QString &message, int duration);
93 
94  /**
95  * This signal should be emitted whenever the user should be warned.
96  *
97  * @param message The message which should be shown to the user.
98  * @param duration The time that the message should be shown to the user.
99  */
100  void warning(const QString &message, int duration);
101 
102  /**
103  * This signal should be emitted whenever the user should be noticed.
104  *
105  * @param message The message which should be shown to the user.
106  * @param duration The time that the message should be shown to the user.
107  */
108  void notice(const QString &message, int duration);
109 
110 protected:
111  /**
112  * Sets the converted QTextDocument object.
113  */
114  void setDocument(QTextDocument *document);
115 
116  /**
117  * This method can be used to calculate the viewport for a given text block.
118  *
119  * @note This method should be called at the end of the conversion, because it
120  * triggers QTextDocument to do the layout calculation.
121  */
122  DocumentViewport calculateViewport(QTextDocument *document, const QTextBlock &block);
123 
124  /**
125  * Returns the generator that owns this converter.
126  *
127  * @note May be null if the converter was not created for a generator.
128  *
129  * @since 0.7 (KDE 4.1)
130  */
131  TextDocumentGenerator *generator() const;
132 
133 private:
134  TextDocumentConverterPrivate *d_ptr;
135  Q_DECLARE_PRIVATE(TextDocumentConverter)
136  Q_DISABLE_COPY(TextDocumentConverter)
137 };
138 
139 /**
140  * @brief QTextDocument-based Generator
141  *
142  * This generator provides a document in the form of a QTextDocument object,
143  * parsed using a specialized TextDocumentConverter.
144  */
145 class OKULARCORE_EXPORT TextDocumentGenerator : public Generator, public Okular::ConfigInterface
146 {
147  /// @cond PRIVATE
148  friend class TextDocumentConverter;
149  /// @endcond
150 
151  Q_OBJECT
152  Q_INTERFACES(Okular::ConfigInterface)
153 
154 public:
155  /**
156  * Creates a new generator that uses the specified @p converter.
157  *
158  * @param converter The text document converter.
159  * @param configName - see Okular::TextDocumentSettings
160  * @param parent The parent object.
161  * @param args The arguments.
162  *
163  * @note the generator will take ownership of the converter, so you
164  * don't have to delete it yourself
165  * @since 0.17 (KDE 4.11)
166  */
167  TextDocumentGenerator(TextDocumentConverter *converter, const QString &configName, QObject *parent, const QVariantList &args);
168 
169  ~TextDocumentGenerator() override;
170 
171  // [INHERITED] load a document and fill up the pagesVector
172  Document::OpenResult loadDocumentWithPassword(const QString &fileName, QVector<Okular::Page *> &pagesVector, const QString &password) override;
173 
174  // [INHERITED] perform actions on document / pages
175  bool canGeneratePixmap() const override;
176  void generatePixmap(Okular::PixmapRequest *request) override;
177 
178  // [INHERITED] print document using already configured QPrinter
179  Document::PrintError print(QPrinter &printer) override;
180 
181  // [INHERITED] text exporting
182  Okular::ExportFormat::List exportFormats() const override;
183  bool exportTo(const QString &fileName, const Okular::ExportFormat &format) override;
184 
185  // [INHERITED] config interface
186  /// By default checks if the default font has changed or not
187  bool reparseConfig() override;
188  /// Does nothing by default. You need to reimplement it in your generator
189  void addPages(KConfigDialog *dlg) override;
190 
191  /**
192  * Config skeleton for TextDocumentSettingsWidget
193  *
194  * You must use new construtor to initialize TextDocumentSettings,
195  * that contain @p configName .
196  *
197  * @since 0.17 (KDE 4.11)
198  */
199  TextDocumentSettings *generalSettings();
200 
201  Okular::DocumentInfo generateDocumentInfo(const QSet<DocumentInfo::Key> &keys) const override;
202  const Okular::DocumentSynopsis *generateDocumentSynopsis() override;
203 
204 protected:
205  bool doCloseDocument() override;
206  Okular::TextPage *textPage(Okular::TextRequest *request) override;
207 
208  /* @since 1.8 */
209  TextDocumentConverter *converter();
210 
211  /* @since 1.8 */
212  void setTextDocument(QTextDocument *textDocument);
213 
214 private:
215  Q_DECLARE_PRIVATE(TextDocumentGenerator)
216  Q_DISABLE_COPY(TextDocumentGenerator)
217 };
218 
219 }
220 
221 #endif
QTextDocument-based Generator.
The documentation to the global Okular namespace.
Definition: action.h:16
Annotation struct holds properties shared by all annotations.
Definition: annotations.h:95
Encapsulates data that describes an action.
Definition: action.h:40
A DOM tree that describes the Table of Contents.
Definition: document.h:1432
Key
The list of predefined keys.
Definition: document.h:82
Defines an entry for the export menu.
Definition: generator.h:78
Represents the textual information of a Page.
Definition: textpage.h:105
Describes a pixmap type request.
Definition: generator.h:610
OpenResult
Describes the result of an open document operation.
Definition: document.h:209
[Abstract Class] The information generator.
Definition: generator.h:187
Describes a text request.
Definition: generator.h:758
void error(QWidget *parent, const QString &text, const QString &title, const KGuiItem &buttonOk, Options options=Notify)
T convert(const QVariant &value)
Abstract interface for configuration control.
QString message
The DocumentInfo structure can be filled in by generators to display metadata about the currently ope...
Definition: document.h:74
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Mar 23 2023 04:04:24 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.