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.
  36  *
  37  * All the resources returned by this interface have default values, that should work in most of the cases.
  38  *
  39  * Default values can be overwritten with environment variables and command line arguments. If both are used,
  40  * then command line arguments have higher priorities.
  41  */
  42 class COMMON_EXPORT iApp : public QObject
  43 {
  44     Q_OBJECT
  45
  46 public:
  47
  48     /// Application return values
  49     enum {
  50         RC_Quit     = 0,        ///< Normal exit
  51         RC_Error    = 1,        ///< Exit due to an error
  52         RC_Restart  = 2         ///< The application is restarting
  53     };
  54
  55     /// Event that requests the eVaf application to quit
  56     static char const * const EV_QUIT;
  57
  58     /// Event that requests the eVaf application to restart
  59     static char const * const EV_RESTART;
  60
  61     /// Event informing that the eVaf application is ready
  62     static char const * const EV_READY;
  63
  64     /// Event informing that the  eVaf application is restarting
  65     static char const * const EV_TERMINATING;
  66
  67     /// Interface constructor
  68     iApp() : QObject() {}
  69
  70     /// Empty virtual destructor
  71     virtual ~iApp() {}
  72
  73     /**
  74      * Returns the iApp interface instance
  75      * @return The iApp interface
  76      *
  77      * This function returns the global iApp interface instance. As all the eVaf modules and applications
  78      * are expected to be linked against the common library, then this is the preferred method of obtaining
  79      * the iApp interface. The other method is by using the iRegistry interface.
  80      */
  81     static iApp * instance();
  82
  83     /**
  84      * Returns the name of the eVaf application
  85      *
  86      * This function returns the name of the eVaf application, which is a string that identifies the application.
  87      * The default name of the application is "eVaf".
  88      *
  89      * This name of the application can be changed with the EVAF_APP_NAME environment variable or with the
  90      * -app[lication]=&lt;name&gt; command line argument.
  91      */
  92     virtual QString const name() const = 0;
  93
  94     /**
  95      * Returns the current language and country used by the application.
  96      *
  97      * This function returns the current lowercase two-letter ISO 639 language code and uppercase
  98      * two-letter ISO 3166 country code if set.
  99      *
 100      * The default language is queried from the operating system.
 101      *
 102      * The language can be changed with the EVAF_LANGUAGE environment variabel or with the
 103      * -lang[uage]=&lt;language&gt; command line argument.
 104      */
 105     virtual QString const language() const = 0;
 106
 107     /**
 108      * Returns the name of the application's XML file.
 109      *
 110      * This function returns the name of the application's XML file.
 111      * It tries to find the most specific file name for the given language. If not found, then
 112      * defaults to the generic name.
 113      *
 114      * For example, if the language is set to "et_EE" and the application's name is "eVaf", then
 115      * it tries to find XML files with the following names "eVaf_et_EE.xml" and "eVaf_et.xml". If
 116      * neither is found, defaults to the name "eVaf.xml".
 117      *
 118      * The path is not included in the returned file name. Use the eVaf::Common::iEnv::etcDir() function
 119      * for the location of the file.
 120      */
 121     virtual QString const xmlFileName() const = 0;
 122
 123     /**
 124      * Requests the eVaf application to restart.
 125      *
 126      * This function requests the eVaf application to restart itself. Restarting the application
 127      * reloads all the plugins and re-initializes them.
 128      */
 129     virtual void restart() = 0;
 130
 131     /**
 132      * Requests the eVaf application to quit.
 133      * @param err If true, then indicates that the application exits due to a fatal error
 134      *
 135      * This function requests the eVaf application to quit.
 136      */
 137     virtual void quit(bool err = false) = 0;
 138
 139     /**
 140      * Returns true if the eVaf application is ready.
 141      */
 142      virtual bool isReady() const = 0;
 143
 144
 145 signals:
 146
 147     /**
 148      * Ready signal.
 149      *
 150      * This signal is emitted when the eVaf application is ready, ie the application initialized and all the
 151      * modules loaded.
 152      */
 153     void ready();
 154
 155     /**
 156      * Terminating signal.
 157      *
 158      * This signal is emitted when the eVaf application is about to terminate.
 159      */
 160     void terminating();
 161
 162 };
 163
 164 } // namespace eVaf::Common
 165 } // namespace eVaf
 166
 167 #endif