Qt Extended Home · Index · Classes · Headers · Overviews codeless banner

QtSingleApplication Class Reference

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

    #include <QtSingleApplication>

Inherits QApplication.

Public Functions

Public Slots

Signals

Additional Inherited 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 that cannot have multiple instances running on the same machine for the same user.

To use the QtSingleApplication class you must provide an ID string that it unique on the system you run the application on. Typical IDs are the name of the application and the application vendor, or a string representation of a UUID.

The application should create the QtSingleApplication object very early in the startup phase, and try to send a message or call isRunning() to find out if an instance of this application is already running.

If an instance is already running, this application instance should terminate. Otherwise the application should call initialize() immediately, and continue with the initialization of the application user interface before entering the event loop with exec(). The messageReceived() signal will be emitted when the application receives messages from another instance of the same application. If a message is received it might be helpful to the user to raise the application so that it becomes visible.

Here's an example that shows how to convert an existing application to us 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;
        app.setMainWidget(&mmw);

        mmw.show();
        return app.exec();
    }

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

        if (app.sendMessage("Do I exist?"))
            return 0;

        app.initialize();

        MyMainWidget mmw;
        app.setMainWidget(&mmw);

        QObject::connect(&app, SIGNAL(messageReceived(QString)),
                &app, SLOT(activateMainWidget()));

        mmw.show();
        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.

Member Function Documentation

QtSingleApplication::QtSingleApplication ( const QString & id, int & argc, char ** argv, Type type = GuiClient )

Creates a QtSingleApplication object with the identifier id. argc, argv and type are passed on to the QAppliation constructor.

There can only be one QtSingleApplication object(and since there can only be one QApplication object you do not need to create another QApplication object yourself).

Warning: On X11 type can not be QApplication::Tty.

QtSingleApplication::~QtSingleApplication ()

Destroys the object, freeing all allocated resources.

If the same application is started again it will not find this instance.

void QtSingleApplication::activateMainWidget ()   [virtual slot]

Calls QWidget::setActiveWindow() on this application's mainWidget(). This function does nothing if no main widget has been set.

This slot is typically connected to the messageReceived() signal.

See also messageReceived().

QString QtSingleApplication::id () const

Returns the identifier of this singleton object.

void QtSingleApplication::initialize ( bool activate = true )

Once this function has been called, this application instance becomes "visible" to other instances. This means that if another instance is started(by the same user), and calls isRunning(), the isRunning() function will return true to that other instance, which should then quit, leaving this instance to continue.

If activate is true(the default) the messageReceived() signal will be connected to the activateMainWidget() slot.

bool QtSingleApplication::isRunning () const

Returns true if another instance of this application has called initialize(); otherwise returns false.

This function does not find instances of this application that are being run by a different user.

See also initialize().

void QtSingleApplication::messageReceived ( const QString & message )   [signal]

This signal is emitted when the current instance receives a message from another instance of this application.

This signal is typically connected to the activateMainWidget() slot.

See also activateMainWidget() and initialize().

bool QtSingleApplication::sendMessage ( const QString & message, int timeout = 5000 )   [slot]

Tries to send the text message to the currently running instance. The QtSingleApplication object in the running instance will emit the messageReceived() signal when it receives the message.

This function returns true if the message has been sent to, and processed by, the current instance. If there is no instance currently running, or if the running instance fails to process the message within timeout milliseconds this function return false.

Note that on X11 systems the timeout parameter is ignored.

See also messageReceived().

Copyright © 2009 Trolltech
Qt Extended Sync Agent Documentation