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         /** The file is not under version control. */
  78         UnversionedVersion,
  79         /**
  80          * The file is under version control and represents
  81          * the latest version.
  82          */
  83         NormalVersion,
  84         /**
  85          * The file is under version control and a newer
  86          * version exists on the main branch.
  87          */
  88         UpdateRequiredVersion,
  89         /**
  90          * The file is under version control and has been
  91          * modified locally. All modifications will be part
  92          * of the next commit.
  93          */
  94         LocallyModifiedVersion,
  95         /**
  96          * The file has not been under version control but
  97          * has been marked to get added with the next commit.
  98          */
  99         AddedVersion,
 100         /**
 101          * The file is under version control but has been marked
 102          * for getting removed with the next commit.
 103          */
 104         RemovedVersion,
 105         /**
 106          * The file is under version control and has been locally
 107          * modified. A modification has also been done on the main
 108          * branch.
 109          */
 110         ConflictingVersion,
 111         /**
 112          * The file is under version control and has local
 113          * modifications, which will not be part of the next
 114          * commit (or are "unstaged" in git jargon).
 115          * @since 4.6
 116          */
 117         LocallyModifiedUnstagedVersion,
 118         /**
 119          * The file is not under version control and is listed
 120          * in the ignore list of the version control system.
 121          * @since 4.8
 122          */
 123         IgnoredVersion,
 124         /**
 125          * The file is tracked by the version control system, but
 126          * is missing in the directory (e.g. by deleted without using
 127          * a version control command).
 128          * @since 4.8
 129          */
 130         MissingVersion
 131     };
 132
 133     KVersionControlPlugin(QObject *parent = nullptr);
 134     ~KVersionControlPlugin() override;
 135
 136     /**
 137      * Returns the name of the file which stores
 138      * the version controls information.
 139      * (e. g. .svn, .cvs, .git).
 140      */
 141     virtual QString fileName() const = 0;
 142
 143     /**
 144      * Returns the path of the local repository root for the versioned directory
 145      * Returns an empty QString when directory is not part of a working copy
 146      */
 147     virtual QString localRepositoryRoot(const QString &directory) const;
 148
 149     /**
 150      * Is invoked whenever the version control
 151      * information will get retrieved for the directory
 152      * \p directory. It is assured that the directory
 153      * contains a trailing slash.
 154      */
 155     virtual bool beginRetrieval(const QString &directory) = 0;
 156
 157     /**
 158      * Is invoked after the version control information has been
 159      * received. It is assured that
 160      * KVersionControlPlugin::beginRetrieval() has been
 161      * invoked before.
 162      */
 163     virtual void endRetrieval() = 0;
 164
 165     /**
 166      * @return The version for the item \p item.
 167      *         It is assured that KVersionControlPlugin::beginRetrieval() has been
 168      *         invoked before and that the file is part of the directory specified
 169      *         in beginRetrieval().
 170      */
 171     virtual ItemVersion itemVersion(const KFileItem &item) const = 0;
 172
 173     /**
 174      * @return List of actions that are available for the \p items in a version controlled
 175      *         path.
 176      */
 177     virtual QList<QAction *> versionControlActions(const KFileItemList &items) const = 0;
 178
 179     /**
 180      * @return List of actions that are available for the out of version control
 181      *         items \p items. It's opposed to the \p versionedActions. Common usage
 182      *         is for clone/checkout actions.
 183      * @since 21.04
 184      */
 185     virtual QList<QAction *> outOfVersionControlActions(const KFileItemList &items) const = 0;
 186
 187 Q_SIGNALS:
 188     /**
 189      * Should be emitted when the version state of items might have been changed
 190      * after the last retrieval (e. g. by executing a context menu action
 191      * of the version control plugin). The file manager will be triggered to
 192      * update the version states of the directory \p directory by invoking
 193      * KVersionControlPlugin::beginRetrieval(),
 194      * KVersionControlPlugin::itemVersion() and
 195      * KVersionControlPlugin::endRetrieval().
 196      */
 197     void itemVersionsChanged();
 198
 199     /**
 200      * Is emitted if an information message with the content \a msg
 201      * should be shown.
 202      */
 203     void infoMessage(const QString &msg);
 204
 205     /**
 206      * Is emitted if an error message with the content \a msg
 207      * should be shown.
 208      */
 209     void errorMessage(const QString &msg);
 210
 211     /**
 212      * Is emitted if an "operation completed" message with the content \a msg
 213      * should be shown.
 214      */
 215     void operationCompletedMessage(const QString &msg);
 216 };
 217
 218 #endif // KVERSIONCONTROLPLUGIN_H