1 | /* |
2 | * Copyright (C) 2008 Nicola Gigante <nicola.gigante@gmail.com> |
3 | * |
4 | * This program is free software; you can redistribute it and/or modify |
5 | * it under the terms of the GNU Lesser General Public License as published by |
6 | * the Free Software Foundation; either version 2.1 of the License, or |
7 | * (at your option) any later version. |
8 | * |
9 | * This program is distributed in the hope that it will be useful, |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
12 | * GNU General Public License for more details. |
13 | * |
14 | * You should have received a copy of the GNU Lesser General Public License |
15 | * along with this program; if not, write to the |
16 | * Free Software Foundation, Inc., |
17 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA . |
18 | */ |
19 | |
20 | #ifndef ACTION_WATCHER_H |
21 | #define ACTION_WATCHER_H |
22 | |
23 | #include <QtCore/QObject> |
24 | #include <QtCore/QString> |
25 | |
26 | #include <kdecore_export.h> |
27 | |
28 | #include "kauthactionreply.h" |
29 | #include "kauthaction.h" |
30 | |
31 | namespace KAuth |
32 | { |
33 | |
34 | /** |
35 | * @brief Class used to receive notifications about the status of an action execution. |
36 | * |
37 | * The ActionWatcher class provides some signals useful to track the execution of an action. |
38 | * The Action class is designed to be very ligthweight, so it's not the case to make it |
39 | * a QObject subclass. This means the action object can't expose signals. This is the reason |
40 | * why every action (not every Action object) used by the app has an associated ActionWatcher. |
41 | * |
42 | * You don't create watchers directly. Instead, you should get one from the Action::watcher() method, |
43 | * if you have an action object, or with the ActionWatcher::watcher() static method, which takes the |
44 | * action name string. |
45 | * |
46 | * See the documentation of single signals for more details about them. |
47 | * |
48 | * @since 4.4 |
49 | */ |
50 | class KDECORE_EXPORT ActionWatcher : public QObject |
51 | { |
52 | Q_OBJECT |
53 | |
54 | class Private; |
55 | Private * const d; |
56 | |
57 | ActionWatcher(); |
58 | ActionWatcher(const QString &action); |
59 | |
60 | Q_PRIVATE_SLOT(d, void actionStartedSlot(const QString &action)) |
61 | Q_PRIVATE_SLOT(d, void actionPerformedSlot(const QString &action, const ActionReply &reply)) |
62 | Q_PRIVATE_SLOT(d, void progressStepSlot(const QString &action, int i)) |
63 | Q_PRIVATE_SLOT(d, void progressStepSlot(const QString &action, const QVariantMap &data)) |
64 | Q_PRIVATE_SLOT(d, void statusChangedSlot(const QString &action, Action::AuthStatus status)) |
65 | |
66 | public: |
67 | /** |
68 | * @brief Factory method to get watchers |
69 | * |
70 | * This method allows you to obtain (and create if needed) an |
71 | * action watcher from the action string identifier. |
72 | * It's more common to obtain a watcher using Action::watcher(), |
73 | * which actually calls this method. |
74 | * |
75 | * Every signal of this class |
76 | * is emitted whichever method you used to execute the action. |
77 | * This means you could connect to the signal actionPerformed() |
78 | * even if you're using the execute() method (which already returns the reply) |
79 | * and you'll get the same reply. |
80 | * |
81 | * @param action The action string identifier for the creation of the watcher |
82 | * @return The action watcher associated with the given action |
83 | */ |
84 | static ActionWatcher *watcher(const QString &action); |
85 | |
86 | /// Virtual destructor |
87 | virtual ~ActionWatcher(); |
88 | |
89 | /// Returns the action name associated with this watcher |
90 | QString action() const; |
91 | |
92 | Q_SIGNALS: |
93 | /** |
94 | * @brief Signal emitted when an action starts the execution |
95 | * |
96 | * This signal is emitted whe In case of |
97 | * execute() and executeAsync(), the signal is emitted about |
98 | * immediately, because the request is very fast. |
99 | * |
100 | * If you execute a group of actions using Action::executeActions(), |
101 | * this signal is emitted when the single action is actually about |
102 | * to be executed, not when the whole group starts executing. |
103 | * This means you can use this signal to start some kind of timeout |
104 | * to handle helper crashes, if you feel the need. |
105 | */ |
106 | void actionStarted(); |
107 | |
108 | /** |
109 | * @brief Signal emitted when an action completed the execution |
110 | * |
111 | * This signal provides the only way to obtain the reply from the helper |
112 | * in case of asynchronous calls. The reply object is the same returned |
113 | * by the helper, or an error reply from the library if something went |
114 | * wrong. |
115 | * |
116 | * @param reply The reply coming from the helper |
117 | */ |
118 | void actionPerformed(const ActionReply &reply); |
119 | |
120 | /** |
121 | * @brief Signal emitted by the helper to notify the action's progress |
122 | * |
123 | * This signal is emitted every time the helper's code calls the |
124 | * HelperSupport::progressStep(int) method. This is useful to let the |
125 | * helper notify the execution status of a long action. |
126 | * The meaning of the integer passed here is totally application-dependent. |
127 | * If you need to be more expressive, you can use the other signal that |
128 | * pass a QVariantMap. |
129 | * |
130 | * @param progress The progress indicator from the helper |
131 | */ |
132 | void progressStep(int progress); |
133 | |
134 | /** |
135 | * @brief Signal emitted by the helper to notify the action's progress |
136 | * |
137 | * This signal is emitted every time the helper's code calls the |
138 | * HelperSupport::progressStep(QVariantMap) method. This is useful to let the |
139 | * helper notify the execution status of a long action, also providing |
140 | * some data, for example if you want to achieve some sort of progressive loading. |
141 | * The meaning of the data passed here is totally application-dependent. |
142 | * If you only need to pass some percentage, you can use the other signal that |
143 | * pass an int. |
144 | * |
145 | * @param data The progress data from the helper |
146 | */ |
147 | void progressStep(const QVariantMap &data); |
148 | |
149 | void statusChanged(int status); |
150 | }; |
151 | |
152 | } // namespace Auth |
153 | |
154 | #endif |
155 | |