polkit-qt-1/gui/polkitqt1-gui-action.h

0001 /*
0002     This file is part of the Polkit-qt project
0003     SPDX-FileCopyrightText: 2009 Daniel Nicoletti <dantti85-pk@yahoo.com.br>
0004     SPDX-FileCopyrightText: 2009 Dario Freddi <drf@kde.org>
0005
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008
0009 #ifndef POLKITQT1_GUI_ACTION_H
0010 #define POLKITQT1_GUI_ACTION_H
0011
0012 #include "polkitqt1-gui-export.h"
0013
0014 #include <QAction>
0015
0016 namespace PolkitQt1
0017 {
0018
0019 namespace Gui
0020 {
0021
0022 /**
0023  * \class Action polkitqt1-gui-action.h Action
0024  * \author Daniel Nicoletti <dantti85-pk@yahoo.com.br>
0025  * \author Dario Freddi <drf@kde.org>
0026  *
0027  * \brief Class used to manage actions
0028  *
0029  * This class is an interface around PolicyKit Actions.
0030  * By using this class, you are able to track the result of a
0031  * given action.
0032  *
0033  * Most of the times, you would want to use this class combined
0034  * with a QAbstractButton. In this case, you can use the more
0035  * comfortable ActionButton class that manages button's properties
0036  * update for you.
0037  *
0038  * \see ActionButton
0039  */
0040 class POLKITQT1_GUI_EXPORT Action : public QAction
0041 {
0042     Q_OBJECT
0043     Q_DISABLE_COPY(Action)
0044 public:
0045
0046     enum State {
0047         None = 0,
0048         SelfBlocked = 1,
0049         Yes = 2,
0050         No = 4,
0051         Auth = 8,
0052         // Future usage = 16,
0053         // Future usage = 32,
0054         // Future usage = 64,
0055         // Future usage = 128,
0056         // Future usage = 256,
0057         All = 512
0058     };
0059     Q_DECLARE_FLAGS(States, State)
0060
0061     /**
0062      * Constructs a new Action item
0063      *
0064      * \param actionId the PolicyKit action Id (e.g.: org.freedesktop.policykit.read)
0065      * \param parent the object parent
0066      */
0067     explicit Action(const QString &actionId = QString(), QObject *parent = nullptr);
0068     ~Action() override;
0069
0070 Q_SIGNALS:
0071     /**
0072      * Emitted when the PolicyKit result (PolKitResult)
0073      * for the given action or the internal data changes
0074      * (i.e. the user called one of the set methods).
0075      * You should connect to this signal if you want
0076      * to track these changes.
0077      */
0078     void dataChanged();
0079
0080     /**
0081      * Emitted when using this class as a proxy
0082      * for a given action, It's only emitted if the
0083      * activate() slot is called and the auth permits
0084      * the action
0085      *
0086      * \see activate()
0087      */
0088     void authorized();
0089
0090 public Q_SLOTS:
0091     /**
0092      * Use this slot if you want to activate
0093      * the action. authorized() will be emitted
0094      * if the action gets authorized.
0095      *
0096      * \return \c true if the caller can do the action
0097      *
0098      * \see authorized()
0099      */
0100     bool activate();
0101
0102     /**
0103      * Defines the checked state. The opposite state will
0104      * trigger authentication for this actions. For example, if
0105      * you set this to \c true, when the action's checked state
0106      * will become \c false, the authentication will be triggered.
0107      *
0108      * \param checked the new checked state
0109      */
0110     void setChecked(bool checked);
0111
0112     /**
0113      * This method can be used to revoke the authorization
0114      * obtained for this action.
0115      */
0116     void revoke();
0117
0118 public:
0119     /**
0120       * Changes the action being tracked
0121       *
0122       * \param actionId The new action ID
0123       */
0124     void setPolkitAction(const QString &actionId);
0125
0126     /**
0127      * Returns the current action ID.
0128      *
0129      * \return The action ID
0130      *
0131      */
0132     QString actionId() const;
0133
0134     /**
0135      * Sets the text for the current action. This will
0136      * be shown only in the states specified in the \c states parameter.
0137      * \param text the new text for the action
0138      * \param states the states of the Polkit action on which the setting
0139      *               will be applied
0140      */
0141     void setText(const QString &text, States states = All);
0142
0143     /**
0144      * Sets the tooltip for the current action. This will
0145      * be shown only in the states specified in the \c states parameter.
0146      * \param toolTip the new tooltip for the action
0147      * \param states the states of the Polkit action on which the setting
0148      *               will be applied
0149      */
0150     void setToolTip(const QString &toolTip, States states = All);
0151
0152     /**
0153      * Sets the whatsthis for the current action. This will
0154      * be shown only in the states specified in the \c states parameter.
0155      * \param whatsThis the new whatsthis for the action
0156      * \param states the states of the Polkit action on which the setting
0157      *               will be applied
0158      */
0159     void setWhatsThis(const QString &whatsThis, States states = All);
0160
0161     /**
0162      * Sets the icon for the current action. This will
0163      * be shown only in the states specified in the \c states parameter.
0164      * \note You need to pass a QIcon here. You can easily
0165      *       create one from a Pixmap, or pass a KIcon
0166      * \param icon the new icon for the action
0167      * \param states the states of the Polkit action on which the setting
0168      *               will be applied
0169      */
0170     void setIcon(const QIcon &icon, States states = All);
0171
0172     /**
0173      * Sets whether the current action is visible or not. This will
0174      * be applied only in the states specified in the \c states parameter.
0175      * \param visible visibility of the action
0176      * \param states the states of the Polkit action on which the setting
0177      *               will be applied
0178      */
0179     void setVisible(bool visible, States states = All);
0180
0181     /**
0182     * Sets whether the current action is enabled or not. This will
0183     * be shown only in the states specified in the \c states parameter.
0184     * \param enabled whether the Action will be enabled or not
0185     * \param states the states of the Polkit action on which the setting
0186     *               will be applied
0187     */
0188     void setEnabled(bool enabled, States states = All);
0189
0190     /**
0191      * This function sets the process id of the target that
0192      * should receive the authorization. Set this to 0 to set
0193      * the current process as the target.
0194      *
0195      * \param pid The target process id; 0 if it is the current process
0196      */
0197     void setTargetPID(qint64 pid);
0198
0199     /**
0200      * Gets the text of the action when it is in the specified state
0201      *
0202      * \note Passing None will return the current value
0203      * \param state The state to be checked
0204      * \returns The text shown when the action is in the specified state
0205      */
0206     QString text(State state = None) const;
0207
0208     /**
0209      * Gets the tooltip of the action when it is in the specified state
0210      *
0211      * \note Passing None will return the current value
0212      * \param state The state to be checked
0213      * \returns The tooltip shown when the action is in the specified state
0214      */
0215     QString toolTip(State state = None) const;
0216
0217     /**
0218      * Gets the whatsThis of the action when it is in the specified state
0219      *
0220      * \param state The state to be checked
0221      * \returns The whatsThis shown when the action is in the specified state
0222      */
0223     QString whatsThis(State state = None) const;
0224
0225     /**
0226      * Gets the icon of the action when it is in the specified state
0227      *
0228      * \note Passing None will return the current value
0229      * \param state The state to be checked
0230      * \returns The icon shown when the action is in the specified state
0231      */
0232     QIcon icon(State state = None) const;
0233
0234     /**
0235      * Gets whether the action is visible or not when it is in the specified state
0236      *
0237      * \note Passing None will return the current value
0238      * \param state The state to be checked
0239      * \returns Whether the action is visible or not in the specified state
0240      */
0241     bool isVisible(State state = None) const;
0242
0243     /**
0244      * Gets whether the action is enabled or not when it is in the specified state
0245      *
0246      * \note Passing None will return the current value
0247      * \param state The state to be checked
0248      * \returns Whether the action is enabled or not in the specified state
0249      */
0250     bool isEnabled(State state = None) const;
0251
0252     /**
0253      * \see setTargetPID
0254      */
0255     qint64 targetPID() const;
0256
0257     /**
0258      * This method can be used to check the if the current action
0259      * can be performed (i.e. PolKitResult is YES).
0260      * \note This method does not call the authentication dialog, use
0261      *       activate() instead
0262      * \return \c true if the action can be performed
0263      */
0264     bool isAllowed() const;
0265
0266     /**
0267      * This method compares a PolicyKit action Id with the
0268      * current one of the object.
0269      *
0270      * \see actionId()
0271      *
0272      * \param actionId the action Id to compare
0273      *
0274      * \return \c true if the actionId is the same as this object's one
0275      */
0276     bool is(const QString &actionId) const;
0277
0278 private:
0279     class Private;
0280     Private * const d;
0281
0282     Q_PRIVATE_SLOT(d, void configChanged())
0283 };
0284
0285 Q_DECLARE_OPERATORS_FOR_FLAGS(Action::States)
0286
0287 }
0288
0289 }
0290
0291 #endif