Tulip  4.8.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
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 <iostream>
25 #include <tulip/tulipconf.h>
26 #include <tulip/Observable.h>
27 #include <tulip/Node.h>
28 #include <tulip/Edge.h>
29 
30 namespace tlp {
31 
32 struct DataMem;
33 
34 class Graph;
35 template<class itType >
36 struct Iterator;
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 source property to this property.
101  * @param source The property from which to copy values.
102  * @warning Be careful when using this method, if you are interested by observing the updates of the values of the current property, because no event is sent for nodes/edges whose value is the default value of the source property.
103  */
104  virtual void copy(PropertyInterface* source) = 0;
105 
106  /**
107  * @brief Creates a property of the same type (e.g. tlp::DoubleProperty) in the graph.
108  * The new property will not contain a copy of this property's values.
109  * @param graph The Graph in which to create the new property.
110  * @param name The name of the new property.
111  * @return The newly created property.
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 const 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  * @brief Rename a property
131  * @param the new name
132  * @return returns true if the renaming succeed.
133  * It may fails if a property with the given name already exists
134  */
135  bool rename(const std::string& newName);
136  /**
137  * @cond DOXYGEN_HIDDEN
138  * @brief Gets the graph on which this property has been defined.
139  * This is an internal function and its behavior can change.
140  * DO NOT USE UNLESS YOU KNOW WHAT YOU ARE DOING.
141  *
142  * Be wary that is might be a different graph that the one you used to get this property.
143  * For instance:
144  * @code
145  * Graph* g = tlp::newGraph();
146  * Graph*sub = g->addCloneSubGraph();
147  *
148  * IntegerProperty* prop = g->getProperty<IntegerProperty>("test");
149  * //prop->getGraph() returns g
150  *
151  * IntegerProperty* prop2 = sub->getProperty<IntegerProperty>("test");
152  * //prop2->getGraph() returns g
153  * @endcode
154  *
155  * This is due to the inheritance system of the properties.
156  *
157  * @return The Graph this property is local to.
158  * @endcond
159  */
160  tlp::Graph * getGraph() const {
161  return graph;
162  }
163 
164  /**
165  * @brief Gets a string representation of the node default value.
166  * @param n The node to get the value of.
167  * @return A string representation of the node default value.
168  */
169  virtual std::string getNodeStringValue( const node n ) const = 0;
170 
171  /**
172  * @brief Gets a string representation of the edge default value.
173  * @param e The edge to get the value of.
174  * @return A string representation of the edge default value.
175  */
176  virtual std::string getEdgeStringValue( const edge e ) const = 0;
177 
178  /**
179  * @brief Sets a new value on the node, represented by the string parameter.
180  * @param n The node on which to set the new value.
181  * @param value A string representing the value to set on the node.
182  * @return Whether the string was a correct representation for this property's type. If not, the value is not set.
183  */
184  virtual bool setNodeStringValue( const node n, const std::string & value ) = 0;
185 
186  /**
187  * @brief Sets a new value on the edge, represented by the string parameter.
188  * @param e The edge on which to set value on.
189  * @param value A string representing the value to set on the edge.
190  * @return Whether the string was a correct representation for this property's type. If not, the value is not set.
191  */
192  virtual bool setEdgeStringValue( const edge e, const std::string & value ) = 0;
193 
194  /**
195  * @brief Gets a string representation of the node default value.
196  * @return A string representation of the node default value.
197  */
198  virtual std::string getNodeDefaultStringValue() const = 0;
199 
200  /**
201  * @brief Gets a string representation of the edge default value.
202  * @return A string representation of the edge default value.
203  */
204  virtual std::string getEdgeDefaultStringValue() const = 0;
205 
206  /**
207  * @brief Sets all the nodes value to the value represented by the string. For some types, some parsing will be necessary (e.g. LayoutPorperty).
208  * All previous values are lost and the represented value is assigned as the default one to the future added nodes.
209  * @param value A string representing the new value to set on all the nodes.
210  * @return Whether the given string was a correct representation for this property's type. If not, the values are not set.
211  */
212  virtual bool setAllNodeStringValue( const std::string & value ) = 0;
213 
214  /**
215  * @brief Sets all the edges value to the value represented by the string. For some types, some parsing will be necessary (e.g. LayoutPorperty).
216  * All previous values are lost and the represented value is assigned as the default one to the future added edges.
217  * @param value A string representing the new value to set on all the edges.
218  * @return Whether the given string was a correct representation for this property's type. If not, the values are not set.
219  */
220  virtual bool setAllEdgeStringValue( const std::string & value ) = 0;
221 
222  /**
223  * @brief Gets a pointer to the tlp::DataMem structure that contains the node default value.
224  * @return The DataMem structure containing the node default value.
225  * @warning The ownership of this pointer is given to the caller.
226  */
227  virtual DataMem* getNodeDefaultDataMemValue() const = 0;
228 
229  /**
230  * @brief Gets a pointer to the tlp::DataMem structure that contains the edge default value.
231  * @return The DataMem structure containing the edge default value.
232  * @warning The ownership of this pointer is given to the caller.
233  */
234  virtual DataMem* getEdgeDefaultDataMemValue() const = 0;
235 
236  /**
237  * @brief Sets all the nodes 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 nodes.
240  */
241  virtual void setAllNodeDataMemValue(const DataMem* value) = 0;
242 
243  /**
244  * @brief Sets all the edges value to the value contained in the given DataMem structure.
245  * All previous values are lost.
246  * @param value The value to set on all the edges.
247  */
248  virtual void setAllEdgeDataMemValue(const DataMem* v ) = 0;
249 
250  /**
251  * @brief Gets the node value, contained in a tlp::DataMem structure.
252  * @param n The node to get the value of.
253  * @return The value of the node, in a tlp::DataMem.
254  *
255  * @warning The ownership of this pointer is given to the caller.
256  */
257  virtual DataMem* getNodeDataMemValue( const node n ) const = 0;
258 
259  /**
260  * @brief Gets the edge value, contained in a tlp::DataMem structure.
261  * @param n The edge to get the value of.
262  * @return The value of the edge, in a tlp::DataMem.
263  *
264  * @warning The ownership of this pointer is given to the caller.
265  */
266  virtual DataMem* getEdgeDataMemValue( const edge e ) const = 0;
267 
268  /**
269  * @brief Returns the value in a DataMem if it is not default, otherwise returns NULL.
270  * @param n The node to get the value of.
271  * @return The value of the node if it is not default, or NULL.
272  *
273  * @warning The ownership of this pointer is given to the caller.
274  */
275  virtual DataMem* getNonDefaultDataMemValue( const node n ) const = 0;
276 
277  /**
278  * @brief Returns the value in a DataMem if it is not default, otherwise returns NULL.
279  * @param e The edge to get the value of.
280  * @return The value of the edge if it is not default, or NULL.
281  *
282  * @warning The ownership of this pointer is given to the caller.
283  */
284  virtual DataMem* getNonDefaultDataMemValue( const edge e ) const = 0;
285 
286  /**
287  * @brief Sets the node value.
288  * @param n The node to set the value of.
289  * @param value The value to set to this node.
290  */
291  virtual void setNodeDataMemValue( const node n, const DataMem* value) = 0;
292 
293  /**
294  * @brief Sets the edge value.
295  * @param e The edge to set the value of.
296  * @param value The value to set to this edge.
297  */
298  virtual void setEdgeDataMemValue( const edge e, const DataMem* v) = 0;
299 
300  /**
301  * @brief Gets an Iterator on all non-default valuated nodes.
302  * When given a Graph as parameter, only nodes belonging to this graph are iterated over.
303  * @return An Iterator over nodes whose value is not default.
304  *
305  * @warning The ownership of the iterator is given to the caller.
306  */
307  virtual tlp::Iterator<node>* getNonDefaultValuatedNodes(const Graph* = NULL) const = 0;
308 
309  /**
310  * @brief Returns the number of nodes with a non default value.
311  * When given a Graph as parameter, only the number of nodes with a non default value belonging to this graph is returned.
312  * @return the number of nodes with a non default value.
313  *
314  */
315  virtual unsigned int numberOfNonDefaultValuatedNodes(const Graph* = NULL) const = 0;
316 
317  /**
318  * @brief Gets an Iterator on all non-default valuated edges.
319  * When given a Graph as parameter, only edges belonging to this graph are iterated over.
320  * @return An Iterator over edges whose value is not default.
321  *
322  * @warning The ownership of the iterator is given to the caller.
323  */
324  virtual tlp::Iterator<edge>* getNonDefaultValuatedEdges(const Graph* = NULL) const = 0;
325 
326  /**
327  * @brief Returns the number of edges with a non default value.
328  * @return the number of edges with a non default value.
329  *
330  */
331  virtual unsigned int numberOfNonDefaultValuatedEdges(const Graph* = NULL) const = 0;
332 
333  /**
334  * @brief Returns the size in bytes of a node's value.
335  * @return the size of a node's value (0 means the size is not fixed)
336  *
337  */
338  virtual unsigned int nodeValueSize() const = 0;
339 
340  /**
341  * @brief Writes the nodes default value
342  *
343  */
344  virtual void writeNodeDefaultValue(std::ostream&) const = 0;
345 
346  /**
347  * @brief Writes the value of a node
348  *
349  */
350  virtual void writeNodeValue(std::ostream&, node) const = 0;
351 
352  /**
353  * @brief Reads the nodes default value
354  *
355  */
356  virtual bool readNodeDefaultValue(std::istream&) = 0;
357 
358  /**
359  * @brief Reads the value of a node
360  *
361  */
362  virtual bool readNodeValue(std::istream&, node) = 0;
363 
364  /**
365  * @brief Returns the size in bytes of an edge's value.
366  * @return the size of a node's value (0 means the size is not fixed)
367  *
368  */
369  virtual unsigned int edgeValueSize() const = 0;
370 
371  /**
372  * @brief Writes the edges default value
373  *
374  */
375  virtual void writeEdgeDefaultValue(std::ostream&) const = 0;
376 
377  /**
378  * @brief Writes the value of an edge
379  *
380  */
381  virtual void writeEdgeValue(std::ostream&, edge) const = 0;
382 
383  /**
384  * @brief Reads the edges default value
385  *
386  */
387  virtual bool readEdgeDefaultValue(std::istream&) = 0;
388 
389  /**
390  * @brief Reads the value of an edge
391  *
392  */
393  virtual bool readEdgeValue(std::istream&, edge) = 0;
394 
395  /**
396  * @brief Sets the value of the metanode to a computed value.
397  *
398  * The value is computed by this property's MetaValueCalculator.
399  * @param metaNode The metanode to compute a value on.
400  * @param subgraph The subgraph pointed by the metanode.
401  * @param metaGraph The graph who owns the meta node.
402  */
403  virtual void computeMetaValue(node metaNode, Graph* subgraph, Graph* metaGraph)=0;
404 
405  /**
406  * @brief Sets the value of the metaedge to a computed value.
407  * @param metaEdge The meta edge to compute a value on.
408  * @param it The edges represented by the meta edge.
409  * @param metaGraph The graph who owns the meta edge.
410  */
411  virtual void computeMetaValue(edge metaEdge, tlp::Iterator<edge>* it, Graph* metaGraph)=0;
412 
413  /**
414  * @brief Base class for computing values on meta nodes and edges.
415  */
417  public:
418  virtual ~MetaValueCalculator() {}
419  };
420 
421  /**
422  * @brief Gets the MetaValueCalculator of this property.
423  * @return The MetaValueCalculator of this property
424  */
426  return metaValueCalculator;
427  }
428 
429  /**
430  * @brief Sets the Calculator for meta nodes and edges.
431  * @param calculator The object containing the logic for computing the meta values for the nodes and edges.
432  *
433  * @warning The ownership of the MetaValueCalculator is not taken by the property.
434  */
435  virtual void setMetaValueCalculator(MetaValueCalculator* calculator) {
436  metaValueCalculator = calculator;
437  }
438 
439  /**
440  * @brief Compares the value this property holds for the two given nodes.
441  * @param n1 The first node to compare the value of.
442  * @param n2 The second node to compare the value of.
443  * @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.
444  */
445  virtual int compare(const node n1,const node n2) const = 0;
446 
447  /**
448  * @brief Compares the value this property holds for the two given edges.
449  * @param e1 The first edge to compare the value of.
450  * @param e2 The second edge to compare the value of.
451  * @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.
452  */
453  virtual int compare(const edge e1,const edge e2) const = 0;
454 
455 protected:
456  MetaValueCalculator* metaValueCalculator;
457 
458  // for notification of PropertyObserver
459  void notifyBeforeSetNodeValue(const node n);
460  void notifyAfterSetNodeValue(const node n);
461  void notifyBeforeSetEdgeValue(const edge e);
462  void notifyAfterSetEdgeValue(const edge e);
463  void notifyBeforeSetAllNodeValue();
464  void notifyAfterSetAllNodeValue();
465  void notifyBeforeSetAllEdgeValue();
466  void notifyAfterSetAllEdgeValue();
467  void notifyDestroy();
468  void notifyRename(const std::string& newName);
469 };
470 
471 /**
472  * @ingroup Graph
473  * @brief VectorPropertyInterface describes the interface of a graph property whose holded value is a vector (std::vector)
474  *
475  */
477 public:
479 
481 
482  /**
483  * @brief Sets a new vector represented by the string parameter as the node value.
484  * @param n The node on which to set the new value.
485  * @param value A string listing the elements of the vector to set on the node.
486  * @param openChar an optional character opening the list of elements. Default value is '('; when set to '\0' it indicates that there is no opening character.
487  * @param sepChar an optional character separing the elements of the list. Default value is ','.
488  * @param closeChar an optional character closing the list of elements. Default value is ')'; when set to '\0' it indicates that there is no opening character.
489  * @return Whether the string was a correct representation for this property's type. If not, the value is not set.
490  */
491  virtual bool setNodeStringValueAsVector(const node n, const std::string & value, char openChar = '(', char sepChar = ',', char closeChar = ')') = 0;
492 
493  /**
494  * @brief Sets a new vector represented by the string parameter as the edge value.
495  * @param e The edge on which to set value on.
496  * @param value A string listing the elements of the vector to set on the edge.
497  * @param openChar an optional character opening the list of elements. Default value is '('; when set to '\0' it indicates that there is no opening character.
498  * @param sepChar an optional character separing the elements of the list. Default value is ','.
499  * @param closeChar an optional character closing the list of elements. Default value is ')'; when set to '\0' it indicates that there is no opening character.
500  * @return Whether the string was a correct representation for this property's type. If not, the value is not set.
501  */
502  virtual bool setEdgeStringValueAsVector(const edge e, const std::string & value, char openChar = '(', char sepChar = ',', char closeChar = ')') = 0;
503 };
504 
505 /**
506  * @ingroup Observation
507  * @brief Contains additional information about events on a property,
508  * such as the property it happened on, the node/edge eventually concerned and such.
509  * It also contains the detailed type of the event.
510  */
511 class TLP_SCOPE PropertyEvent :public Event {
512 public:
513 
514  // be careful about the ordering of the constants
515  // in the enum below because it is used in some assertions
516  enum PropertyEventType {TLP_BEFORE_SET_NODE_VALUE = 0,
517  TLP_AFTER_SET_NODE_VALUE,
518  TLP_BEFORE_SET_ALL_NODE_VALUE,
519  TLP_AFTER_SET_ALL_NODE_VALUE,
520  TLP_BEFORE_SET_ALL_EDGE_VALUE,
521  TLP_AFTER_SET_ALL_EDGE_VALUE,
522  TLP_BEFORE_SET_EDGE_VALUE,
523  TLP_AFTER_SET_EDGE_VALUE
524  };
525  PropertyEvent(const PropertyInterface& prop, PropertyEventType propEvtType,
526  Event::EventType evtType = Event::TLP_MODIFICATION,
527  unsigned int id = UINT_MAX)
528  : Event(prop, evtType), evtType(propEvtType), eltId(id) {}
529 
530  PropertyInterface* getProperty() const {
531  return reinterpret_cast<PropertyInterface *>(sender());
532  }
533 
534  node getNode() const {
535  assert(evtType < TLP_BEFORE_SET_ALL_NODE_VALUE);
536  return node(eltId);
537  }
538 
539  edge getEdge() const {
540  assert(evtType > TLP_AFTER_SET_ALL_EDGE_VALUE);
541  return edge(eltId);
542  }
543 
544  PropertyEventType getType() const {
545  return evtType;
546  }
547 
548 protected:
549  PropertyEventType evtType;
550  unsigned int eltId;
551 };
552 }
553 
554 //================================================================================
555 // these functions allow to use tlp::PropertyInterface as a key in a hash-based data structure (e.g. hashmap).
556 //================================================================================
557 #ifndef DOXYGEN_NOTFOR_DEVEL
558 
559 TLP_BEGIN_HASH_NAMESPACE {
560  template <>
561  struct TLP_SCOPE hash<const tlp::PropertyInterface *> {
562  size_t operator()(const tlp::PropertyInterface *prop) const {return size_t(prop);}
563  };
564  template <>
565  struct TLP_SCOPE hash<tlp::PropertyInterface *> {
566  size_t operator()(tlp::PropertyInterface *prop) const {return size_t(prop);}
567  };
568 } TLP_END_HASH_NAMESPACE
569 
570 #endif // DOXYGEN_NOTFOR_DEVEL
571 
572 #endif // PROPERTY_INTERFACE_H
PropertyInterface describes the interface of a graph property.
Contains additional information about events on a property, such as the property it happened on...
MetaValueCalculator * getMetaValueCalculator()
Gets the MetaValueCalculator of this property.
The edge struct represents an edge in a Graph object.
Definition: Edge.h:39
The node struct represents a node in a Graph object.
Definition: Node.h:39
VectorPropertyInterface describes the interface of a graph property whose holded value is a vector (s...
Event is the base class for all events used in the Observation mechanism.
Definition: Observable.h:47
const std::string & getName() const
Gets the name of the property (e.g. viewLayout).
Base class for computing values on meta nodes and edges.
virtual void setMetaValueCalculator(MetaValueCalculator *calculator)
Sets the Calculator for meta nodes and edges.
The Observable class is the base of Tulip's observation system.
Definition: Observable.h:123