/**
 * @file Common/iapp.h
 * @brief eVaf application interface
 * @author Enar Vaikene
 *
 * Copyright (c) 2011-2019 Enar Vaikene
 *
 * This file is part of the eVaf C++ cross-platform application development framework.
 *
 * This file can be used under the terms of the GNU General Public License
 * version 3.0 as published by the Free Software Foundation and appearing in
 * the file LICENSE included in the packaging of this file. Please review the
 * the following information to ensure the GNU General Public License version
 * 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
 *
 * Alternatively, this file may be used in accordance with the Commercial License
 * Agreement provided with the Software.
 */

#ifndef __COMMON_IAPP_H
#define __COMMON_IAPP_H

#include "libcommon.h"

#include <QObject>
#include <QString>

namespace eVaf {
namespace Common {

/**
 * eVaf application interface
 * @code#include <Common/iApp>@endcode
 *
 * The iApp interface provides information about current eVaf application. Functions in this interface return
 * the name of the application, names of directories where different recources are located etc. Modules should
 * always use the iApp interface for directory names and locations.
 *
 * For example, all the configuration files should be located in the eVaf::Common::iApp::instance()->etcDir() directory.
 *
 * Directory names returned by functions in this interface are UNIX path names and they are quaranteed to
 * end with the '/' character.
 *
 * All the resources returned by this interface have default values, that should work in most of the cases.
 * Fox example, the binary directory is set to the same directory where the application's main executable is found.
 * The root directory is the parent of the binary directory etc.
 *
 * Default values can be overwritten with environment variables and command line arguments. If both are used,
 * then command line arguments have higher priorities.
 */
class COMMON_EXPORT iApp : public QObject
{
    Q_OBJECT

public:

    /// Application return values
    enum {
        RC_Quit     = 0,        ///< Normal exit
        RC_Error    = 1,        ///< Exit due to an error
        RC_Restart  = 2         ///< The application is restarting
    };

    /// Event that requests the eVaf application to quit
    static char const * const EV_QUIT;

    /// Event that requests the eVaf application to restart
    static char const * const EV_RESTART;

    /// Event informing that the eVaf application is ready
    static char const * const EV_READY;

    /// Event informing that the  eVaf application is restarting
    static char const * const EV_TERMINATING;

    /// Interface constructor
    iApp() : QObject() {}

    /// Empty virtual destructor
    virtual ~iApp() {}

    /**
     * Returns the iApp interface instance
     * @return The iApp interface
     *
     * This function returns the global iApp interface instance. As all the eVaf modules and applications
     * are expected to be linked against the common library, then this is the preferred method of obtaining
     * the iApp interface. The other method is by using the iRegistry interface.
     */
    static iApp * instance();

    /**
     * Returns the name of the eVaf application
     *
     * This function returns the name of the eVaf application, which is a string that identifies the application.
     * The default name of the application is "eVaf".
     *
     * This name of the application can be changed with the EVAF_APP_NAME environment variable or with the
     * -app[lication]=&lt;name&gt; command line argument.
     */
    virtual QString const name() const = 0;

    /**
     * Returns the current language and country used by the application.
     *
     * This function returns the current lowercase two-letter ISO 639 language code and uppercase
     * two-letter ISO 3166 country code if set.
     *
     * The default language is queried from the operating system.
     *
     * The language can be changed with the EVAF_LANGUAGE environment variabel or with the
     * -lang[uage]=&lt;language&gt; command line argument.
     */
    virtual QString const language() const = 0;

    /**
     * Returns the name of the application's XML file.
     *
     * This function returns the name of the application's XML file.
     * It tries to find the most specific file name for the given language. If not found, then
     * defaults to the generic name.
     *
     * For example, if the language is set to "et_EE" and the application's name is "eVaf", then
     * it tries to find XML files with the following names "eVaf_et_EE.xml" and "eVaf_et.xml". If
     * neither is found, defaults to the name "eVaf.xml".
     *
     * The path is not included in the returned file name. Use the eVaf::Common::iEnv::etcDir() function
     * for the location of the file.
     */
    virtual QString const xmlFileName() const = 0;

