<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- qtsingleapplication-2.6_1-opensource/src/qtsingleapplication.cpp -->
<head>
<title>QtSingleApplication Class Reference</title>
<link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top" width="32"><img src="images/qt-logo.png" align="left" width="57" height="67" border="0" /></td>
<td width="1"> </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a></td>
</tr></table><h1 class="title">QtSingleApplication Class Reference</h1>
<p>The QtSingleApplication class provides an API to detect and communicate with running instances of an application. <a href="#details">More...</a></p>
<pre> #include <QtSingleApplication></pre><p>Inherits <a href="http://qt.nokia.com/doc/4.5/qapplication.html">QApplication</a>.</p>
<ul>
<li><a href="qtsingleapplication-members.html">List of all members, including inherited members</a></li>
<li><a href="qtsingleapplication-obsolete.html">Obsolete members</a></li>
</ul>
<a name="public-functions"></a>
<h3>Public Functions</h3>
<ul>
<li><div class="fn"></div><b><a href="qtsingleapplication.html#QtSingleApplication">QtSingleApplication</a></b> ( int & <i>argc</i>, char ** <i>argv</i>, bool <i>GUIenabled</i> = true )</li>
<li><div class="fn"></div><b><a href="qtsingleapplication.html#QtSingleApplication-2">QtSingleApplication</a></b> ( const QString & <i>appId</i>, int & <i>argc</i>, char ** <i>argv</i> )</li>
<li><div class="fn"></div><b><a href="qtsingleapplication.html#QtSingleApplication-3">QtSingleApplication</a></b> ( int & <i>argc</i>, char ** <i>argv</i>, Type <i>type</i> )</li>
<li><div class="fn"></div><b><a href="qtsingleapplication.html#QtSingleApplication-4">QtSingleApplication</a></b> ( Display * <i>dpy</i>, Qt::HANDLE <i>visual</i> = 0, Qt::HANDLE <i>cmap</i> = 0 )</li>
<li><div class="fn"></div><b><a href="qtsingleapplication.html#QtSingleApplication-5">QtSingleApplication</a></b> ( Display * <i>dpy</i>, int & <i>argc</i>, char ** <i>argv</i>, Qt::HANDLE <i>visual</i> = 0, Qt::HANDLE <i>cmap</i> = 0 )</li>
<li><div class="fn"></div><b><a href="qtsingleapplication.html#QtSingleApplication-6">QtSingleApplication</a></b> ( Display * <i>dpy</i>, const QString & <i>appId</i>, int <i>argc</i>, char ** <i>argv</i>, Qt::HANDLE <i>visual</i> = 0, Qt::HANDLE <i>cmap</i> = 0 )</li>
<li><div class="fn"></div>QWidget * <b><a href="qtsingleapplication.html#activationWindow">activationWindow</a></b> () const</li>
<li><div class="fn"></div>QString <b><a href="qtsingleapplication.html#id">id</a></b> () const</li>
<li><div class="fn"></div>bool <b><a href="qtsingleapplication.html#isRunning">isRunning</a></b> ()</li>
<li><div class="fn"></div>void <b><a href="qtsingleapplication.html#setActivationWindow">setActivationWindow</a></b> ( QWidget * <i>aw</i>, bool <i>activateOnMessage</i> = true )</li>
</ul>
<ul>
<li><div class="fn"></div>13 public functions inherited from <a href="http://qt.nokia.com/doc/4.5/qapplication.html#public-functions">QApplication</a></li>
<li><div class="fn"></div>4 public functions inherited from <a href="http://qt.nokia.com/doc/4.5/qcoreapplication.html#public-functions">QCoreApplication</a></li>
<li><div class="fn"></div>29 public functions inherited from <a href="http://qt.nokia.com/doc/4.5/qobject.html#public-functions">QObject</a></li>
</ul>
<a name="public-slots"></a>
<h3>Public Slots</h3>
<ul>
<li><div class="fn"></div>void <b><a href="qtsingleapplication.html#activateWindow">activateWindow</a></b> ()</li>
<li><div class="fn"></div>bool <b><a href="qtsingleapplication.html#sendMessage">sendMessage</a></b> ( const QString & <i>message</i>, int <i>timeout</i> = 5000 )</li>
</ul>
<ul>
<li><div class="fn"></div>7 public slots inherited from <a href="http://qt.nokia.com/doc/4.5/qapplication.html#public-slots">QApplication</a></li>
<li><div class="fn"></div>1 public slot inherited from <a href="http://qt.nokia.com/doc/4.5/qcoreapplication.html#public-slots">QCoreApplication</a></li>
<li><div class="fn"></div>1 public slot inherited from <a href="http://qt.nokia.com/doc/4.5/qobject.html#public-slots">QObject</a></li>
</ul>
<a name="signals"></a>
<h3>Signals</h3>
<ul>
<li><div class="fn"></div>void <b><a href="qtsingleapplication.html#messageReceived">messageReceived</a></b> ( const QString & <i>message</i> )</li>
</ul>
<ul>
<li><div class="fn"></div>5 signals inherited from <a href="http://qt.nokia.com/doc/4.5/qapplication.html#signals">QApplication</a></li>
<li><div class="fn"></div>1 signal inherited from <a href="http://qt.nokia.com/doc/4.5/qcoreapplication.html#signals">QCoreApplication</a></li>
<li><div class="fn"></div>1 signal inherited from <a href="http://qt.nokia.com/doc/4.5/qobject.html#signals">QObject</a></li>
</ul>
<h3>Additional Inherited Members</h3>
<ul>
<li><div class="fn"></div>13 properties inherited from <a href="http://qt.nokia.com/doc/4.5/qapplication.html#properties">QApplication</a></li>
<li><div class="fn"></div>4 properties inherited from <a href="http://qt.nokia.com/doc/4.5/qcoreapplication.html#properties">QCoreApplication</a></li>
<li><div class="fn"></div>1 property inherited from <a href="http://qt.nokia.com/doc/4.5/qobject.html#properties">QObject</a></li>
<li><div class="fn"></div>1 public type inherited from <a href="http://qt.nokia.com/doc/4.5/qobject.html#public-variables">QObject</a></li>
<li><div class="fn"></div>72 static public members inherited from <a href="http://qt.nokia.com/doc/4.5/qapplication.html#static-public-members">QApplication</a></li>
<li><div class="fn"></div>38 static public members inherited from <a href="http://qt.nokia.com/doc/4.5/qcoreapplication.html#static-public-members">QCoreApplication</a></li>
<li><div class="fn"></div>4 static public members inherited from <a href="http://qt.nokia.com/doc/4.5/qobject.html#static-public-members">QObject</a></li>
<li><div class="fn"></div>7 protected functions inherited from <a href="http://qt.nokia.com/doc/4.5/qobject.html#protected-functions">QObject</a></li>
<li><div class="fn"></div>2 protected variables inherited from <a href="http://qt.nokia.com/doc/4.5/qobject.html#protected-variables">QObject</a></li>
</ul>
<a name="details"></a>
<hr />
<h2>Detailed Description</h2>
<p>The QtSingleApplication class provides an API to detect and communicate with running instances of an application.</p>
<p>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.</p>
<p>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.</p>
<p>The application should create the QtSingleApplication object early in the startup phase, and call <a href="qtsingleapplication.html#isRunning">isRunning</a>() or <a href="qtsingleapplication.html#sendMessage">sendMessage</a>() 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 <a href="qtsingleapplication.html#sendMessage">sendMessage</a>() function.</p>
<p>If <a href="qtsingleapplication.html#isRunning">isRunning</a>() or <a href="qtsingleapplication.html#sendMessage">sendMessage</a>() 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 <a href="http://qt.nokia.com/doc/4.5/qapplication.html#exec">exec</a>(), as normal. The <a href="qtsingleapplication.html#messageReceived">messageReceived</a>() signal will be emitted when the application receives messages from another instance of the same application.</p>
<p>If <a href="qtsingleapplication.html#isRunning">isRunning</a>() or <a href="qtsingleapplication.html#sendMessage">sendMessage</a>() returns true, another instance is already running, and the application should terminate or enter client mode.</p>
<p>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 <a href="qtsingleapplication.html#setActivationWindow">setActivationWindow</a>() function and the <a href="qtsingleapplication.html#activateWindow">activateWindow</a>() slot.</p>
<p>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).</p>
<pre><span class="comment"> // Original</span>
int main(int argc, char **argv)
{
QApplication app(argc, argv);
MyMainWidget mmw;
mmw.show();
return app.exec();
}
<span class="comment"> // Single instance</span>
int main(int argc, char **argv)
{
QtSingleApplication app(argc, argv);
if (app.isRunning())
return 0;
MyMainWidget mmw;
app.setActivationWindow(&mmw);
mmw.show();
return app.exec();
}</pre>
<p>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 <a href="qtsingleapplication.html#isRunning">isRunning</a>() or <a href="qtsingleapplication.html#sendMessage">sendMessage</a>() will assume the role as the new running instance.</p>
<p>For console (non-GUI) applications, <a href="qtsinglecoreapplication.html">QtSingleCoreApplication</a> may be used instead of this class, to avoid the dependency on the <a href="http://qt.nokia.com/doc/4.5/qtgui.html">QtGui</a> library.</p>
<p>See also <a href="qtsinglecoreapplication.html">QtSingleCoreApplication</a>.</p>
<hr />
<h2>Member Function Documentation</h2>
<h3 class="fn"><a name="QtSingleApplication"></a>QtSingleApplication::QtSingleApplication ( int & <i>argc</i>, char ** <i>argv</i>, bool <i>GUIenabled</i> = true )</h3>
<p>Creates a <a href="qtsingleapplication.html">QtSingleApplication</a> object. The application identifier will be <a href="http://qt.nokia.com/doc/4.5/qcoreapplication.html#applicationFilePath">QCoreApplication::applicationFilePath</a>(). <i>argc</i>, <i>argv</i>, and <i>GUIenabled</i> are passed on to the QAppliation constructor.</p>
<p>If you are creating a console application (i.e. setting <i>GUIenabled</i> to false), you may consider using <a href="qtsinglecoreapplication.html">QtSingleCoreApplication</a> instead.</p>
<h3 class="fn"><a name="QtSingleApplication-2"></a>QtSingleApplication::QtSingleApplication ( const <a href="http://qt.nokia.com/doc/4.5/qstring.html">QString</a> & <i>appId</i>, int & <i>argc</i>, char ** <i>argv</i> )</h3>
<p>Creates a <a href="qtsingleapplication.html">QtSingleApplication</a> object with the application identifier <i>appId</i>. <i>argc</i> and <i>argv</i> are passed on to the QAppliation constructor.</p>
<h3 class="fn"><a name="QtSingleApplication-3"></a>QtSingleApplication::QtSingleApplication ( int & <i>argc</i>, char ** <i>argv</i>, <a href="http://qt.nokia.com/doc/4.5/qapplication.html#Type-enum">Type</a> <i>type</i> )</h3>
<p>Creates a <a href="qtsingleapplication.html">QtSingleApplication</a> object. The application identifier will be <a href="http://qt.nokia.com/doc/4.5/qcoreapplication.html#applicationFilePath">QCoreApplication::applicationFilePath</a>(). <i>argc</i>, <i>argv</i>, and <i>type</i> are passed on to the QAppliation constructor.</p>
<h3 class="fn"><a name="QtSingleApplication-4"></a>QtSingleApplication::QtSingleApplication ( Display * <i>dpy</i>, <a href="http://qt.nokia.com/doc/4.5/qt.html#HANDLE-typedef">Qt::HANDLE</a> <i>visual</i> = 0, <a href="http://qt.nokia.com/doc/4.5/qt.html#HANDLE-typedef">Qt::HANDLE</a> <i>cmap</i> = 0 )</h3>
<p>Special constructor for X11, ref. the documentation of <a href="http://qt.nokia.com/doc/4.5/qapplication.html">QApplication</a>'s corresponding constructor. The application identifier will be <a href="http://qt.nokia.com/doc/4.5/qcoreapplication.html#applicationFilePath">QCoreApplication::applicationFilePath</a>(). <i>dpy</i>, <i>visual</i>, and <i>cmap</i> are passed on to the <a href="http://qt.nokia.com/doc/4.5/qapplication.html">QApplication</a> constructor.</p>
<h3 class="fn"><a name="QtSingleApplication-5"></a>QtSingleApplication::QtSingleApplication ( Display * <i>dpy</i>, int & <i>argc</i>, char ** <i>argv</i>, <a href="http://qt.nokia.com/doc/4.5/qt.html#HANDLE-typedef">Qt::HANDLE</a> <i>visual</i> = 0, <a href="http://qt.nokia.com/doc/4.5/qt.html#HANDLE-typedef">Qt::HANDLE</a> <i>cmap</i> = 0 )</h3>
<p>Special constructor for X11, ref. the documentation of <a href="http://qt.nokia.com/doc/4.5/qapplication.html">QApplication</a>'s corresponding constructor. The application identifier will be <a href="http://qt.nokia.com/doc/4.5/qcoreapplication.html#applicationFilePath">QCoreApplication::applicationFilePath</a>(). <i>dpy</i>, <i>argc</i>, <i>argv</i>, <i>visual</i>, and <i>cmap</i> are passed on to the <a href="http://qt.nokia.com/doc/4.5/qapplication.html">QApplication</a> constructor.</p>
<h3 class="fn"><a name="QtSingleApplication-6"></a>QtSingleApplication::QtSingleApplication ( Display * <i>dpy</i>, const <a href="http://qt.nokia.com/doc/4.5/qstring.html">QString</a> & <i>appId</i>, int <i>argc</i>, char ** <i>argv</i>, <a href="http://qt.nokia.com/doc/4.5/qt.html#HANDLE-typedef">Qt::HANDLE</a> <i>visual</i> = 0, <a href="http://qt.nokia.com/doc/4.5/qt.html#HANDLE-typedef">Qt::HANDLE</a> <i>cmap</i> = 0 )</h3>
<p>Special constructor for X11, ref. the documentation of <a href="http://qt.nokia.com/doc/4.5/qapplication.html">QApplication</a>'s corresponding constructor. The application identifier will be <i>appId</i>. <i>dpy</i>, <i>argc</i>, <i>argv</i>, <i>visual</i>, and <i>cmap</i> are passed on to the <a href="http://qt.nokia.com/doc/4.5/qapplication.html">QApplication</a> constructor.</p>
<h3 class="fn"><a name="activateWindow"></a>void QtSingleApplication::activateWindow () <tt> [slot]</tt></h3>
<p>De-minimizes, raises, and activates this application's activation window. This function does nothing if no activation window has been set.</p>
<p>This is a convenience function to show the user that this application instance has been activated when he has tried to start another instance.</p>
<p>This function should typically be called in response to the <a href="qtsingleapplication.html#messageReceived">messageReceived</a>() signal. By default, that will happen automatically, if an activation window has been set.</p>
<p>See also <a href="qtsingleapplication.html#setActivationWindow">setActivationWindow</a>(), <a href="qtsingleapplication.html#messageReceived">messageReceived</a>(), and <a href="qtsingleapplication-obsolete.html#initialize">initialize</a>().</p>
<h3 class="fn"><a name="activationWindow"></a><a href="http://qt.nokia.com/doc/4.5/qwidget.html">QWidget</a> * QtSingleApplication::activationWindow () const</h3>
<p>Returns the applications activation window if one has been set by calling <a href="qtsingleapplication.html#setActivationWindow">setActivationWindow</a>(), otherwise returns 0.</p>
<p>See also <a href="qtsingleapplication.html#setActivationWindow">setActivationWindow</a>().</p>
<h3 class="fn"><a name="id"></a><a href="http://qt.nokia.com/doc/4.5/qstring.html">QString</a> QtSingleApplication::id () const</h3>
<p>Returns the application identifier. Two processes with the same identifier will be regarded as instances of the same application.</p>
<h3 class="fn"><a name="isRunning"></a>bool QtSingleApplication::isRunning ()</h3>
<p>Returns true if another instance of this application is running; otherwise false.</p>
<p>This function does not find instances of this application that are being run by a different user (on Windows: that are running in another session).</p>
<p>See also <a href="qtsingleapplication.html#sendMessage">sendMessage</a>().</p>
<h3 class="fn"><a name="messageReceived"></a>void QtSingleApplication::messageReceived ( const <a href="http://qt.nokia.com/doc/4.5/qstring.html">QString</a> & <i>message</i> ) <tt> [signal]</tt></h3>
<p>This signal is emitted when the current instance receives a <i>message</i> from another instance of this application.</p>
<p>See also <a href="qtsingleapplication.html#sendMessage">sendMessage</a>(), <a href="qtsingleapplication.html#setActivationWindow">setActivationWindow</a>(), and <a href="qtsingleapplication.html#activateWindow">activateWindow</a>().</p>
<h3 class="fn"><a name="sendMessage"></a>bool QtSingleApplication::sendMessage ( const <a href="http://qt.nokia.com/doc/4.5/qstring.html">QString</a> & <i>message</i>, int <i>timeout</i> = 5000 ) <tt> [slot]</tt></h3>
<p>Tries to send the text <i>message</i> to the currently running instance. The <a href="qtsingleapplication.html">QtSingleApplication</a> object in the running instance will emit the <a href="qtsingleapplication.html#messageReceived">messageReceived</a>() signal when it receives the message.</p>
<p>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 <i>timeout</i> milliseconds, this function return false.</p>
<p>See also <a href="qtsingleapplication.html#isRunning">isRunning</a>() and <a href="qtsingleapplication.html#messageReceived">messageReceived</a>().</p>
<h3 class="fn"><a name="setActivationWindow"></a>void QtSingleApplication::setActivationWindow ( <a href="http://qt.nokia.com/doc/4.5/qwidget.html">QWidget</a> * <i>aw</i>, bool <i>activateOnMessage</i> = true )</h3>
<p>Sets the activation window of this application to <i>aw</i>. The activation window is the widget that will be activated by <a href="qtsingleapplication.html#activateWindow">activateWindow</a>(). This is typically the application's main window.</p>
<p>If <i>activateOnMessage</i> is true (the default), the window will be activated automatically every time a message is received, just prior to the <a href="qtsingleapplication.html#messageReceived">messageReceived</a>() signal being emitted.</p>
<p>See also <a href="qtsingleapplication.html#activationWindow">activationWindow</a>(), <a href="qtsingleapplication.html#activateWindow">activateWindow</a>(), and <a href="qtsingleapplication.html#messageReceived">messageReceived</a>().</p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%" align="left">Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies)</td>
<td width="40%" align="center"><a href="http://qt.nokia.com/doc/trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt Solutions</div></td>
</tr></table></div></address></body>
</html>
