KParts

readwritepart.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_READWRITEPART_H
10 #define _KPARTS_READWRITEPART_H
11 
12 #include <kparts/readonlypart.h>
13 
14 namespace KParts
15 {
16 class 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  */
35 class KPARTS_EXPORT ReadWritePart : public ReadOnlyPart
36 {
37  Q_OBJECT
38 
39  KPARTS_DECLARE_PRIVATE(ReadWritePart)
40 
41 public:
42  /**
43  * Constructor
44  * See parent constructor for instructions.
45  */
46  explicit ReadWritePart(QObject *parent = nullptr);
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 
118 Q_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 
126 public 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 
147 protected:
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 
171 private:
172  Q_DISABLE_COPY(ReadWritePart)
173 };
174 
175 } // namespace
176 
177 #endif
Base class for an "editor" part.
Definition: readwritepart.h:35
Base class for any "viewer" part.
Definition: readonlypart.h:51
The KParts namespace,.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Tue Aug 9 2022 03:51:33 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.