src/views/versioncontrol/kversioncontrolplugin.h

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