Logo Search packages:      
Sourcecode: cb2bib version File versions

QtSingleApplication Class Reference

#include <qtsingleapplication.h>

List of all members.

Detailed Description

The QtSingleApplication class provides an API to detect and communicate with running instances of an application.

This class allows you to create applications where only one instance should be running at a time. I.e., if the user tries to launch another instance, the already running instance will be activated instead. Another usecase is a client-server system, where the first started instance will assume the role of server, and the later instances will act as clients of that server.

By default, the full path of the executable file is used to determine whether two processes are instances of the same application. You can also provide an explicit identifier string that will be compared instead.

The application should create the QtSingleApplication object early in the startup phase, and call isRunning() or sendMessage() to find out if another instance of this application is already running. Startup parameters (e.g. the name of the file the user wanted this new instance to open) can be passed to the running instance in the sendMessage() function.

If isRunning() or sendMessage() returns false, it means that no other instance is running, and this instance has assumed the role as the running instance. The application should continue with the initialization of the application user interface before entering the event loop with exec(), as normal. The messageReceived() signal will be emitted when the application receives messages from another instance of the same application.

If isRunning() or sendMessage() returns true, another instance is already running, and the application should terminate or enter client mode.

If a message is received it might be helpful to the user to raise the application so that it becomes visible. To facilitate this, QtSingleApplication provides the setActivationWindow() function and the activateWindow() slot.

Here's an example that shows how to convert an existing application to use QtSingleApplication. It is very simple and does not make use of all QtSingleApplication's functionality (see the examples for that).

    // Original
    int main(int argc, char **argv)
        QApplication app(argc, argv);

        MyMainWidget mmw;

        return app.exec();

    // Single instance
    int main(int argc, char **argv)
        QtSingleApplication app(argc, argv);

        if (app.isRunning())
            return 0;

        MyMainWidget mmw;


        return app.exec();

Once this QtSingleApplication instance is destroyed(for example, when the user quits), when the user next attempts to run the application this instance will not, of course, be encountered. The next instance to call isRunning() or sendMessage() will assume the role as the new running instance.

For console (non-GUI) applications, QtSingleCoreApplication may be used instead of this class, to avoid the dependency on the QtGui library.

See also:

Definition at line 68 of file qtsingleapplication.h.

Public Slots

void activateWindow ()
bool sendMessage (const QString &message, int timeout=5000)


void messageReceived (const QString &message)

Public Member Functions

QWidget * activationWindow () const
QString id () const
void initialize (bool dummy=true)
bool isRunning ()
 QtSingleApplication (int &argc, char **argv, Type type)
 QtSingleApplication (const QString &id, int &argc, char **argv)
 QtSingleApplication (int &argc, char **argv, bool GUIenabled=true)
void setActivationWindow (QWidget *aw, bool activateOnMessage=true)

Private Member Functions

void sysInit (const QString &appId=QString())

Private Attributes

QWidget * actWin
QtLocalPeer * peer

The documentation for this class was generated from the following files:

Generated by  Doxygen 1.6.0   Back to index