KParts

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

KDE's Doxygen guidelines are available online.