src/views/versioncontrol/kversioncontrolplugin.h

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