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_INFO_H
0008 #define ACTIVITIES_INFO_H
0009 
0010 #include <QFuture>
0011 #include <QObject>
0012 #include <QString>
0013 
0014 #include "kactivities_export.h"
0015 
0016 namespace KActivities
0017 {
0018 class InfoPrivate;
0019 
0020 /**
0021  * This class provides info about an activity. Most methods in it require a
0022  * semantic backend running to function properly.
0023  *
0024  * This class is not thread-safe.
0025  *
0026  * @see Consumer for info about activities
0027  *
0028  * The API of the class is synchronous, but the most used properties
0029  * are pre-fetched and cached. This means that, in order to get the least
0030  * amount of d-bus related locks, you should declare long-lived instances
0031  * of this class.
0032  *
0033  * Before relying on the values retrieved by the class, make sure that the
0034  * state is not Info::Unknown. You can get invalid data either because the
0035  * service is not functioning properly (or at all) or because the class did
0036  * not have enough time to synchronize the data with it.
0037  *
0038  * For example, if this is the only existing instance of the Info class, the
0039  * name method will return an empty string.
0040  *
0041  * For example, this is wrong (works, but blocks):
0042  * @code
0043  * void someMethod(const QString & activity) {
0044  *     // Do not copy. This approach is not a good one!
0045  *     Info info(activity);
0046  *     doSomethingWith(info.name());
0047  * }
0048  * @endcode
0049  *
0050  * Instances of the Info class should be long-lived. For example, members
0051  * of the classes that use them, and you should listen for the changes in the
0052  * provided properties.
0053  *
0054  * @since 4.5
0055  */
0056 class KACTIVITIES_EXPORT Info : public QObject
0057 {
0058     Q_OBJECT
0059 
0060     Q_PROPERTY(QString id READ id)
0061     Q_PROPERTY(QString name READ name NOTIFY nameChanged)
0062     Q_PROPERTY(QString description READ description NOTIFY descriptionChanged)
0063     Q_PROPERTY(QString icon READ icon NOTIFY iconChanged)
0064     Q_PROPERTY(bool isCurrent READ isCurrent NOTIFY isCurrentChanged)
0065     Q_PROPERTY(Info::State state READ state NOTIFY stateChanged)
0066 
0067 public:
0068     explicit Info(const QString &activity, QObject *parent = nullptr);
0069     ~Info() override;
0070 
0071     /**
0072      * @return true if the activity represented by this object exists and is valid
0073      */
0074     bool isValid() const;
0075 
0076     /**
0077      * Specifies which parts of this class are functional
0078      */
0079     enum Availability {
0080         Nothing = 0, ///< No activity info provided (isValid is false)
0081         BasicInfo = 1, ///< Basic info is provided
0082         Everything = 2, ///< Everything is available
0083     };
0084 
0085     /**
0086      * State of the activity
0087      */
0088     enum State {
0089         Invalid = 0, ///< This activity does not exist
0090         Unknown = 1, ///< Information is not yet retrieved from the service
0091         Running = 2, ///< Activity is running
0092         Starting = 3, ///< Activity is begin started
0093         Stopped = 4, ///< Activity is stopped
0094         Stopping = 5, ///< Activity is begin started
0095     };
0096 
0097     /**
0098      * @returns what info is provided by this instance of Info
0099      */
0100     Availability availability() const;
0101 
0102     /**
0103      * @returns the URI of this activity. The same URI is used by activities
0104      * KIO worker.
0105      */
0106     QString uri() const;
0107 
0108     /**
0109      * @returns the id of the activity
0110      */
0111     QString id() const;
0112 
0113     /**
0114      * @returns whether this activity is the current one
0115      */
0116     bool isCurrent() const;
0117 
0118     /**
0119      * @returns the name of the activity
0120      */
0121     QString name() const;
0122 
0123     /**
0124      * @returns the description of the activity
0125      */
0126     QString description() const;
0127 
0128     /**
0129      * @returns the icon of the activity. Icon can be a freedesktop.org name or
0130      * a file path. Or empty if no icon is set.
0131      */
0132     QString icon() const;
0133 
0134     /**
0135      * @returns the state of the activity
0136      */
0137     State state() const;
0138 
0139     /**
0140      * Links the specified resource to the activity
0141      * @param resourceUri resource URI
0142      * @note This method is <b>asynchronous</b>. It will return before the
0143      * resource is actually linked to the activity.
0144      */
0145     // QFuture<void> linkResource(const QString &resourceUri);
0146 
0147     /**
0148      * Unlinks the specified resource from the activity
0149      * @param resourceUri resource URI
0150      * @note This method is <b>asynchronous</b>. It will return before the
0151      * resource is actually unlinked from the activity.
0152      */
0153     // QFuture<void> unlinkResource(const QString &resourceUri);
0154 
0155     /**
0156      * @returns whether a resource is linked to this activity
0157      * @note This QFuture is not thread-based, you can not call synchronous
0158      * methods like waitForFinished, cancel, pause on it.
0159      * @since 5.0
0160      */
0161     // QFuture<bool> isResourceLinked(const QString &resourceUri);
0162 
0163 Q_SIGNALS:
0164     /**
0165      * Emitted when the activity's name, icon or some custom property is changed
0166      */
0167     void infoChanged();
0168 
0169     /**
0170      * Emitted when the name is changed
0171      */
0172     void nameChanged(const QString &name);
0173 
0174     /**
0175      * Emitted when the activity becomes the current one, or when it stops
0176      * being the current one
0177      */
0178     void isCurrentChanged(bool current);
0179 
0180     /**
0181      * Emitted when the description is changed
0182      */
0183     void descriptionChanged(const QString &description);
0184 
0185     /**
0186      * Emitted when the icon was changed
0187      */
0188     void iconChanged(const QString &icon);
0189 
0190     /**
0191      * Emitted when the activity is added
0192      */
0193     void added();
0194 
0195     /**
0196      * Emitted when the activity is removed
0197      */
0198     void removed();
0199 
0200     /**
0201      * Emitted when the activity is started
0202      */
0203     void started();
0204 
0205     /**
0206      * Emitted when the activity is stopped
0207      */
0208     void stopped();
0209 
0210     /**
0211      * Emitted when the activity changes state
0212      * @param state new state of the activity
0213      */
0214     void stateChanged(KActivities::Info::State state);
0215 
0216 private:
0217     const QScopedPointer<InfoPrivate> d;
0218 
0219     Q_PRIVATE_SLOT(d, void activityStateChanged(const QString &, int))
0220     Q_PRIVATE_SLOT(d, void added(const QString &))
0221     Q_PRIVATE_SLOT(d, void removed(const QString &))
0222     Q_PRIVATE_SLOT(d, void started(const QString &))
0223     Q_PRIVATE_SLOT(d, void stopped(const QString &))
0224     Q_PRIVATE_SLOT(d, void infoChanged(const QString &))
0225     Q_PRIVATE_SLOT(d, void nameChanged(const QString &, const QString &))
0226     Q_PRIVATE_SLOT(d, void descriptionChanged(const QString &, const QString &))
0227     Q_PRIVATE_SLOT(d, void iconChanged(const QString &, const QString &))
0228     Q_PRIVATE_SLOT(d, void setServiceStatus(Consumer::ServiceStatus))
0229     Q_PRIVATE_SLOT(d, void setCurrentActivity(const QString &))
0230 
0231     friend class InfoPrivate;
0232 };
0233 
0234 } // namespace KActivities
0235 
0236 #endif // ACTIVITIES_INFO_H