KDELibs4Support

kapplication.h
1 /* This file is part of the KDE libraries
2  Copyright (C) 1997 Matthias Kalle Dalheimer ([email protected])
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 #include <kdelibs4support_export.h>
26 
27 #ifdef KDELIBS4SUPPORT_NO_DEPRECATED_NOISE
28 #warning "This file is deprecated."
29 #endif
30 
31 class KConfig;
32 
33 #ifdef KDE3_SUPPORT
34 #include <krandom.h>
35 #include <kcmdlineargs.h>
36 #include <kiconloader.h>
37 #include <QPixmap>
38 #include <QIcon>
39 #endif
40 
41 typedef unsigned long Atom;
42 #include <qplatformdefs.h>
43 
44 #include <QApplication>
45 #include <kcomponentdata.h>
46 
47 struct _IceConn;
48 class QPixmap;
49 
50 #define kapp KApplication::kApplication()
51 
52 class KApplicationPrivate;
53 
54 /**
55 * Controls and provides information to all KDE applications.
56 *
57 * Only one object of this class can be instantiated in a single app.
58 * This instance is always accessible via the 'kapp' global variable.
59 *
60 * This class provides the following services to all KDE applications.
61 *
62 * @li It controls the event queue (see QApplication ).
63 * @li It provides the application with KDE resources such as
64 * accelerators, common menu entries, a KConfig object. session
65 * management events, help invocation etc.
66 * @li Installs an empty signal handler for the SIGPIPE signal.
67 * If you want to catch this signal
68 * yourself, you have set a new signal handler after KApplication's
69 * constructor has run.
70 * @li It can start new services
71 *
72 *
73 * @short Controls and provides information to all KDE applications.
74 * @author Matthias Kalle Dalheimer <[email protected]>
75 */
76 class KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE KApplication : public QApplication
77 {
78  Q_OBJECT
79  Q_CLASSINFO("D-Bus Interface", "org.kde.KApplication")
80 public:
81  /**
82  * This constructor is the one you should use.
83  * It takes aboutData and command line arguments from KCmdLineArgs.
84  *
85  * @param GUIenabled Set to false to disable all GUI stuff.
86  * Note that for a non-GUI daemon, you might want to use QCoreApplication
87  * and a KComponentData instance instead. You'll save an unnecessary dependency
88  * to kdeui. The main difference is that you will have to do a number of things yourself:
89  * <ul>
90  * <li>Register to DBus, if necessary.</li>
91  * <li>Call KLocale::global(), if using multiple threads.</li>
92  * </ul>
93  */
94  KDELIBS4SUPPORT_DEPRECATED explicit KApplication(bool GUIenabled = true);
95 
96  ~KApplication() override;
97 
98  /**
99  * Returns the current application object.
100  *
101  * This is similar to the global QApplication pointer qApp. It
102  * allows access to the single global KApplication object, since
103  * more than one cannot be created in the same application. It
104  * saves you the trouble of having to pass the pointer explicitly
105  * to every function that may require it.
106  * @return the current application object
107  */
108  static KApplication *kApplication();
109 
110  /**
111  * @deprecated
112  * Returns the application session config object.
113  *
114  * @return A pointer to the application's instance specific
115  * KConfig object.
116  * @see KConfigGui::sessionConfig
117  */
118  KConfig *sessionConfig();
119 
120 #ifdef KDE3_SUPPORT
121  /**
122  * Is the application restored from the session manager?
123  *
124  * @return If true, this application was restored by the session manager.
125  * Note that this may mean the config object returned by
126  * sessionConfig() contains data saved by a session closedown.
127  * @see sessionConfig()
128  * @deprecated use qApp->isSessionRestored()
129  */
130  inline KDELIBS4SUPPORT_DEPRECATED bool isRestored() const
131  {
133  }
134 #endif
135 
136  /**
137  * Disables session management for this application.
138  *
139  * Useful in case your application is started by the
140  * initial "startkde" script.
141  *
142  * @deprecated, use qunsetenv("SESSION_MANAGER") (X11-specific) or
143  * @code
144  auto disableSessionManagement = [](QSessionManager &sm) {
145  sm.setRestartHint(QSessionManager::RestartNever);
146  };
147  QObject::connect(qApp, &QGuiApplication::commitDataRequest, disableSessionManagement);
148  QObject::connect(qApp, &QGuiApplication::saveStateRequest, disableSessionManagement);
149  * @endcode
150  * TODO: contribute a QGuiApplication::disableSessionManagement() method
151  */
152  void disableSessionManagement();
153 
154  /**
155  * Enables session management for this application, formerly
156  * disabled by calling disableSessionManagement(). You usually
157  * shouldn't call this function, as session management is enabled
158  * by default.
159  */
160  void enableSessionManagement();
161 
162  /**
163  * @deprecated since 5.0, use QGuiApplication::isSavingSession()
164  *
165  * Returns true if the application is currently saving its session
166  * data (most probably before KDE logout). This is intended for use
167  * mainly in KMainWindow::queryClose() and KMainWindow::queryExit().
168  *
169  * @see KMainWindow::queryClose
170  * @see KMainWindow::queryExit
171  */
172  bool sessionSaving() const;
173 
174 #ifdef KDE3_SUPPORT
175  /**
176  * Returns a QPixmap with the application icon.
177  * @return the application icon
178  * @deprecated Use QApplication::windowIcon()
179  */
180  inline KDELIBS4SUPPORT_DEPRECATED QPixmap icon() const
181  {
182  int size = IconSize(KIconLoader::Desktop);
183  return windowIcon().pixmap(size, size);
184  }
185 
186  /**
187  * Returns the mini-icon for the application as a QPixmap.
188  * @return the application's mini icon
189  * @deprecated Use QApplication::windowIcon()
190  */
191  inline KDELIBS4SUPPORT_DEPRECATED QPixmap miniIcon() const
192  {
193  int size = IconSize(KIconLoader::Small);
194  return windowIcon().pixmap(size, size);
195  }
196 #endif
197 
198  /**
199  * Sets the top widget of the application.
200  * This means basically applying the right window caption.
201  * An application may have several top widgets. You don't
202  * need to call this function manually when using KMainWindow.
203  *
204  * @param topWidget A top widget of the application.
205  *
206  * @see icon(), caption()
207  * @deprecated since 5.0. This was doing two things: 1) setting the window title to
208  * include the appname; Qt now takes care of that on platforms where this is wanted.
209  * 2) setting the window startup ID, which Qt should take care of in the future.
210  * -> simply remove this call.
211  */
212  void setTopWidget(QWidget *topWidget);
213 
214  /**
215  * Get a file name in order to make a temporary copy of your document.
216  *
217  * @param pFilename The full path to the current file of your
218  * document.
219  * @return A new filename for auto-saving.
220  * @deprecated use QTemporaryFile, QSaveFile or KAutoSaveFile instead
221  */
222 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED
223  static KDELIBS4SUPPORT_DEPRECATED QString tempSaveName(const QString &pFilename);
224 #endif
225 
226  /**
227  * Check whether an auto-save file exists for the document you want to
228  * open.
229  *
230  * @param pFilename The full path to the document you want to open.
231  * @param bRecover This gets set to true if there was a recover
232  * file.
233  * @return The full path of the file to open.
234  */
235  static QString checkRecoverFile(const QString &pFilename, bool &bRecover);
236 
237  /**
238  * @deprecated since 5.0, use QCoreApplication::installNativeEventFilter
239  * Installs widget filter as global X11 event filter.
240  *
241  * The widget
242  * filter receives XEvents in its standard QWidget::x11Event() function.
243  *
244  * Warning: Only do this when absolutely necessary. An installed X11 filter
245  * can slow things down.
246  */
247  void installX11EventFilter(QWidget *filter);
248 
249  /**
250  * @deprecated since 5.0, use QCoreApplication::removeNativeEventFilter
251  * Removes global X11 event filter previously installed by
252  * installX11EventFilter().
253  */
254  void removeX11EventFilter(const QWidget *filter);
255 
256 #ifdef KDE3_SUPPORT
257  /**
258  * Generates a uniform random number.
259  * @return A truly unpredictable number in the range [0, RAND_MAX)
260  * @deprecated Use KRandom::random()
261  */
262  static inline KDELIBS4SUPPORT_DEPRECATED int random()
263  {
264  return KRandom::random();
265  }
266 
267  /**
268  * Generates a random string. It operates in the range [A-Za-z0-9]
269  * @param length Generate a string of this length.
270  * @return the random string
271  * @deprecated use KRandom::randomString() instead.
272  */
273  static inline KDELIBS4SUPPORT_DEPRECATED QString randomString(int length)
274  {
275  return KRandom::randomString(length);
276  }
277 #endif
278 
279  /**
280  * @deprecated
281  * Returns the app startup notification identifier for this running
282  * application.
283  * @return the startup notification identifier
284  * @see KStartupInfo::startupId
285  */
286  QByteArray startupId() const;
287 
288  /**
289  * @internal
290  * @deprecated
291  * Sets a new value for the application startup notification window property for newly
292  * created toplevel windows.
293  * @param startup_id the startup notification identifier
294  * @see KStartupInfo::setStartupId
295  * @see KStartupInfo::setNewStartupId
296  */
297  void setStartupId(const QByteArray &startup_id);
298  /**
299  * @internal
300  * Used only by KStartupId.
301  */
302  void clearStartupId();
303 
304  /**
305  * @deprecated
306  * Returns the last user action timestamp or 0 if no user activity has taken place yet.
307  * @see updateuserTimestamp
308  * @see KUserTimestamp::userTimestamp
309  */
310  unsigned long userTimestamp() const;
311 
312  /**
313  * Updates the last user action timestamp in the application registered to DBUS with id service
314  * to the given time, or to this application's user time, if 0 is given.
315  * Use before causing user interaction in the remote application, e.g. invoking a dialog
316  * in the application using a DCOP call.
317  * Consult focus stealing prevention section in kdebase/kwin/README.
318  */
319  void updateRemoteUserTimestamp(const QString &service, int time = 0);
320 
321 #ifdef KDE3_SUPPORT
322  /**
323  * Returns the argument to --geometry if any, so the geometry can be set
324  * wherever necessary
325  * @return the geometry argument, or QString() if there is none
326  * @deprecated please use the following code instead:
327  *
328  * <code>
329  * QString geometry;
330  * KCmdLineArgs *args = KCmdLineArgs::parsedArgs("kde");
331  * if (args && args->isSet("geometry"))
332  * geometry = args->getOption("geometry");
333  *
334  * </code>
335  */
336  static inline KDELIBS4SUPPORT_DEPRECATED QString geometryArgument()
337  {
338  KCmdLineArgs *args = KCmdLineArgs::parsedArgs("kde");
339  return args->isSet("geometry") ? args->getOption("geometry") : QString();
340  }
341 #endif
342 
343 public Q_SLOTS:
344  /**
345  * @deprecated
346  * Updates the last user action timestamp to the given time, or to the current time,
347  * if 0 is given. Do not use unless you're really sure what you're doing.
348  * Consult focus stealing prevention section in kdebase/kwin/README.
349  * @see KUserTimestamp::updateUserTimestamp
350  */
351  Q_SCRIPTABLE void updateUserTimestamp(int time = 0);
352 
353  /**
354  * Slot connected to QGuiApplication::commitDataRequest() to implement highlevel
355  * handling of session management with KSessionManager.
356  * @internal
357  */
358  void commitData(QSessionManager &sm);
359 
360  /**
361  * Slot connected to QGuiApplication::saveStateRequest() to implement highlevel
362  * handling of session management with KSessionManager.
363  * @internal
364  */
365  void saveState(QSessionManager &sm);
366 
367 
368  // D-Bus Q_SLOTS:
369  Q_SCRIPTABLE void reparseConfiguration();
370  Q_SCRIPTABLE void quit();
371 
372 Q_SIGNALS:
373  /**
374  @deprecated since 5.0, connect to saveStateRequest instead
375 
376  Session management asks you to save the state of your application.
377 
378  This signal is provided for compatibility only. For new
379  applications, simply use KMainWindow. By reimplementing
380  KMainWindow::queryClose(), KMainWindow::saveProperties() and
381  KMainWindow::readProperties() you can simply handle session
382  management for applications with multiple toplevel windows.
383 
384  For purposes without KMainWindow, create an instance of
385  KSessionManager and reimplement the functions
386  KSessionManager::commitData() and/or
387  KSessionManager::saveState()
388 
389  If you still want to use this signal, here is what you should do:
390 
391  Connect to this signal in order to save your data. Do NOT
392  manipulate the UI in that slot, it is blocked by the session
393  manager.
394 
395  Use the sessionConfig() KConfig object to store all your
396  instance specific data.
397 
398  Do not do any closing at this point! The user may still select
399  Cancel wanting to continue working with your
400  application. Cleanups could be done after aboutToQuit().
401  */
402  void saveYourself();
403 
404 protected:
405  /**
406  * @internal Used by KUniqueApplication
407  */
408  KApplication(bool GUIenabled, const KComponentData &cData);
409 
410  /// Current application object.
411  static KApplication *KApp;
412 
413 private:
414  KApplication(const KApplication &);
415  KApplication &operator=(const KApplication &);
416 
417 private:
418  // This is to catch invalid implicit conversions
419  KApplication(bool, bool);
420 
421  friend class KApplicationPrivate;
422  KApplicationPrivate *const d;
423 
424  Q_PRIVATE_SLOT(d, void _k_x11FilterDestroyed())
425  Q_PRIVATE_SLOT(d, void _k_slot_KToolInvocation_hook(QStringList &, QByteArray &))
426 };
427 
428 #endif
429 
Controls and provides information to all KDE applications.
Definition: kapplication.h:76
Q_CLASSINFO(Name, Value)
static KCmdLineArgs * parsedArgs(const QByteArray &id=QByteArray())
Access parsed arguments.
A class for command-line argument handling.
Definition: kcmdlineargs.h:286
bool isSessionRestored() const const
static KApplication * KApp
Current application object.
Definition: kapplication.h:411
bool isSet(const QByteArray &option) const
Read out a boolean option or check for the presence of string option.
QPixmap pixmap(const QSize &size, QIcon::Mode mode, QIcon::State state) const const
KCOREADDONS_EXPORT int random()
QIcon windowIcon()
QString getOption(const QByteArray &option) const
Read out a string option.
KCOREADDONS_EXPORT QString randomString(int length)
Per component data.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Nov 28 2021 22:51:19 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.