Make lxqt globals a public header
[lxde/liblxqt.git] / lxqtsingleapplication.h
1 /* BEGIN_COMMON_COPYRIGHT_HEADER
2 * (c)LGPL2+
3 *
4 * LXQt - a lightweight, Qt based, desktop toolset
5 * http://lxqt.org
6 *
7 * Copyright: 2014 LXQt team
8 * Authors:
9 * Luís Pereira <luis.artur.pereira@gmail.com>
10 *
11 * This program or library is free software; you can redistribute it
12 * and/or modify it under the terms of the GNU Lesser General Public
13 * License as published by the Free Software Foundation; either
14 * version 2.1 of the License, or (at your option) any later version.
15 *
16 * This library is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * Lesser General Public License for more details.
20
21 * You should have received a copy of the GNU Lesser General
22 * Public License along with this library; if not, write to the
23 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
24 * Boston, MA 02110-1301 USA
25 *
26 * END_COMMON_COPYRIGHT_HEADER */
27
28 #ifndef LXQTSINGLEAPPLICATION_H
29 #define LXQTSINGLEAPPLICATION_H
30
31 #include "lxqtapplication.h"
32
33 class QWidget;
34
35 namespace LXQt {
36
37 /*! \class SingleApplication
38 * \brief The SingleApplication class provides an single instance Application.
39 *
40 * This class allows the user to create applications where only one instance
41 * is allowed to be running at an given time. If the user tries to launch
42 * another instance, the already running instance will be activated instead.
43 *
44 * The user has to set the activation window with setActivationWindow. If it
45 * doesn't the second instance will quietly exit without activating the first
46 * instance window. In any case only one instance is allowed.
47 *
48 * These classes depend on D-Bus and KF5::WindowSystem
49 *
50 * \code
51 *
52 * // Original code
53 * int main(int argc, char **argv)
54 * {
55 * LXQt::Application app(argc, argv);
56 *
57 * MainWidget w;
58 * w.show();
59 *
60 * return app.exec();
61 * }
62 *
63 * // Using the library
64 * int main(int argc, char **argv)
65 * {
66 * LXQt::SingleApplication app(argc, argv);
67 *
68 * MainWidget w;
69 * app.setActivationWindow(&w);
70 * w.show();
71 *
72 * return app.exec();
73 * }
74 * \endcode
75 * \sa SingleApplication
76 */
77
78 class LXQT_API SingleApplication : public Application {
79 Q_OBJECT
80
81 public:
82 /*!
83 * \brief Options to control the D-Bus failure related application behaviour
84 *
85 * By default (ExitOnDBusFailure) if an instance can't connect to the D-Bus
86 * session bus, that instance calls ::exit(1). Not even the first instance
87 * will run. Connecting to the D-Bus session bus is an condition to
88 * guarantee that only one instance will run.
89 *
90 * If an user wants to allow an application to run without D-Bus, it must
91 * use the NoExitOnDBusFailure option.
92 *
93 * ExitOnDBusFailure is the default.
94 */
95 enum StartOptions {
96 /** Exit if the connection to the D-Bus session bus fails.
97 * It's the default
98 */
99 ExitOnDBusFailure,
100 /** Don't exit if the connection to the D-Bus session bus fails.*/
101 NoExitOnDBusFailure
102 };
103 Q_ENUM(StartOptions)
104
105 /*!
106 * \brief Construct a LXQt SingleApplication object.
107 * \param argc standard argc as in QApplication
108 * \param argv standard argv as in QApplication
109 * \param options Control the on D-Bus failure application behaviour
110 *
111 * \sa StartOptions.
112 */
113 SingleApplication(int &argc, char **argv, StartOptions options = ExitOnDBusFailure);
114 virtual ~SingleApplication();
115
116 /*!
117 * \brief Sets the activation window.
118 * \param w activation window.
119 *
120 * Sets the activation window of this application to w. The activation
121 * window is the widget that will be activated by \a activateWindow().
122 *
123 * \sa activationWindow() \sa activateWindow();
124 */
125 void setActivationWindow(QWidget *w);
126
127 /*!
128 * \brief Gets the current activation window.
129 * \return The current activation window.
130 *
131 * \sa setActivationWindow();
132 */
133 QWidget *activationWindow() const;
134
135 public Q_SLOTS:
136 /*!
137 * \brief Activates this application activation window.
138 *
139 * Changes to the desktop where this applications is. It then de-minimizes,
140 * raises and activates the application's activation window.
141 * If no activation window has been set, this function does nothing.
142 *
143 * \sa setActivationWindow();
144 */
145 void activateWindow();
146
147 private:
148 QWidget *mActivationWindow;
149 };
150
151 #if defined(lxqtSingleApp)
152 #undef lxqtSingleApp
153 #endif
154 #define lxqtSingleApp (static_cast<LXQt::SingleApplication *>(qApp))
155
156 } // namespace LXQt
157
158 #endif // LXQTSINGLEAPPLICATION_H