File indexing completed on 2024-04-28 15:29:23
0001 /* 0002 This file is part of the KDE project 0003 SPDX-FileCopyrightText: 1999 Simon Hausmann <hausmann@kde.org> 0004 SPDX-FileCopyrightText: 1999 David Faure <faure@kde.org> 0005 0006 SPDX-License-Identifier: LGPL-2.0-or-later 0007 */ 0008 0009 #ifndef _KPARTS_READONLYPART_H 0010 #define _KPARTS_READONLYPART_H 0011 0012 #include <kparts/part.h> 0013 0014 #include <QUrl> 0015 0016 class KJob; 0017 namespace KIO 0018 { 0019 class Job; 0020 } 0021 0022 namespace KParts 0023 { 0024 class ReadOnlyPartPrivate; 0025 class BrowserExtension; 0026 class OpenUrlArguments; 0027 0028 /** 0029 * @class ReadOnlyPart readonlypart.h <KParts/ReadOnlyPart> 0030 * 0031 * @short Base class for any "viewer" part. 0032 * 0033 * This class takes care of network transparency for you, 0034 * in the simplest way (downloading to a temporary file, then letting the part 0035 * load from the temporary file). 0036 * To use the built-in network transparency, you only need to implement 0037 * openFile(), not openUrl(). 0038 * 0039 * To implement network transparency differently (e.g. for progressive loading, 0040 * like a web browser does for instance), or to prevent network transparency 0041 * (but why would you do that?), you can override openUrl(). 0042 * 0043 * An application using KParts can use the signals to show feedback while 0044 * the URL is being loaded. 0045 * 0046 * ReadOnlyPart handles the window caption by setting it to the current URL 0047 * (set in openUrl(), and each time the part is activated). 0048 * If you want another caption, set it in openFile() and, 0049 * if the part might ever be used with a part manager, in guiActivateEvent(). 0050 */ 0051 class KPARTS_EXPORT ReadOnlyPart : public Part 0052 { 0053 Q_OBJECT 0054 0055 Q_PROPERTY(QUrl url READ url) 0056 0057 KPARTS_DECLARE_PRIVATE(ReadOnlyPart) 0058 0059 public: 0060 /** 0061 * Constructor. 0062 * See also Part for the setXXX methods to call. 0063 */ 0064 explicit ReadOnlyPart(QObject *parent = nullptr); 0065 0066 /** 0067 * Destructor. 0068 */ 0069 ~ReadOnlyPart() override; 0070 0071 /** 0072 * Call this to turn off the progress info dialog used by 0073 * the internal KIO job. Use this if you provide another way 0074 * of displaying progress info (e.g. a statusbar), using the 0075 * signals emitted by this class, and/or those emitted by 0076 * the job given by started(). 0077 */ 0078 void setProgressInfoEnabled(bool show); 0079 0080 /** 0081 * Returns whether the part shows the progress info dialog used by the internal 0082 * KIO job. 0083 */ 0084 bool isProgressInfoEnabled() const; 0085 0086 #if KPARTS_ENABLE_DEPRECATED_SINCE(3, 0) 0087 /** 0088 * @deprecated Since 3.0, use setProgressInfoEnabled(bool) 0089 */ 0090 KPARTS_DEPRECATED_VERSION(3, 0, "Use ReadOnlyPart::setProgressInfoEnabled(bool)") 0091 void showProgressInfo(bool show); 0092 #endif 0093 0094 public Q_SLOTS: 0095 /** 0096 * Only reimplement this if you don't want the network transparency support 0097 * to download from the URL into a temporary file (when the URL isn't local). 0098 * Otherwise, reimplement openFile() only. 0099 * 0100 * If you reimplement it, don't forget to set the caption, usually with 0101 * @code 0102 * Q_EMIT setWindowCaption( url.toDisplayString() ); 0103 * @endcode 0104 * and also, if the URL refers to a local file, resolve it to a 0105 * local path and call setLocalFilePath(). 0106 */ 0107 virtual bool openUrl(const QUrl &url); 0108 0109 public: 0110 /** 0111 * Returns the URL currently opened in (or being opened by) this part. 0112 * @note The URL is not cleared if openUrl() fails to load the URL. 0113 * Call closeUrl() if you need to explicitly reset it. 0114 * 0115 * @return The current URL. 0116 */ 0117 QUrl url() const; 0118 0119 /** 0120 * Called when closing the current URL (for example, a document), for instance 0121 * when switching to another URL (note that openUrl() calls it 0122 * automatically in this case). 0123 * If the current URL is not fully loaded yet, aborts loading. 0124 * Deletes the temporary file used when the URL is remote. 0125 * Resets the current url() to QUrl(). 0126 * @return always true, but the return value exists for reimplementations 0127 */ 0128 virtual bool closeUrl(); 0129 0130 /** 0131 * This convenience method returns the BrowserExtension for this part, 0132 * or @c nullptr if there isn't one. 0133 */ 0134 BrowserExtension *browserExtension() const; 0135 0136 /** 0137 * Sets the arguments to use for the next openUrl() call. 0138 */ 0139 void setArguments(const OpenUrlArguments &arguments); 0140 // TODO to avoid problems with the case where the loading fails, this could also be a openUrl() argument (heavy porting!). 0141 // However we need to have setArguments in any case for updated made by the part, see e.g. KHTMLPart::openUrl. 0142 // Well, maybe we should have setArguments (affects next openurl call) and updateArguments? 0143 0144 /** 0145 * @return the arguments that were used to open this URL. 0146 */ 0147 OpenUrlArguments arguments() const; 0148 0149 public: 0150 /** 0151 * Initiate sending data to this part. 0152 * This is an alternative to openUrl(), which allows the user of the part 0153 * to load the data itself, and send it progressively to the part. 0154 * 0155 * @param mimeType the type of data that is going to be sent to this part. 0156 * @param url the URL representing this data. Although not directly used, 0157 * every ReadOnlyPart has a URL (see url()), so this simply sets it. 0158 * @return true if the part supports progressive loading and accepts data, false otherwise. 0159 */ 0160 bool openStream(const QString &mimeType, const QUrl &url); 0161 0162 /** 0163 * Send some data to the part. openStream must have been called previously, 0164 * and must have returned true. 0165 * @return true if the data was accepted by the part. If false is returned, 0166 * the application should stop sending data, and doesn't have to call closeStream. 0167 */ 0168 bool writeStream(const QByteArray &data); 0169 0170 /** 0171 * Terminate the sending of data to the part. 0172 * With some data types (text, html...) closeStream might never actually be called, 0173 * in the case of continuous streams, for instance plain text or HTML data. 0174 */ 0175 bool closeStream(); 0176 0177 #ifdef K_DOXYGEN 0178 protected: // are parsed by doxygen (kapidox/ecm_add_qch): unhide for doxygen configured to skip private methods 0179 #else 0180 private: // Makes no sense for inherited classes to call those. But make it protected there. 0181 #endif // K_DOXYGEN 0182 0183 /** 0184 * Called by openStream to initiate sending of data. 0185 * Parts which implement progress loading should check the @p mimeType 0186 * parameter, and return true if they can accept a data stream of that type. 0187 */ 0188 virtual bool doOpenStream(const QString &mimeType) 0189 { 0190 Q_UNUSED(mimeType); 0191 return false; 0192 } 0193 /** 0194 * Receive some data from the hosting application. 0195 * In this method the part should attempt to display the data progressively. 0196 * With some data types (text, html...) closeStream might never actually be called, 0197 * in the case of continuous streams. This can't happen with e.g. images. 0198 */ 0199 virtual bool doWriteStream(const QByteArray &data) 0200 { 0201 Q_UNUSED(data); 0202 return false; 0203 } 0204 /** 0205 * This is called by closeStream(), to indicate that all the data has been sent. 0206 * Parts should ensure that all of the data is displayed at this point. 0207 * @return whether the data could be displayed correctly. 0208 */ 0209 virtual bool doCloseStream() 0210 { 0211 return false; 0212 } 0213 0214 Q_SIGNALS: 0215 /** 0216 * The part emits this when starting to load data. 0217 * If using a KIO::Job, it provides the @p job so that 0218 * progress information can be shown. Otherwise, @p job is @c nullptr. 0219 **/ 0220 void started(KIO::Job *job); 0221 0222 /** 0223 * Emit this when you have completed loading data. 0224 * Hosting applications will want to know when the process of loading the data 0225 * is finished, so that they can access the data when everything is loaded. 0226 **/ 0227 void completed(); // clazy:exclude=overloaded-signal 0228 0229 #if KPARTS_ENABLE_DEPRECATED_SINCE(5, 80) 0230 /** 0231 * Same as the above signal except it indicates whether there is 0232 * a pending action to be executed on a delay timer. An example of 0233 * this is the meta-refresh tags on web pages used to reload/redirect 0234 * after a certain period of time. This signal is useful if you want 0235 * to give the user the ability to cancel such pending actions. 0236 * 0237 * @p pendingAction true if a pending action exists, false otherwise. 0238 * 0239 * @deprecated since 5.80, use the KParts::ReadOnlyPart::completedWithPendingAction() signal 0240 */ 0241 KPARTS_DEPRECATED_VERSION(5, 81, "Use the KParts::ReadOnlyPart::completedWithPendingAction() signal") 0242 void completed(bool pendingAction); // clazy:exclude=overloaded-signal 0243 #endif 0244 0245 /** 0246 * This signal is similar to the @c KParts::ReadOnlyPart::completed() signal 0247 * except it is only emitted if there is still a pending action to be executed 0248 * on a delayed timer. 0249 * 0250 * An example of this is the meta-refresh tags on web pages used to reload/redirect 0251 * after a certain period of time. This signal is useful if you want to give the 0252 * user the ability to cancel such pending actions. 0253 * 0254 * @since 5.81 0255 */ 0256 void completedWithPendingAction(); 0257 0258 /** 0259 * Emit this if loading is canceled by the user or by an error. 0260 * @param errMsg the error message, empty if the user canceled the loading voluntarily. 0261 */ 0262 void canceled(const QString &errMsg); 0263 0264 /** 0265 * Emitted by the part when url() changes 0266 * @since 4.10 0267 */ 0268 void urlChanged(const QUrl &url); 0269 0270 protected: 0271 /** 0272 * If the part uses the standard implementation of openUrl(), 0273 * it must reimplement this to open the local file. 0274 * The default implementation simply returns false. 0275 * 0276 * If this method returns true the part emits completed(), 0277 * otherwise it emits canceled(). 0278 * 0279 * @see completed(), canceled() 0280 */ 0281 virtual bool openFile(); 0282 0283 /** 0284 * @internal 0285 */ 0286 void abortLoad(); 0287 0288 /** 0289 * Reimplemented from Part, so that the window caption is set to 0290 * the current URL (decoded) when the part is activated. 0291 * This is the usual behavior in 99% of applications. 0292 * Reimplement if you don't like it - test for event->activated()! 0293 * 0294 * @note This is done with GUIActivateEvent and not with 0295 * PartActivateEvent because it's handled by the main window 0296 * (which gets the event after the PartActivateEvent events have been sent). 0297 */ 0298 void guiActivateEvent(GUIActivateEvent *event) override; 0299 0300 #if KPARTS_ENABLE_DEPRECATED_SINCE(5, 0) 0301 /** 0302 * @internal 0303 */ 0304 KPARTS_DEPRECATED_VERSION(5, 0, "Do not use feature") 0305 bool isLocalFileTemporary() const; 0306 0307 /** 0308 * @internal 0309 */ 0310 KPARTS_DEPRECATED_VERSION(5, 0, "Do not use feature") 0311 void setLocalFileTemporary(bool temp); 0312 #endif 0313 0314 /** 0315 * Sets the URL associated with this part. 0316 */ 0317 void setUrl(const QUrl &url); 0318 0319 /** 0320 * Returns the local file path associated with this part. 0321 * 0322 * @note The result will only be valid if openUrl() or 0323 * setLocalFilePath() has previously been called. 0324 */ 0325 QString localFilePath() const; 0326 0327 /** 0328 * Sets the local file path associated with this part. 0329 */ 0330 void setLocalFilePath(const QString &localFilePath); 0331 0332 protected: 0333 KPARTS_NO_EXPORT ReadOnlyPart(ReadOnlyPartPrivate &dd, QObject *parent); 0334 0335 private: 0336 Q_DISABLE_COPY(ReadOnlyPart) 0337 }; 0338 0339 } // namespace 0340 0341 #endif