1/*****************************************************************************
2 * Copyright (C) 2009 by Peter Penz <peter.penz19@gmail.com> *
3 * *
4 * This library is free software; you can redistribute it and/or *
5 * modify it under the terms of the GNU Library General Public *
6 * License version 2 as published by the Free Software Foundation. *
7 * *
8 * This library is distributed in the hope that it will be useful, *
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
11 * Library General Public License for more details. *
12 * *
13 * You should have received a copy of the GNU Library General Public License *
14 * along with this library; see the file COPYING.LIB. If not, write to *
15 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, *
16 * Boston, MA 02110-1301, USA. *
17 *****************************************************************************/
18
19#ifndef KVERSIONCONTROLPLUGIN_H
20#define KVERSIONCONTROLPLUGIN_H
21
22#include <libkonq_export.h>
23
24#include <QObject>
25
26class KFileItem;
27class KFileItemList;
28class QAction;
29
30/**
31 * @brief Base class for version control plugins.
32 *
33 * It is recommended to use the KVersionControlPlugin2 interface. KVersionControlPlugin2
34 * allows having context menu actions also for non-versioned directories and provides
35 * some interface cleanups. It replaces:
36 * - contextMenuActions() by KVersionControlPlugin2::actions()
37 * - versionState() by KVersionControlPlugin2::itemVersion()
38 * - versionStatesChanged() by KVersionControlPlugin2::itemVersionsChanged()
39 * - VersionState by ItemState
40 *
41 * @since 4.4
42 */
43class LIBKONQ_EXPORT KVersionControlPlugin : public QObject
44{
45 Q_OBJECT
46
47public:
48 enum VersionState
49 {
50 /** The file is not under version control. */
51 UnversionedVersion,
52 /**
53 * The file is under version control and represents
54 * the latest version.
55 */
56 NormalVersion,
57 /**
58 * The file is under version control and a newer
59 * version exists on the main branch.
60 */
61 UpdateRequiredVersion,
62 /**
63 * The file is under version control and has been
64 * modified locally. All modifications will be part
65 * of the next commit.
66 */
67 LocallyModifiedVersion,
68 /**
69 * The file has not been under version control but
70 * has been marked to get added with the next commit.
71 */
72 AddedVersion,
73 /**
74 * The file is under version control but has been marked
75 * for getting removed with the next commit.
76 */
77 RemovedVersion,
78 /**
79 * The file is under version control and has been locally
80 * modified. A modification has also been done on the main
81 * branch.
82 */
83 ConflictingVersion,
84 /**
85 * The file is under version control and has local
86 * modifications, which will not be part of the next
87 * commit (or are "unstaged" in git jargon).
88 * @since 4.6
89 */
90 LocallyModifiedUnstagedVersion
91 };
92
93 KVersionControlPlugin(QObject* parent = 0);
94 virtual ~KVersionControlPlugin();
95
96 /**
97 * Returns the name of the file which stores
98 * the version controls information.
99 * (e. g. .svn, .cvs, .git).
100 */
101 virtual QString fileName() const = 0;
102
103 /**
104 * Is invoked whenever the version control
105 * information will get retrieved for the directory
106 * \p directory. It is assured that the directory
107 * contains a trailing slash.
108 */
109 virtual bool beginRetrieval(const QString& directory) = 0;
110
111 /**
112 * Is invoked after the version control information has been
113 * received. It is assured that
114 * KVersionControlPlugin::beginInfoRetrieval() has been
115 * invoked before.
116 */
117 virtual void endRetrieval() = 0;
118
119 /**
120 * Returns the version state for the file \p item.
121 * It is assured that KVersionControlPlugin::beginInfoRetrieval() has been
122 * invoked before and that the file is part of the directory specified
123 * in beginInfoRetrieval().
124 *
125 * @deprecated Use KVersionControlPlugin2::itemVersion() instead.
126 */
127 virtual VersionState versionState(const KFileItem& item) = 0;
128
129 /**
130 * Returns the list of actions that should be shown in the context menu
131 * for the files \p items. It is assured that the passed list is not empty.
132 * If an action triggers a change of the versions, the signal
133 * KVersionControlPlugin::versionStatesChanged() must be emitted.
134 *
135 * @deprecated Use KVersionControlPlugin2::actions() instead.
136 */
137 virtual QList<QAction*> contextMenuActions(const KFileItemList& items) = 0;
138
139 /**
140 * Returns the list of actions that should be shown in the context menu
141 * for the directory \p directory. If an action triggers a change of the versions,
142 * the signal KVersionControlPlugin::versionStatesChanged() must be emitted.
143 *
144 * @deprecated Use KVersionControlPlugin2::actions() instead.
145 */
146 virtual QList<QAction*> contextMenuActions(const QString& directory) = 0;
147
148signals:
149 /**
150 * Should be emitted when the version state of files might have been changed
151 * after the last retrieval (e. g. by executing a context menu action
152 * of the version control plugin). The file manager will be triggered to
153 * update the version states of the directory \p directory by invoking
154 * KVersionControlPlugin::beginRetrieval(),
155 * KVersionControlPlugin::versionState() and
156 * KVersionControlPlugin::endRetrieval().
157 *
158 * @deprecated Use KVersionControlPlugin2::itemVersionsChanged() instead.
159 */
160 void versionStatesChanged();
161
162 /**
163 * Is emitted if an information message with the content \a msg
164 * should be shown.
165 */
166 void infoMessage(const QString& msg);
167
168 /**
169 * Is emitted if an error message with the content \a msg
170 * should be shown.
171 */
172 void errorMessage(const QString& msg);
173
174 /**
175 * Is emitted if an "operation completed" message with the content \a msg
176 * should be shown.
177 */
178 void operationCompletedMessage(const QString& msg);
179};
180
181#endif // KVERSIONCONTROLPLUGIN_H
182
183