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