1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 1999 Simon Hausmann <hausmann@kde.org>
4 SPDX-FileCopyrightText: 1999 David Faure <faure@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef _KPARTS_READONLYPART_H
10#define _KPARTS_READONLYPART_H
11
12#include <kparts/part.h>
13
14#include <QUrl>
15
16class KJob;
17namespace KIO
18{
19class Job;
20}
21
22namespace KParts
23{
24class ReadOnlyPartPrivate;
25class NavigationExtension;
26class OpenUrlArguments;
27
28/*!
29 * \class KParts::ReadOnlyPart
30 * \inheaderfile KParts/ReadOnlyPart
31 * \inmodule KParts
32 *
33 * \brief Base class for any "viewer" part.
34 *
35 * This class takes care of network transparency for you,
36 * in the simplest way (downloading to a temporary file, then letting the part
37 * load from the temporary file).
38 * To use the built-in network transparency, you only need to implement
39 * openFile(), not openUrl().
40 *
41 * To implement network transparency differently (e.g. for progressive loading,
42 * like a web browser does for instance), or to prevent network transparency
43 * (but why would you do that?), you can override openUrl().
44 *
45 * An application using KParts can use the signals to show feedback while
46 * the URL is being loaded.
47 *
48 * ReadOnlyPart handles the window caption by setting it to the current URL
49 * (set in openUrl(), and each time the part is activated).
50 * If you want another caption, set it in openFile() and,
51 * if the part might ever be used with a part manager, in guiActivateEvent().
52 */
53class KPARTS_EXPORT ReadOnlyPart : public Part
54{
55 Q_OBJECT
56
57 /*!
58 * \property KParts::ReadOnlyPart::url
59 */
60 Q_PROPERTY(QUrl url READ url)
61
62 KPARTS_DECLARE_PRIVATE(ReadOnlyPart)
63
64public:
65 /*!
66 * Constructor.
67 *
68 * See also Part for the setXXX methods to call.
69 */
70 explicit ReadOnlyPart(QObject *parent = nullptr, const KPluginMetaData &data = {});
71
72 ~ReadOnlyPart() override;
73
74 /*!
75 * Call this to turn off the progress info dialog used by
76 * the internal KIO job. Use this if you provide another way
77 * of displaying progress info (e.g. a statusbar), using the
78 * signals emitted by this class, and/or those emitted by
79 * the job given by started().
80 */
81 void setProgressInfoEnabled(bool show);
82
83 /*!
84 * Returns whether the part shows the progress info dialog used by the internal
85 * KIO job.
86 */
87 bool isProgressInfoEnabled() const;
88
89public Q_SLOTS:
90 /*!
91 * Only reimplement this if you don't want the network transparency support
92 * to download from the URL into a temporary file (when the URL isn't local).
93 * Otherwise, reimplement openFile() only.
94 *
95 * If you reimplement it, don't forget to set the caption, usually with
96 * \code
97 * Q_EMIT setWindowCaption( url.toDisplayString(QUrl::PreferLocalFile) );
98 * \endcode
99 * and also, if the URL refers to a local file, resolve it to a
100 * local path and call setLocalFilePath().
101 */
102 virtual bool openUrl(const QUrl &url);
103
104public:
105 /*!
106 * Returns the URL currently opened in (or being opened by) this part.
107 *
108 * \note The URL is not cleared if openUrl() fails to load the URL.
109 * Call closeUrl() if you need to explicitly reset it.
110 */
111 QUrl url() const;
112
113 /*!
114 * Called when closing the current URL (for example, a document), for instance
115 * when switching to another URL (note that openUrl() calls it
116 * automatically in this case).
117 *
118 * If the current URL is not fully loaded yet, aborts loading.
119 *
120 * Deletes the temporary file used when the URL is remote.
121 *
122 * Resets the current url() to QUrl().
123 *
124 * Returns always \c true, but the return value exists for reimplementations
125 */
126 virtual bool closeUrl();
127
128 /*!
129 * This convenience method returns the NavigationExtension for this part,
130 * or \c nullptr if there isn't one.
131 */
132 NavigationExtension *navigationExtension() const;
133
134 /*!
135 * Sets the arguments to use for the next openUrl() call.
136 */
137 void setArguments(const OpenUrlArguments &arguments);
138 // TODO to avoid problems with the case where the loading fails, this could also be a openUrl() argument (heavy porting!).
139 // However we need to have setArguments in any case for updated made by the part, see e.g. KHTMLPart::openUrl.
140 // Well, maybe we should have setArguments (affects next openurl call) and updateArguments?
141
142 /*!
143 * Returns the arguments that were used to open this URL.
144 */
145 OpenUrlArguments arguments() const;
146
147public:
148 /*!
149 * Initiate sending data to this part.
150 * This is an alternative to openUrl(), which allows the user of the part
151 * to load the data itself, and send it progressively to the part.
152 *
153 * \a mimeType the type of data that is going to be sent to this part.
154 *
155 * \a url the URL representing this data. Although not directly used,
156 * every ReadOnlyPart has a URL (see url()), so this simply sets it.
157 *
158 * Returns \c true if the part supports progressive loading and accepts data, \c false otherwise.
159 */
160 bool openStream(const QString &mimeType, const QUrl &url);
161
162 /*!
163 * Send some data to the part. openStream must have been called previously,
164 * and must have returned \c true.
165 *
166 * Returns \c true if the data was accepted by the part. If false is returned,
167 * the application should stop sending data, and doesn't have to call closeStream.
168 */
169 bool writeStream(const QByteArray &data);
170
171 /*!
172 * Terminate the sending of data to the part.
173 * With some data types (text, html...) closeStream might never actually be called,
174 * in the case of continuous streams, for instance plain text or HTML data.
175 */
176 bool closeStream();
177
178private:
179 /*!
180 * Called by openStream to initiate sending of data.
181 * Parts which implement progress loading should check the \a mimeType
182 * parameter, and return true if they can accept a data stream of that type.
183 */
184 virtual bool doOpenStream(const QString &mimeType)
185 {
186 Q_UNUSED(mimeType);
187 return false;
188 }
189 /*!
190 * Receive some data from the hosting application.
191 * In this method the part should attempt to display the data progressively.
192 * With some data types (text, html...) closeStream might never actually be called,
193 * in the case of continuous streams. This can't happen with e.g. images.
194 */
195 virtual bool doWriteStream(const QByteArray &data)
196 {
197 Q_UNUSED(data);
198 return false;
199 }
200 /*!
201 * This is called by closeStream(), to indicate that all the data has been sent.
202 * Parts should ensure that all of the data is displayed at this point.
203 * Returns whether the data could be displayed correctly.
204 */
205 virtual bool doCloseStream()
206 {
207 return false;
208 }
209
210Q_SIGNALS:
211 /*!
212 * The part emits this when starting to load data.
213 *
214 * If using a KIO::Job, it provides the \a job so that
215 * progress information can be shown. Otherwise, \a job is \c nullptr.
216 **/
217 void started(KIO::Job *job);
218
219 /*!
220 * Emit this when you have completed loading data.
221 *
222 * Hosting applications will want to know when the process of loading the data
223 * is finished, so that they can access the data when everything is loaded.
224 **/
225 void completed();
226
227 /*!
228 * This signal is similar to the \c KParts::ReadOnlyPart::completed() signal
229 * except it is only emitted if there is still a pending action to be executed
230 * on a delayed timer.
231 *
232 * An example of this is the meta-refresh tags on web pages used to reload/redirect
233 * after a certain period of time. This signal is useful if you want to give the
234 * user the ability to cancel such pending actions.
235 *
236 * \since 5.81
237 */
238 void completedWithPendingAction();
239
240 /*!
241 * Emit this if loading is canceled by the user or by an error.
242 * \a errMsg the error message, empty if the user canceled the loading voluntarily.
243 */
244 void canceled(const QString &errMsg);
245
246 /*!
247 * Emitted by the part when url() changes
248 * \since 4.10
249 */
250 void urlChanged(const QUrl &url);
251
252protected:
253 /*!
254 * If the part uses the standard implementation of openUrl(),
255 * it must reimplement this to open the local file.
256 * The default implementation simply returns false.
257 *
258 * If this method returns true the part emits completed(),
259 * otherwise it emits canceled().
260 *
261 * \sa completed(), canceled()
262 */
263 virtual bool openFile();
264
265 void abortLoad();
266
267 /*!
268 * Reimplemented from Part, so that the window caption is set to
269 * the current URL (decoded) when the part is activated.
270 *
271 * This is the usual behavior in 99% of applications.
272 * Reimplement if you don't like it - test for event->activated()!
273 *
274 * \note This is done with GUIActivateEvent and not with
275 * PartActivateEvent because it's handled by the main window
276 * (which gets the event after the PartActivateEvent events have been sent).
277 */
278 void guiActivateEvent(GUIActivateEvent *event) override;
279
280 /*!
281 * Sets the URL associated with this part.
282 */
283 void setUrl(const QUrl &url);
284
285 /*!
286 * Returns the local file path associated with this part.
287 *
288 * \note The result will only be valid if openUrl() or
289 * setLocalFilePath() has previously been called.
290 */
291 QString localFilePath() const;
292
293 /*!
294 * Sets the local file path associated with this part.
295 */
296 void setLocalFilePath(const QString &localFilePath);
297
298protected:
299 KPARTS_NO_EXPORT ReadOnlyPart(ReadOnlyPartPrivate &dd, QObject *parent);
300
301private:
302 Q_DISABLE_COPY(ReadOnlyPart)
303};
304
305} // namespace
306
307#endif
308

source code of kparts/src/readonlypart.h