summaryrefslogtreecommitdiffstats
path: root/tdecore/kuniqueapplication.h
diff options
context:
space:
mode:
Diffstat (limited to 'tdecore/kuniqueapplication.h')
-rw-r--r--tdecore/kuniqueapplication.h221
1 files changed, 221 insertions, 0 deletions
diff --git a/tdecore/kuniqueapplication.h b/tdecore/kuniqueapplication.h
new file mode 100644
index 000000000..f5c4bcc18
--- /dev/null
+++ b/tdecore/kuniqueapplication.h
@@ -0,0 +1,221 @@
+/* This file is part of the KDE libraries
+ Copyright (c) 1999 Preston Brown <pbrown@kde.org>
+ Copyright (c) 2000-2001 Waldo Bastian <bastian@kde.org>
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Library General Public
+ License as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Library General Public License for more details.
+
+ You should have received a copy of the GNU Library General Public License
+ along with this library; see the file COPYING.LIB. If not, write to
+ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
+*/
+
+#ifndef _KUNIQUEAPP_H
+#define _KUNIQUEAPP_H
+
+#include <kapplication.h>
+#include <dcopobject.h>
+
+class KUniqueApplicationPrivate;
+
+/**
+ * Maintains only a single
+ * instance of a running application at a time.
+ *
+ * If another instance
+ * is started, it will determine (via DCOP) whether it is the first instance
+ * or a second instance. If it is a second instance, it will forward on
+ * the information to the first instance and then quit.
+ *
+ * The .desktop file for the application should state X-DCOP-ServiceType=Unique,
+ * see kapplication.h
+ *
+ * If your application is used to open files, it should also support the --tempfile
+ * option (see KCmdLineArgs::addTempFileOption()), to delete tempfiles after use.
+ * Add X-KDE-HasTempFileOption=true to the .desktop file to indicate this.
+ *
+ * @see KApplication DCOPObject
+ * @author Preston Brown <pbrown@kde.org>
+ */
+class KDECORE_EXPORT KUniqueApplication : public KApplication, public DCOPObject
+{
+ Q_OBJECT
+public:
+ /**
+ * Constructor. Takes command line arguments from KCmdLineArgs
+ *
+ * @param allowStyles Set to false to disable the loading on plugin based
+ * styles. This is only useful to applications that do not display a GUI
+ * normally. If you do create an application with @p allowStyles set to false
+ * it normally runs in the background but under special circumstances
+ * displays widgets. Call KApplication::enableStyles() before
+ * displaying any widgets.
+ * @param GUIenabled Set to false to disable all GUI stuff. This implies
+ * no styles either.
+ * @param configUnique If true, the uniqueness of the application will
+ * depend on the value of the "MultipleInstances"
+ * key in the "KDE" group of the application config file.
+ */
+ KUniqueApplication( bool allowStyles=true,
+ bool GUIenabled=true,
+ bool configUnique=false);
+
+#ifdef Q_WS_X11
+ /**
+ * Constructor. Takes command line arguments from KCmdLineArgs
+ *
+ * @param display Will be passed to Qt as the X display. The display
+ * must be valid and already opened.
+ * @param visual Pointer to the X11 visual that should be used by the
+ * application. If NULL, the default visual will be used instead.
+ * @param colormap The colormap that should be used by the application.
+ * If 0, the default colormap will be used instead.
+ * @param allowStyles Set to false to disable the loading on plugin based
+ * styles. This is only useful to applications that do not display a GUI
+ * normally. If you do create an application with @p allowStyles set to false
+ * it normally runs in the background but under special circumstances
+ * displays widgets. Call KApplication::enableStyles() before
+ * displaying any widgets.
+ * @param configUnique If true, the uniqueness of the application will
+ * depend on the value of the "MultipleInstances"
+ * key in the "KDE" group of the application config file.
+ * @since KDE 3.3
+ */
+ KUniqueApplication( Display *display,
+ Qt::HANDLE visual=0,
+ Qt::HANDLE colormap=0,
+ bool allowStyles=true,
+ bool configUnique=false);
+#endif
+
+ /**
+ * Adds command line options specific for KUniqueApplication.
+ *
+ * Should be called before calling KUniqueApplication constructor
+ * and / or start().
+ */
+ static void addCmdLineOptions();
+
+ /**
+ * Forks and registers with dcop.
+ *
+ * The command line arguments are being sent via DCOP to newInstance()
+ * and will be received once the application enters the event loop.
+ *
+ * Typically this is used like:
+ * \code
+ * int main(int argc, char **argv) {
+ * KAboutData about("myappname", "myAppName", .....);
+ * KCmdLineArgs::init(argc, argv, &about);
+ * KCmdLineArgs::addCmdLineOptions( myCmdOptions );
+ * KUniqueApplication::addCmdLineOptions();
+ *
+ * if (!KUniqueApplication::start()) {
+ * fprintf(stderr, "myAppName is already running!\n");
+ * exit(0);
+ * }
+ * KUniqueApplication a;
+ * a.exec();
+ * }
+ * \endcode
+ * Note that it's not necessary to call start() explicitly. It will be
+ * called automatically before creating KUniqueApplication if it hasn't
+ * been called yet, without any performance impact.
+ *
+ * @return true if registration is successful.
+ * false if another process was already running.
+ */
+ static bool start();
+
+ /**
+ * Destructor
+ */
+ virtual ~KUniqueApplication();
+
+ /**
+ * Dispatches any incoming DCOP message for a new instance.
+ *
+ * If it is not a request for a new instance, return false.
+ * Overloaded from DCOPObject to make sure that the application
+ * stays unique.
+ * @param fun DCOP function signature
+ * @param data the data for the arguments
+ * @param replyType the type of the reply value
+ * @param replyData the reply
+ * @see DCOPObject
+ */
+ bool process(const TQCString &fun, const TQByteArray &data,
+ TQCString &replyType, TQByteArray &replyData);
+
+ /**
+ * Creates a new "instance" of the application.
+ *
+ * Usually this will involve making some calls into the GUI portion of your
+ * application asking for a new window to be created, possibly with
+ * some data already loaded based on the arguments received.
+ *
+ * Command line arguments have been passed to KCmdLineArgs before this
+ * function is called and can be checked in the usual way.
+ *
+ * The default implementation ensures the mainwindow of the already
+ * running instance is shown and activated if necessary. You should
+ * prefer using it from your overridden method instead of doing
+ * it directly.
+ *
+ * Note that newInstance() is called also in the first started
+ * application process.
+ *
+ * @return An exit value. The calling process will exit with this value.
+ */
+ virtual int newInstance();
+
+ /**
+ * Returns whether newInstance() is being called while session
+ * restoration is in progress.
+ *
+ * @since KDE 3.3
+ */
+ bool restoringSession();
+
+ /**
+ * @internal
+ */
+ static void setHandleAutoStarted();
+
+private:
+ /**
+ * Delays the processing of a DCOP request.
+ */
+ void delayRequest(const TQCString &fun, const TQByteArray &data);
+
+private slots:
+ /**
+ * Delayed processing of DCOP requests.
+ */
+ void processDelayed();
+
+ void newInstanceNoFork();
+
+ static KInstance* initHack( bool configUnique );
+
+private:
+ static bool s_nofork;
+ static bool s_multipleInstances;
+ static bool s_uniqueTestDone;
+ static bool s_handleAutoStarted;
+
+protected:
+ virtual void virtual_hook( int id, void* data );
+private:
+ KUniqueApplicationPrivate *d;
+};
+
+#endif