KParts

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

KDE's Doxygen guidelines are available online.