1 | /* |
2 | * Copyright (c) 2010, 2011, 2012 Ivan Cukic <ivan.cukic(at)kde.org> |
3 | * |
4 | * This library is free software; you can redistribute it and/or |
5 | * modify it under the terms of the GNU Library General Public |
6 | * License version 2 as published by the Free Software Foundation. |
7 | * |
8 | * This library is distributed in the hope that it will be useful, |
9 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
10 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
11 | * Library General Public License for more details. |
12 | * |
13 | * You should have received a copy of the GNU Library General Public License |
14 | * along with this library; see the file COPYING.LIB. If not, write to |
15 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
16 | * Boston, MA 02110-1301, USA. |
17 | */ |
18 | |
19 | #ifndef ACTIVITIES_INFO_H |
20 | #define ACTIVITIES_INFO_H |
21 | |
22 | #include <QObject> |
23 | #include <QString> |
24 | #include <QStringList> |
25 | #include <QFuture> |
26 | |
27 | #include "kactivities_export.h" |
28 | |
29 | namespace KActivities { |
30 | |
31 | class InfoPrivate; |
32 | |
33 | /** |
34 | * This class provides info about an activity. Most methods in it require a |
35 | * semantic backend running to function properly. |
36 | * |
37 | * This class is not thread-safe. |
38 | * |
39 | * @see Consumer for info about activities |
40 | * |
41 | * The API of the class is synchronous, but the most used properties |
42 | * are pre-fetched and cached. This means that, in order to get the least |
43 | * amount of d-bus related locks, you should declare long-lived instances |
44 | * of this class. |
45 | * |
46 | * Before relying on the values retrieved by the class, make sure that the |
47 | * state is not Info::Unknown. You can get invalid data either because the |
48 | * service is not functioning properly (or at all) or because the class did |
49 | * not have enough time to synchronize the data with it. |
50 | * |
51 | * For example, if this is the only existing instance of the Info class, the |
52 | * name method will return an empty string. |
53 | * |
54 | * For example, this is wrong (works, but blocks): |
55 | * @code |
56 | * void someMethod(const QString & activity) { |
57 | * // Do not copy. This approach is not a good one! |
58 | * Info info(activity); |
59 | * doSomethingWith(info.name()); |
60 | * } |
61 | * @endcode |
62 | * |
63 | * Instances of the Info class should be long-lived. For example, members |
64 | * of the classes that use them, and you should listen for the changes in the |
65 | * provided properties. |
66 | * |
67 | * @since 4.5 |
68 | */ |
69 | class KACTIVITIES_EXPORT Info : public QObject { |
70 | Q_OBJECT |
71 | |
72 | Q_PROPERTY(QString id READ id) |
73 | Q_PROPERTY(QString name READ name NOTIFY nameChanged) |
74 | Q_PROPERTY(QString icon READ icon NOTIFY iconChanged) |
75 | Q_PROPERTY(Info::State state READ state NOTIFY stateChanged) |
76 | |
77 | public: |
78 | explicit Info(const QString &activity, QObject *parent = Q_NULLPTR); |
79 | ~Info(); |
80 | |
81 | /** |
82 | * @return true if the activity represented by this object exists and is valid |
83 | */ |
84 | bool isValid() const; |
85 | |
86 | /** |
87 | * Specifies which parts of this class are functional |
88 | */ |
89 | enum Availability { |
90 | Nothing = 0, ///< No activity info provided (isValid is false) |
91 | BasicInfo = 1, ///< Basic info is provided |
92 | Everything = 2 ///< Everything is available |
93 | }; |
94 | |
95 | /** |
96 | * State of the activity |
97 | */ |
98 | enum State { |
99 | Invalid = 0, ///< This activity does not exist |
100 | Unknown = 1, ///< Information is not yet retrieved from the service |
101 | Running = 2, ///< Activity is running |
102 | Starting = 3, ///< Activity is begin started |
103 | Stopped = 4, ///< Activity is stopped |
104 | Stopping = 5 ///< Activity is begin started |
105 | }; |
106 | |
107 | /** |
108 | * @returns what info is provided by this instance of Info |
109 | */ |
110 | Availability availability() const; |
111 | |
112 | /** |
113 | * @returns the URI of this activity. The same URI is used by activities |
114 | * KIO slave. |
115 | */ |
116 | QString uri() const; |
117 | |
118 | /** |
119 | * @returns the id of the activity |
120 | */ |
121 | QString id() const; |
122 | |
123 | /** |
124 | * @returns the name of the activity |
125 | */ |
126 | QString name() const; |
127 | |
128 | /** |
129 | * @returns the icon of the activity. Icon can be a freedesktop.org name or |
130 | * a file path. Or empty if no icon is set. |
131 | */ |
132 | QString icon() const; |
133 | |
134 | /** |
135 | * @returns the state of the activity |
136 | */ |
137 | State state() const; |
138 | |
139 | /** |
140 | * Links the specified resource to the activity |
141 | * @param resourceUri resource URI |
142 | * @note This method is <b>asynchronous</b>. It will return before the |
143 | * resource is actually linked to the activity. |
144 | */ |
145 | void linkResource(const QString &resourceUri); |
146 | |
147 | /** |
148 | * Unlinks the specified resource from the activity |
149 | * @param resourceUri resource URI |
150 | * @note This method is <b>asynchronous</b>. It will return before the |
151 | * resource is actually unlinked from the activity. |
152 | */ |
153 | void unlinkResource(const QString &resourceUri); |
154 | |
155 | /** |
156 | * @returns whether a resource is linked to this activity |
157 | * @note This QFuture is not thread-based, you can not call synchronous |
158 | * methods like waitForFinished, cancel, pause on it. |
159 | * @since 5.0 |
160 | */ |
161 | QFuture<bool> isResourceLinked(const QString &resourceUri); |
162 | |
163 | Q_SIGNALS: |
164 | /** |
165 | * Emitted when the activity's name, icon or some custom property is changed |
166 | */ |
167 | void infoChanged(); |
168 | |
169 | /** |
170 | * Emitted when the name is changed |
171 | */ |
172 | void nameChanged(const QString &name); |
173 | |
174 | /** |
175 | * Emitted when the icon was changed |
176 | */ |
177 | void iconChanged(const QString &icon); |
178 | |
179 | /** |
180 | * Emitted when the activity is added |
181 | */ |
182 | void added(); |
183 | |
184 | /** |
185 | * Emitted when the activity is removed |
186 | */ |
187 | void removed(); |
188 | |
189 | /** |
190 | * Emitted when the activity is started |
191 | */ |
192 | void started(); |
193 | |
194 | /** |
195 | * Emitted when the activity is stopped |
196 | */ |
197 | void stopped(); |
198 | |
199 | /** |
200 | * Emitted when the activity changes state |
201 | * @param state new state of the activity |
202 | */ |
203 | void stateChanged(KActivities::Info::State state); |
204 | |
205 | private: |
206 | const QScopedPointer<InfoPrivate> d; |
207 | |
208 | Q_PRIVATE_SLOT(d, void activityStateChanged(const QString &, int)) |
209 | Q_PRIVATE_SLOT(d, void added(const QString &)) |
210 | Q_PRIVATE_SLOT(d, void removed(const QString &)) |
211 | Q_PRIVATE_SLOT(d, void started(const QString &)) |
212 | Q_PRIVATE_SLOT(d, void stopped(const QString &)) |
213 | Q_PRIVATE_SLOT(d, void infoChanged(const QString &)) |
214 | Q_PRIVATE_SLOT(d, void nameChanged(const QString &, const QString &)) |
215 | Q_PRIVATE_SLOT(d, void iconChanged(const QString &, const QString &)) |
216 | Q_PRIVATE_SLOT(d, void setServiceStatus(Consumer::ServiceStatus)) |
217 | |
218 | friend class InfoPrivate; |
219 | }; |
220 | |
221 | } // namespace KActivities |
222 | |
223 | #endif // ACTIVITIES_INFO_H |
224 | |