File indexing completed on 2022-11-29 13:02:28

0001 /*
0002     SPDX-FileCopyrightText: 2010-2016 Ivan Cukic <ivan.cukic(at)kde.org>
0003 
0004     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0005 */
0006 
0007 #ifndef ACTIVITIES_CONSUMER_H
0008 #define ACTIVITIES_CONSUMER_H
0009 
0010 #include <QObject>
0011 #include <QScopedPointer>
0012 #include <QString>
0013 #include <QStringList>
0014 
0015 #include "info.h"
0016 
0017 #include "kactivities_export.h"
0018 
0019 namespace KActivities
0020 {
0021 class ConsumerPrivate;
0022 
0023 /**
0024  * Contextual information can be, from the user's point of view, divided
0025  * into three aspects - "who am I?", "where am I?" (what are my surroundings?)
0026  * and "what am I doing?".
0027  *
0028  * Activities deal with the last one - "what am I doing?". The current activity
0029  * refers to what the user is doing at the moment, while the other activities
0030  * represent things that he/she was doing before, and probably will be doing
0031  * again.
0032  *
0033  * Activity is an abstract concept whose meaning can differ from one user to
0034  * another. Typical examples of activities are "developing a KDE project",
0035  * "studying the 19th century art", "composing music", "lazing on a Sunday
0036  * afternoon" etc.
0037  *
0038  * Consumer provides read-only information about activities.
0039  *
0040  * Before relying on the values retrieved by the class, make sure that the
0041  * serviceStatus is set to Running. Otherwise, you can get invalid data either
0042  * because the service is not functioning properly (or at all) or because
0043  * the class did not have enough time to synchronize the data with it.
0044  *
0045  * For example, if this is the only existing instance of the Consumer class,
0046  * the listActivities method will return an empty list.
0047  *
0048  * @code
0049  * void someMethod() {
0050  *     // Do not copy. This approach is not a good one!
0051  *     Consumer c;
0052  *     doSomethingWith(c.listActivities());
0053  * }
0054  * @endcode
0055  *
0056  * Instances of the Consumer class should be long-lived. For example, members
0057  * of the classes that use them, and you should listen for the changes in the
0058  * provided properties.
0059  *
0060  * @since 4.5
0061  */
0062 class KACTIVITIES_EXPORT Consumer : public QObject
0063 {
0064     Q_OBJECT
0065 
0066     Q_PROPERTY(QString currentActivity READ currentActivity NOTIFY currentActivityChanged)
0067     Q_PROPERTY(QStringList activities READ activities NOTIFY activitiesChanged)
0068     Q_PROPERTY(QStringList runningActivities READ runningActivities NOTIFY runningActivitiesChanged)
0069     Q_PROPERTY(ServiceStatus serviceStatus READ serviceStatus NOTIFY serviceStatusChanged)
0070 
0071 public:
0072     /**
0073      * Different states of the activities service
0074      */
0075     enum ServiceStatus {
0076         NotRunning, ///< Service is not running
0077         Unknown, ///< Unable to determine the status of the service
0078         Running, ///< Service is running properly
0079     };
0080 
0081     explicit Consumer(QObject *parent = nullptr);
0082 
0083     ~Consumer() override;
0084 
0085     /**
0086      * @returns the id of the current activity
0087      * @note Activity ID is a UUID-formatted string. If the serviceStatus
0088      *       is not Running, a null UUID is returned. The ID can also be an empty
0089      *       string in the case there is no current activity.
0090      */
0091     QString currentActivity() const;
0092 
0093     /**
0094      * @returns the list of activities filtered by state
0095      * @param state state of the activity
0096      * @note If the serviceStatus is not Running, only a null activity will be
0097      *       returned.
0098      */
0099     QStringList activities(Info::State state) const;
0100 
0101     /**
0102      * @returns a list of running activities
0103      * This is a convenience method that returns Running and Stopping activities
0104      */
0105     QStringList runningActivities() const;
0106 
0107     /**
0108      * @returns the list of all existing activities
0109      * @note If the serviceStatus is not Running, only a null activity will be
0110      *       returned.
0111      */
0112     QStringList activities() const;
0113 
0114     /**
0115      * @returns status of the activities service
0116      */
0117     ServiceStatus serviceStatus();
0118 
0119 Q_SIGNALS:
0120     /**
0121      * This signal is emitted when the current activity is changed
0122      * @param id id of the new current activity
0123      */
0124     void currentActivityChanged(const QString &id);
0125 
0126     /**
0127      * This signal is emitted when the activity service goes online or offline,
0128      * or when the class manages to synchronize the data with the service.
0129      * @param status new status of the service
0130      */
0131     void serviceStatusChanged(Consumer::ServiceStatus status);
0132 
0133     /**
0134      * This signal is emitted when a new activity is added
0135      * @param id id of the new activity
0136      */
0137     void activityAdded(const QString &id);
0138 
0139     /**
0140      * This signal is emitted when an activity has been removed
0141      * @param id id of the removed activity
0142      */
0143     void activityRemoved(const QString &id);
0144 
0145     /**
0146      * This signal is emitted when the activity list changes
0147      * @param activities list of activities
0148      */
0149     void activitiesChanged(const QStringList &activities);
0150 
0151     /**
0152      * This signal is emitted when the list of running activities changes
0153      * @param runningActivities list of running activities
0154      */
0155     void runningActivitiesChanged(const QStringList &runningActivities);
0156 
0157 private:
0158     const QScopedPointer<ConsumerPrivate> d;
0159 };
0160 
0161 } // namespace KActivities
0162 
0163 #endif // ACTIVITIES_CONSUMER_H