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

0001 /*
0002     SPDX-FileCopyrightText: 2011-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_RESOURCEINSTANCE_H
0008 #define ACTIVITIES_RESOURCEINSTANCE_H
0009 
0010 #include <QObject>
0011 #include <QUrl>
0012 
0013 #include "kactivities_export.h"
0014 
0015 namespace KActivities
0016 {
0017 class ResourceInstancePrivate;
0018 
0019 /**
0020  * This class is used to notify the system that a file, web page
0021  * or some other resource has been accessed.
0022  *
0023  * It provides methods to notify the system when the resource was
0024  * opened, modified and closed, along with in what window the
0025  * resource is shown.
0026  *
0027  * You should create an instance of this class for every resource
0028  * you open.
0029  *
0030  * "The system" in this case can be the backend for tracking
0031  * and automatically scoring files that are being accessed, the
0032  * system to show the open files per window in the taskbar,
0033  * the share-like-connect, etc.
0034  *
0035  * The user of this class shouldn't care about the backend
0036  * systems - everything is done under-the-hood automatically.
0037  *
0038  */
0039 class KACTIVITIES_EXPORT ResourceInstance : public QObject
0040 {
0041     Q_OBJECT
0042 
0043     Q_PROPERTY(QUrl uri READ uri WRITE setUri)
0044     Q_PROPERTY(QString mimetype READ mimetype WRITE setMimetype)
0045     Q_PROPERTY(QString title READ title WRITE setTitle)
0046     Q_PROPERTY(quintptr winId READ winId)
0047 
0048 public:
0049     /**
0050      * Creates a new resource instance
0051      * @param wid id of the window that will show the resource
0052      * @param parent pointer to the parent object
0053      * @since 4.10
0054      */
0055     explicit ResourceInstance(quintptr wid, QObject *parent = nullptr);
0056 
0057     /**
0058      * Creates a new resource instance
0059      * @param wid id of the window that will show the resource
0060      * @param application application's name (the name used for the .desktop file).
0061      *        If not specified, QCoreApplication::applicationName is used
0062      * @param parent pointer to the parent object
0063      */
0064     explicit ResourceInstance(quintptr wid, const QString &application, QObject *parent = nullptr);
0065 
0066     /**
0067      * Creates a new resource instance and automatically
0068      * notifies the system that it was opened.
0069      *
0070      * In some special cases, where the URI of the resource is
0071      * being constantly changed (for example, in the world globe,
0072      * street map applications) you have two options:
0073      *  - to pass an empty resourceUri while passing the mimetype
0074      *  - to update the uri from time to time (in the example of
0075      *    the world map - to send URIs for major objects - cities
0076      *    or main streets.
0077      * and in both cases reimplementing the currentUri() method
0078      * which will return the exact URI shown at that specific moment.
0079      *
0080      * @param wid window id in which the resource is shown
0081      * @param resourceUri URI of the resource that is shown
0082      * @param mimetype the mime type of the resource
0083      * @param title the title of the resource
0084      * @param application application's name (the name used for the .desktop file).
0085      *        If not specified, QCoreApplication::applicationName is used
0086      * @param parent pointer to the parent object
0087      */
0088     ResourceInstance(quintptr wid,
0089                      QUrl resourceUri,
0090                      const QString &mimetype = QString(),
0091                      const QString &title = QString(),
0092                      const QString &application = QString(),
0093                      QObject *parent = nullptr);
0094 
0095     /**
0096      * Destroys the ResourceInstance and notifies the system
0097      * that the resource has been closed
0098      */
0099     ~ResourceInstance() override;
0100 
0101 public Q_SLOTS:
0102     /**
0103      * Call this method to notify the system that you modified
0104      * (the contents of) the resource
0105      */
0106     void notifyModified();
0107 
0108     /**
0109      * Call this method to notify the system that the resource
0110      * has the focus in your application
0111      * @note You only need to call this in MDI applications
0112      */
0113     void notifyFocusedIn();
0114 
0115     /**
0116      * Call this method to notify the system that the resource
0117      * lost the focus in your application
0118      * @note You only need to call this in MDI applications
0119      */
0120     void notifyFocusedOut();
0121 
0122     /**
0123      * This is a convenience method that sets the new URI.
0124      * This is usually handled by sending the close event for
0125      * the previous URI, and an open event for the new one.
0126      */
0127     void setUri(const QUrl &newUri);
0128 
0129     /**
0130      * Sets the mimetype for this resource
0131      */
0132     void setMimetype(const QString &mimetype);
0133 
0134     /**
0135      * Sets the title for this resource
0136      */
0137     void setTitle(const QString &title);
0138 
0139 Q_SIGNALS:
0140     /**
0141      * Emitted when the system wants to show the resource
0142      * represented by this ResourceInstance.
0143      *
0144      * You should listen to this signal if you have multiple
0145      * resources shown in one window (MDI). On catching it, show
0146      * the resource and give it focus.
0147      */
0148     void requestsFocus();
0149 
0150 public:
0151     /**
0152      * @returns the current uri
0153      * The default implementation returns the URI that was passed
0154      * to the constructor.
0155      * You need to reimplement it only for the applications with
0156      * frequently updated URIs.
0157      */
0158     virtual QUrl uri() const;
0159 
0160     /**
0161      * @returns mimetype of the resource
0162      */
0163     QString mimetype() const;
0164 
0165     /**
0166      * @returns title of the resource
0167      */
0168     QString title() const;
0169 
0170     /**
0171      * @returns the window id
0172      */
0173     quintptr winId() const;
0174 
0175     /**
0176      * If there's no way to tell for how long an application is keeping
0177      * the resource open, you can just call this static method - it
0178      * will notify the system that the application has accessed the
0179      * resource
0180      * @param uri URI of the resource
0181      * @param application application's name (the name used for the .desktop file).
0182      *        If not specified, QCoreApplication::applicationName is used
0183      *
0184      */
0185     static void notifyAccessed(const QUrl &uri, const QString &application = QString());
0186 
0187 private:
0188     const QScopedPointer<ResourceInstancePrivate> d;
0189 };
0190 }
0191 
0192 #endif // ACTIVITIES_RESOURCEINSTANCE_H