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 | |
28 | namespace KActivities { |
29 | |
30 | class 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 | */ |
52 | class 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 | |
60 | public: |
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 | |
110 | public 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 | |
148 | Q_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 | |
159 | public: |
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 | |
196 | private: |
197 | const QScopedPointer<ResourceInstancePrivate> d; |
198 | }; |
199 | } |
200 | |
201 | #endif // ACTIVITIES_RESOURCEINSTANCE_H |
202 | |