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