vaikene.ee Git - evaf/blob - src/libs/Common/ienv.h

   1 /**
   2  * @file Common/ienv.h
   3  * @brief Environment 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_IENV_H
  21 #define __COMMON_IENV_H
  22
  23 #include "libcommon.h"
  24
  25 #include <QObject>
  26 #include <QString>
  27
  28 namespace eVaf {
  29 namespace Common {
  30
  31 /**
  32  * Environment interface for eVaf applications
  33  * @code#include <Common/iEnv>@endcode
  34  *
  35  * The iEnv interface provides information about the environment where the application is running.
  36  * Functions in this interface return names of directories where different resources are located.
  37  * Modules should always use the iEnv interface for directory names and locations.
  38  *
  39  * Directory names returned by functions in this interface are UNIX path names and they are quaranteed
  40  * to end with the '/' character.
  41  *
  42  * All the directories have reasonable default values, that should work in most of the cases. For example,
  43  * the binary directory is set to the same directory where the application's main executable is located.
  44  * The root directory is the parent of the binary directory etc.
  45  *
  46  * Default values can be overwritten with environment variables and command line arguments. If both are used,
  47  * then command line arguments have higher priorities.
  48  */
  49 class COMMON_EXPORT iEnv : public QObject
  50 {
  51     Q_OBJECT
  52
  53 public:
  54
  55     /// Interface constructor
  56     iEnv() : QObject() {}
  57
  58     /// Empty virtual destructor
  59     virtual ~iEnv() {}
  60
  61     /**
  62      * Returns the iEnv interface instance
  63      * @return The iEnv interface
  64      *
  65      * This function returns the global iEnv interface instance. As all the eVaf modules and applications
  66      * are expected to be linked against the common library, then this is the preferred method of obtaining
  67      * the iEnv interface. The other method is by using the iRegistry interface.
  68      */
  69     static iEnv * instance();
  70
  71     /**
  72      * Returns the name of the eVaf root directory
  73      *
  74      * The root directory is the base directory where the eVaf application is installed. The default root
  75      * directory is the parent of the binary directory.
  76      *
  77      * Write access to the root directory is not required to run the application.
  78      *
  79      * This directory can be changed with the EVAF_ROOT_DIR environment variable or with the -root[dir]=&lt;directory&gt;
  80      * command line argument.
  81      */
  82     virtual QString const rootDir() const = 0;
  83
  84     /**
  85      * Returns the name of the eVaf data directory.
  86      *
  87      * The data root directory is the base directory for all the directories that require write access.
  88      *
  89      * The default data directory on Windows is \%APPDATA\%/\%EVAF_APP_NAME\%. The default data directory
  90      * on Linux is ${HOME}/.${EVAF_APP_NAME}.
  91      *
  92      * This directory can be changed with the EVAF_DATA_ROOT_DIR environment variable or with the
  93      * -dataroot[dir]=&lt;directory&gt; command line argument.
  94      */
  95     virtual QString const dataRootDir() const = 0;
  96
  97     /**
  98      * Returns the name of the binary files directory.
  99      *
 100      * The binary directory is the directory where all the application's binary files (main executable and
 101      * modules) are located. The default binary directory is where the main executable is located.
 102      *
 103      * NB! Changing the application's root directory does not change the location of the binary directory.
 104      */
 105     virtual QString const binDir() const = 0;
 106
 107     /**
 108      * Returns the configuration files directory.
 109      *
 110      * This is the directory where all the application's configuration files are located. The default
 111      * configuration files directory is 'etc' in the data root directory.
 112      *
 113      * This directory can be changed with the EVAF_ETC_DIR environment variable or with the -etc[dir]=&lt;directory&gt;
 114      * command line argument.
 115      */
 116     virtual QString const etcDir() const = 0;
 117
 118     /**
 119      * Returns the log files directory.
 120      *
 121      * This is the directory where the application outputs all the log files. The default log files
 122      * directory is 'log' in the data root directory.
 123      *
 124      * This directory can be changed with the EVAF_LOG_DIR environment variable or with the
 125      * -log[dir]=&lt;directory&gt; command line argument.
 126      */
 127     virtual QString const logDir() const = 0;
 128
 129     /**
 130      * Returns the documentation directory.
 131      *
 132      * This is the directory where all the documentation and help files are located. The default
 133      * documentation directory is 'doc' in the root directory.
 134      *
 135      * This directory can be changed with the EVAF_DOC_DIR environment variable or with the
 136      * -doc[dir]=&lt;directory&gt; command line argument.
 137      */
 138     virtual QString const docDir() const = 0;
 139
 140     /**
 141      * Returns the Qt plugins directory.
 142      *
 143      * The Qt plugins directory is where additional Qt plugins are located. These Qt plugins
 144      * are loaded manually by the application and specified in the application's XML file.
 145      *
 146      * Changing this directory does not affect the way how Qt itself loads its plugins.
 147      *
 148      * This directory can be changed with the EVAF_QT_PLUGINS_DIR environment variable or with the
 149      * -qtplugins[dir]=&lt;directory&gt; command line argument.
 150      */
 151     virtual QString const qtPluginsDir() const = 0;
 152
 153 };
 154
 155 } // namespace eVaf::Common
 156 } // namespace eVaf
 157
 158 #endif