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_READWRITEPART_H 0010 #define _KPARTS_READWRITEPART_H 0011 0012 #include <kparts/readonlypart.h> 0013 0014 namespace KParts 0015 { 0016 class ReadWritePartPrivate; 0017 0018 /** 0019 * @class ReadWritePart readwritepart.h <KParts/ReadWritePart> 0020 * 0021 * @short Base class for an "editor" part. 0022 * 0023 * This class handles network transparency for you. 0024 * Anything that can open a URL, allow modifications, and save 0025 * (to the same URL or a different one). 0026 * 0027 * A read-write part can be set to read-only mode, using setReadWrite(). 0028 * 0029 * Part writers : 0030 * Any part inheriting ReadWritePart should check isReadWrite 0031 * before allowing any action that modifies the part. 0032 * The part probably wants to reimplement setReadWrite, disable those 0033 * actions. Don't forget to call the parent setReadWrite. 0034 */ 0035 class KPARTS_EXPORT ReadWritePart : public ReadOnlyPart 0036 { 0037 Q_OBJECT 0038 0039 KPARTS_DECLARE_PRIVATE(ReadWritePart) 0040 0041 public: 0042 /** 0043 * Constructor 0044 * See parent constructor for instructions. 0045 */ 0046 explicit ReadWritePart(QObject *parent = nullptr); 0047 /** 0048 * Destructor 0049 * Applications using a ReadWritePart should make sure, before 0050 * destroying it, to call closeUrl(). 0051 * In KMainWindow::queryClose(), for instance, they should allow 0052 * closing only if the return value of closeUrl() was true. 0053 * This allows to cancel. 0054 */ 0055 ~ReadWritePart() override; 0056 0057 /** 0058 * @return true if the part is in read-write mode 0059 */ 0060 bool isReadWrite() const; 0061 0062 /** 0063 * Changes the behavior of this part to readonly or readwrite. 0064 * @param readwrite set to true to enable readwrite mode 0065 */ 0066 virtual void setReadWrite(bool readwrite = true); 0067 0068 /** 0069 * @return true if the document has been modified. 0070 */ 0071 bool isModified() const; 0072 0073 /** 0074 * If the document has been modified, ask the user to save changes. 0075 * This method is meant to be called from KMainWindow::queryClose(). 0076 * It will also be called from closeUrl(). 0077 * 0078 * @return true if closeUrl() can be called without the user losing 0079 * important data, false if the user chooses to cancel. 0080 */ 0081 virtual bool queryClose(); 0082 0083 /** 0084 * Called when closing the current url (e.g. document), for instance 0085 * when switching to another url (note that openUrl() calls it 0086 * automatically in this case). 0087 * 0088 * If the current URL is not fully loaded yet, aborts loading. 0089 * 0090 * If isModified(), queryClose() will be called. 0091 * 0092 * @return false on cancel 0093 */ 0094 bool closeUrl() override; 0095 0096 /** 0097 * Call this method instead of the above if you need control if 0098 * the save prompt is shown. For example, if you call queryClose() 0099 * from KMainWindow::queryClose(), you would not want to prompt 0100 * again when closing the url. 0101 * 0102 * Equivalent to promptToSave ? closeUrl() : ReadOnlyPart::closeUrl() 0103 */ 0104 virtual bool closeUrl(bool promptToSave); 0105 0106 /** 0107 * Save the file to a new location. 0108 * 0109 * Calls save(), no need to reimplement 0110 */ 0111 virtual bool saveAs(const QUrl &url); 0112 0113 /** 0114 * Sets the modified flag of the part. 0115 */ 0116 virtual void setModified(bool modified); 0117 0118 Q_SIGNALS: 0119 /** 0120 * set handled to true, if you don't want the default handling 0121 * set abortClosing to true, if you handled the request, 0122 * but for any reason don't want to allow closing the document 0123 */ 0124 void sigQueryClose(bool *handled, bool *abortClosing); 0125 0126 public Q_SLOTS: 0127 /** 0128 * Call setModified() whenever the contents get modified. 0129 * This is a slot for convenience, since it simply calls setModified(true), 0130 * so that you can connect it to a signal, like textChanged(). 0131 */ 0132 void setModified(); 0133 0134 /** 0135 * Save the file in the location from which it was opened. 0136 * You can connect this to the "save" action. 0137 * Calls saveFile() and saveToUrl(), no need to reimplement. 0138 */ 0139 virtual bool save(); 0140 0141 /** 0142 * Waits for any pending upload job to finish and returns whether the 0143 * last save() action was successful. 0144 */ 0145 bool waitSaveComplete(); 0146 0147 protected: 0148 /** 0149 * Save to a local file. 0150 * You need to implement it, to save to the local file. 0151 * The framework takes care of re-uploading afterwards. 0152 * 0153 * @return true on success, false on failure. 0154 * On failure the function should inform the user about the 0155 * problem with an appropriate message box. Standard error 0156 * messages can be constructed using KIO::buildErrorString() 0157 * in combination with the error codes defined in kio/global.h 0158 */ 0159 virtual bool saveFile() = 0; 0160 0161 /** 0162 * Save the file. 0163 * 0164 * Uploads the file, if @p url is remote. 0165 * This will emit started(), and either completed() or canceled(), 0166 * in case you want to provide feedback. 0167 * @return true on success, false on failure. 0168 */ 0169 virtual bool saveToUrl(); 0170 0171 private: 0172 Q_DISABLE_COPY(ReadWritePart) 0173 }; 0174 0175 } // namespace 0176 0177 #endif