1 /****************************************************************************
3 ** This file is part of a Qt Solutions component.
5 ** Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
7 ** Contact: Qt Software Information (qt-info@nokia.com)
10 ** Licensees holding valid Qt Commercial licenses may use this file in
11 ** accordance with the Qt Solutions Commercial License Agreement provided
12 ** with the Software or, alternatively, in accordance with the terms
13 ** contained in a written agreement between you and Nokia.
15 ** GNU Lesser General Public License Usage
16 ** Alternatively, this file may be used under the terms of the GNU Lesser
17 ** General Public License version 2.1 as published by the Free Software
18 ** Foundation and appearing in the file LICENSE.LGPL included in the
19 ** packaging of this file. Please review the following information to
20 ** ensure the GNU Lesser General Public License version 2.1 requirements
21 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23 ** In addition, as a special exception, Nokia gives you certain
24 ** additional rights. These rights are described in the Nokia Qt LGPL
25 ** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
28 ** GNU General Public License Usage
29 ** Alternatively, this file may be used under the terms of the GNU
30 ** General Public License version 3.0 as published by the Free Software
31 ** Foundation and appearing in the file LICENSE.GPL included in the
32 ** packaging of this file. Please review the following information to
33 ** ensure the GNU General Public License version 3.0 requirements will be
34 ** met: http://www.gnu.org/copyleft/gpl.html.
36 ** Please note Third Party Software included with Qt Solutions may impose
37 ** additional restrictions and it is the user's responsibility to ensure
38 ** that they have met the licensing requirements of the GPL, LGPL, or Qt
39 ** Solutions Commercial license and the relevant license of the Third
40 ** Party Software they are using.
42 ** If you are unsure which license is appropriate for your use, please
43 ** contact the sales department at qt-sales@nokia.com.
45 ****************************************************************************/
48 #include "qtsingleapplication.h"
49 #include "qtlocalpeer.h"
50 #include <QtGui/QWidget>
54 \class QtSingleApplication qtsingleapplication.h
55 \brief The QtSingleApplication class provides an API to detect and
56 communicate with running instances of an application.
58 This class allows you to create applications where only one
59 instance should be running at a time. I.e., if the user tries to
60 launch another instance, the already running instance will be
61 activated instead. Another usecase is a client-server system,
62 where the first started instance will assume the role of server,
63 and the later instances will act as clients of that server.
65 By default, the full path of the executable file is used to
66 determine whether two processes are instances of the same
67 application. You can also provide an explicit identifier string
68 that will be compared instead.
70 The application should create the QtSingleApplication object early
71 in the startup phase, and call isRunning() or sendMessage() to
72 find out if another instance of this application is already
73 running. Startup parameters (e.g. the name of the file the user
74 wanted this new instance to open) can be passed to the running
75 instance in the sendMessage() function.
77 If isRunning() or sendMessage() returns false, it means that no
78 other instance is running, and this instance has assumed the role
79 as the running instance. The application should continue with the
80 initialization of the application user interface before entering
81 the event loop with exec(), as normal. The messageReceived()
82 signal will be emitted when the application receives messages from
83 another instance of the same application.
85 If isRunning() or sendMessage() returns true, another instance is
86 already running, and the application should terminate or enter
89 If a message is received it might be helpful to the user to raise
90 the application so that it becomes visible. To facilitate this,
91 QtSingleApplication provides the setActivationWindow() function
92 and the activateWindow() slot.
94 Here's an example that shows how to convert an existing
95 application to use QtSingleApplication. It is very simple and does
96 not make use of all QtSingleApplication's functionality (see the
101 int main(int argc, char **argv)
103 QApplication app(argc, argv);
112 int main(int argc, char **argv)
114 QtSingleApplication app(argc, argv);
121 app.setActivationWindow(&mmw);
128 Once this QtSingleApplication instance is destroyed(for example,
129 when the user quits), when the user next attempts to run the
130 application this instance will not, of course, be encountered. The
131 next instance to call isRunning() or sendMessage() will assume the
132 role as the new running instance.
134 For console (non-GUI) applications, QtSingleCoreApplication may be
135 used instead of this class, to avoid the dependency on the QtGui
138 \sa QtSingleCoreApplication
142 void QtSingleApplication::sysInit(const QString &appId)
145 peer = new QtLocalPeer(this, appId);
146 connect(peer, SIGNAL(messageReceived(const QString&)), SIGNAL(messageReceived(const QString&)));
151 Creates a QtSingleApplication object. The application identifier
152 will be QCoreApplication::applicationFilePath(). \a argc, \a
153 argv, and \a GUIenabled are passed on to the QAppliation constructor.
155 If you are creating a console application (i.e. setting \a
156 GUIenabled to false), you may consider using
157 QtSingleCoreApplication instead.
160 QtSingleApplication::QtSingleApplication(int &argc, char **argv, bool GUIenabled)
161 : QApplication(argc, argv, GUIenabled)
168 Creates a QtSingleApplication object with the application
169 identifier \a appId. \a argc and \a argv are passed on to the
170 QAppliation constructor.
173 QtSingleApplication::QtSingleApplication(const QString &appId, int &argc, char **argv)
174 : QApplication(argc, argv)
181 Creates a QtSingleApplication object. The application identifier
182 will be QCoreApplication::applicationFilePath(). \a argc, \a
183 argv, and \a type are passed on to the QAppliation constructor.
185 QtSingleApplication::QtSingleApplication(int &argc, char **argv, Type type)
186 : QApplication(argc, argv, type)
192 #if defined(Q_WS_X11)
194 Special constructor for X11, ref. the documentation of
195 QApplication's corresponding constructor. The application identifier
196 will be QCoreApplication::applicationFilePath(). \a dpy, \a visual,
197 and \a cmap are passed on to the QApplication constructor.
199 QtSingleApplication::QtSingleApplication(Display* dpy, Qt::HANDLE visual, Qt::HANDLE cmap)
200 : QApplication(dpy, visual, cmap)
206 Special constructor for X11, ref. the documentation of
207 QApplication's corresponding constructor. The application identifier
208 will be QCoreApplication::applicationFilePath(). \a dpy, \a argc, \a
209 argv, \a visual, and \a cmap are passed on to the QApplication
212 QtSingleApplication::QtSingleApplication(Display *dpy, int &argc, char **argv, Qt::HANDLE visual, Qt::HANDLE cmap)
213 : QApplication(dpy, argc, argv, visual, cmap)
219 Special constructor for X11, ref. the documentation of
220 QApplication's corresponding constructor. The application identifier
221 will be \a appId. \a dpy, \a argc, \a
222 argv, \a visual, and \a cmap are passed on to the QApplication
225 QtSingleApplication::QtSingleApplication(Display* dpy, const QString &appId, int argc, char **argv, Qt::HANDLE visual, Qt::HANDLE cmap)
226 : QApplication(dpy, argc, argv, visual, cmap)
234 Returns true if another instance of this application is running;
237 This function does not find instances of this application that are
238 being run by a different user (on Windows: that are running in
244 bool QtSingleApplication::isRunning()
246 return peer->isClient();
251 Tries to send the text \a message to the currently running
252 instance. The QtSingleApplication object in the running instance
253 will emit the messageReceived() signal when it receives the
256 This function returns true if the message has been sent to, and
257 processed by, the current instance. If there is no instance
258 currently running, or if the running instance fails to process the
259 message within \a timeout milliseconds, this function return false.
261 \sa isRunning(), messageReceived()
263 bool QtSingleApplication::sendMessage(const QString &message, int timeout)
265 return peer->sendMessage(message, timeout);
270 Returns the application identifier. Two processes with the same
271 identifier will be regarded as instances of the same application.
273 QString QtSingleApplication::id() const
275 return peer->applicationId();
280 Sets the activation window of this application to \a aw. The
281 activation window is the widget that will be activated by
282 activateWindow(). This is typically the application's main window.
284 If \a activateOnMessage is true (the default), the window will be
285 activated automatically every time a message is received, just prior
286 to the messageReceived() signal being emitted.
288 \sa activateWindow(), messageReceived()
291 void QtSingleApplication::setActivationWindow(QWidget* aw, bool activateOnMessage)
294 if (activateOnMessage)
295 connect(peer, SIGNAL(messageReceived(const QString&)), this, SLOT(activateWindow()));
297 disconnect(peer, SIGNAL(messageReceived(const QString&)), this, SLOT(activateWindow()));
302 Returns the applications activation window if one has been set by
303 calling setActivationWindow(), otherwise returns 0.
305 \sa setActivationWindow()
307 QWidget* QtSingleApplication::activationWindow() const
314 De-minimizes, raises, and activates this application's activation window.
315 This function does nothing if no activation window has been set.
317 This is a convenience function to show the user that this
318 application instance has been activated when he has tried to start
321 This function should typically be called in response to the
322 messageReceived() signal. By default, that will happen
323 automatically, if an activation window has been set.
325 \sa setActivationWindow(), messageReceived(), initialize()
327 void QtSingleApplication::activateWindow()
330 actWin->setWindowState(actWin->windowState() & ~Qt::WindowMinimized);
332 actWin->activateWindow();
338 \fn void QtSingleApplication::messageReceived(const QString& message)
340 This signal is emitted when the current instance receives a \a
341 message from another instance of this application.
343 \sa sendMessage(), setActivationWindow(), activateWindow()
348 \fn void QtSingleApplication::initialize(bool dummy = true)