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