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