Warning, file /frameworks/kactivities/src/lib/resourceinstance.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).
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