File indexing completed on 2024-05-12 05:47:52

 /*
  * SPDX-FileCopyrightText: 2011 Vishesh Yadav <vishesh3y@gmail.com>
  * SPDX-FileCopyrightText: 2011 Peter Penz <peter.penz19@gmail.com>
  *
  * SPDX-License-Identifier: LGPL-2.0-only
  */
 
 #ifndef KVERSIONCONTROLPLUGIN_H
 #define KVERSIONCONTROLPLUGIN_H
 
 #include <dolphinvcs_export.h>
 
 #include <QAction>
 #include <QObject>
 
 class KFileItemList;
 class KFileItem;
 /**
  * @brief Base class for version control plugins.
  *
  * Enables the file manager to show the version state
  * of a versioned file. To write a custom plugin, the following
  * steps are required (in the example below it is assumed that a plugin for
  * Subversion will be written):
  *
  * - Create a fileviewsvnplugin.json file with the following content:
  *   <code>
  *   {
  *      "KPlugin": {
  *          "Description": "The svn plugin",
  *          "Name": "Svn"
  *      }
  *   }
 
  *   </code>
  *
  * - Create a class FileViewSvnPlugin derived from KVersionControlPlugin and
  *   implement all abstract interfaces (fileviewsvnplugin.h, fileviewsvnplugin.cpp).
  *
  * - Take care that the constructor has the following signature:
  *   <code>
  *   FileViewSvnPlugin(QObject* parent, const QList<QVariant>& args);
  *   </code>
  *
  * - Add the following lines at the top of fileviewsvnplugin.cpp:
  *   <code>
  *   #include <KPluginFactory>
  *   K_PLUGIN_CLASS_WITH_JSON(FileViewSvnPlugin, "fileviewsvnplugin.json")
  *   </code>
  *
  * - Add the following lines to your CMakeLists.txt file:
  *   <code>
  *   kcoreaddons_add_plugin(fileviewsvnplugin SOURCES fileviewsvnplugin.cpp INSTALL_NAMESPACE "dolphin/vcs")
  *   target_link_libraries(fileviewsvnplugin DolphinVcs)
  *   </code>
  *
  * General implementation notes:
  *
  *  - The implementations of beginRetrieval(), endRetrieval() and versionState()
  *    can contain blocking operations, as Dolphin will execute
  *    those methods in a separate thread. It is assured that
  *    all other methods are invoked in a serialized way, so that it is not necessary for
  *    the plugin to use any mutex.
  *
  * -  Dolphin keeps only one instance of the plugin, which is instantiated shortly after
  *    starting Dolphin. Take care that the constructor does no expensive and time
  *    consuming operations.
  *
  * @since 4.8
  */
 class DOLPHINVCS_EXPORT KVersionControlPlugin : public QObject
 {
     Q_OBJECT
 
 public:
     enum ItemVersion {
         /** The file is not under version control. */
         UnversionedVersion,
         /**
          * The file is under version control and represents
          * the latest version.
          */
         NormalVersion,
         /**
          * The file is under version control and a newer
          * version exists on the main branch.
          */
         UpdateRequiredVersion,
         /**
          * The file is under version control and has been
          * modified locally. All modifications will be part
          * of the next commit.
          */
         LocallyModifiedVersion,
         /**
          * The file has not been under version control but
          * has been marked to get added with the next commit.
          */
         AddedVersion,
         /**
          * The file is under version control but has been marked
          * for getting removed with the next commit.
          */
         RemovedVersion,
         /**
          * The file is under version control and has been locally
          * modified. A modification has also been done on the main
          * branch.
          */
         ConflictingVersion,
         /**
          * The file is under version control and has local
          * modifications, which will not be part of the next
          * commit (or are "unstaged" in git jargon).
          * @since 4.6
          */
         LocallyModifiedUnstagedVersion,
         /**
          * The file is not under version control and is listed
          * in the ignore list of the version control system.
          * @since 4.8
          */
         IgnoredVersion,
         /**
          * The file is tracked by the version control system, but
          * is missing in the directory (e.g. by deleted without using
          * a version control command).
          * @since 4.8
          */
         MissingVersion
     };
 
     KVersionControlPlugin(QObject *parent = nullptr);
     ~KVersionControlPlugin() override;
 
     /**
      * Returns the name of the file which stores
      * the version controls information.
      * (e. g. .svn, .cvs, .git).
      */
     virtual QString fileName() const = 0;
 
     /**
      * Returns the path of the local repository root for the versioned directory
      * Returns an empty QString when directory is not part of a working copy
      */
     virtual QString localRepositoryRoot(const QString &directory) const;
 
     /**
      * Is invoked whenever the version control
      * information will get retrieved for the directory
      * \p directory. It is assured that the directory
      * contains a trailing slash.
      */
     virtual bool beginRetrieval(const QString &directory) = 0;
 
     /**
      * Is invoked after the version control information has been
      * received. It is assured that
      * KVersionControlPlugin::beginRetrieval() has been
      * invoked before.
      */
     virtual void endRetrieval() = 0;
 
     /**
      * @return The version for the item \p item.
      *         It is assured that KVersionControlPlugin::beginRetrieval() has been
      *         invoked before and that the file is part of the directory specified
      *         in beginRetrieval().
      */
     virtual ItemVersion itemVersion(const KFileItem &item) const = 0;
 
     /**
      * @return List of actions that are available for the \p items in a version controlled
      *         path.
      */
     virtual QList<QAction *> versionControlActions(const KFileItemList &items) const = 0;
 
     /**
      * @return List of actions that are available for the out of version control
      *         items \p items. It's opposed to the \p versionedActions. Common usage
      *         is for clone/checkout actions.
      * @since 21.04
      */
     virtual QList<QAction *> outOfVersionControlActions(const KFileItemList &items) const = 0;
 
 Q_SIGNALS:
     /**
      * Should be emitted when the version state of items might have been changed
      * after the last retrieval (e. g. by executing a context menu action
      * of the version control plugin). The file manager will be triggered to
      * update the version states of the directory \p directory by invoking
      * KVersionControlPlugin::beginRetrieval(),
      * KVersionControlPlugin::itemVersion() and
      * KVersionControlPlugin::endRetrieval().
      */
     void itemVersionsChanged();
 
     /**
      * Is emitted if an information message with the content \a msg
      * should be shown.
      */
     void infoMessage(const QString &msg);
 
     /**
      * Is emitted if an error message with the content \a msg
      * should be shown.
      */
     void errorMessage(const QString &msg);
 
     /**
      * Is emitted if an "operation completed" message with the content \a msg
      * should be shown.
      */
     void operationCompletedMessage(const QString &msg);
 };
 
 #endif // KVERSIONCONTROLPLUGIN_H