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 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