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 KDELIBS_KTEXTEDITOR_MODIFICATIONINTERFACE_H
22#define KDELIBS_KTEXTEDITOR_MODIFICATIONINTERFACE_H
23
24#include <ktexteditor/ktexteditor_export.h>
25
26#include <QtCore/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 * KTextEditor::ModificationInterface *iface =
59 * qobject_cast<KTextEditor::ModificationInterface*>( doc );
60 *
61 * if( iface ) {
62 * // the implementation supports the interface
63 * // do stuff
64 * }
65 * \endcode
66 *
67 * \see KTextEditor::Document
68 * \author Christoph Cullmann \<cullmann@kde.org\>
69 */
70class KTEXTEDITOR_EXPORT ModificationInterface
71{
72 public:
73 ModificationInterface ();
74
75 /**
76 * Virtual destructor.
77 */
78 virtual ~ModificationInterface ();
79
80 public:
81 /**
82 * Reasons why a document is modified on disk.
83 */
84 enum ModifiedOnDiskReason {
85 OnDiskUnmodified = 0, ///< Not modified
86 OnDiskModified = 1, ///< The file was modified by another program
87 OnDiskCreated = 2, ///< The file was created by another program
88 OnDiskDeleted = 3 ///< The file was deleted
89 };
90
91 public:
92 /**
93 * Set the document's modified-on-disk state to \p reason.
94 * KTextEditor implementations should emit the signal modifiedOnDisk()
95 * along with the reason. When the document is in a clean state again the
96 * reason should be ModifiedOnDiskReason::OnDiskUnmodified.
97 *
98 * \param reason the modified-on-disk reason.
99 * \see ModifiedOnDiskReason, modifiedOnDisk()
100 */
101 virtual void setModifiedOnDisk( ModifiedOnDiskReason reason ) = 0;
102
103 /**
104 * Control, whether the editor should show a warning dialog whenever a file
105 * was modified on disk. If \p on is \e true the editor will show warning
106 * dialogs.
107 * \param on controls, whether the editor should show a warning dialog for
108 * files modified on disk
109 */
110 virtual void setModifiedOnDiskWarning ( bool on ) = 0;
111
112 /*
113 * These stuff is implemented as SLOTS in the real document
114 */
115 public:
116 /**
117 * Ask the user what to do, if the file was modified on disk.
118 * The argument \p view is used to avoid asking again, when the editor
119 * regains focus after the dialog is hidden.
120 * \param view the view that should be notified of the user's decision
121 * \see setModifiedOnDisk(), modifiedOnDisk()
122 */
123 virtual void slotModifiedOnDisk( View *view = 0 ) = 0;
124
125 /*
126 * These stuff is implemented as SIGNALS in the real document
127 */
128 public:
129 /**
130 * This signal is emitted whenever the \p document changed its
131 * modified-on-disk state.
132 * \param document the Document object that represents the file on disk
133 * \param isModified if \e true, the file was modified rather than created
134 * or deleted
135 * \param reason the reason why the signal was emitted
136 * \see setModifiedOnDisk()
137 */
138 virtual void modifiedOnDisk (KTextEditor::Document *document,
139 bool isModified,
140 KTextEditor::ModificationInterface::ModifiedOnDiskReason reason) = 0;
141
142 private:
143 class ModificationInterfacePrivate* const d;
144};
145
146}
147
148Q_DECLARE_INTERFACE(KTextEditor::ModificationInterface, "org.kde.KTextEditor.ModificationInterface")
149
150#endif
151
152// kate: space-indent on; indent-width 2; replace-tabs on;
153
154