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_READWRITEPART_H
10#define _KPARTS_READWRITEPART_H
11
12#include <kparts/readonlypart.h>
13
14namespace KParts
15{
16class ReadWritePartPrivate;
17
18/*!
19 * \class KParts::ReadWritePart
20 * \inheaderfile KParts/ReadWritePart
21 * \inmodule KParts
22 *
23 * \brief Base class for an "editor" part.
24 *
25 * This class handles network transparency for you.
26 * Anything that can open a URL, allow modifications, and save
27 * (to the same URL or a different one).
28 *
29 * A read-write part can be set to read-only mode, using setReadWrite().
30 *
31 * Part writers:
32 * Any part inheriting ReadWritePart should check isReadWrite
33 * before allowing any action that modifies the part.
34 * The part probably wants to reimplement setReadWrite, disable those
35 * actions. Don't forget to call the parent setReadWrite.
36 */
37class KPARTS_EXPORT ReadWritePart : public ReadOnlyPart
38{
39 Q_OBJECT
40
41 KPARTS_DECLARE_PRIVATE(ReadWritePart)
42
43public:
44 /*!
45 * Constructor
46 * See parent constructor for instructions.
47 */
48 explicit ReadWritePart(QObject *parent = nullptr, const KPluginMetaData &data = {});
49 /*!
50 * Destructor
51 * Applications using a ReadWritePart should make sure, before
52 * destroying it, to call closeUrl().
53 * In KMainWindow::queryClose(), for instance, they should allow
54 * closing only if the return value of closeUrl() was true.
55 * This allows to cancel.
56 */
57 ~ReadWritePart() override;
58
59 /*!
60 * Returns true if the part is in read-write mode
61 */
62 bool isReadWrite() const;
63
64 /*!
65 * Changes the behavior of this part to readonly or readwrite.
66 *
67 * \a readwrite set to true to enable readwrite mode
68 */
69 virtual void setReadWrite(bool readwrite = true);
70
71 /*!
72 * Returns true if the document has been modified.
73 */
74 bool isModified() const;
75
76 /*!
77 * If the document has been modified, ask the user to save changes.
78 * This method is meant to be called from KMainWindow::queryClose().
79 * It will also be called from closeUrl().
80 *
81 * Returns true if closeUrl() can be called without the user losing
82 * important data, false if the user chooses to cancel.
83 */
84 virtual bool queryClose();
85
86 /*!
87 * Called when closing the current url (e.g. document), for instance
88 * when switching to another url (note that openUrl() calls it
89 * automatically in this case).
90 *
91 * If the current URL is not fully loaded yet, aborts loading.
92 *
93 * If isModified(), queryClose() will be called.
94 *
95 * Returns false on cancel
96 */
97 bool closeUrl() override;
98
99 /*!
100 * Call this method instead of the above if you need control if
101 * the save prompt is shown. For example, if you call queryClose()
102 * from KMainWindow::queryClose(), you would not want to prompt
103 * again when closing the url.
104 *
105 * Equivalent to promptToSave ? closeUrl() : ReadOnlyPart::closeUrl()
106 */
107 virtual bool closeUrl(bool promptToSave);
108
109 /*!
110 * Save the file to a new location.
111 *
112 * Calls save(), no need to reimplement
113 */
114 virtual bool saveAs(const QUrl &url);
115
116 /*!
117 * Sets the modified flag of the part.
118 */
119 virtual void setModified(bool modified);
120
121Q_SIGNALS:
122 /*!
123 * set handled to true, if you don't want the default handling
124 * set abortClosing to true, if you handled the request,
125 * but for any reason don't want to allow closing the document
126 */
127 void sigQueryClose(bool *handled, bool *abortClosing);
128
129public Q_SLOTS:
130 /*!
131 * Call setModified() whenever the contents get modified.
132 * This is a slot for convenience, since it simply calls setModified(true),
133 * so that you can connect it to a signal, like textChanged().
134 */
135 void setModified();
136
137 /*!
138 * Save the file in the location from which it was opened.
139 * You can connect this to the "save" action.
140 * Calls saveFile() and saveToUrl(), no need to reimplement.
141 */
142 virtual bool save();
143
144 /*!
145 * Waits for any pending upload job to finish and returns whether the
146 * last save() action was successful.
147 */
148 bool waitSaveComplete();
149
150protected:
151 /*!
152 * Save to a local file.
153 * You need to implement it, to save to the local file.
154 * The framework takes care of re-uploading afterwards.
155 *
156 * Returns true on success, false on failure.
157 * On failure the function should inform the user about the
158 * problem with an appropriate message box. Standard error
159 * messages can be constructed using KIO::buildErrorString()
160 * in combination with the error codes defined in kio/global.h
161 */
162 virtual bool saveFile() = 0;
163
164 /*!
165 * Save the file.
166 *
167 * Uploads the file, if \a url is remote.
168 * This will emit started(), and either completed() or canceled(),
169 * in case you want to provide feedback.
170 *
171 * Returns true on success, false on failure.
172 */
173 virtual bool saveToUrl();
174
175private:
176 Q_DISABLE_COPY(ReadWritePart)
177};
178
179} // namespace
180
181#endif
182

source code of kparts/src/readwritepart.h