PolkitQt-1

polkitqt1-gui-action.h
1 /*
2  This file is part of the Polkit-qt project
3  SPDX-FileCopyrightText: 2009 Daniel Nicoletti <[email protected]>
4  SPDX-FileCopyrightText: 2009 Dario Freddi <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef POLKITQT1_GUI_ACTION_H
10 #define POLKITQT1_GUI_ACTION_H
11 
12 #include "polkitqt1-gui-export.h"
13 
14 #include <QAction>
15 
16 namespace PolkitQt1
17 {
18 
19 namespace Gui
20 {
21 
22 /**
23  * \class Action polkitqt1-gui-action.h Action
24  * \author Daniel Nicoletti <[email protected]>
25  * \author Dario Freddi <[email protected]>
26  *
27  * \brief Class used to manage actions
28  *
29  * This class is an interface around PolicyKit Actions.
30  * By using this class, you are able to track the result of a
31  * given action.
32  *
33  * Most of the times, you would want to use this class combined
34  * with a QAbstractButton. In this case, you can use the more
35  * comfortable ActionButton class that manages button's properties
36  * update for you.
37  *
38  * \see ActionButton
39  */
40 class POLKITQT1_GUI_EXPORT Action : public QAction
41 {
42  Q_OBJECT
43  Q_DISABLE_COPY(Action)
44 public:
45 
46  enum State {
47  None = 0,
48  SelfBlocked = 1,
49  Yes = 2,
50  No = 4,
51  Auth = 8,
52  // Future usage = 16,
53  // Future usage = 32,
54  // Future usage = 64,
55  // Future usage = 128,
56  // Future usage = 256,
57  All = 512
58  };
59  Q_DECLARE_FLAGS(States, State)
60 
61  /**
62  * Constructs a new Action item
63  *
64  * \param actionId the PolicyKit action Id (e.g.: org.freedesktop.policykit.read)
65  * \param parent the object parent
66  */
67  explicit Action(const QString &actionId = QString(), QObject *parent = nullptr);
68  ~Action() override;
69 
70 Q_SIGNALS:
71  /**
72  * Emitted when the PolicyKit result (PolKitResult)
73  * for the given action or the internal data changes
74  * (i.e. the user called one of the set methods).
75  * You should connect to this signal if you want
76  * to track these changes.
77  */
78  void dataChanged();
79 
80  /**
81  * Emitted when using this class as a proxy
82  * for a given action, It's only emitted if the
83  * activate() slot is called and the auth permits
84  * the action
85  *
86  * \see activate()
87  */
88  void authorized();
89 
90 public Q_SLOTS:
91  /**
92  * Use this slot if you want to activate
93  * the action. authorized() will be emitted
94  * if the action gets authorized.
95  *
96  * \return \c true if the caller can do the action
97  *
98  * \see authorized()
99  */
100  bool activate();
101 
102  /**
103  * Defines the checked state. The opposite state will
104  * trigger authentication for this actions. For example, if
105  * you set this to \c true, when the action's checked state
106  * will become \c false, the authentication will be triggered.
107  *
108  * \param checked the new checked state
109  */
110  void setChecked(bool checked);
111 
112  /**
113  * This method can be used to revoke the authorization
114  * obtained for this action.
115  */
116  void revoke();
117 
118 public:
119  /**
120  * Changes the action being tracked
121  *
122  * \param actionId The new action ID
123  */
124  void setPolkitAction(const QString &actionId);
125 
126  /**
127  * Returns the current action ID.
128  *
129  * \return The action ID
130  *
131  */
132  QString actionId() const;
133 
134  /**
135  * Sets the text for the current action. This will
136  * be shown only in the states specified in the \c states parameter.
137  * \param text the new text for the action
138  * \param states the states of the Polkit action on which the setting
139  * will be applied
140  */
141  void setText(const QString &text, States states = All);
142 
143  /**
144  * Sets the tooltip for the current action. This will
145  * be shown only in the states specified in the \c states parameter.
146  * \param toolTip the new tooltip for the action
147  * \param states the states of the Polkit action on which the setting
148  * will be applied
149  */
150  void setToolTip(const QString &toolTip, States states = All);
151 
152  /**
153  * Sets the whatsthis for the current action. This will
154  * be shown only in the states specified in the \c states parameter.
155  * \param whatsThis the new whatsthis for the action
156  * \param states the states of the Polkit action on which the setting
157  * will be applied
158  */
159  void setWhatsThis(const QString &whatsThis, States states = All);
160 
161  /**
162  * Sets the icon for the current action. This will
163  * be shown only in the states specified in the \c states parameter.
164  * \note You need to pass a QIcon here. You can easily
165  * create one from a Pixmap, or pass a KIcon
166  * \param icon the new icon for the action
167  * \param states the states of the Polkit action on which the setting
168  * will be applied
169  */
170  void setIcon(const QIcon &icon, States states = All);
171 
172  /**
173  * Sets whether the current action is visible or not. This will
174  * be applied only in the states specified in the \c states parameter.
175  * \param visible visibility of the action
176  * \param states the states of the Polkit action on which the setting
177  * will be applied
178  */
179  void setVisible(bool visible, States states = All);
180 
181  /**
182  * Sets whether the current action is enabled or not. This will
183  * be shown only in the states specified in the \c states parameter.
184  * \param enabled whether the Action will be enabled or not
185  * \param states the states of the Polkit action on which the setting
186  * will be applied
187  */
188  void setEnabled(bool enabled, States states = All);
189 
190  /**
191  * This function sets the process id of the target that
192  * should receive the authorization. Set this to 0 to set
193  * the current process as the target.
194  *
195  * \param pid The target process id; 0 if it is the current process
196  */
197  void setTargetPID(qint64 pid);
198 
199  /**
200  * Gets the text of the action when it is in the specified state
201  *
202  * \note Passing None will return the current value
203  * \param state The state to be checked
204  * \returns The text shown when the action is in the specified state
205  */
206  QString text(State state = None) const;
207 
208  /**
209  * Gets the tooltip of the action when it is in the specified state
210  *
211  * \note Passing None will return the current value
212  * \param state The state to be checked
213  * \returns The tooltip shown when the action is in the specified state
214  */
215  QString toolTip(State state = None) const;
216 
217  /**
218  * Gets the whatsThis of the action when it is in the specified state
219  *
220  * \param state The state to be checked
221  * \returns The whatsThis shown when the action is in the specified state
222  */
223  QString whatsThis(State state = None) const;
224 
225  /**
226  * Gets the icon of the action when it is in the specified state
227  *
228  * \note Passing None will return the current value
229  * \param state The state to be checked
230  * \returns The icon shown when the action is in the specified state
231  */
232  QIcon icon(State state = None) const;
233 
234  /**
235  * Gets whether the action is visible or not when it is in the specified state
236  *
237  * \note Passing None will return the current value
238  * \param state The state to be checked
239  * \returns Whether the action is visible or not in the specified state
240  */
241  bool isVisible(State state = None) const;
242 
243  /**
244  * Gets whether the action is enabled or not when it is in the specified state
245  *
246  * \note Passing None will return the current value
247  * \param state The state to be checked
248  * \returns Whether the action is enabled or not in the specified state
249  */
250  bool isEnabled(State state = None) const;
251 
252  /**
253  * \see setTargetPID
254  */
255  qint64 targetPID() const;
256 
257  /**
258  * This method can be used to check the if the current action
259  * can be performed (i.e. PolKitResult is YES).
260  * \note This method does not call the authentication dialog, use
261  * activate() instead
262  * \return \c true if the action can be performed
263  */
264  bool isAllowed() const;
265 
266  /**
267  * This method compares a PolicyKit action Id with the
268  * current one of the object.
269  *
270  * \see actionId()
271  *
272  * \param actionId the action Id to compare
273  *
274  * \return \c true if the actionId is the same as this object's one
275  */
276  bool is(const QString &actionId) const;
277 
278 private:
279  class Private;
280  Private * const d;
281 
282  Q_PRIVATE_SLOT(d, void configChanged())
283 };
284 
285 Q_DECLARE_OPERATORS_FOR_FLAGS(Action::States)
286 
287 }
288 
289 }
290 
291 #endif
Class used to manage actions.
Namespace wrapping Polkit-Qt classes.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Jun 4 2023 03:56:46 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.