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
29namespace KActivities {
30
31class 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 */
69class 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
77public:
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
163Q_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
205private:
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