vaikene.ee Git - evaf/blob - 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-2019 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      * Enters the main event loop of the Qt application.
 134      * @return Value returned by the Qt application
 135      *
 136      * This function enters the event loop of the Qt application. Use this function to start event handling
 137      * instead of calling QCoreApplication::exec() or QApplication::exec() functions directly.
 138      */
 139     virtual int exec() = 0;
 140
 141     /**
 142      * Requests the eVaf application to restart.
 143      *
 144      * This function requests the eVaf application to restart itself. Restarting the application
 145      * reloads all the plugins and re-initializes them.
 146      */
 147     virtual void restart() = 0;
 148
 149     /**
 150      * Requests the eVaf application to quit.
 151      * @param err If true, then indicates that the application exits due to a fatal error
 152      *
 153      * This function requests the eVaf application to quit.
 154      */
 155     virtual void quit(bool err = false) = 0;
 156
 157     /**
 158      * Returns true if the eVaf application is ready.
 159      */
 160      virtual bool isReady() const = 0;
 161
 162     /**
 163      * Returns the name of the eVaf root directory
 164      *
 165      * The root directory is the base directory where the eVaf application is installed. The default root
 166      * directory is the parent of the binary directory.
 167      *
 168      * Write access to the root directory is not required to run the application.
 169      *
 170      * This directory can be changed with the EVAF_ROOT_DIR environment variable or with the -root[dir]=&lt;directory&gt;
 171      * command line argument.
 172      */
 173     virtual QString const rootDir() const = 0;
 174
 175     /**
 176      * Returns the name of the eVaf data directory.
 177      *
 178      * The data root directory is the base directory for all the directories that require write access.
 179      *
 180      * The default data directory on Windows is \%APPDATA\%/\%EVAF_APP_NAME\%. The default data directory
 181      * on Linux is ${HOME}/.${EVAF_APP_NAME}.
 182      *
 183      * This directory can be changed with the EVAF_DATA_ROOT_DIR environment variable or with the
 184      * -dataroot[dir]=&lt;directory&gt; command line argument.
 185      */
 186     virtual QString const dataRootDir() const = 0;
 187
 188     /**
 189      * Returns the name of the binary files directory.
 190      *
 191      * The binary directory is the directory where all the application's binary files (main executable and
 192      * modules) are located. The default binary directory is where the main executable is located.
 193      *
 194      * NB! Changing the application's root directory does not change the location of the binary directory.
 195      */
 196     virtual QString const binDir() const = 0;
 197
 198     /**
 199      * Returns the configuration files directory.
 200      *
 201      * This is the directory where all the application's configuration files are located. The default
 202      * configuration files directory is 'etc' in the data root directory.
 203      *
 204      * This directory can be changed with the EVAF_ETC_DIR environment variable or with the -etc[dir]=&lt;directory&gt;
 205      * command line argument.
 206      */
 207     virtual QString const etcDir() const = 0;
 208
 209     /**
 210      * Returns the log files directory.
 211      *
 212      * This is the directory where the application outputs all the log files. The default log files
 213      * directory is 'log' in the data root directory.
 214      *
 215      * This directory can be changed with the EVAF_LOG_DIR environment variable or with the
 216      * -log[dir]=&lt;directory&gt; command line argument.
 217      */
 218     virtual QString const logDir() const = 0;
 219
 220     /**
 221      * Returns the documentation directory.
 222      *
 223      * This is the directory where all the documentation and help files are located. The default
 224      * documentation directory is 'doc' in the root directory.
 225      *
 226      * This directory can be changed with the EVAF_DOC_DIR environment variable or with the
 227      * -doc[dir]=&lt;directory&gt; command line argument.
 228      */
 229     virtual QString const docDir() const = 0;
 230
 231     /**
 232      * Returns the Qt plugins directory.
 233      *
 234      * The Qt plugins directory is where additional Qt plugins are located. These Qt plugins
 235      * are loaded manually by the application and specified in the application's XML file.
 236      *
 237      * Changing this directory does not affect the way how Qt itself loads its plugins.
 238      *
 239      * This directory can be changed with the EVAF_QT_PLUGINS_DIR environment variable or with the
 240      * -qtplugins[dir]=&lt;directory&gt; command line argument.
 241      */
 242     virtual QString const qtPluginsDir() const = 0;
 243
 244
 245 signals:
 246
 247     /**
 248      * Ready signal.
 249      *
 250      * This signal is emitted when the eVaf application is ready, ie the application initialized and all the
 251      * modules loaded.
 252      */
 253     void ready();
 254
 255     /**
 256      * Terminating signal.
 257      *
 258      * This signal is emitted when the eVaf application is about to terminate.
 259      */
 260     void terminating();
 261
 262 };
 263
 264 } // namespace eVaf::Common
 265 } // namespace eVaf
 266
 267 #endif