src/admin/workerintegration.h

   1 /*
   2     This file is part of the KDE project
   3     SPDX-FileCopyrightText: 2022 Felix Ernst <felixernst@kde.org>
   4
   5     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
   6 */
   7
   8 #ifndef ADMINWORKERINTEGRATION_H
   9 #define ADMINWORKERINTEGRATION_H
  10
  11 #include <QObject>
  12
  13 class DolphinMainWindow;
  14 class DolphinViewContainer;
  15 class KActionCollection;
  16 class QAction;
  17 class QUrl;
  18
  19 /**
  20  * @brief This namespace contains everything that is necessary to nicely integrate "KIO Admin Worker" into Dolphin.
  21  *
  22  * @see https://commits.kde.org/kio-admin
  23  */
  24 namespace Admin
  25 {
  26 /**
  27  * When a user starts Dolphin with arguments that imply that they want to use administrative rights, this method is called.
  28  * This function acts like a command line program that guides users towards installing kio-admin. It will not return until this is accomplished.
  29  * This function will do nothing if kio-admin is already installed.
  30  */
  31 void guideUserTowardsInstallingAdminWorker();
  32
  33 void guideUserTowardsUsingAdminWorker();
  34
  35 /**
  36  * Used with the KMessageBox API so users can disable the warning.
  37  * @see KMessageBox::saveDontShowAgainContinue()
  38  * @see KMessageBox::enableMessage()
  39  */
  40 constexpr QLatin1String warningDontShowAgainName{"warnAboutRisksBeforeActingAsAdmin"};
  41
  42 /** @returns an elaborate warning about the dangers of acting with administrative privileges. */
  43 QString warningMessage();
  44
  45 /**
  46  * @brief A class encapsulating the "Act as Admin"-toggle action.
  47  *
  48  * @see https://commits.kde.org/kio-admin
  49  */
  50 class WorkerIntegration : public QObject
  51 {
  52     Q_OBJECT
  53
  54 public:
  55     /**
  56      * Adds a toggle action to the \a actionCollection.
  57      * The action switches between acting as a normal user or acting as an administrator.
  58      */
  59     static void createActAsAdminAction(KActionCollection *actionCollection, DolphinMainWindow *dolphinMainWindow);
  60
  61     /**
  62      * An interface that only allows friend classes to show the WorkerIntegration::m_actAsAdminAction to users.
  63      * Aside from these friend classes the action is only accessible through the actionCollection of DolphinMainWindow.
  64      */
  65     class FriendAccess
  66     {
  67         /** @returns WorkerIntegration::m_actAsAdminAction or crashes if WorkerIntegration::createActAsAdminAction() has not been called previously. */
  68         static QAction *actAsAdminAction();
  69
  70         friend class Bar; /// Allows the bar to access the actAsAdminAction, so users can use the bar to change who they are acting as.
  71         friend DolphinViewContainer; // Allows the view container to access the actAsAdminAction, so the action can be shown to users when they are trying to
  72                                      // view a folder for which they are lacking read permissions.
  73     };
  74
  75 private:
  76     WorkerIntegration(DolphinMainWindow *parent, QAction *actAsAdminAction);
  77
  78     /**
  79      * Toggles between acting with admin rights or not.
  80      * This enables editing more files than the normal user account would be allowed to but requires re-authorization.
  81      */
  82     void toggleActAsAdmin();
  83
  84     /** Updates the toggled/checked state of the action depending on the state of the currently active view. */
  85     static void updateActAsAdminAction();
  86
  87 private:
  88     /** @see createActAsAdminAction() */
  89     QAction *const m_actAsAdminAction = nullptr;
  90 };
  91
  92 }
  93
  94 #endif // ADMINWORKERINTEGRATION_H