File indexing completed on 2021-12-21 12:33:57

0001 /* This file is part of the KDE libraries
0002     Copyright (C) 1997 Matthias Kalle Dalheimer (kalle@kde.org)
0003     Copyright (c) 1998, 1999 KDE Team
0004 
0005     This library is free software; you can redistribute it and/or
0006     modify it under the terms of the GNU Library General Public
0007     License as published by the Free Software Foundation; either
0008     version 2 of the License, or (at your option) any later version.
0009 
0010     This library is distributed in the hope that it will be useful,
0011     but WITHOUT ANY WARRANTY; without even the implied warranty of
0012     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0013     Library General Public License for more details.
0014 
0015     You should have received a copy of the GNU Library General Public License
0016     along with this library; see the file COPYING.LIB.  If not, write to
0017     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0018     Boston, MA 02110-1301, USA.
0019 */
0020 
0021 #ifndef KAPP_H
0022 #define KAPP_H
0023 
0024 // Version macros. Never put this further down.
0025 #include <kdelibs4support_export.h>
0026 
0027 #ifdef KDELIBS4SUPPORT_NO_DEPRECATED_NOISE
0028 #warning "This file is deprecated."
0029 #endif
0030 
0031 class KConfig;
0032 
0033 #ifdef KDE3_SUPPORT
0034 #include <krandom.h>
0035 #include <kcmdlineargs.h>
0036 #include <kiconloader.h>
0037 #include <QPixmap>
0038 #include <QIcon>
0039 #endif
0040 
0041 typedef unsigned long Atom;
0042 #include <qplatformdefs.h>
0043 
0044 #include <QApplication>
0045 #include <kcomponentdata.h>
0046 
0047 struct _IceConn;
0048 class QPixmap;
0049 
0050 #define kapp KApplication::kApplication()
0051 
0052 class KApplicationPrivate;
0053 
0054 /**
0055 * Controls and provides information to all KDE applications.
0056 *
0057 * Only one object of this class can be instantiated in a single app.
0058 * This instance is always accessible via the 'kapp' global variable.
0059 *
0060 * This class provides the following services to all KDE applications.
0061 *
0062 * @li It controls the event queue (see QApplication ).
0063 * @li It provides the application with KDE resources such as
0064 * accelerators, common menu entries, a KConfig object. session
0065 * management events, help invocation etc.
0066 * @li Installs an empty signal handler for the SIGPIPE signal.
0067 * If you want to catch this signal
0068 * yourself, you have set a new signal handler after KApplication's
0069 * constructor has run.
0070 * @li It can start new services
0071 *
0072 *
0073 * @short Controls and provides information to all KDE applications.
0074 * @author Matthias Kalle Dalheimer <kalle@kde.org>
0075 */
0076 class KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE KApplication : public QApplication
0077 {
0078     Q_OBJECT
0079     Q_CLASSINFO("D-Bus Interface", "org.kde.KApplication")
0080 public:
0081     /**
0082      * This constructor is the one you should use.
0083      * It takes aboutData and command line arguments from KCmdLineArgs.
0084      *
0085      * @param GUIenabled Set to false to disable all GUI stuff.
0086      * Note that for a non-GUI daemon, you might want to use QCoreApplication
0087      * and a KComponentData instance instead. You'll save an unnecessary dependency
0088      * to kdeui. The main difference is that you will have to do a number of things yourself:
0089      * <ul>
0090      *  <li>Register to DBus, if necessary.</li>
0091      *  <li>Call KLocale::global(), if using multiple threads.</li>
0092      * </ul>
0093      */
0094     KDELIBS4SUPPORT_DEPRECATED explicit KApplication(bool GUIenabled = true);
0095 
0096     ~KApplication() override;
0097 
0098     /**
0099      * Returns the current application object.
0100      *
0101      * This is similar to the global QApplication pointer qApp. It
0102      * allows access to the single global KApplication object, since
0103      * more than one cannot be created in the same application. It
0104      * saves you the trouble of having to pass the pointer explicitly
0105      * to every function that may require it.
0106      * @return the current application object
0107      */
0108     static KApplication *kApplication();
0109 
0110     /**
0111      * @deprecated
0112      * Returns the application session config object.
0113      *
0114      * @return A pointer to the application's instance specific
0115      * KConfig object.
0116      * @see KConfigGui::sessionConfig
0117      */
0118     KConfig *sessionConfig();
0119 
0120 #ifdef KDE3_SUPPORT
0121     /**
0122       * Is the application restored from the session manager?
0123       *
0124       * @return If true, this application was restored by the session manager.
0125       *    Note that this may mean the config object returned by
0126       * sessionConfig() contains data saved by a session closedown.
0127       * @see sessionConfig()
0128       * @deprecated use qApp->isSessionRestored()
0129       */
0130     inline KDELIBS4SUPPORT_DEPRECATED bool isRestored() const
0131     {
0132         return QApplication::isSessionRestored();
0133     }
0134 #endif
0135 
0136     /**
0137      * Disables session management for this application.
0138      *
0139      * Useful in case  your application is started by the
0140      * initial "startkde" script.
0141      *
0142      * @deprecated, use qunsetenv("SESSION_MANAGER") (X11-specific) or
0143      * @code
0144         auto disableSessionManagement = [](QSessionManager &sm) {
0145             sm.setRestartHint(QSessionManager::RestartNever);
0146         };
0147         QObject::connect(qApp, &QGuiApplication::commitDataRequest, disableSessionManagement);
0148         QObject::connect(qApp, &QGuiApplication::saveStateRequest, disableSessionManagement);
0149      * @endcode
0150      * TODO: contribute a QGuiApplication::disableSessionManagement() method
0151      */
0152     void disableSessionManagement();
0153 
0154     /**
0155      * Enables session management for this application, formerly
0156      * disabled by calling disableSessionManagement(). You usually
0157      * shouldn't call this function, as session management is enabled
0158      * by default.
0159      */
0160     void enableSessionManagement();
0161 
0162     /**
0163      * @deprecated since 5.0, use QGuiApplication::isSavingSession()
0164      *
0165      * Returns true if the application is currently saving its session
0166      * data (most probably before KDE logout). This is intended for use
0167      * mainly in KMainWindow::queryClose() and KMainWindow::queryExit().
0168      *
0169      * @see KMainWindow::queryClose
0170      * @see KMainWindow::queryExit
0171      */
0172     bool sessionSaving() const;
0173 
0174 #ifdef KDE3_SUPPORT
0175     /**
0176      * Returns a QPixmap with the application icon.
0177      * @return the application icon
0178      * @deprecated Use QApplication::windowIcon()
0179      */
0180     inline KDELIBS4SUPPORT_DEPRECATED QPixmap icon() const
0181     {
0182         int size = IconSize(KIconLoader::Desktop);
0183         return windowIcon().pixmap(size, size);
0184     }
0185 
0186     /**
0187      * Returns the mini-icon for the application as a QPixmap.
0188      * @return the application's mini icon
0189      * @deprecated Use QApplication::windowIcon()
0190      */
0191     inline KDELIBS4SUPPORT_DEPRECATED QPixmap miniIcon() const
0192     {
0193         int size = IconSize(KIconLoader::Small);
0194         return windowIcon().pixmap(size, size);
0195     }
0196 #endif
0197 
0198     /**
0199      *  Sets the top widget of the application.
0200      *  This means basically applying the right window caption.
0201      *  An application may have several top widgets. You don't
0202      *  need to call this function manually when using KMainWindow.
0203      *
0204      *  @param topWidget A top widget of the application.
0205      *
0206      *  @see icon(), caption()
0207      * @deprecated since 5.0. This was doing two things: 1) setting the window title to
0208      * include the appname; Qt now takes care of that on platforms where this is wanted.
0209      * 2) setting the window startup ID, which Qt should take care of in the future.
0210      * -> simply remove this call.
0211      */
0212     void setTopWidget(QWidget *topWidget);
0213 
0214     /**
0215      * Get a file name in order to make a temporary copy of your document.
0216      *
0217      * @param pFilename The full path to the current file of your
0218      * document.
0219      * @return A new filename for auto-saving.
0220      * @deprecated use QTemporaryFile, QSaveFile or KAutoSaveFile instead
0221      */
0222 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED
0223     static KDELIBS4SUPPORT_DEPRECATED QString tempSaveName(const QString &pFilename);
0224 #endif
0225 
0226     /**
0227      * Check whether  an auto-save file exists for the document you want to
0228      * open.
0229      *
0230      * @param pFilename The full path to the document you want to open.
0231      * @param bRecover  This gets set to true if there was a recover
0232      * file.
0233      * @return The full path of the file to open.
0234      */
0235     static QString checkRecoverFile(const QString &pFilename, bool &bRecover);
0236 
0237     /**
0238      * @deprecated since 5.0, use QCoreApplication::installNativeEventFilter
0239      *  Installs widget filter as global X11 event filter.
0240      *
0241      * The widget
0242      *  filter receives XEvents in its standard QWidget::x11Event() function.
0243      *
0244      *  Warning: Only do this when absolutely necessary. An installed X11 filter
0245      *  can slow things down.
0246      */
0247     void installX11EventFilter(QWidget *filter);
0248 
0249     /**
0250      * @deprecated since 5.0, use QCoreApplication::removeNativeEventFilter
0251      * Removes global X11 event filter previously installed by
0252      * installX11EventFilter().
0253      */
0254     void removeX11EventFilter(const QWidget *filter);
0255 
0256 #ifdef KDE3_SUPPORT
0257     /**
0258      * Generates a uniform random number.
0259      * @return A truly unpredictable number in the range [0, RAND_MAX)
0260      * @deprecated Use KRandom::random()
0261      */
0262     static inline KDELIBS4SUPPORT_DEPRECATED int random()
0263     {
0264         return KRandom::random();
0265     }
0266 
0267     /**
0268      * Generates a random string.  It operates in the range [A-Za-z0-9]
0269      * @param length Generate a string of this length.
0270      * @return the random string
0271      * @deprecated use KRandom::randomString() instead.
0272      */
0273     static inline KDELIBS4SUPPORT_DEPRECATED QString randomString(int length)
0274     {
0275         return KRandom::randomString(length);
0276     }
0277 #endif
0278 
0279     /**
0280      * @deprecated
0281      * Returns the app startup notification identifier for this running
0282      * application.
0283      * @return the startup notification identifier
0284      * @see KStartupInfo::startupId
0285      */
0286     QByteArray startupId() const;
0287 
0288     /**
0289      * @internal
0290      * @deprecated
0291      * Sets a new value for the application startup notification window property for newly
0292      * created toplevel windows.
0293      * @param startup_id the startup notification identifier
0294      * @see KStartupInfo::setStartupId
0295      * @see KStartupInfo::setNewStartupId
0296      */
0297     void setStartupId(const QByteArray &startup_id);
0298     /**
0299      * @internal
0300      * Used only by KStartupId.
0301      */
0302     void clearStartupId();
0303 
0304     /**
0305      * @deprecated
0306      * Returns the last user action timestamp or 0 if no user activity has taken place yet.
0307      * @see updateuserTimestamp
0308      * @see KUserTimestamp::userTimestamp
0309      */
0310     unsigned long userTimestamp() const;
0311 
0312     /**
0313      * Updates the last user action timestamp in the application registered to DBUS with id service
0314      * to the given time, or to this application's user time, if 0 is given.
0315      * Use before causing user interaction in the remote application, e.g. invoking a dialog
0316      * in the application using a DCOP call.
0317      * Consult focus stealing prevention section in kdebase/kwin/README.
0318      */
0319     void updateRemoteUserTimestamp(const QString &service, int time = 0);
0320 
0321 #ifdef KDE3_SUPPORT
0322     /**
0323     * Returns the argument to --geometry if any, so the geometry can be set
0324     * wherever necessary
0325     * @return the geometry argument, or QString() if there is none
0326     * @deprecated please use the following code instead:
0327     *
0328     * <code>
0329     * QString geometry;
0330     * KCmdLineArgs *args = KCmdLineArgs::parsedArgs("kde");
0331     * if (args && args->isSet("geometry"))
0332     *     geometry = args->getOption("geometry");
0333     *
0334     * </code>
0335     */
0336     static inline KDELIBS4SUPPORT_DEPRECATED QString geometryArgument()
0337     {
0338         KCmdLineArgs *args = KCmdLineArgs::parsedArgs("kde");
0339         return args->isSet("geometry") ? args->getOption("geometry") : QString();
0340     }
0341 #endif
0342 
0343 public Q_SLOTS:
0344     /**
0345      * @deprecated
0346      * Updates the last user action timestamp to the given time, or to the current time,
0347      * if 0 is given. Do not use unless you're really sure what you're doing.
0348      * Consult focus stealing prevention section in kdebase/kwin/README.
0349      * @see KUserTimestamp::updateUserTimestamp
0350      */
0351     Q_SCRIPTABLE void updateUserTimestamp(int time = 0);
0352 
0353     /**
0354      * Slot connected to QGuiApplication::commitDataRequest() to implement highlevel
0355      *  handling of session management with KSessionManager.
0356      * @internal
0357      */
0358     void commitData(QSessionManager &sm);
0359 
0360     /**
0361      * Slot connected to QGuiApplication::saveStateRequest() to implement highlevel
0362      *  handling of session management with KSessionManager.
0363      * @internal
0364      */
0365     void saveState(QSessionManager &sm);
0366 
0367 
0368     // D-Bus Q_SLOTS:
0369     Q_SCRIPTABLE void reparseConfiguration();
0370     Q_SCRIPTABLE void quit();
0371 
0372 Q_SIGNALS:
0373     /**
0374        @deprecated since 5.0, connect to saveStateRequest instead
0375 
0376        Session management asks you to save the state of your application.
0377 
0378        This signal is provided for compatibility only. For new
0379        applications, simply use KMainWindow. By reimplementing
0380        KMainWindow::queryClose(), KMainWindow::saveProperties() and
0381        KMainWindow::readProperties() you can simply handle session
0382        management for applications with multiple toplevel windows.
0383 
0384        For purposes without KMainWindow, create an instance of
0385        KSessionManager and reimplement the functions
0386        KSessionManager::commitData() and/or
0387        KSessionManager::saveState()
0388 
0389        If you still want to use this signal, here is what you should do:
0390 
0391        Connect to this signal in order to save your data. Do NOT
0392        manipulate the UI in that slot, it is blocked by the session
0393        manager.
0394 
0395        Use the sessionConfig() KConfig object to store all your
0396        instance specific data.
0397 
0398        Do not do any closing at this point! The user may still select
0399        Cancel  wanting to continue working with your
0400        application. Cleanups could be done after aboutToQuit().
0401     */
0402     void saveYourself();
0403 
0404 protected:
0405     /**
0406      * @internal Used by KUniqueApplication
0407      */
0408     KApplication(bool GUIenabled, const KComponentData &cData);
0409 
0410     /// Current application object.
0411     static KApplication *KApp;
0412 
0413 private:
0414     KApplication(const KApplication &);
0415     KApplication &operator=(const KApplication &);
0416 
0417 private:
0418     // This is to catch invalid implicit conversions
0419     KApplication(bool, bool);
0420 
0421     friend class KApplicationPrivate;
0422     KApplicationPrivate *const d;
0423 
0424     Q_PRIVATE_SLOT(d, void _k_x11FilterDestroyed())
0425     Q_PRIVATE_SLOT(d, void _k_slot_KToolInvocation_hook(QStringList &, QByteArray &))
0426 };
0427 
0428 #endif
0429