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 | |
28 | namespace KTextEditor |
29 | { |
30 | |
31 | class Document; |
32 | class 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 | */ |
70 | class 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 | |
148 | Q_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 | |