root/middleware-offline/trunk/_src/eidmw/eidgui/qtsingleapplication.cpp @ 271

Revision 271, 8.8 KB (checked in by vsilva, 6 years ago)

First official release

Line 
1/****************************************************************************
2**
3** Copyright (C) 2003-2007 Trolltech ASA. All rights reserved.
4**
5** This file is part of a Qt Solutions component.
6**
7** Licensees holding a valid Qt Solutions License Agreement may use this
8** file in accordance with the rights, responsibilities, and obligations
9** contained therein. Please consult your licensing agreement or contact
10** sales@trolltech.com if any conditions of this licensing are not clear
11** to you.
12**
13** Further information about Qt Solutions licensing is available at:
14** http://www.trolltech.com/products/qt/addon/solutions/
15** or by contacting info@trolltech.com.
16**
17** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
18** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
19**
20****************************************************************************/
21#include "qtsingleapplication.h"
22#include <QtGui/QWidget>
23
24#include <QtGui/QApplication>
25#include <QtGui/QImage>
26#include <QtGui/QLabel>
27#include <QtGui/QPixmap>
28#include <QtGui>
29
30
31class QtSingletonPrivate
32{
33public:
34    QString id;
35};
36
37/*!
38    \class QtSingleApplication qtsingleapplication.h
39    \brief The QtSingleApplication class provides an API to detect and
40    communicate with running instances of an application.
41
42    This class allows you to create applications that cannot have
43    multiple instances running on the same machine for the same user.
44
45    To use the QtSingleApplication class you must provide an ID string
46    that it unique on the system you run the application on. Typical
47    IDs are the name of the application and the application vendor, or
48    a string representation of a \link QUuid UUID\endlink.
49
50    The application should create the QtSingleApplication object very
51    early in the startup phase, and try to send a message or call
52    isRunning() to find out if an instance of this application is
53    already running.
54
55    If an instance is already running, this application instance
56    should terminate. Otherwise the application should call
57    initialize() immediately, and continue with the initialization of
58    the application user interface before entering the event loop with
59    exec(). The messageReceived() signal will be emitted when the
60    application receives messages from another instance of the same
61    application.
62
63    If a message is received it might be helpful to the user to raise
64    the application so that it becomes visible. To facilitate this,
65    QtSingleApplication provides the setActivationWindow() function
66    and the activateWindow() slot.
67
68    Here's an example that shows how to convert an existing
69    application to us QtSingleApplication. It is very simple and does
70    not make use of all QtSingleApplication's functionality (see the
71    examples for that).
72
73    \code
74    // Original
75    int main(int argc, char **argv)
76    {
77        QApplication app(argc, argv);
78
79        MyMainWidget mmw;
80
81        mmw.show();
82        return app.exec();
83    }
84
85    // Single instance
86    int main(int argc, char **argv)
87    {
88        QtSingleApplication app("MySingleInstance", argc, argv);
89
90        if (app.sendMessage("Do I exist?"))
91            return 0;
92
93        app.initialize();
94
95        MyMainWidget mmw;
96
97        app.setActivationWindow(&mmw);
98
99        mmw.show();
100        return app.exec();
101    }
102    \endcode
103
104    Once this QtSingleApplication instance is destroyed(for example,
105    when the user quits), when the user next attempts to run the
106    application this instance will not, of course, be encountered.
107*/
108
109/*!
110    Creates a QtSingleApplication object with the identifier \a id. \a
111    argc, \a argv and \a type are passed on to the QAppliation
112    constructor.
113
114    There can only be one QtSingleApplication object(and since there
115    can only be one QApplication object you do not need to create
116    another QApplication object yourself).
117
118    \warning On X11 type can not be QApplication::Tty.
119
120*/
121QtSingleApplication::QtSingleApplication(const QString &id, int &argc, char **argv, Type type)
122    : QApplication(argc, argv, type)
123{
124#ifdef Q_WS_X11
125    Q_ASSERT_X(type != Tty, "QtSingleApplication::QtSingleApplication",
126               "QApplication::Tty cannot be used with QtSingleApplication on X11");
127#endif
128    d = new QtSingletonPrivate;
129    d->id = id;
130    actWin = 0;
131
132    sysInit();
133}
134
135#ifdef Q_WS_X11
136
137/*!
138    Creates a QtSingleApplication object, given an already open display
139    \a dpy. Uses the identifier \a id. \a argc and \a argv are
140    passed on to the QAppliation constructor. If \a visual and \a colormap
141    are non-zero, the application will use those as the default Visual and
142    Colormap contexts.
143
144    There can only be one QtSingleApplication object(and since there
145    can only be one QApplication object you do not need to create
146    another QApplication object yourself).
147
148    \warning Qt only supports TrueColor visuals at depths higher than 8
149    bits-per-pixel.
150
151    This is available only on X11.
152*/
153QtSingleApplication::QtSingleApplication(Display* dpy, const QString &id, int &argc, char **argv,
154                                         Qt::HANDLE visual, Qt::HANDLE colormap)
155    : QApplication(dpy, argc, argv, visual, colormap)
156{
157    d = new QtSingletonPrivate;
158    d->id = id;
159    actWin = 0;
160
161    sysInit();
162}
163
164#endif // Q_WS_X11
165
166
167/*!
168    Destroys the object, freeing all allocated resources.
169
170    If the same application is started again it will not find this
171    instance.
172*/
173QtSingleApplication::~QtSingleApplication()
174{
175    sysCleanup();
176
177    delete d;
178}
179
180/*!
181    Returns the identifier of this singleton object.
182*/
183QString QtSingleApplication::id() const
184{
185    return d->id;
186}
187
188
189/*!
190  Sets the activation window of this application to \a aw. The
191  activation window is the widget that will be activated by
192  activateWindow(). This is typically the application's main window.
193
194  \sa activateWindow(), messageReceived()
195*/
196void QtSingleApplication::setActivationWindow(QWidget* aw)
197{
198    actWin = aw;
199}
200
201
202/*!
203    Returns the applications activation window if one has been set by
204    calling setActivationWindow(), otherwise returns 0.
205
206    \sa setActivationWindow()
207*/
208QWidget* QtSingleApplication::activationWindow() const
209{
210    return actWin;
211}
212
213
214/*!
215  De-minimizes, raises, and activates this application's activation window.
216  This function does nothing if no activation window has been set.
217
218  This is a convenience function to show the user that this
219  application instance has been activated when he has tried to start
220  another instance.
221
222  This function should typically be called in response to the
223  messageReceived() signal. initialize() will connect that
224  signal to this slot by default.
225
226  \sa setActivationWindow(), messageReceived(), initialize()
227*/
228
229void QtSingleApplication::activateWindow()
230{
231    if (actWin) {
232        actWin->setWindowState(actWin->windowState() & ~Qt::WindowMinimized);
233        actWin->raise();
234        actWin->activateWindow();
235    }
236}
237
238
239/*! \fn bool QtSingleApplication::isRunning() const
240
241    Returns true if another instance of this application has called
242    initialize(); otherwise returns false.
243
244    This function does not find instances of this application that are
245    being run by a different user.
246
247    \sa initialize()
248*/
249
250/*!
251    \fn void QtSingleApplication::initialize(bool activate)
252
253    Once this function has been called, this application instance
254    becomes "visible" to other instances. This means that if another
255    instance is started(by the same user), and calls isRunning(), the
256    isRunning() function will return true to that other instance,
257    which should then quit, leaving this instance to continue.
258
259    If \a activate is true (the default) the messageReceived() signal
260    will be connected to the activateWindow() slot.
261*/
262
263/*!
264    \fn bool QtSingleApplication::sendMessage(const QString& message, int timeout)
265
266    Tries to send the text \a message to the currently running
267    instance. The QtSingleApplication object in the running instance
268    will emit the messageReceived() signal when it receives the
269    message.
270
271    This function returns true if the message has been sent to, and
272    processed by, the current instance. If there is no instance
273    currently running, or if the running instance fails to process the
274    message within \a timeout milliseconds this function return false.
275
276    Note that on X11 systems the \a timeout parameter is ignored.
277
278    \sa messageReceived()
279*/
280
281/*!
282    \fn void QtSingleApplication::messageReceived(const QString& message)
283
284    This signal is emitted when the current instance receives a \a
285    message from another instance of this application.
286
287    This signal is typically connected to the activateWindow()
288    slot.
289
290    \sa activateWindow(), initialize()
291*/
292
Note: See TracBrowser for help on using the browser.