1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 1997 Matthias Kalle Dalheimer (kalle@kde.org) |
3 | Copyright (c) 1998, 1999 KDE Team |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Library General Public |
7 | License as published by the Free Software Foundation; either |
8 | version 2 of the License, or (at your option) any later version. |
9 | |
10 | This library is distributed in the hope that it will be useful, |
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | Library General Public License for more details. |
14 | |
15 | You should have received a copy of the GNU Library General Public License |
16 | along with this library; see the file COPYING.LIB. If not, write to |
17 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
18 | Boston, MA 02110-1301, USA. |
19 | */ |
20 | |
21 | #ifndef KAPP_H |
22 | #define KAPP_H |
23 | |
24 | // Version macros. Never put this further down. |
25 | // TODO: KDE5 -#include "kdeversion.h" |
26 | #include "kdeversion.h" |
27 | #include <kdeui_export.h> |
28 | |
29 | class KConfig; |
30 | |
31 | #ifdef KDE3_SUPPORT |
32 | #include <krandom.h> |
33 | #include <kcmdlineargs.h> |
34 | #include <kiconloader.h> |
35 | #include <kicontheme.h> |
36 | #include <QtGui/QPixmap> |
37 | #include <QtGui/QIcon> |
38 | #endif |
39 | |
40 | typedef unsigned long Atom; |
41 | #if !defined(Q_WS_X11) |
42 | typedef void Display; |
43 | #endif |
44 | |
45 | #include <QtGui/QApplication> |
46 | #include <kcomponentdata.h> |
47 | #include <kglobal.h> |
48 | |
49 | #ifdef Q_WS_X11 |
50 | #include <QtGui/QX11Info> |
51 | #endif |
52 | |
53 | struct _IceConn; |
54 | class QPixmap; |
55 | |
56 | #define kapp KApplication::kApplication() |
57 | |
58 | class KApplicationPrivate; |
59 | |
60 | /** |
61 | * Controls and provides information to all KDE applications. |
62 | * |
63 | * Only one object of this class can be instantiated in a single app. |
64 | * This instance is always accessible via the 'kapp' global variable. |
65 | * |
66 | * This class provides the following services to all KDE applications. |
67 | * |
68 | * @li It controls the event queue (see QApplication ). |
69 | * @li It provides the application with KDE resources such as |
70 | * accelerators, common menu entries, a KConfig object. session |
71 | * management events, help invocation etc. |
72 | * @li Installs an empty signal handler for the SIGPIPE signal. |
73 | * If you want to catch this signal |
74 | * yourself, you have set a new signal handler after KApplication's |
75 | * constructor has run. |
76 | * @li It can start new services |
77 | * |
78 | * |
79 | * @short Controls and provides information to all KDE applications. |
80 | * @author Matthias Kalle Dalheimer <kalle@kde.org> |
81 | */ |
82 | class KDEUI_EXPORT KApplication : public QApplication |
83 | { |
84 | Q_OBJECT |
85 | Q_CLASSINFO("D-Bus Interface" , "org.kde.KApplication" ) |
86 | public: |
87 | /** |
88 | * This constructor is the one you should use. |
89 | * It takes aboutData and command line arguments from KCmdLineArgs. |
90 | * |
91 | * @param GUIenabled Set to false to disable all GUI stuff. |
92 | * Note that for a non-GUI daemon, you might want to use QCoreApplication |
93 | * and a KComponentData instance instead. You'll save an unnecessary dependency |
94 | * to kdeui. The main difference is that you will have to do a number of things yourself: |
95 | * <ul> |
96 | * <li>Register to DBus, if necessary.</li> |
97 | * <li>Call KGlobal::locale(), if using multiple threads.</li> |
98 | * </ul> |
99 | */ |
100 | explicit KApplication(bool GUIenabled = true); |
101 | |
102 | #ifdef Q_WS_X11 |
103 | /** |
104 | * Constructor. Parses command-line arguments. Use this constructor when you |
105 | * you need to use a non-default visual or colormap. |
106 | * |
107 | * @param display Will be passed to Qt as the X display. The display must be |
108 | * valid and already opened. |
109 | * |
110 | * @param visual A pointer to the X11 visual that should be used by the |
111 | * application. Note that only TrueColor visuals are supported on depths |
112 | * greater than 8 bpp. If this parameter is NULL, the default visual will |
113 | * be used instead. |
114 | * |
115 | * @param colormap The colormap that should be used by the application. If |
116 | * this parameter is 0, the default colormap will be used instead. |
117 | */ |
118 | explicit KApplication(Display *display, Qt::HANDLE visual = 0, Qt::HANDLE colormap = 0); |
119 | |
120 | /** |
121 | * Constructor. Parses command-line arguments. Use this constructor to use KApplication |
122 | * in a Motif or Xt program. |
123 | * |
124 | * @param display Will be passed to Qt as the X display. The display must be valid and already |
125 | * opened. |
126 | * |
127 | * @param argc command line argument count |
128 | * |
129 | * @param argv command line argument value(s) |
130 | * |
131 | * @param rAppName application name. Will be used for finding the |
132 | * associated message files and icon files, and as the default |
133 | * registration name for DCOP. This is a mandatory parameter. |
134 | * |
135 | * @param GUIenabled Set to false to disable all GUI stuff. |
136 | */ |
137 | KApplication(Display *display, int& argc, char** argv, const QByteArray& rAppName, |
138 | bool GUIenabled=true); |
139 | #endif |
140 | |
141 | virtual ~KApplication(); |
142 | |
143 | /** |
144 | * Returns the current application object. |
145 | * |
146 | * This is similar to the global QApplication pointer qApp. It |
147 | * allows access to the single global KApplication object, since |
148 | * more than one cannot be created in the same application. It |
149 | * saves you the trouble of having to pass the pointer explicitly |
150 | * to every function that may require it. |
151 | * @return the current application object |
152 | */ |
153 | static KApplication* kApplication(); |
154 | |
155 | /** |
156 | * Returns the application session config object. |
157 | * |
158 | * @return A pointer to the application's instance specific |
159 | * KConfig object. |
160 | * @see KConfig |
161 | */ |
162 | KConfig* sessionConfig(); |
163 | |
164 | #ifdef KDE3_SUPPORT |
165 | /** |
166 | * Is the application restored from the session manager? |
167 | * |
168 | * @return If true, this application was restored by the session manager. |
169 | * Note that this may mean the config object returned by |
170 | * sessionConfig() contains data saved by a session closedown. |
171 | * @see sessionConfig() |
172 | * @deprecated use qApp->isSessionRestored() |
173 | */ |
174 | inline KDE_DEPRECATED bool isRestored() const { return QApplication::isSessionRestored(); } |
175 | #endif |
176 | |
177 | /** |
178 | * Disables session management for this application. |
179 | * |
180 | * Useful in case your application is started by the |
181 | * initial "startkde" script. |
182 | */ |
183 | void disableSessionManagement(); |
184 | |
185 | /** |
186 | * Enables session management for this application, formerly |
187 | * disabled by calling disableSessionManagement(). You usually |
188 | * shouldn't call this function, as session management is enabled |
189 | * by default. |
190 | */ |
191 | void enableSessionManagement(); |
192 | |
193 | /** |
194 | * Reimplemented for internal purposes, mainly the highlevel |
195 | * handling of session management with KSessionManager. |
196 | * @internal |
197 | */ |
198 | void commitData( QSessionManager& sm ); |
199 | |
200 | /** |
201 | * Reimplemented for internal purposes, mainly the highlevel |
202 | * handling of session management with KSessionManager. |
203 | * @internal |
204 | */ |
205 | void saveState( QSessionManager& sm ); |
206 | |
207 | /** |
208 | * Returns true if the application is currently saving its session |
209 | * data (most probably before KDE logout). This is intended for use |
210 | * mainly in KMainWindow::queryClose() and KMainWindow::queryExit(). |
211 | * |
212 | * @see KMainWindow::queryClose |
213 | * @see KMainWindow::queryExit |
214 | */ |
215 | bool sessionSaving() const; |
216 | |
217 | #ifdef KDE3_SUPPORT |
218 | /** |
219 | * Returns a QPixmap with the application icon. |
220 | * @return the application icon |
221 | * @deprecated Use QApplication::windowIcon() |
222 | */ |
223 | inline KDE_DEPRECATED QPixmap icon() const { |
224 | int size = IconSize(KIconLoader::Desktop); |
225 | return windowIcon().pixmap(size,size); |
226 | } |
227 | |
228 | /** |
229 | * Returns the mini-icon for the application as a QPixmap. |
230 | * @return the application's mini icon |
231 | * @deprecated Use QApplication::windowIcon() |
232 | */ |
233 | inline KDE_DEPRECATED QPixmap miniIcon() const { |
234 | int size = IconSize(KIconLoader::Small); |
235 | return windowIcon().pixmap(size,size); |
236 | } |
237 | #endif |
238 | |
239 | /** |
240 | * Sets the top widget of the application. |
241 | * This means basically applying the right window caption. |
242 | * An application may have several top widgets. You don't |
243 | * need to call this function manually when using KMainWindow. |
244 | * |
245 | * @param topWidget A top widget of the application. |
246 | * |
247 | * @see icon(), caption() |
248 | **/ |
249 | void setTopWidget( QWidget *topWidget ); |
250 | |
251 | /** |
252 | * Get a file name in order to make a temporary copy of your document. |
253 | * |
254 | * @param pFilename The full path to the current file of your |
255 | * document. |
256 | * @return A new filename for auto-saving. |
257 | * @deprecated use KTemporaryFile, KSaveFile or KAutoSaveFile instead |
258 | */ |
259 | #ifndef KDE_NO_DEPRECATED |
260 | static KDE_DEPRECATED QString tempSaveName( const QString& pFilename ); |
261 | #endif |
262 | |
263 | /** |
264 | * Check whether an auto-save file exists for the document you want to |
265 | * open. |
266 | * |
267 | * @param pFilename The full path to the document you want to open. |
268 | * @param bRecover This gets set to true if there was a recover |
269 | * file. |
270 | * @return The full path of the file to open. |
271 | */ |
272 | static QString checkRecoverFile( const QString& pFilename, bool& bRecover ); |
273 | |
274 | #ifdef KDE3_SUPPORT |
275 | #ifdef Q_WS_X11 |
276 | /** |
277 | * Get the X11 display |
278 | * @return the X11 Display |
279 | * @deprecated use QX11Info::display() |
280 | */ |
281 | static inline KDE_DEPRECATED Display *getDisplay() { return QX11Info::display(); } |
282 | #endif |
283 | #endif |
284 | |
285 | /** |
286 | * Installs widget filter as global X11 event filter. |
287 | * |
288 | * The widget |
289 | * filter receives XEvents in its standard QWidget::x11Event() function. |
290 | * |
291 | * Warning: Only do this when absolutely necessary. An installed X11 filter |
292 | * can slow things down. |
293 | **/ |
294 | void installX11EventFilter( QWidget* filter ); |
295 | |
296 | /** |
297 | * Removes global X11 event filter previously installed by |
298 | * installX11EventFilter(). |
299 | */ |
300 | void removeX11EventFilter( const QWidget* filter ); |
301 | |
302 | #ifdef KDE3_SUPPORT |
303 | /** |
304 | * Generates a uniform random number. |
305 | * @return A truly unpredictable number in the range [0, RAND_MAX) |
306 | * @deprecated Use KRandom::random() |
307 | */ |
308 | static inline KDE_DEPRECATED int random() { return KRandom::random(); } |
309 | |
310 | /** |
311 | * Generates a random string. It operates in the range [A-Za-z0-9] |
312 | * @param length Generate a string of this length. |
313 | * @return the random string |
314 | * @deprecated use KRandom::randomString() instead. |
315 | */ |
316 | static inline KDE_DEPRECATED QString randomString(int length) { return KRandom::randomString(length); } |
317 | #endif |
318 | |
319 | /** |
320 | * Returns the app startup notification identifier for this running |
321 | * application. |
322 | * @return the startup notification identifier |
323 | */ |
324 | QByteArray startupId() const; |
325 | |
326 | /** |
327 | * @internal |
328 | * Sets a new value for the application startup notification window property for newly |
329 | * created toplevel windows. |
330 | * @param startup_id the startup notification identifier |
331 | * @see KStartupInfo::setNewStartupId |
332 | */ |
333 | void setStartupId( const QByteArray& startup_id ); |
334 | /** |
335 | * @internal |
336 | * Used only by KStartupId. |
337 | */ |
338 | void clearStartupId(); |
339 | |
340 | /** |
341 | * Sets how the primary and clipboard selections are synchronized in an X11 environment |
342 | */ |
343 | void setSynchronizeClipboard(bool synchronize); |
344 | |
345 | /** |
346 | * Returns the last user action timestamp or 0 if no user activity has taken place yet. |
347 | * @see updateuserTimestamp |
348 | */ |
349 | unsigned long userTimestamp() const; |
350 | |
351 | /** |
352 | * Updates the last user action timestamp in the application registered to DBUS with id service |
353 | * to the given time, or to this application's user time, if 0 is given. |
354 | * Use before causing user interaction in the remote application, e.g. invoking a dialog |
355 | * in the application using a DCOP call. |
356 | * Consult focus stealing prevention section in kdebase/kwin/README. |
357 | */ |
358 | void updateRemoteUserTimestamp( const QString& service, int time = 0 ); |
359 | |
360 | #ifdef KDE3_SUPPORT |
361 | /** |
362 | * Returns the argument to --geometry if any, so the geometry can be set |
363 | * wherever necessary |
364 | * @return the geometry argument, or QString() if there is none |
365 | * @deprecated please use the following code instead: |
366 | * |
367 | * <code> |
368 | * QString geometry; |
369 | * KCmdLineArgs *args = KCmdLineArgs::parsedArgs("kde"); |
370 | * if (args && args->isSet("geometry")) |
371 | * geometry = args->getOption("geometry"); |
372 | * |
373 | * </code> |
374 | */ |
375 | static inline KDE_DEPRECATED QString geometryArgument() { |
376 | KCmdLineArgs *args = KCmdLineArgs::parsedArgs("kde" ); |
377 | return args->isSet("geometry" ) ? args->getOption("geometry" ) : QString(); |
378 | } |
379 | #endif |
380 | |
381 | /** |
382 | @internal |
383 | */ |
384 | bool notify( QObject* receiver, QEvent* event ); |
385 | |
386 | /** |
387 | @internal |
388 | */ |
389 | int xErrhandler( Display*, void* ); |
390 | |
391 | /** |
392 | @internal |
393 | */ |
394 | int xioErrhandler( Display* ); |
395 | |
396 | /** |
397 | * @internal |
398 | */ |
399 | void iceIOErrorHandler( _IceConn *conn ); |
400 | |
401 | /** |
402 | * @internal |
403 | */ |
404 | static bool loadedByKdeinit; |
405 | |
406 | public Q_SLOTS: |
407 | /** |
408 | * Updates the last user action timestamp to the given time, or to the current time, |
409 | * if 0 is given. Do not use unless you're really sure what you're doing. |
410 | * Consult focus stealing prevention section in kdebase/kwin/README. |
411 | */ |
412 | Q_SCRIPTABLE void updateUserTimestamp( int time = 0 ); |
413 | |
414 | // D-Bus slots: |
415 | Q_SCRIPTABLE void reparseConfiguration(); |
416 | Q_SCRIPTABLE void quit(); |
417 | |
418 | Q_SIGNALS: |
419 | /** |
420 | Session management asks you to save the state of your application. |
421 | |
422 | This signal is provided for compatibility only. For new |
423 | applications, simply use KMainWindow. By reimplementing |
424 | KMainWindow::queryClose(), KMainWindow::saveProperties() and |
425 | KMainWindow::readProperties() you can simply handle session |
426 | management for applications with multiple toplevel windows. |
427 | |
428 | For purposes without KMainWindow, create an instance of |
429 | KSessionManager and reimplement the functions |
430 | KSessionManager::commitData() and/or |
431 | KSessionManager::saveState() |
432 | |
433 | If you still want to use this signal, here is what you should do: |
434 | |
435 | Connect to this signal in order to save your data. Do NOT |
436 | manipulate the UI in that slot, it is blocked by the session |
437 | manager. |
438 | |
439 | Use the sessionConfig() KConfig object to store all your |
440 | instance specific data. |
441 | |
442 | Do not do any closing at this point! The user may still select |
443 | Cancel wanting to continue working with your |
444 | application. Cleanups could be done after aboutToQuit(). |
445 | */ |
446 | void saveYourself(); |
447 | |
448 | protected: |
449 | /** |
450 | * @internal Used by KUniqueApplication |
451 | */ |
452 | KApplication(bool GUIenabled, const KComponentData &cData); |
453 | |
454 | #ifdef Q_WS_X11 |
455 | /** |
456 | * @internal Used by KUniqueApplication |
457 | */ |
458 | KApplication(Display *display, Qt::HANDLE visual, Qt::HANDLE colormap, |
459 | const KComponentData &cData); |
460 | |
461 | /** |
462 | * Used to catch X11 events |
463 | */ |
464 | bool x11EventFilter( XEvent * ); |
465 | #endif |
466 | |
467 | /// Current application object. |
468 | static KApplication *KApp; |
469 | |
470 | private: |
471 | KApplication(const KApplication&); |
472 | KApplication& operator=(const KApplication&); |
473 | |
474 | private: |
475 | //### KDE4: This is to catch invalid implicit conversions, may want to reconsider |
476 | KApplication(bool, bool); |
477 | |
478 | friend class KApplicationPrivate; |
479 | KApplicationPrivate* const d; |
480 | |
481 | Q_PRIVATE_SLOT(d, void _k_x11FilterDestroyed()) |
482 | Q_PRIVATE_SLOT(d, void _k_checkAppStartedSlot()) |
483 | Q_PRIVATE_SLOT(d, void _k_slot_KToolInvocation_hook(QStringList&, QByteArray&)) |
484 | }; |
485 | |
486 | #endif |
487 | |
488 | |