1 | /***************************************************************************** |
2 | * Copyright (C) 2011 by Vishesh Yadav <vishesh3y@gmail.com> * |
3 | * Copyright (C) 2011 by Peter Penz <peter.penz19@gmail.com> * |
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 version 2 as published by the Free Software Foundation. * |
8 | * * |
9 | * This library is distributed in the hope that it will be useful, * |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of * |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * |
12 | * Library General Public License for more details. * |
13 | * * |
14 | * You should have received a copy of the GNU Library General Public License * |
15 | * along with this library; see the file COPYING.LIB. If not, write to * |
16 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, * |
17 | * Boston, MA 02110-1301, USA. * |
18 | *****************************************************************************/ |
19 | |
20 | #ifndef KVERSIONCONTROLPLUGIN2_H |
21 | #define KVERSIONCONTROLPLUGIN2_H |
22 | |
23 | #include <libkonq_export.h> |
24 | #include <kversioncontrolplugin.h> |
25 | |
26 | /** |
27 | * @brief Base class for version control plugins. |
28 | * |
29 | * Enables the file manager to show the version state |
30 | * of a versioned file. To write a custom plugin, the following |
31 | * steps are required (in the example below it is assumed that a plugin for |
32 | * Subversion will be written): |
33 | * |
34 | * - Create a fileviewsvnplugin.desktop file with the following content: |
35 | * <code> |
36 | * [Desktop Entry] |
37 | * Type=Service |
38 | * Name=Subversion |
39 | * X-KDE-ServiceTypes=FileViewVersionControlPlugin |
40 | * MimeType=text/plain; |
41 | * X-KDE-Library=fileviewsvnplugin |
42 | * </code> |
43 | * |
44 | * - Create a class FileViewSvnPlugin derived from KVersionControlPlugin2 and |
45 | * implement all abstract interfaces (fileviewsvnplugin.h, fileviewsvnplugin.cpp). |
46 | * |
47 | * - Take care that the constructor has the following signature: |
48 | * <code> |
49 | * FileViewSvnPlugin(QObject* parent, const QList<QVariant>& args); |
50 | * </code> |
51 | * |
52 | * - Add the following lines at the top of fileviewsvnplugin.cpp: |
53 | * <code> |
54 | * #include <KPluginFactory> |
55 | * #include <KPluginLoader> |
56 | * K_PLUGIN_FACTORY(FileViewSvnPluginFactory, registerPlugin<FileViewSvnPlugin>();) |
57 | * K_EXPORT_PLUGIN(FileViewSvnPluginFactory("fileviewsvnplugin")) |
58 | * </code> |
59 | * |
60 | * - Add the following lines to your CMakeLists.txt file: |
61 | * <code> |
62 | * kde4_add_plugin(fileviewsvnplugin fileviewsvnplugin.cpp) |
63 | * target_link_libraries(fileviewsvnplugin konq) |
64 | * install(FILES fileviewsvnplugin.desktop DESTINATION ${SERVICES_INSTALL_DIR}) |
65 | * </code> |
66 | * |
67 | * General implementation notes: |
68 | * |
69 | * - The implementations of beginRetrieval(), endRetrieval() and versionState() |
70 | * can contain blocking operations, as Dolphin will execute |
71 | * those methods in a separate thread. It is assured that |
72 | * all other methods are invoked in a serialized way, so that it is not necessary for |
73 | * the plugin to use any mutex. |
74 | * |
75 | * - Dolphin keeps only one instance of the plugin, which is instantiated shortly after |
76 | * starting Dolphin. Take care that the constructor does no expensive and time |
77 | * consuming operations. |
78 | * |
79 | * @since 4.8 |
80 | */ |
81 | class LIBKONQ_EXPORT KVersionControlPlugin2 : public KVersionControlPlugin |
82 | { |
83 | Q_OBJECT |
84 | |
85 | public: |
86 | enum ItemVersion |
87 | { |
88 | /** The file is not under version control. */ |
89 | UnversionedVersion, |
90 | /** |
91 | * The file is under version control and represents |
92 | * the latest version. |
93 | */ |
94 | NormalVersion, |
95 | /** |
96 | * The file is under version control and a newer |
97 | * version exists on the main branch. |
98 | */ |
99 | UpdateRequiredVersion, |
100 | /** |
101 | * The file is under version control and has been |
102 | * modified locally. All modifications will be part |
103 | * of the next commit. |
104 | */ |
105 | LocallyModifiedVersion, |
106 | /** |
107 | * The file has not been under version control but |
108 | * has been marked to get added with the next commit. |
109 | */ |
110 | AddedVersion, |
111 | /** |
112 | * The file is under version control but has been marked |
113 | * for getting removed with the next commit. |
114 | */ |
115 | RemovedVersion, |
116 | /** |
117 | * The file is under version control and has been locally |
118 | * modified. A modification has also been done on the main |
119 | * branch. |
120 | */ |
121 | ConflictingVersion, |
122 | /** |
123 | * The file is under version control and has local |
124 | * modifications, which will not be part of the next |
125 | * commit (or are "unstaged" in git jargon). |
126 | * @since 4.6 |
127 | */ |
128 | LocallyModifiedUnstagedVersion, |
129 | /** |
130 | * The file is not under version control and is listed |
131 | * in the ignore list of the version control system. |
132 | * @since 4.8 |
133 | */ |
134 | IgnoredVersion, |
135 | /** |
136 | * The file is is tracked by the version control system, but |
137 | * is missing in the directory (e.g. by deleted without using |
138 | * a version control command). |
139 | * @since 4.8 |
140 | */ |
141 | MissingVersion |
142 | }; |
143 | |
144 | KVersionControlPlugin2(QObject* parent = 0); |
145 | virtual ~KVersionControlPlugin2(); |
146 | |
147 | /** |
148 | * Returns the name of the file which stores |
149 | * the version controls information. |
150 | * (e. g. .svn, .cvs, .git). |
151 | */ |
152 | virtual QString fileName() const = 0; |
153 | |
154 | /** |
155 | * Is invoked whenever the version control |
156 | * information will get retrieved for the directory |
157 | * \p directory. It is assured that the directory |
158 | * contains a trailing slash. |
159 | */ |
160 | virtual bool beginRetrieval(const QString& directory) = 0; |
161 | |
162 | /** |
163 | * Is invoked after the version control information has been |
164 | * received. It is assured that |
165 | * KVersionControlPluginV2::beginInfoRetrieval() has been |
166 | * invoked before. |
167 | */ |
168 | virtual void endRetrieval() = 0; |
169 | |
170 | /** |
171 | * @return The version for the item \p item. |
172 | * It is assured that KVersionControlPlugin::beginInfoRetrieval() has been |
173 | * invoked before and that the file is part of the directory specified |
174 | * in beginInfoRetrieval(). |
175 | */ |
176 | virtual ItemVersion itemVersion(const KFileItem& item) const = 0; |
177 | |
178 | /** |
179 | * @return List of actions that are available for the items \p items. |
180 | * It is recommended to keep the number of returned actions small |
181 | * in case if an item is an unversioned directory that is not |
182 | * inside the hierarchy tree of the version control system. This |
183 | * prevents having a cluttered context menu for directories |
184 | * outside the version control system. |
185 | */ |
186 | virtual QList<QAction*> actions(const KFileItemList& items) const = 0; |
187 | |
188 | /** Empty implementation for deprecated interface of KVersionControlPlugin. */ |
189 | virtual VersionState versionState(const KFileItem& item); |
190 | |
191 | /** Empty implementation for deprecated interface of KVersionControlPlugin. */ |
192 | virtual QList<QAction*> (const KFileItemList& items); |
193 | |
194 | /** Empty implementation for deprecated interface of KVersionControlPlugin. */ |
195 | virtual QList<QAction*> (const QString& directory); |
196 | |
197 | signals: |
198 | /** |
199 | * Should be emitted when the version state of items might have been changed |
200 | * after the last retrieval (e. g. by executing a context menu action |
201 | * of the version control plugin). The file manager will be triggered to |
202 | * update the version states of the directory \p directory by invoking |
203 | * KVersionControlPlugin::beginRetrieval(), |
204 | * KVersionControlPlugin::itemVersion() and |
205 | * KVersionControlPlugin::endRetrieval(). |
206 | */ |
207 | void itemVersionsChanged(); |
208 | |
209 | /** |
210 | * Is emitted if an information message with the content \a msg |
211 | * should be shown. |
212 | */ |
213 | void infoMessage(const QString& msg); |
214 | |
215 | /** |
216 | * Is emitted if an error message with the content \a msg |
217 | * should be shown. |
218 | */ |
219 | void errorMessage(const QString& msg); |
220 | |
221 | /** |
222 | * Is emitted if an "operation completed" message with the content \a msg |
223 | * should be shown. |
224 | */ |
225 | void operationCompletedMessage(const QString& msg); |
226 | }; |
227 | |
228 | #endif // KVERSIONCONTROLPLUGIN2_H |
229 | |
230 | |