extension.h 5.26 KB
Newer Older
1
2
3
4
5
6
/**
\page subp_how_to_use Using this package

\section usecase How to use this package

\subsection use_programmatically General introduction
7
8
9

For control purposes the main use of this package is to create new entities and connect them through signals.

10
Objects, which are derived from Entities (base class dynamicgraph::Entity), can be
11
declared within the code and compiled as shared libraries (.so/.dll files).
12
13
14
15
16
17
These libraries can be loaded at run-time using the PluginLoader methods,
and at the same time register their class names to the Factory (see the
examples in the <a href="http://projects.laas.fr/gepetto/doc/stack-of-tasks/sot-core/master/doxygen-html">sot-core documentation</a> 
for advanced control examples).

The Factory can then create instances of these objects and subsequently
18
register them in the Pool. From the pool they can be listed, accessed, and acted upon
19
20
21
22
23
24
25
26
27
28
29
30
31
32
(see PoolStorage documentation). Basic commands defined by entities include
signal connection graph file generation, help and name print, and signals.
This is usually done through a scripting language such as python (see
<a hef="https://github.com/stack-of-tasks/dynamic-graph-python">dynamic-graph-python</a>)

The singletons made available by including the corresponding headers in this
module are:
\li dynamicgraph::FactoryStorage
\li dynamicgraph::PoolStorage

For an example of a program creating entities in C++, see the unit test
test_pool.cpp (in your package source directory/tests).

\subsection Tutorial
33
34
A tutorial is available <a href="http://stack-of-tasks.github.io/dynamic-graph-tutorial/">here</a>.
It is providing a step-by-step way of building an entity
35
36
37

\section sec_htw_helpers Helpers

38

39
40
When writing entities you might use some macros which are very useful to write your class.

41
42
43
\subsection subsec_howto_typedef Entity helpers

The header <b>entity-helper.h</b> is defining a type called EntityClassName 
44

45
46
\section sec_howto_macros_helpers Macro helpers

47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
\subsection subsec_howto_macros_helpers_ent Preprocessing macros for entities

<ul> 
  <li> <b>DYNAMIC_GRAPH_ENTITY_DECL()</b>:
  This macro creates a method <b>getClassName()</b> which returns the class name.</li>
  This macro <b>should</b> be used in the declaration of the class.
  </li> 
  <li> <b>DYNAMICGRAPH_FACTORY_ENTITY_PLUGIN(classtype,classname)</b>
  This macros creates the methods necessary to have a factory building the C++ class 
  <b>classtype</b> from the string <b>classname</b>.
  This macro <b>should</b> be used in the implementation of the class.
  </li>
</ul>

\subsection subsec_howto_macros_helpers_sig Preprocessing macros for signals
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

<ul>
  <li>  Macro for input signals
    <ul>
      <li> <b>DECLARE_SIGNAL_IN(signal_name,type)</b>:
      Declare an input time dependent signal as a field of the class with the following name:
      \code
      m_signal_nameSIN
      \endcode
      </li>
      <li> <b>CONSTRUCT_SIGNAL_IN(signal_name,type)</b>:
      This macro is used in the constructor of the entity class handling this signal.
      It is calling the signal constructor and set the signal name to:
      \code
      EntityClassName(entity-name)::input(type)::signal_name
      \endcode
    </ul>
  </li>
  <li>  Macro for output signals
    <ul>
      <li> <b>DECLARE_SIGNAL_OUT(signal_name,type)</b>:
      Declare an output time dependent signal as a field of the class with the following name:
      \code
      m_signal_nameSOUT
      \endcode
      It also declares a method with the following pattern:
      \code
      type signal_nameSOUT_function(type &,int)
      \endcode
      The second pattern is the time when calling the output.
      </li>
      <li> <b>CONSTRUCT_SIGNAL_OUT(signal_name,type)</b>
      This macro is used in the constructor of the entity class handling this signal.
      It creates the binding to the method described previously, and set the signal name to:
      \code
      EntityClassName(entity_name)::output(type)::signal_name
      \endcode
      where entity_name is the name of the entity currently instanciated.
      </li>

      <li> <b>DEFINE_SIGNAL_OUT_FUNCTION(signal_name, type)</b>:
      This macro is used when implementing the method specific to the output signal.
      It is used in the main body of the entity class to declare the header of the method 
      with the following pattern:
      \code
      type EntityClassName::signal_nameSOUT_function(type &, int iter)
      \endcode
      </li>

    </ul>
  <li> 
113
114
  </li> Inner signals
    <ul>
115
116
117
118
119
120
      <li> <b> DECLARE_SIGNAL_INNER(signal_name,type)</b>
      Inner signal are signal that depend on a state of the entity and not on input signals.
      This macro declares an inner signal with the following pattern:
      \code
      m_signal_nameSINNER
      \endcode
121
122
123
124
125
126
127
128
129
130
131
132
133
      It also creates a member function with the following pattern:
      \code
      type & EntityClassName::nameSINNER_function(signal_name)(type &, int)
      \endcode
      </li>
      <li> <b>DEFINE_SIGNAL_INNER_FUNCTION(signal_name,type)</b> 
      This macro is used to implement the method related to signal_name. More precisely 
      it provides the header of the member function(i.e. method) declaration.
      </li>
      <li><b>DECLARE_SIGNAL_INNER_FUNCTION(signal_name,type)</b>
      This macros declares the member function used to handle the access to this signal.
      </li>
    </ul>
134
</ul>
135
136

*/