]> vaikene.ee Git - evaf/blob - src/libs/Common/iapp.h
Merged the Common::iEnv interface into Common::iApp
[evaf] / src / libs / Common / iapp.h
1 /**
2 * @file Common/iapp.h
3 * @brief eVaf application interface
4 * @author Enar Vaikene
5 *
6 * Copyright (c) 2011 Enar Vaikene
7 *
8 * This file is part of the eVaf C++ cross-platform application development framework.
9 *
10 * This file can be used under the terms of the GNU General Public License
11 * version 3.0 as published by the Free Software Foundation and appearing in
12 * the file LICENSE included in the packaging of this file. Please review the
13 * the following information to ensure the GNU General Public License version
14 * 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
15 *
16 * Alternatively, this file may be used in accordance with the Commercial License
17 * Agreement provided with the Software.
18 */
19
20 #ifndef __COMMON_IAPP_H
21 #define __COMMON_IAPP_H
22
23 #include "libcommon.h"
24
25 #include <QObject>
26 #include <QString>
27
28 namespace eVaf {
29 namespace Common {
30
31 /**
32 * eVaf application interface
33 * @code#include <Common/iApp>@endcode
34 *
35 * The iApp interface provides information about current eVaf application. Functions in this interface return
36 * the name of the application, names of directories where different recources are located etc. Modules should
37 * always use the iApp interface for directory names and locations.
38 *
39 * For example, all the configuration files should be located in the eVaf::Common::iApp::instance()->etcDir() directory.
40 *
41 * Directory names returned by functions in this interface are UNIX path names and they are quaranteed to
42 * end with the '/' character.
43 *
44 * All the resources returned by this interface have default values, that should work in most of the cases.
45 * Fox example, the binary directory is set to the same directory where the application's main executable is found.
46 * The root directory is the parent of the binary directory etc.
47 *
48 * Default values can be overwritten with environment variables and command line arguments. If both are used,
49 * then command line arguments have higher priorities.
50 */
51 class COMMON_EXPORT iApp : public QObject
52 {
53 Q_OBJECT
54
55 public:
56
57 /// Application return values
58 enum {
59 RC_Quit = 0, ///< Normal exit
60 RC_Error = 1, ///< Exit due to an error
61 RC_Restart = 2 ///< The application is restarting
62 };
63
64 /// Event that requests the eVaf application to quit
65 static char const * const EV_QUIT;
66
67 /// Event that requests the eVaf application to restart
68 static char const * const EV_RESTART;
69
70 /// Event informing that the eVaf application is ready
71 static char const * const EV_READY;
72
73 /// Event informing that the eVaf application is restarting
74 static char const * const EV_TERMINATING;
75
76 /// Interface constructor
77 iApp() : QObject() {}
78
79 /// Empty virtual destructor
80 virtual ~iApp() {}
81
82 /**
83 * Returns the iApp interface instance
84 * @return The iApp interface
85 *
86 * This function returns the global iApp interface instance. As all the eVaf modules and applications
87 * are expected to be linked against the common library, then this is the preferred method of obtaining
88 * the iApp interface. The other method is by using the iRegistry interface.
89 */
90 static iApp * instance();
91
92 /**
93 * Returns the name of the eVaf application
94 *
95 * This function returns the name of the eVaf application, which is a string that identifies the application.
96 * The default name of the application is "eVaf".
97 *
98 * This name of the application can be changed with the EVAF_APP_NAME environment variable or with the
99 * -app[lication]=&lt;name&gt; command line argument.
100 */
101 virtual QString const name() const = 0;
102
103 /**
104 * Returns the current language and country used by the application.
105 *
106 * This function returns the current lowercase two-letter ISO 639 language code and uppercase
107 * two-letter ISO 3166 country code if set.
108 *
109 * The default language is queried from the operating system.
110 *
111 * The language can be changed with the EVAF_LANGUAGE environment variabel or with the
112 * -lang[uage]=&lt;language&gt; command line argument.
113 */
114 virtual QString const language() const = 0;
115
116 /**
117 * Returns the name of the application's XML file.
118 *
119 * This function returns the name of the application's XML file.
120 * It tries to find the most specific file name for the given language. If not found, then
121 * defaults to the generic name.
122 *
123 * For example, if the language is set to "et_EE" and the application's name is "eVaf", then
124 * it tries to find XML files with the following names "eVaf_et_EE.xml" and "eVaf_et.xml". If
125 * neither is found, defaults to the name "eVaf.xml".
126 *
127 * The path is not included in the returned file name. Use the eVaf::Common::iEnv::etcDir() function
128 * for the location of the file.
129 */
130 virtual QString const xmlFileName() const = 0;
131
132 /**
133 * Requests the eVaf application to restart.
134 *
135 * This function requests the eVaf application to restart itself. Restarting the application
136 * reloads all the plugins and re-initializes them.
137 */
138 virtual void restart() = 0;
139
140 /**
141 * Requests the eVaf application to quit.
142 * @param err If true, then indicates that the application exits due to a fatal error
143 *
144 * This function requests the eVaf application to quit.
145 */
146 virtual void quit(bool err = false) = 0;
147
148 /**
149 * Returns true if the eVaf application is ready.
150 */
151 virtual bool isReady() const = 0;
152
153 /**
154 * Returns the name of the eVaf root directory
155 *
156 * The root directory is the base directory where the eVaf application is installed. The default root
157 * directory is the parent of the binary directory.
158 *
159 * Write access to the root directory is not required to run the application.
160 *
161 * This directory can be changed with the EVAF_ROOT_DIR environment variable or with the -root[dir]=&lt;directory&gt;
162 * command line argument.
163 */
164 virtual QString const rootDir() const = 0;
165
166 /**
167 * Returns the name of the eVaf data directory.
168 *
169 * The data root directory is the base directory for all the directories that require write access.
170 *
171 * The default data directory on Windows is \%APPDATA\%/\%EVAF_APP_NAME\%. The default data directory
172 * on Linux is ${HOME}/.${EVAF_APP_NAME}.
173 *
174 * This directory can be changed with the EVAF_DATA_ROOT_DIR environment variable or with the
175 * -dataroot[dir]=&lt;directory&gt; command line argument.
176 */
177 virtual QString const dataRootDir() const = 0;
178
179 /**
180 * Returns the name of the binary files directory.
181 *
182 * The binary directory is the directory where all the application's binary files (main executable and
183 * modules) are located. The default binary directory is where the main executable is located.
184 *
185 * NB! Changing the application's root directory does not change the location of the binary directory.
186 */
187 virtual QString const binDir() const = 0;
188
189 /**
190 * Returns the configuration files directory.
191 *
192 * This is the directory where all the application's configuration files are located. The default
193 * configuration files directory is 'etc' in the data root directory.
194 *
195 * This directory can be changed with the EVAF_ETC_DIR environment variable or with the -etc[dir]=&lt;directory&gt;
196 * command line argument.
197 */
198 virtual QString const etcDir() const = 0;
199
200 /**
201 * Returns the log files directory.
202 *
203 * This is the directory where the application outputs all the log files. The default log files
204 * directory is 'log' in the data root directory.
205 *
206 * This directory can be changed with the EVAF_LOG_DIR environment variable or with the
207 * -log[dir]=&lt;directory&gt; command line argument.
208 */
209 virtual QString const logDir() const = 0;
210
211 /**
212 * Returns the documentation directory.
213 *
214 * This is the directory where all the documentation and help files are located. The default
215 * documentation directory is 'doc' in the root directory.
216 *
217 * This directory can be changed with the EVAF_DOC_DIR environment variable or with the
218 * -doc[dir]=&lt;directory&gt; command line argument.
219 */
220 virtual QString const docDir() const = 0;
221
222 /**
223 * Returns the Qt plugins directory.
224 *
225 * The Qt plugins directory is where additional Qt plugins are located. These Qt plugins
226 * are loaded manually by the application and specified in the application's XML file.
227 *
228 * Changing this directory does not affect the way how Qt itself loads its plugins.
229 *
230 * This directory can be changed with the EVAF_QT_PLUGINS_DIR environment variable or with the
231 * -qtplugins[dir]=&lt;directory&gt; command line argument.
232 */
233 virtual QString const qtPluginsDir() const = 0;
234
235
236 signals:
237
238 /**
239 * Ready signal.
240 *
241 * This signal is emitted when the eVaf application is ready, ie the application initialized and all the
242 * modules loaded.
243 */
244 void ready();
245
246 /**
247 * Terminating signal.
248 *
249 * This signal is emitted when the eVaf application is about to terminate.
250 */
251 void terminating();
252
253 };
254
255 } // namespace eVaf::Common
256 } // namespace eVaf
257
258 #endif