1/* This file is part of the KDE project
2 Copyright (C) 2005 Christoph Cullmann (cullmann@kde.org)
3 Copyright (C) 2005 Dominik Haumann (dhdev@gmx.de) (documentation)
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KTEXTEDITOR_MODIFICATIONINTERFACE_H
22#define KTEXTEDITOR_MODIFICATIONINTERFACE_H
23
24#include <ktexteditor_export.h>
25
26#include <QObject>
27
28namespace KTextEditor
29{
30
31class Document;
32class View;
33
34/**
35 * \brief External modification extension interface for the Document.
36 *
37 * \ingroup kte_group_doc_extensions
38 *
39 * \section modiface_intro Introduction
40 *
41 * The class ModificationInterface provides methods to handle modifications
42 * of all opened files caused by external programs. Whenever the
43 * modified-on-disk state changes the signal modifiedOnDisk() is emitted
44 * along with a ModifiedOnDiskReason. Set the state by calling
45 * setModifiedOnDisk(). Whether the Editor should show warning dialogs to
46 * inform the user about external modified files can be controlled with
47 * setModifiedOnDiskWarning(). The slot modifiedOnDisk() is called to ask
48 * the user what to do whenever a file was modified.
49 *
50 * \section modiface_access Accessing the ModificationInterface
51 *
52 * The ModificationInterface is supposed to be an extension interface for a
53 * Document, i.e. the Document inherits the interface \e provided that the
54 * used KTextEditor library implements the interface. Use qobject_cast to
55 * access the interface:
56 * \code
57 * // doc is of type KTextEditor::Document*
58 * auto iface = qobject_cast<KTextEditor::ModificationInterface*>(doc);
59 *
60 * if (iface) {
61 * // the implementation supports the interface
62 * // do stuff
63 * } else {
64 * // the implementation does not support the interface
65 * }
66 * \endcode
67 *
68 * \see KTextEditor::Document
69 * \author Christoph Cullmann \<cullmann@kde.org\>
70 */
71class KTEXTEDITOR_EXPORT ModificationInterface
72{
73public:
74 ModificationInterface();
75
76 /**
77 * Virtual destructor.
78 */
79 virtual ~ModificationInterface();
80
81public:
82 /**
83 * Reasons why a document is modified on disk.
84 */
85 enum ModifiedOnDiskReason {
86 OnDiskUnmodified = 0, ///< Not modified
87 OnDiskModified = 1, ///< The file was modified by another program
88 OnDiskCreated = 2, ///< The file was created by another program
89 OnDiskDeleted = 3 ///< The file was deleted
90 };
91
92public:
93 /**
94 * Set the document's modified-on-disk state to \p reason.
95 * KTextEditor implementations should emit the signal modifiedOnDisk()
96 * along with the reason. When the document is in a clean state again the
97 * reason should be ModifiedOnDiskReason::OnDiskUnmodified.
98 *
99 * \param reason the modified-on-disk reason.
100 * \see ModifiedOnDiskReason, modifiedOnDisk()
101 */
102 virtual void setModifiedOnDisk(ModifiedOnDiskReason reason) = 0;
103
104 /**
105 * Control, whether the editor should show a warning dialog whenever a file
106 * was modified on disk. If \p on is \e true the editor will show warning
107 * dialogs.
108 * \param on controls, whether the editor should show a warning dialog for
109 * files modified on disk
110 */
111 virtual void setModifiedOnDiskWarning(bool on) = 0;
112
113 /*
114 * These stuff is implemented as SIGNALS in the real document
115 */
116public:
117 /**
118 * This signal is emitted whenever the \p document changed its
119 * modified-on-disk state.
120 * \param document the Document object that represents the file on disk
121 * \param isModified if \e true, the file was modified rather than created
122 * or deleted
123 * \param reason the reason why the signal was emitted
124 * \see setModifiedOnDisk()
125 */
126 virtual void modifiedOnDisk(KTextEditor::Document *document,
127 bool isModified,
128 KTextEditor::ModificationInterface::ModifiedOnDiskReason reason) = 0;
129
130private:
131 class ModificationInterfacePrivate *const d = nullptr;
132};
133
134}
135
136Q_DECLARE_INTERFACE(KTextEditor::ModificationInterface, "org.kde.KTextEditor.ModificationInterface")
137
138#endif
139
140