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 */
81class LIBKONQ_EXPORT KVersionControlPlugin2 : public KVersionControlPlugin
82{
83 Q_OBJECT
84
85public:
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*> contextMenuActions(const KFileItemList& items);
193
194 /** Empty implementation for deprecated interface of KVersionControlPlugin. */
195 virtual QList<QAction*> contextMenuActions(const QString& directory);
196
197signals:
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