atria-soft/eproperty
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[DEV] write basic documantation

Browse Source
This commit is contained in:
Edouard DUPIN 2016-04-08 22:56:21 +02:00
parent dfaa1bd035
commit 05e1d7d2d7
15 changed files with 543 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
doc/build.md Normal file
View File

@ -0,0 +1,65 @@
Build lib & build sample {#eproperty_build}
========================
@tableofcontents
Download: {#eproperty_build_download}
=========
eproperty use some tools to manage source and build it:
lutin (build-system): {#eproperty_build_download_lutin}
---------------------
```{.sh}
pip install lutin --user
# optionnal dependency of lutin (manage image changing size for application release
pip install pillow --user
```
dependency: {#eproperty_build_download_dependency}
-----------
```{.sh}
mkdir framework
cd framework
git clone https://github.com/atria-soft/elog.git
git clone https://github.com/atria-soft/etk.git
cd ..
```
sources: {#eproperty_build_download_sources}
--------
```{.sh}
cd framework
git clone https://github.com/atria-soft/eproperty.git
cd ..
```
Build: {#eproperty_build_build}
======
library: {#eproperty_build_build_library}
--------
```{.sh}
lutin -mdebug eproperty
```
Sample: {#eproperty_build_build_sample}
-------
```{.sh}
lutin -mdebug eproperty-sample
```
Run sample: {#eproperty_build_run_sample}
===========
```{.sh}
lutin -mdebug eproperty-sample?run
```

30
doc/mainpage.md
View File

@ -1,30 +1,33 @@
EPROPERTY library {#mainpage}
=================
What is EPROPERTY, and how can I use it?
----------------------------------------
@tableofcontents
EPROPERTY, or Ewol signal engine is a simple messaging layer, managing multiple connection and manage disconnection
What is EPROPERTY: {#eproperty_mainpage_what}
==================
EPROPERTY, or Ewol property interface is a simple property API to set and get generic APIS
EPROPERTY is designed for
- Expose property on generic class
- Call class when the parameter change
- permit to set value throw string (good for XML configurations)
What languages are supported?
-----------------------------
What languages are supported? {#eproperty_mainpage_language}
=============================
EPROPERTY is written in C++.
Are there any licensing restrictions?
-------------------------------------
Are there any licensing restrictions? {#eproperty_mainpage_license_restriction}
=====================================
EPROPERTY is **FREE software** and _all sub-library are FREE and staticly linkable !!!_
License (APACHE-2.0)
--------------------
License (APACHE-2.0) {#eproperty_mainpage_license}
====================
Copyright EPROPERTY Edouard DUPIN
@ -40,3 +43,12 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Other pages {#eproperty_mainpage_sub_page}
===========
- @ref eproperty_build
- @ref eproperty_tutorial
- [**ewol coding style**](http://atria-soft.github.io/ewol/ewol_coding_style.html)

138
doc/tutorial.md Normal file
View File

@ -0,0 +1,138 @@
Tutorial {#eproperty_tutorial}
========
@tableofcontents
What is a property: {#eproperty_tutorial_what}
===================
A property is a generic interface to manage parameter of a class whithout redeclare all the time the setter and getter (that is a little boring)
Calling a property car mermit to be notify when the value change and to control the values range of list ...
A property can use agreator interface eproperty::interface that declare a **"properties"** variablke that permit to acces at all the property declared.
Declare a class that have this interface:
@snippet sampleAll.cpp eproperty_sample_declare_class_with_interface
Declare property: {#eproperty_tutorial_declare}
=================
We have some basic properties:
- eproperty::Value Simple store of a unique Value
- eproperty::Range Store a value inside an authorized range
- eproperty::List Store a value inside a list of values (set in constructor)
Declare a Value property: {#eproperty_tutorial_declare_value}
-------------------------
Do the correct include:
@snippet sampleAll.cpp eproperty_sample_declare_value
Declare your property:
@snippet sampleAll.cpp eproperty_sample_declare_class_property_value
Construct the property with eproperty::Interface:
@snippet sampleAll.cpp eproperty_sample_initialize_class_property_value
Construct the property with **NO** eproperty::Interface:
@snippet sampleAll.cpp eproperty_sample_initialize_class_property_value2
Configure your property:
@snippet sampleAll.cpp eproperty_sample_use_set_value_1
Use your property:
@snippet sampleAll.cpp eproperty_sample_get_value_value
Declare a Range property: {#eproperty_tutorial_declare_range}
-------------------------
Do the correct include:
@snippet sampleAll.cpp eproperty_sample_declare_range
Declare your property:
@snippet sampleAll.cpp eproperty_sample_declare_class_property_range
Construct the property with eproperty::Interface:
@snippet sampleAll.cpp eproperty_sample_initialize_class_property_range
Construct the property with **NO** eproperty::Interface:
@snippet sampleAll.cpp eproperty_sample_initialize_class_property_range2
Configure your property:
@snippet sampleAll.cpp eproperty_sample_use_set_range_1
Use your property:
@snippet sampleAll.cpp eproperty_sample_get_value_range
Declare a List property: {#eproperty_tutorial_declare_list}
------------------------
Do the correct include:
@snippet sampleAll.cpp eproperty_sample_declare_list
Declare your property:
@snippet sampleAll.cpp eproperty_sample_declare_class_property_list
Construct the property with eproperty::Interface:
@snippet sampleAll.cpp eproperty_sample_initialize_class_property_list
Construct the property with **NO** eproperty::Interface:
@snippet sampleAll.cpp eproperty_sample_initialize_class_property_list2
Special case for the List is adding the value with their string assiciated:
@snippet sampleAll.cpp eproperty_sample_initialize_class_property_list_add
Configure your property:
@snippet sampleAll.cpp eproperty_sample_use_set_list_1
Use your property:
@snippet sampleAll.cpp eproperty_sample_get_value_list
Particularity: {#eproperty_tutorial_particularity}
==============
Define a callback: {#eproperty_tutorial_particularity_callback}
------------------
All property can define a callback, it is used to update class property with special settings.
The callback is set in the construction instruction like:
@snippet sampleAll.cpp eproperty_sample_initialize_class_property_value
The fucntion define is like:
@snippet sampleAll.cpp eproperty_sample_initialize_class_property_value_callback
It is called every time the Value change, if the value is identical the callback is not called.
Set value without calling the callback: {#eproperty_tutorial_particularity_direct_set}
---------------------------------------
To set a value in a property without calling the nitifiction function, you might use:
@snippet sampleAll.cpp eproperty_sample_initialize_class_property_set_direct
Please do not use it ouside the internal class that define the peoperty (call me if you have an api to control it at the compilation time)
Heritage and callback: {#eproperty_tutorial_particularity_heritage}
----------------------
When you herit from an other class with theire property you can prefer changing the default value or set an other list of parameter.
To set value without calling the callback (that can be virtual then ==0 in the initialisation state), you need to call:
@snippet sampleAll.cpp eproperty_sample_initialize_class_property_set_direct
For the eproperty::List, you chan rename enumeration or remove values:
@snippet sampleAll.cpp eproperty_sample_initialize_class_property_list_rename
All sample Code: {#eproperty_tutorial_all_code}
================
This Will generate this simple sample code:
@snippet sampleAll.cpp eproperty_sample_all

13
doxy_eproperty.py
View File

@ -17,5 +17,18 @@ def create(target, module_name):
my_module.add_module_depend([
'etk'
])
my_module.add_sample_path([
'sample'
])
my_module.add_exclude_symbols([
'*operator<<*',
])
my_module.add_exclude_file([
'debug.h',
])
my_module.add_file_patterns([
'*.h',
'*.md',
])
return my_module

10
eproperty/List.h
View File

@ -20,7 +20,7 @@ namespace eproperty {
std::map<std::string, TYPE> m_list; //!< pointer on the list of all elements.
public:
/**
* @brief Create a parameter with List of element parameter.
* @brief Create a parameter with List of element parameter (nullptr if none).
* @param[in] _owner reference on the parameter lister.
* @param[in] _name Static name of the parameter.
* @param[in] _defaultValue Default value of the parameter.
@ -35,6 +35,14 @@ namespace eproperty {
void (CLASS_TYPE::*_setObs)()=nullptr) :
eproperty::PropertyType<TYPE>(_owner, _name, _defaultValue, _description, _setObs) {
};
/**
* @brief Create a parameter with List of element parameter (nullptr if none).
* @param[in] _defaultValue Default value of the parameter.
*/
List(const TYPE& _defaultValue) :
eproperty::PropertyType<TYPE>(_defaultValue) {
};
/**
* @brief virtualisation of Destructor.

7
eproperty/Property.cpp
View File

@ -21,6 +21,13 @@ eproperty::Property::Property(eproperty::Interface* _paramInterfaceLink, const s
}
}
eproperty::Property::Property() :
m_interfaceLink(nullptr),
m_setObserver(),
m_name("") {
}
void eproperty::Property::setObserver(eproperty::Property::Observer _setObs) {
m_setObserver = _setObs;
}

46
eproperty/Property.h
View File

@ -34,6 +34,10 @@ namespace eproperty {
* @param[in] _name Name of the parameter (must be unique if _paramInterfaceLink is define)
*/
Property(eproperty::Interface* _paramInterfaceLink, const std::string& _name);
/**
* @brief Basic property elements
*/
Property();
/**
* @brief Virtualize the destructor
* @internal
@ -102,22 +106,52 @@ namespace eproperty {
return std::vector<std::string>();
}
public:
//! @not_in_doc
/**
* @brief Eguality comparaison operator (REMOVED)
* @param[in] _obj Object to compare
* @return true The current object is identic
* @return false The current object is NOT identic
*/
template<class TYPE>
bool operator== (const TYPE& _obj) const = delete;
//! @not_in_doc
/**
* @brief IN-Eguality comparaison operator (REMOVED)
* @param[in] _obj Object to compare
* @return true The current object is NOT identic
* @return false The current object is identic
*/
template<class TYPE>
bool operator!= (const TYPE& _obj) const = delete;
//! @not_in_doc
/**
* @brief Lesser eguality comparaison operator (REMOVED)
* @param[in] _obj Object to compare
* @return true The current object lesser or equal than input object
* @return false The current object greater than input object
*/
template<class TYPE>
bool operator<= (const TYPE& _obj) const = delete;
//! @not_in_doc
/**
* @brief Greater eguality comparaison operator (REMOVED)
* @param[in] _obj Object to compare
* @return true The current object greater or equal than input object
* @return false The current object lesser than input object
*/
template<class TYPE>
bool operator>= (const TYPE& _obj) const = delete;
//! @not_in_doc
/**
* @brief Lesser comparaison operator (REMOVED)
* @param[in] _obj Object to compare
* @return true The current object lesser than input object
* @return false The current object greater or equal than input object
*/
template<class TYPE>
bool operator< (const TYPE& _obj) const = delete;
//! @not_in_doc
/**
* @brief Greater comparaison operator (REMOVED)
* @param[in] _obj Object to compare
* @return true The current object greater than input object
* @return false The current object lesser or equal than input object
*/
template<class TYPE>
bool operator> (const TYPE& _obj) const = delete;
};

19
eproperty/PropertyType.h
View File

@ -22,7 +22,7 @@ namespace eproperty {
public:
/**
* @brief Create a parameter with a specific type.
* @param[in] _owner Owner of the parameter.
* @param[in] _owner Owner of the parameter (nullptr if none).
* @param[in] _name Static name of the parameter.
* @param[in] _defaultValue Default value of the parameter.
* @param[in] _description description of the parameter.
@ -41,6 +41,15 @@ namespace eproperty {
setObserver([=](){(*_owner.*_setObs)();});
}
}
/**
* @brief Create a parameter with a specific type.
* @param[in] _defaultValue Default value of the parameter.
*/
PropertyType(const TYPE& _defaultValue) :
m_value(_defaultValue),
m_default(_defaultValue) {
}
/**
* @brief Destructor.
*/
@ -148,8 +157,12 @@ namespace eproperty {
const TYPE* operator->() const noexcept {
return &m_value;
}
//! @not_in_doc
const PropertyType<TYPE>& operator= (const TYPE& _newVal) = delete;
/**
* @brief Assignation opérator (REMOVED)
* @param _newVal Value to asign
* @return Reference on current object
*/
PropertyType<TYPE>& operator= (const TYPE& _newVal) = delete;
};
//! @not_in_doc
template<typename TYPE> std::ostream& operator <<(std::ostream& _os, const eproperty::PropertyType<TYPE>& _obj) {

11
eproperty/Range.h
View File

@ -23,7 +23,7 @@ namespace eproperty {
public:
/**
* @brief Create a parameter with a specific type.
* @param[in] _owner reference on the parameter lister.
* @param[in] _owner reference on the parameter lister (nullptr if none).
* @param[in] _name Static name of the parameter.
* @param[in] _defaultValue Default value of the parameter.
* @param[in] _min Minumum value.
@ -46,6 +46,15 @@ namespace eproperty {
//EPROPERTY_CRITICAL("min > max...");
}
};
/**
* @brief Create a parameter with a specific type.
* @param[in] _defaultValue Default value of the parameter.
* @param[in] _min Minumum value.
* @param[in] _max Maximum value.
*/
Range(const TYPE& _defaultValue,
const TYPE& _min,
const TYPE& _max);
/**
* @brief Destructor.
*/

9
eproperty/Value.h
View File

@ -21,7 +21,7 @@ namespace eproperty {
public:
/**
* @brief Create a parameter with a specific type.
* @param[in] _owner Owner of the parameter.
* @param[in] _owner Owner of the parameter (nullptr if none).
* @param[in] _name Static name of the parameter.
* @param[in] _defaultValue Default value of the parameter.
* @param[in] _description description of the parameter.
@ -36,7 +36,12 @@ namespace eproperty {
eproperty::PropertyType<TYPE>(_owner, _name, _defaultValue, _description, _setObs) {
}
protected:
/**
* @brief Create a parameter with a specific type.
* @param[in] _defaultValue Default value of the parameter.
*/
Value(const TYPE& _defaultValue);
public:
std::string getValueSpecific(const TYPE& _valueRequested) const override;
void setString(const std::string& _newVal) override;
};

13
eproperty/details/Range.hxx
View File

@ -9,6 +9,19 @@
#include <eproperty/Range.h>
template<class TYPE>
eproperty::Range<TYPE>::Range(const TYPE& _defaultValue,
const TYPE& _min,
const TYPE& _max) :
eproperty::Value<TYPE>(_defaultValue),
m_min(_min),
m_max(_max) {
if (m_min > m_max) {
//EPROPERTY_CRITICAL("min > max...");
}
}
template<class TYPE>
std::string eproperty::Range<TYPE>::getPropertyType() const {
return "eproperty::Range";

7
eproperty/details/Value.hxx
View File

@ -9,6 +9,13 @@
#include <eproperty/Value.h>
template<class TYPE>
eproperty::Value<TYPE>::Value(const TYPE& _defaultValue) :
eproperty::PropertyType<TYPE>(_defaultValue) {
}
template<class TYPE>
std::string eproperty::Value<TYPE>::getValueSpecific(const TYPE& _valueRequested) const {
return etk::to_string(_valueRequested);

34
lutin_eproperty-sample.py Normal file
View File

@ -0,0 +1,34 @@
#!/usr/bin/python
import lutin.module as module
import lutin.tools as tools
import datetime
def get_type():
return "BINARY"
def get_sub_type():
return "SAMPLE"
def get_desc():
return "e-property sample 1"
def get_licence():
return "APACHE-2"
def get_compagny_type():
return "com"
def get_compagny_name():
return "atria-soft"
def get_maintainer():
return ["Mr DUPIN Edouard <yui.heero@gmail.com>"]
def create(target, module_name):
my_module = module.Module(__file__, module_name, get_type())
my_module.add_src_file([
'sample/sampleAll.cpp'
])
my_module.add_module_depend(['eproperty', 'test-debug'])
return my_module

163
sample/sampleAll.cpp Normal file
View File

@ -0,0 +1,163 @@
/** @file
* @author Edouard DUPIN
*
* @copyright 2016, Edouard DUPIN, all right reserved
*
* @license APACHE v2.0 (see license file)
*/
#include <etk/etk.h>
#include <test-debug/debug.h>
//! [eproperty_sample_all]
//! [eproperty_sample_declare_interface]
#include <eproperty/Interface.h>
//! [eproperty_sample_declare_interface]
//! [eproperty_sample_declare_value]
#include <eproperty/Value.h>
//! [eproperty_sample_declare_value]
//! [eproperty_sample_declare_list]
#include <eproperty/List.h>
//! [eproperty_sample_declare_list]
//! [eproperty_sample_declare_range]
#include <eproperty/Range.h>
//! [eproperty_sample_declare_range]
//! [eproperty_sample_declare_an_enum]
enum simpleEnum {
simpleEnum_enum1,
simpleEnum_enum2,
simpleEnum_enum3,
simpleEnum_enum4,
};
//! [eproperty_sample_declare_an_enum]
//! [eproperty_sample_class_with_interface]
//! [eproperty_sample_declare_class_with_interface]
class sampleClassGroup : public eproperty::Interface {
//! [eproperty_sample_declare_class_with_interface]
public:
//! [eproperty_sample_declare_class_property_value]
eproperty::Value<std::string> propertyValue; //!< Simple property Value with type string
//! [eproperty_sample_declare_class_property_value]
//! [eproperty_sample_declare_class_property_list]
eproperty::List<enum simpleEnum> propertyList; //!< Simple property List with type enumeration
//! [eproperty_sample_declare_class_property_list]
//! [eproperty_sample_declare_class_property_range]
eproperty::Range<int32_t> propertyRange; //!< Simple property Range with type integer
//! [eproperty_sample_declare_class_property_range]
sampleClassGroup():
//! [eproperty_sample_initialize_class_property_value]
propertyValue(this, "value", "default value", "optionnal Description", &sampleClassGroup::onPropertyChangeValue),
//! [eproperty_sample_initialize_class_property_value]
//! [eproperty_sample_initialize_class_property_list]
propertyList(this, "list", simpleEnum_enum4),
//! [eproperty_sample_initialize_class_property_list]
//! [eproperty_sample_initialize_class_property_range]
propertyRange(this, "range", 5646546, -5, 555555555) {
//! [eproperty_sample_initialize_class_property_range]
// add all enumeration values
//! [eproperty_sample_initialize_class_property_list_add]
propertyList.add(simpleEnum_enum1, "enum1");
propertyList.add(simpleEnum_enum2, "enum2");
propertyList.add(simpleEnum_enum3, "enum3");
propertyList.add(simpleEnum_enum4, "enum4");
//! [eproperty_sample_initialize_class_property_list_add]
//! [eproperty_sample_initialize_class_property_list_rename]
// Rename an element
propertyList.rename("enum1", "new enum name");
// Remove an element
propertyList.remove("enum2");
//! [eproperty_sample_initialize_class_property_list_rename]
//! [eproperty_sample_initialize_class_property_set_direct]
// no check on the value set (the faster in CPU cycle)
propertyValue.setDirect("New Value to Set");
// Check the internal value (better for range)
propertyRange.setDirectCheck(-5555);
//! [eproperty_sample_initialize_class_property_set_direct]
}
//! [eproperty_sample_initialize_class_property_value_callback]
void onPropertyChangeValue() {
TEST_PRINT("Property value has change ... " << *propertyValue);
TEST_INFO("Use properties:");
//! [eproperty_sample_get_value_value]
TEST_INFO(" value:" << *propertyValue);
//! [eproperty_sample_get_value_value]
//! [eproperty_sample_get_value_range]
TEST_INFO(" range:" << *propertyRange);
//! [eproperty_sample_get_value_range]
//! [eproperty_sample_get_value_list]
TEST_INFO(" list:" << *propertyList);
//! [eproperty_sample_get_value_list]
}
//! [eproperty_sample_initialize_class_property_value_callback]
};
//! [eproperty_sample_class_with_interface]
//! [eproperty_sample_class_without_interface]
class sampleClassSolo {
public:
eproperty::Value<std::string> propertyValue;
eproperty::List<enum simpleEnum> propertyList;
eproperty::Range<int32_t> propertyRange;
sampleClassSolo():
//! [eproperty_sample_initialize_class_property_value2]
propertyValue("default value"),
//! [eproperty_sample_initialize_class_property_value2]
//! [eproperty_sample_initialize_class_property_list2]
propertyList(simpleEnum_enum4),
//! [eproperty_sample_initialize_class_property_list2]
//! [eproperty_sample_initialize_class_property_range2]
propertyRange(5646546, -5, 555555555) {
//! [eproperty_sample_initialize_class_property_range2]
propertyList.add(simpleEnum_enum1, "enum1");
propertyList.add(simpleEnum_enum2, "enum2");
propertyList.add(simpleEnum_enum3, "enum3");
propertyList.add(simpleEnum_enum4, "enum4");
}
};
//! [eproperty_sample_class_without_interface]
void simpleSet() {
//! [eproperty_sample_use_declare_class]
sampleClassGroup myClass;
//! [eproperty_sample_use_declare_class]
//! [eproperty_sample_use_set_value_1]
myClass.propertyValue.set("New Value");
myClass.propertyValue.setString("New Value 2");
//! [eproperty_sample_use_set_value_1]
//! [eproperty_sample_use_set_list_1]
myClass.propertyList.set(simpleEnum_enum3);
myClass.propertyList.setString("enum3");
//! [eproperty_sample_use_set_list_1]
//! [eproperty_sample_use_set_range_1]
myClass.propertyRange.set(15621);
myClass.propertyRange.setString("15621");
//! [eproperty_sample_use_set_range_1]
//! [eproperty_sample_use_set_value_2]
myClass.properties.set("value", "New Value in string");
//! [eproperty_sample_use_set_value_2]
//! [eproperty_sample_use_set_list_2]
myClass.properties.set("list", "enum4");
//! [eproperty_sample_use_set_list_2]
//! [eproperty_sample_use_set_range_2]
myClass.properties.set("range", "-2");
//! [eproperty_sample_use_set_range_2]
}
//! [eproperty_sample_all]
int main(int _argc, const char *_argv[]) {
etk::init(_argc, _argv);
TEST_INFO("simpleSet [START] ***************************");
simpleSet();
TEST_INFO("simpleSet [STOP] ***************************");
return 0;
}

3
test/main.cpp
View File

@ -12,9 +12,6 @@
#include <test-debug/debug.h>
#include <gtest/gtest.h>
#undef __class__
#define __class__ "eproperty-test"
int main(int _argc, const char *_argv[]) {
::testing::InitGoogleTest(&_argc, const_cast<char **>(_argv));
etk::init(_argc, _argv);