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

   1 /**
   2  * @file Common/iprop.h
   3  * @brief eVaf properties 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_IPROP_H
  21 #  define __COMMON_IPROP_H
  22
  23 #include "libcommon.h"
  24
  25 #include <QObject>
  26 #include <QString>
  27 #include <QVariant>
  28
  29 namespace eVaf {
  30 namespace Common {
  31
  32 /**
  33  * Global properties and variables for eVaf applications.
  34  * @code#include <Common/iProp>@endcode
  35  *
  36  * Global properties and variables are shared by all the eVaf modules. Their function is similar to
  37  * configuration parameters with the main difference that properties are not meant to be modified by
  38  * users. For example, the 'applicationName' property contains the name of the current application.
  39  *
  40  * Properties are implemented as name/value pairs where the name uniquely identifies the property.
  41  * The default implementation of the iProp interface does not enforce any rules for property names and any
  42  * string is a valid name.
  43  *
  44  * Properties can be temporary or persistent. Temporary properties exist only as long as the application
  45  * is running and will be lost when the application is restarted. Persistent properties are stored
  46  * and reloaded when the application is restarted.
  47  *
  48  * Application's XML file section \<properties\> can be used to define default properties for the application.
  49  * These are initialized when the application is started up.
  50  *
  51  * Individual properties are defined in \<property\> nodes with the following attributes:
  52  * @li name="\<name\>" - specifies the name of the global property;
  53  * @li value="\<value\>" - specifies the value of the global property;
  54  * @li config="\<file/section/key\>" - value of the property is read from the configuration file (used only if
  55  * the 'value' attribute is missing);
  56  * @li windowsonly="yes" - the property is initialized only on Windows;
  57  * @li linuxonly="yes" - the property is initialized only on Linux.
  58  */
  59 class COMMON_EXPORT iProp : public QObject
  60 {
  61     Q_OBJECT
  62
  63 public:
  64
  65     /// Interface constructor
  66     iProp() : QObject() {}
  67
  68     /// Empty virtual dtor
  69     virtual ~iProp() {}
  70
  71     /**
  72      * Returns the iProp interface instance
  73      * @return The iProp interface instance
  74      *
  75      * This function returns the global iProp interface instance. If the eVaf module is linked against
  76      * the common eVaf library, then this is the preferred method of obtaining the iProp interface.
  77      * Another option would be using the eVaf::Common::iRegistry interface.
  78      */
  79     static iProp * instance();
  80
  81     /**
  82      * Returns the value of the global property or variable
  83      * @param name Name of the property
  84      * @param defaultValue Default value
  85      * @return The value of the global property or the default value if the property cannot be found
  86      *
  87      * The getValue() function returns a global property or variable identified by the name. If the property
  88      * is not found, returns the default value.
  89      */
  90     virtual QVariant getValue(QString const & name, QVariant const & defaultValue = QVariant()) const = 0;
  91
  92     /**
  93      * Sets the global property or variable
  94      * @param name Name of the property
  95      * @param value Value of the property
  96      * @param persistent If True, then the property is stored permanently
  97      *
  98      * The setValue() function sets the value of a global property or variable identified by the name. The property
  99      * is added if it does not exist. Set the persistent argument to True to make the change permanent.
 100      *
 101      * The valueChanged() signal is emitted indicating that a property changed.
 102      */
 103     virtual void setValue(QString const & name, QVariant const & value, bool persistent = false) = 0;
 104
 105
 106 signals:
 107
 108     /**
 109      * Global property or variable changed
 110      * @param name Name of the property
 111      * @param value New value of the property
 112      *
 113      * The valueChanged() signal is emitted when a global property or variable is changed.
 114      */
 115     void valueChanged(QString const & name, QVariant const & value);
 116
 117 };
 118
 119 } // namespace eVaf::Common
 120 } // namespace eVaf
 121
 122 #endif // iprop.h