Added the eVaf::Common::iProp interface for global properties and variables.

[evaf] / src / libs / Common / iprop.h

diff --git a/src/libs/Common/iprop.h b/src/libs/Common/iprop.h
new file mode 100644 (file)
index 0000000..864c8f5
--- /dev/null
+++ b/src/libs/Common/iprop.h
@@ -0,0 +1,122 @@
+/**
+ * @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