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 <QtGui/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 QtSingleApplication::QtSingleApplication(int &argc, char **argv, Type type)
 186     : QApplication(argc, argv, type)
 187 {
 188     sysInit();
 189 }
 190
 191
 192 #if defined(Q_WS_X11)
 193 /*!
 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.
 198 */
 199 QtSingleApplication::QtSingleApplication(Display* dpy, Qt::HANDLE visual, Qt::HANDLE cmap)
 200     : QApplication(dpy, visual, cmap)
 201 {
 202     sysInit();
 203 }
 204
 205 /*!
 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
 210   constructor.
 211 */
 212 QtSingleApplication::QtSingleApplication(Display *dpy, int &argc, char **argv, Qt::HANDLE visual, Qt::HANDLE cmap)
 213     : QApplication(dpy, argc, argv, visual, cmap)
 214 {
 215     sysInit();
 216 }
 217
 218 /*!
 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
 223   constructor.
 224 */
 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)
 227 {
 228     sysInit(appId);
 229 }
 230 #endif
 231
 232
 233 /*!
 234     Returns true if another instance of this application is running;
 235     otherwise false.
 236
 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
 239     another session).
 240
 241     \sa sendMessage()
 242 */
 243
 244 bool QtSingleApplication::isRunning()
 245 {
 246     return peer->isClient();
 247 }
 248
 249
 250 /*!
 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
 254     message.
 255
 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.
 260
 261     \sa isRunning(), messageReceived()
 262 */
 263 bool QtSingleApplication::sendMessage(const QString &message, int timeout)
 264 {
 265     return peer->sendMessage(message, timeout);
 266 }
 267
 268
 269 /*!
 270     Returns the application identifier. Two processes with the same
 271     identifier will be regarded as instances of the same application.
 272 */
 273 QString QtSingleApplication::id() const
 274 {
 275     return peer->applicationId();
 276 }
 277
 278
 279 /*!
 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.
 283
 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.
 287
 288   \sa activateWindow(), messageReceived()
 289 */
 290
 291 void QtSingleApplication::setActivationWindow(QWidget* aw, bool activateOnMessage)
 292 {
 293     actWin = aw;
 294     if (activateOnMessage)
 295         connect(peer, SIGNAL(messageReceived(const QString&)), this, SLOT(activateWindow()));
 296     else
 297         disconnect(peer, SIGNAL(messageReceived(const QString&)), this, SLOT(activateWindow()));
 298 }
 299
 300
 301 /*!
 302     Returns the applications activation window if one has been set by
 303     calling setActivationWindow(), otherwise returns 0.
 304
 305     \sa setActivationWindow()
 306 */
 307 QWidget* QtSingleApplication::activationWindow() const
 308 {
 309     return actWin;
 310 }
 311
 312
 313 /*!
 314   De-minimizes, raises, and activates this application's activation window.
 315   This function does nothing if no activation window has been set.
 316
 317   This is a convenience function to show the user that this
 318   application instance has been activated when he has tried to start
 319   another instance.
 320
 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.
 324
 325   \sa setActivationWindow(), messageReceived(), initialize()
 326 */
 327 void QtSingleApplication::activateWindow()
 328 {
 329     if (actWin) {
 330         actWin->setWindowState(actWin->windowState() & ~Qt::WindowMinimized);
 331         actWin->raise();
 332         actWin->activateWindow();
 333     }
 334 }
 335
 336
 337 /*!
 338     \fn void QtSingleApplication::messageReceived(const QString& message)
 339
 340     This signal is emitted when the current instance receives a \a
 341     message from another instance of this application.
 342
 343     \sa sendMessage(), setActivationWindow(), activateWindow()
 344 */
 345
 346
 347 /*!
 348     \fn void QtSingleApplication::initialize(bool dummy = true)
 349
 350     \obsolete
 351 */