git.sur5r.net Git - minitube/blob - src/qtsingleapplication/qtsingleapplication.cpp

   1 /****************************************************************************
   2 **
   3 ** This file is part of a Qt Solutions component.
   4 **
   5 ** Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
   6 **
   7 ** Contact:  Qt Software Information (qt-info@nokia.com)
   8 **
   9 ** Commercial Usage
  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.
  14 **
  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.
  22 **
  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
  26 ** package.
  27 **
  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.
  35 **
  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.
  41 **
  42 ** If you are unsure which license is appropriate for your use, please
  43 ** contact the sales department at qt-sales@nokia.com.
  44 **
  45 ****************************************************************************/
  46
  47
  48 #include "qtsingleapplication.h"
  49 #include "qtlocalpeer.h"
  50 #include <QWidget>
  51
  52
  53 /*!
  54     \class QtSingleApplication qtsingleapplication.h
  55     \brief The QtSingleApplication class provides an API to detect and
  56     communicate with running instances of an application.
  57
  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.
  64
  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.
  69
  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.
  76
  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.
  84
  85     If isRunning() or sendMessage() returns true, another instance is
  86     already running, and the application should terminate or enter
  87     client mode.
  88
  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.
  93
  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
  97     examples for that).
  98
  99     \code
 100     // Original
 101     int main(int argc, char **argv)
 102     {
 103         QApplication app(argc, argv);
 104
 105         MyMainWidget mmw;
 106
 107         mmw.show();
 108         return app.exec();
 109     }
 110
 111     // Single instance
 112     int main(int argc, char **argv)
 113     {
 114         QtSingleApplication app(argc, argv);
 115
 116         if (app.isRunning())
 117             return 0;
 118
 119         MyMainWidget mmw;
 120
 121         app.setActivationWindow(&mmw);
 122
 123         mmw.show();
 124         return app.exec();
 125     }
 126     \endcode
 127
 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.
 133
 134     For console (non-GUI) applications, QtSingleCoreApplication may be
 135     used instead of this class, to avoid the dependency on the QtGui
 136     library.
 137
 138     \sa QtSingleCoreApplication
 139 */
 140
 141
 142 void QtSingleApplication::sysInit(const QString &appId)
 143 {
 144     actWin = 0;
 145     peer = new QtLocalPeer(this, appId);
 146     connect(peer, SIGNAL(messageReceived(const QString&)), SIGNAL(messageReceived(const QString&)));
 147 }
 148
 149
 150 /*!
 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.
 154
 155     If you are creating a console application (i.e. setting \a
 156     GUIenabled to false), you may consider using
 157     QtSingleCoreApplication instead.
 158 */
 159
 160 QtSingleApplication::QtSingleApplication(int &argc, char **argv, bool GUIenabled)
 161     : QApplication(argc, argv, GUIenabled)
 162 {
 163     sysInit();
 164 }
 165
 166
 167 /*!
 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.
 171 */
 172
 173 QtSingleApplication::QtSingleApplication(const QString &appId, int &argc, char **argv)
 174     : QApplication(argc, argv)
 175 {
 176     sysInit(appId);
 177 }
 178
 179
 180 /*!
 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.
 184 */
 185 /*
 186 QtSingleApplication::QtSingleApplication(int &argc, char **argv, Type type)
 187     : QApplication(argc, argv, type)
 188 {
 189     sysInit();
 190 }
 191 */
 192
 193
 194 #if defined(Q_OS_LINUX_NO)
 195 /*!
 196   Special constructor for X11, ref. the documentation of
 197   QApplication's corresponding constructor. The application identifier
 198   will be QCoreApplication::applicationFilePath(). \a dpy, \a visual,
 199   and \a cmap are passed on to the QApplication constructor.
 200 */
 201 QtSingleApplication::QtSingleApplication(Display* dpy, Qt::HANDLE visual, Qt::HANDLE cmap)
 202     : QApplication(dpy, visual, cmap)
 203 {
 204     sysInit();
 205 }
 206
 207 /*!
 208   Special constructor for X11, ref. the documentation of
 209   QApplication's corresponding constructor. The application identifier
 210   will be QCoreApplication::applicationFilePath(). \a dpy, \a argc, \a
 211   argv, \a visual, and \a cmap are passed on to the QApplication
 212   constructor.
 213 */
 214 QtSingleApplication::QtSingleApplication(Display *dpy, int &argc, char **argv, Qt::HANDLE visual, Qt::HANDLE cmap)
 215     : QApplication(dpy, argc, argv, visual, cmap)
 216 {
 217     sysInit();
 218 }
 219
 220 /*!
 221   Special constructor for X11, ref. the documentation of
 222   QApplication's corresponding constructor. The application identifier
 223   will be \a appId. \a dpy, \a argc, \a
 224   argv, \a visual, and \a cmap are passed on to the QApplication
 225   constructor.
 226 */
 227 QtSingleApplication::QtSingleApplication(Display* dpy, const QString &appId, int argc, char **argv, Qt::HANDLE visual, Qt::HANDLE cmap)
 228     : QApplication(dpy, argc, argv, visual, cmap)
 229 {
 230     sysInit(appId);
 231 }
 232 #endif
 233
 234
 235 /*!
 236     Returns true if another instance of this application is running;
 237     otherwise false.
 238
 239     This function does not find instances of this application that are
 240     being run by a different user (on Windows: that are running in
 241     another session).
 242
 243     \sa sendMessage()
 244 */
 245
 246 bool QtSingleApplication::isRunning()
 247 {
 248     return peer->isClient();
 249 }
 250
 251
 252 /*!
 253     Tries to send the text \a message to the currently running
 254     instance. The QtSingleApplication object in the running instance
 255     will emit the messageReceived() signal when it receives the
 256     message.
 257
 258     This function returns true if the message has been sent to, and
 259     processed by, the current instance. If there is no instance
 260     currently running, or if the running instance fails to process the
 261     message within \a timeout milliseconds, this function return false.
 262
 263     \sa isRunning(), messageReceived()
 264 */
 265 bool QtSingleApplication::sendMessage(const QString &message, int timeout)
 266 {
 267     return peer->sendMessage(message, timeout);
 268 }
 269
 270
 271 /*!
 272     Returns the application identifier. Two processes with the same
 273     identifier will be regarded as instances of the same application.
 274 */
 275 QString QtSingleApplication::id() const
 276 {
 277     return peer->applicationId();
 278 }
 279
 280
 281 /*!
 282   Sets the activation window of this application to \a aw. The
 283   activation window is the widget that will be activated by
 284   activateWindow(). This is typically the application's main window.
 285
 286   If \a activateOnMessage is true (the default), the window will be
 287   activated automatically every time a message is received, just prior
 288   to the messageReceived() signal being emitted.
 289
 290   \sa activateWindow(), messageReceived()
 291 */
 292
 293 void QtSingleApplication::setActivationWindow(QWidget* aw, bool activateOnMessage)
 294 {
 295     actWin = aw;
 296     if (activateOnMessage)
 297         connect(peer, SIGNAL(messageReceived(const QString&)), this, SLOT(activateWindow()));
 298     else
 299         disconnect(peer, SIGNAL(messageReceived(const QString&)), this, SLOT(activateWindow()));
 300 }
 301
 302
 303 /*!
 304     Returns the applications activation window if one has been set by
 305     calling setActivationWindow(), otherwise returns 0.
 306
 307     \sa setActivationWindow()
 308 */
 309 QWidget* QtSingleApplication::activationWindow() const
 310 {
 311     return actWin;
 312 }
 313
 314
 315 /*!
 316   De-minimizes, raises, and activates this application's activation window.
 317   This function does nothing if no activation window has been set.
 318
 319   This is a convenience function to show the user that this
 320   application instance has been activated when he has tried to start
 321   another instance.
 322
 323   This function should typically be called in response to the
 324   messageReceived() signal. By default, that will happen
 325   automatically, if an activation window has been set.
 326
 327   \sa setActivationWindow(), messageReceived(), initialize()
 328 */
 329 void QtSingleApplication::activateWindow()
 330 {
 331     if (actWin) {
 332         actWin->setWindowState(actWin->windowState() & ~Qt::WindowMinimized);
 333         actWin->raise();
 334         actWin->activateWindow();
 335     }
 336 }
 337
 338
 339 /*!
 340     \fn void QtSingleApplication::messageReceived(const QString& message)
 341
 342     This signal is emitted when the current instance receives a \a
 343     message from another instance of this application.
 344
 345     \sa sendMessage(), setActivationWindow(), activateWindow()
 346 */
 347
 348
 349 /*!
 350     \fn void QtSingleApplication::initialize(bool dummy = true)
 351
 352     \obsolete
 353 */