Tulip  4.1.0
Better Visualization Through Research
 All Classes Files Functions Variables Enumerations Enumerator Properties Groups Pages
PropertyInterface.h
1 /*
2  *
3  * This file is part of Tulip (www.tulip-software.org)
4  *
5  * Authors: David Auber and the Tulip development Team
6  * from LaBRI, University of Bordeaux 1 and Inria Bordeaux - Sud Ouest
7  *
8  * Tulip is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License
10  * as published by the Free Software Foundation, either version 3
11  * of the License, or (at your option) any later version.
12  *
13  * Tulip is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16  * See the GNU General Public License for more details.
17  *
18  */
19 
20 #ifndef PROPERTY_INTERFACE_H
21 #define PROPERTY_INTERFACE_H
22 
23 #include <string>
24 #include <tulip/tulipconf.h>
25 #include <tulip/Observable.h>
26 #include <tulip/Node.h>
27 #include <tulip/Edge.h>
28 
29 namespace tlp {
30 
31 struct DataMem;
32 
33 class Graph;
34 template<class itType >
35 struct Iterator;
36 class PropertyObserver;
37 
38 //=============================================================
39 /**
40  * @ingroup Graph
41  * @brief PropertyInterface describes the interface of a graph property.
42  *
43  * The intent of a property is to hold a value for each node and edge (e.g. the degree of the nodes).
44  *
45  * A property can be used in two different ways :
46  * Either it is attached to a graph; and in this case creating and deleting the property is handled by the graph
47  * (@see Graph::getProperty()).
48  *
49  * Either is is detached from a graph, and you have to handle creation and deletion yourself.
50  * This is most useful for some algorithms that need a temporary property, but do not want the property to appear on the graph
51  * after the computation.
52  */
53 class TLP_SCOPE PropertyInterface: public Observable {
54  friend class PropertyManager;
55 protected:
56  // name of the property when registered as a property of a graph
57  std::string name;
58  // the graph for whom the property is registered
59  Graph *graph;
60 
61 public:
63 
64  virtual ~PropertyInterface();
65 
66  /**
67  * @brief Erases the value stored for the given node.
68  * The new value for the node is the default value.
69  */
70  virtual void erase(const node) = 0;
71 
72  /**
73  * @brief Erases the value stored for the given edge.
74  * The new value for the edge is the default value.
75  */
76  virtual void erase(const edge) = 0;
77 
78  /**
79  * @brief Copies the value of a node in another property to a node in this property.
80  * @param destination The node whose value will be set.
81  * @param source The node whose value to copy.
82  * @param property The property from which to copy the source node value.
83  * @param ifNotDefault If true, the copy will only be performed if the source node's value is not the default value.
84  * @return True if the copy was performed, false otherwise.
85  */
86  virtual bool copy(const node destination, const node source, PropertyInterface *property,
87  bool ifNotDefault = false) =0;
88  /**
89  * @brief Copies the value of an edge in another property to an edge in this property.
90  * @param destination The edge whose value will be set.
91  * @param source The edge whose value to copy.
92  * @param property The property from which to copy the source edge value.
93  * @param ifNotDefault If true, the copy will only be performed if the source edge's value is not the default value.
94  * @return True if the copy was performed, false otherwise.
95  */
96  virtual bool copy(const edge destination, const edge source, PropertyInterface *property,
97  bool ifNotDefault = false) =0;
98 
99  /**
100  * @brief Copies the values of the passed property to this property.
101  * @param source The property from which to copy values.
102  */
103  virtual void copy(PropertyInterface* source) = 0;
104 
105  /**
106  * @brief Creates a property of the same type (e.g. tlp::DoubleProperty) in the graph.
107  * The new property will not contain a copy of this property's values.
108  * @param graph The Graph in which to create the new property.
109  * @param name The name of the new property.
110  * @return The newly created property.
111  */
112 
113  virtual PropertyInterface* clonePrototype(Graph *graph, const std::string& name) =0;
114 
115  /**
116  * @brief Gets a string describing the type of the property (e.g. "graph", "double", "layout", "string", "integer", "color", "size").
117  * @return The name of this property's type.
118  */
119  virtual std::string getTypename() const = 0;
120 
121  /**
122  * @brief Gets the name of the property (e.g. viewLayout).
123  * @return The name of this property.
124  */
125  const std::string& getName() const {
126  return name;
127  }
128 
129  /**
130  * @cond DOXYGEN_HIDDEN
131  * @brief Gets the graph on which this property has been defined.
132  * This is an internal function and its behavior can change.
133  * DO NOT USE UNLESS YOU KNOW WHAT YOU ARE DOING.
134  *
135  * Be wary that is might be a different graph that the one you used to get this property.
136  * For instance:
137  * @code
138  * Graph* g = tlp::newGraph();
139  * Graph*sub = g->addCloneSubGraph();
140  *
141  * IntegerProperty* prop = g->getProperty<IntegerProperty>("test");
142  * //prop->getGraph() returns g
143  *
144  * IntegerProperty* prop2 = sub->getProperty<IntegerProperty>("test");
145  * //prop2->getGraph() returns g
146  * @endcode
147  *
148  * This is due to the inheritance system of the properties.
149  *
150  * @return The Graph this property is local to.
151  * @endcond
152  */
153  tlp::Graph * getGraph() const {
154  return graph;
155  }
156 
157  /**
158  * @brief Gets a string representation of the node default value.
159  * @param n The node to get the value of.
160  * @return A string representation of the node default value.
161  */
162  virtual std::string getNodeStringValue( const node n ) const = 0;
163 
164  /**
165  * @brief Gets a string representation of the edge default value.
166  * @param e The edge to get the value of.
167  * @return A string representation of the edge default value.
168  */
169  virtual std::string getEdgeStringValue( const edge e ) const = 0;
170 
171  /**
172  * @brief Sets a new value on the node, described by the string parameter.
173  * @param n The node on which to set the new value.
174  * @param value A string describing the value to set on the node.
175  * @return Whether the string was a correct representation for this property's type. If not, the value is not set.
176  */
177  virtual bool setNodeStringValue( const node n, const std::string & value ) = 0;
178 
179  /**
180  * @brief Sets a new value on the edge, described by the string parameter.
181  * @param e The edge on which to set value on.
182  * @param value A string describing the value to set on the edge.
183  * @return Whether the string was a correct representation for this property's type. If not, the value is not set.
184  */
185  virtual bool setEdgeStringValue( const edge e, const std::string & value ) = 0;
186 
187  /**
188  * @brief Gets a string representation of the node default value.
189  * @return A string representation of the node default value.
190  */
191  virtual std::string getNodeDefaultStringValue() const = 0;
192 
193  /**
194  * @brief Gets a string representation of the edge default value.
195  * @return A string representation of the edge default value.
196  */
197  virtual std::string getEdgeDefaultStringValue() const = 0;
198 
199  /**
200  * @brief Sets all the nodes value to the value described by the string. For some types, some parsing will be necessary (e.g. LayoutPorperty).
201  * All previous values are lost.
202  * @param value A string describing the new value to set on all the nodes.
203  * @return Whether the given string was a correct representation for this property's type. If not, the values are not set.
204  */
205  virtual bool setAllNodeStringValue( const std::string & value ) = 0;
206 
207  /**
208  * @brief Sets all the edges value to the value described by the string. For some types, some parsing will be necessary (e.g. LayoutPorperty).
209  * All previous values are lost.
210  * @param value A string describing the new value to set on all the edges.
211  * @return Whether the given string was a correct representation for this property's type. If not, the values are not set.
212  */
213  virtual bool setAllEdgeStringValue( const std::string & value ) = 0;
214 
215  /**
216  * @brief Gets a pointer to the tlp::DataMem structure that contains the node default value.
217  * @return The DataMem structure containing the node default value.
218  * @warning The ownership of this pointer is given to the caller.
219  */
220  virtual DataMem* getNodeDefaultDataMemValue() const = 0;
221 
222  /**
223  * @brief Gets a pointer to the tlp::DataMem structure that contains the edge default value.
224  * @return The DataMem structure containing the edge default value.
225  * @warning The ownership of this pointer is given to the caller.
226  */
227  virtual DataMem* getEdgeDefaultDataMemValue() const = 0;
228 
229  /**
230  * @brief Sets all the nodes value to the value contained in the given DataMem structure.
231  * All previous values are lost.
232  * @param value The value to set on all the nodes.
233  */
234  virtual void setAllNodeDataMemValue(const DataMem* value) = 0;
235 
236  /**
237  * @brief Sets all the edges value to the value contained in the given DataMem structure.
238  * All previous values are lost.
239  * @param value The value to set on all the edges.
240  */
241  virtual void setAllEdgeDataMemValue(const DataMem* v ) = 0;
242 
243  /**
244  * @brief Gets the node value, contained in a tlp::DataMem structure.
245  * @param n The node to get the value of.
246  * @return The value of the node, in a tlp::DataMem.
247  *
248  * @warning The ownership of this pointer is given to the caller.
249  */
250  virtual DataMem* getNodeDataMemValue( const node n ) const = 0;
251 
252  /**
253  * @brief Gets the edge value, contained in a tlp::DataMem structure.
254  * @param n The edge to get the value of.
255  * @return The value of the edge, in a tlp::DataMem.
256  *
257  * @warning The ownership of this pointer is given to the caller.
258  */
259  virtual DataMem* getEdgeDataMemValue( const edge e ) const = 0;
260 
261  /**
262  * @brief Returns the value in a DataMem if it is not default, otherwise returns NULL.
263  * @param n The node to get the value of.
264  * @return The value of the node if it is not default, or NULL.
265  *
266  * @warning The ownership of this pointer is given to the caller.
267  */
268  virtual DataMem* getNonDefaultDataMemValue( const node n ) const = 0;
269 
270  /**
271  * @brief Returns the value in a DataMem if it is not default, otherwise returns NULL.
272  * @param e The edge to get the value of.
273  * @return The value of the edge if it is not default, or NULL.
274  *
275  * @warning The ownership of this pointer is given to the caller.
276  */
277  virtual DataMem* getNonDefaultDataMemValue( const edge e ) const = 0;
278 
279  /**
280  * @brief Sets the node value.
281  * @param n The node to set the value of.
282  * @param value The value to set to this node.
283  */
284  virtual void setNodeDataMemValue( const node n, const DataMem* value) = 0;
285 
286  /**
287  * @brief Sets the edge value.
288  * @param e The edge to set the value of.
289  * @param value The value to set to this edge.
290  */
291  virtual void setEdgeDataMemValue( const edge e, const DataMem* v) = 0;
292 
293  /**
294  * @brief Gets an Iterator on all non-default valuated nodes.
295  * When given a Graph as parameter, only nodes belonging to this graph are iterated over.
296  * @return An Iterator over nodes whose value is not default.
297  *
298  * @warning The ownership of the iterator is given to the caller.
299  */
300  virtual tlp::Iterator<node>* getNonDefaultValuatedNodes(const Graph* = NULL) const = 0;
301 
302  /**
303  * @brief Gets an Iterator on all non-default valuated edges.
304  * When given a Graph as parameter, only edges belonging to this graph are iterated over.
305  * @return An Iterator over edges whose value is not default.
306  *
307  * @warning The ownership of the iterator is given to the caller.
308  */
309  virtual tlp::Iterator<edge>* getNonDefaultValuatedEdges(const Graph* = NULL) const = 0;
310 
311  /**
312  * @brief Sets the value of the metanode to a computed value.
313  *
314  * The value is computed by this property's MetaValueCalculator.
315  * @param metaNode The metanode to compute a value on.
316  * @param subgraph The subgraph pointed by the metanode.
317  * @param metaGraph The graph who owns the meta node.
318  */
319  virtual void computeMetaValue(node metaNode, Graph* subgraph, Graph* metaGraph)=0;
320 
321  /**
322  * @brief Sets the value of the metaedge to a computed value.
323  * @param metaEdge The meta edge to compute a value on.
324  * @param it The edges represented by the meta edge.
325  * @param metaGraph The graph who owns the meta edge.
326  */
327  virtual void computeMetaValue(edge metaEdge, tlp::Iterator<edge>* it, Graph* metaGraph)=0;
328 
329  /**
330  * @brief Base class for computing values on meta nodes and edges.
331  */
333  public:
334  virtual ~MetaValueCalculator() {}
335  };
336 
337  /**
338  * @brief Gets the MetaValueCalculator of this property.
339  * @return The MetaValueCalculator of this property
340  */
342  return metaValueCalculator;
343  }
344 
345  /**
346  * @brief Sets the Calculator for meta nodes and edges.
347  * @param calculator The object containing the logic for computing the meta values for the nodes and edges.
348  *
349  * @warning The ownership of the MetaValueCalculator is not taken by the property.
350  */
351  virtual void setMetaValueCalculator(MetaValueCalculator* calculator) {
352  metaValueCalculator = calculator;
353  }
354 
355  /**
356  * @brief Adds a Listener to this property.
357  * @deprecated Use addListener instead.
358  */
359  void _DEPRECATED addPropertyObserver(Observable *pObs) {
360  addListener(pObs);
361  }
362 
363  /**
364  * @brief Removes a Listener from this property.
365  * @deprecated Use removeListener instead.
366  */
367  void _DEPRECATED removePropertyObserver(Observable *pObs) {
368  removeListener(pObs);
369  }
370 
371  /**
372  * @brief Compares the value this property holds for the two given nodes.
373  * @param n1 The first node to compare the value of.
374  * @param n2 The second node to compare the value of.
375  * @return 0 if the values are identical, a positive value if n1 is greater than n2, and a negative value if n1 is less than n2.
376  */
377  virtual int compare(const node n1,const node n2) const = 0;
378 
379  /**
380  * @brief Compares the value this property holds for the two given edges.
381  * @param e1 The first edge to compare the value of.
382  * @param e2 The second edge to compare the value of.
383  * @return 0 if the values are identical, a positive value if e1 is greater than e2, and a negative value if e1 is less than e2.
384  */
385  virtual int compare(const edge e1,const edge e2) const = 0;
386 
387 protected:
388  MetaValueCalculator* metaValueCalculator;
389 
390  // for notification of PropertyObserver
391  void notifyBeforeSetNodeValue(const node n);
392  void notifyAfterSetNodeValue(const node n);
393  void notifyBeforeSetEdgeValue(const edge e);
394  void notifyAfterSetEdgeValue(const edge e);
395  void notifyBeforeSetAllNodeValue();
396  void notifyAfterSetAllNodeValue();
397  void notifyBeforeSetAllEdgeValue();
398  void notifyAfterSetAllEdgeValue();
399  void notifyDestroy();
400 };
401 
402 /**
403  * @ingroup Observation
404  * @brief Contains additional informations about events on a property,
405  * such as the property it happened on, the node/edge eventually concerned and such.
406  * It also contains the detailed type of the event.
407  */
408 class TLP_SCOPE PropertyEvent :public Event {
409 public:
410 
411  // be careful about the ordering of the constants
412  // in the enum below because it is used in some assertions
413  enum PropertyEventType {TLP_BEFORE_SET_NODE_VALUE = 0,
414  TLP_AFTER_SET_NODE_VALUE,
415  TLP_BEFORE_SET_ALL_NODE_VALUE,
416  TLP_AFTER_SET_ALL_NODE_VALUE,
417  TLP_BEFORE_SET_ALL_EDGE_VALUE,
418  TLP_AFTER_SET_ALL_EDGE_VALUE,
419  TLP_BEFORE_SET_EDGE_VALUE,
420  TLP_AFTER_SET_EDGE_VALUE
421  };
422  PropertyEvent(const PropertyInterface& prop, PropertyEventType propEvtType,
423  Event::EventType evtType = Event::TLP_MODIFICATION,
424  unsigned int id = UINT_MAX)
425  : Event(prop, evtType), evtType(propEvtType), eltId(id) {}
426 
427  PropertyInterface* getProperty() const {
428  return reinterpret_cast<PropertyInterface *>(sender());
429  }
430 
431  node getNode() const {
432  assert(evtType < TLP_BEFORE_SET_ALL_NODE_VALUE);
433  return node(eltId);
434  }
435 
436  edge getEdge() const {
437  assert(evtType > TLP_AFTER_SET_ALL_EDGE_VALUE);
438  return edge(eltId);
439  }
440 
441  PropertyEventType getType() const {
442  return evtType;
443  }
444 
445 protected:
446  PropertyEventType evtType;
447  unsigned int eltId;
448 };
449 }
450 
451 //================================================================================
452 // these functions allow to use tlp::PropertyInterface as a key in a hash-based data structure (e.g. hashmap).
453 //================================================================================
454 #ifndef DOXYGEN_NOTFOR_DEVEL
455 
456 TLP_BEGIN_HASH_NAMESPACE {
457  template <>
458  struct TLP_SCOPE hash<const tlp::PropertyInterface *> {
459  size_t operator()(const tlp::PropertyInterface *prop) const {return size_t(prop);}
460  };
461  template <>
462  struct TLP_SCOPE hash<tlp::PropertyInterface *> {
463  size_t operator()(tlp::PropertyInterface *prop) const {return size_t(prop);}
464  };
465 } TLP_END_HASH_NAMESPACE
466 
467 #endif // DOXYGEN_NOTFOR_DEVEL
468 
469 #endif // PROPERTY_INTERFACE_H