1/*
2 * Copyright (C) 2011, 2012 Ivan Cukic <ivan.cukic(at)kde.org>
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License version 2,
6 * or (at your option) any later version, as published by the Free
7 * Software Foundation
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU Lesser General Public License for more details
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this program; if not, write to the
16 * Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 */
19
20#ifndef ACTIVITIES_RESOURCEINSTANCE_H
21#define ACTIVITIES_RESOURCEINSTANCE_H
22
23#include <QObject>
24#include <QUrl>
25
26#include "kactivities_export.h"
27
28namespace KActivities {
29
30class ResourceInstancePrivate;
31
32/**
33 * This class is used to notify the system that a file, web page
34 * or some other resource has been accessed.
35 *
36 * It provides methods to notify the system when the resource was
37 * opened, modified and closed, along with in what window the
38 * resource is shown.
39 *
40 * You should create an instance of this class for every resource
41 * you open.
42 *
43 * "The system" in this case can be the backend for tracking
44 * and automatically scoring files that are being accessed, the
45 * system to show the open files per window in the taskbar,
46 * the share-like-connect, etc.
47 *
48 * The user of this class shouldn't care about the backend
49 * systems - everything is done under-the-hood automatically.
50 *
51 */
52class KACTIVITIES_EXPORT ResourceInstance : public QObject {
53 Q_OBJECT
54
55 Q_PROPERTY(QUrl uri READ uri WRITE setUri)
56 Q_PROPERTY(QString mimetype READ mimetype WRITE setMimetype)
57 Q_PROPERTY(QString title READ title WRITE setTitle)
58 Q_PROPERTY(quintptr winId READ winId)
59
60public:
61 /**
62 * Creates a new resource instance
63 * @param wid id of the window that will show the resource
64 * @param parent pointer to the parent object
65 * @since 4.10
66 */
67 explicit ResourceInstance(quintptr wid, QObject *parent = Q_NULLPTR);
68
69 /**
70 * Creates a new resource instance
71 * @param wid id of the window that will show the resource
72 * @param application application's name (the name used for the .desktop file).
73 * If not specified, QCoreApplication::applicationName is used
74 * @param parent pointer to the parent object
75 */
76 explicit ResourceInstance(quintptr wid, const QString &application = QString(), QObject *parent = Q_NULLPTR);
77
78 /**
79 * Creates a new resource instance and automatically
80 * notifies the system that it was opened.
81 *
82 * In some special cases, where the URI of the resource is
83 * being constantly changed (for example, in the world globe,
84 * street map applications) you have two options:
85 * - to pass an empty resourceUri while passing the mimetype
86 * - to update the uri from time to time (in the example of
87 * the world map - to send URIs for major objects - cities
88 * or main streets.
89 * and in both cases reimplementing the currentUri() method
90 * which will return the exact URI shown at that specific moment.
91 *
92 * @param wid window id in which the resource is shown
93 * @param resourceUri URI of the resource that is shown
94 * @param mimetype the mime type of the resource
95 * @param title the title of the resource
96 * @param application application's name (the name used for the .desktop file).
97 * If not specified, QCoreApplication::applicationName is used
98 * @param parent pointer to the parent object
99 */
100 ResourceInstance(quintptr wid, QUrl resourceUri, const QString &mimetype = QString(),
101 const QString &title = QString(), const QString &application = QString(),
102 QObject *parent = Q_NULLPTR);
103
104 /**
105 * Destroys the ResourceInstance and notifies the system
106 * that the resource has been closed
107 */
108 ~ResourceInstance();
109
110public Q_SLOTS:
111 /**
112 * Call this method to notify the system that you modified
113 * (the contents of) the resource
114 */
115 void notifyModified();
116
117 /**
118 * Call this method to notify the system that the resource
119 * has the focus in your application
120 * @note You only need to call this in MDI applications
121 */
122 void notifyFocusedIn();
123
124 /**
125 * Call this method to notify the system that the resource
126 * lost the focus in your application
127 * @note You only need to call this in MDI applications
128 */
129 void notifyFocusedOut();
130
131 /**
132 * This is a convenience method that sets the new URI.
133 * This is usually handled by sending the close event for
134 * the previous URI, and an open event for the new one.
135 */
136 void setUri(const QUrl &newUri);
137
138 /**
139 * Sets the mimetype for this resource
140 */
141 void setMimetype(const QString &mimetype);
142
143 /**
144 * Sets the title for this resource
145 */
146 void setTitle(const QString &title);
147
148Q_SIGNALS:
149 /**
150 * Emitted when the system wants to show the resource
151 * represented by this ResourceInstance.
152 *
153 * You should listen to this signal if you have multiple
154 * resources shown in one window (MDI). On catching it, show
155 * the resource and give it focus.
156 */
157 void requestsFocus();
158
159public:
160 /**
161 * @returns the current uri
162 * The default implementation returns the URI that was passed
163 * to the constructor.
164 * You need to reimplement it only for the applications with
165 * frequently updated URIs.
166 */
167 virtual QUrl uri() const;
168
169 /**
170 * @returns mimetype of the resource
171 */
172 QString mimetype() const;
173
174 /**
175 * @returns title of the resource
176 */
177 QString title() const;
178
179 /**
180 * @returns the window id
181 */
182 quintptr winId() const;
183
184 /**
185 * If there's no way to tell for how long an application is keeping
186 * the resource open, you can just call this static method - it
187 * will notify the system that the application has accessed the
188 * resource
189 * @param uri URI of the resource
190 * @param application application's name (the name used for the .desktop file).
191 * If not specified, QCoreApplication::applicationName is used
192 *
193 */
194 static void notifyAccessed(const QUrl &uri, const QString &application = QString());
195
196private:
197 const QScopedPointer<ResourceInstancePrivate> d;
198};
199}
200
201#endif // ACTIVITIES_RESOURCEINSTANCE_H
202