/**
 * @file Common/iprop.h
 * @brief eVaf properties interface
 * @author Enar Vaikene
 *
 * Copyright (c) 2011 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_IPROP_H
#  define __COMMON_IPROP_H

#include "libcommon.h"

#include <QObject>
#include <QString>
#include <QVariant>

namespace eVaf {
namespace Common {

/**
 * Global properties and variables for eVaf applications.
 * @code#include <Common/iProp>@endcode
 *
 * Global properties and variables are shared by all the eVaf modules. Their function is similar to
 * configuration parameters with the main difference that properties are not meant to be modified by
 * users. For example, the 'applicationName' property contains the name of the current application.
 *
 * Properties are implemented as name/value pairs where the name uniquely identifies the property.
 * The default implementation of the iProp interface does not enforce any rules for property names and any
 * string is a valid name.
 *
 * Properties can be temporary or persistent. Temporary properties exist only as long as the application
 * is running and will be lost when the application is restarted. Persistent properties are stored
 * and reloaded when the application is restarted.
 *
 * Application's XML file section \<properties\> can be used to define default properties for the application.
 * These are initialized when the application is started up.
 *
 * Individual properties are defined in \<property\> nodes with the following attributes:
 * @li name="\<name\>" - specifies the name of the global property;
 * @li value="\<value\>" - specifies the value of the global property;
 * @li config="\<file/section/key\>" - value of the property is read from the configuration file (used only if
 * the 'value' attribute is missing);
 * @li windowsonly="yes" - the property is initialized only on Windows;
 * @li linuxonly="yes" - the property is initialized only on Linux.
 */
class COMMON_EXPORT iProp : public QObject
{
    Q_OBJECT

public:

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

    /// Empty virtual dtor
    virtual ~iProp() {}

    /**
     * Returns the iProp interface instance
     * @return The iProp interface instance
     *
     * This function returns the global iProp interface instance. If the eVaf module is linked against
     * the common eVaf library, then this is the preferred method of obtaining the iProp interface.
     * Another option would be using the eVaf::Common::iRegistry interface.
     */
    static iProp * instance();

    /**
     * Returns the value of the global property or variable
     * @param name Name of the property
     * @param defaultValue Default value
     * @return The value of the global property or the default value if the property cannot be found
     *
     * The getValue() function returns a global property or variable identified by the name. If the property
     * is not found, returns the default value.
     */
    virtual QVariant getValue(QString const & name, QVariant const & defaultValue = QVariant()) const = 0;

    /**
     * Sets the global property or variable
     * @param name Name of the property
     * @param value Value of the property
     * @param persistent If True, then the property is stored permanently
     *
     * The setValue() function sets the value of a global property or variable identified by the name. The property
     * is added if it does not exist. Set the persistent argument to True to make the change permanent.
     *
     * The valueChanged() signal is emitted indicating that a property changed.
     */
    virtual void setValue(QString const & name, QVariant const & value, bool persistent = false) = 0;


signals:

    /**
     * Global property or variable changed
     * @param name Name of the property
     * @param value New value of the property
     *
     * The valueChanged() signal is emitted when a global property or variable is changed.
     */
    void valueChanged(QString const & name, QVariant const & value);

};

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

#endif // iprop.h