    /**
     * Enters the main event loop of the Qt application.
     * @return Value returned by the Qt application
     *
     * This function enters the event loop of the Qt application. Use this function to start event handling
     * instead of calling QCoreApplication::exec() or QApplication::exec() functions directly.
     */
    virtual int exec() = 0;

    /**
     * Requests the eVaf application to restart.
     *
     * This function requests the eVaf application to restart itself. Restarting the application
     * reloads all the plugins and re-initializes them.
     */
    virtual void restart() = 0;

    /**
     * Requests the eVaf application to quit.
     * @param err If true, then indicates that the application exits due to a fatal error
     *
     * This function requests the eVaf application to quit.
     */
    virtual void quit(bool err = false) = 0;

    /**
     * Returns true if the eVaf application is ready.
     */
     virtual bool isReady() const = 0;

    /**
     * Returns the name of the eVaf root directory
     *
     * The root directory is the base directory where the eVaf application is installed. The default root
     * directory is the parent of the binary directory.
     *
     * Write access to the root directory is not required to run the application.
     *
     * This directory can be changed with the EVAF_ROOT_DIR environment variable or with the -root[dir]=&lt;directory&gt;
     * command line argument.
     */
    virtual QString const rootDir() const = 0;

    /**
     * Returns the name of the eVaf data directory.
     *
     * The data root directory is the base directory for all the directories that require write access.
     *
     * The default data directory on Windows is \%APPDATA\%/\%EVAF_APP_NAME\%. The default data directory
     * on Linux is ${HOME}/.${EVAF_APP_NAME}.
     *
     * This directory can be changed with the EVAF_DATA_ROOT_DIR environment variable or with the
     * -dataroot[dir]=&lt;directory&gt; command line argument.
     */
    virtual QString const dataRootDir() const = 0;

    /**
     * Returns the name of the binary files directory.
     *
     * The binary directory is the directory where all the application's binary files (main executable and
     * modules) are located. The default binary directory is where the main executable is located.
     *
     * NB! Changing the application's root directory does not change the location of the binary directory.
     */
    virtual QString const binDir() const = 0;

    /**
     * Returns the configuration files directory.
     *
     * This is the directory where all the application's configuration files are located. The default
     * configuration files directory is 'etc' in the data root directory.
     *
     * This directory can be changed with the EVAF_ETC_DIR environment variable or with the -etc[dir]=&lt;directory&gt;
     * command line argument.
     */
    virtual QString const etcDir() const = 0;

    /**
     * Returns the log files directory.
     *
     * This is the directory where the application outputs all the log files. The default log files
     * directory is 'log' in the data root directory.
     *
     * This directory can be changed with the EVAF_LOG_DIR environment variable or with the
     * -log[dir]=&lt;directory&gt; command line argument.
     */
    virtual QString const logDir() const = 0;

    /**
     * Returns the documentation directory.
     *
     * This is the directory where all the documentation and help files are located. The default
     * documentation directory is 'doc' in the root directory.
     *
     * This directory can be changed with the EVAF_DOC_DIR environment variable or with the
     * -doc[dir]=&lt;directory&gt; command line argument.
     */
    virtual QString const docDir() const = 0;

    /**
     * Returns the Qt plugins directory.
     *
     * The Qt plugins directory is where additional Qt plugins are located. These Qt plugins
     * are loaded manually by the application and specified in the application's XML file.
     *
     * Changing this directory does not affect the way how Qt itself loads its plugins.
     *
     * This directory can be changed with the EVAF_QT_PLUGINS_DIR environment variable or with the
     * -qtplugins[dir]=&lt;directory&gt; command line argument.
     */
    virtual QString const qtPluginsDir() const = 0;


signals:

    /**
     * Ready signal.
     *
     * This signal is emitted when the eVaf application is ready, ie the application initialized and all the
     * modules loaded.
     */
    void ready();

    /**
     * Terminating signal.
     *
     * This signal is emitted when the eVaf application is about to terminate.
     */
    void terminating();

};

} // namespace eVaf::Common
} // namespace eVaf

#endif