Tulip  4.10.0
Better Visualization Through Research
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) const =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  * @param graph (since Tulip 4.10) An optional descendant graph from the one associated to that property (itself included).
211  * If provided, only the nodes from that descendant graph will have their value modified.
212  * In the case of the descendant graph is different from the one associated to that property, the default node value will not be modified.
213  * @warning If the provided graph is not a descendant of the one associated to that property, no node value will be modified in it.
214  * @return Whether the given string was a correct representation for this property's type. If not, the values are not set.
215  */
216  virtual bool setAllNodeStringValue( const std::string & value, const Graph *graph = NULL ) = 0;
217 
218  /**
219  * @brief Sets all the edges value to the value represented by the string. For some types, some parsing will be necessary (e.g. LayoutPorperty).
220  * All previous values are lost and the represented value is assigned as the default one to the future added edges.
221  * @param value A string representing the new value to set on all the edges.
222  * @param graph (since Tulip 4.10)An optional descendant graph from the one associated to that property (itself included).
223  * If provided, only the edges from that descendant graph will have their value modified.
224  * In the case of the descendant graph is different from the one associated to that property, the default edge value will not be modified.
225  * @warning If the provided graph is not a descendant of the one associated to that property, no edge value will be modified in it.
226  * @return Whether the given string was a correct representation for this property's type. If not, the values are not set.
227  */
228  virtual bool setAllEdgeStringValue( const std::string & value, const Graph *graph = NULL ) = 0;
229 
230  /**
231  * @brief Gets a pointer to the tlp::DataMem structure that contains the node default value.
232  * @return The DataMem structure containing the node default value.
233  * @warning The ownership of this pointer is given to the caller.
234  */
235  virtual DataMem* getNodeDefaultDataMemValue() const = 0;
236 
237  /**
238  * @brief Gets a pointer to the tlp::DataMem structure that contains the edge default value.
239  * @return The DataMem structure containing the edge default value.
240  * @warning The ownership of this pointer is given to the caller.
241  */
242  virtual DataMem* getEdgeDefaultDataMemValue() const = 0;
243 
244  /**
245  * @brief Sets all the nodes value to the value contained in the given DataMem structure.
246  * All previous values are lost.
247  * @param value The value to set on all the nodes.
248  */
249  virtual void setAllNodeDataMemValue(const DataMem* value) = 0;
250 
251  /**
252  * @brief Sets all the edges value to the value contained in the given DataMem structure.
253  * All previous values are lost.
254  * @param value The value to set on all the edges.
255  */
256  virtual void setAllEdgeDataMemValue(const DataMem* v ) = 0;
257 
258  /**
259  * @brief Gets the node value, contained in a tlp::DataMem structure.
260  * @param n The node to get the value of.
261  * @return The value of the node, in a tlp::DataMem.
262  *
263  * @warning The ownership of this pointer is given to the caller.
264  */
265  virtual DataMem* getNodeDataMemValue( const node n ) const = 0;
266 
267  /**
268  * @brief Gets the edge value, contained in a tlp::DataMem structure.
269  * @param n The edge to get the value of.
270  * @return The value of the edge, in a tlp::DataMem.
271  *
272  * @warning The ownership of this pointer is given to the caller.
273  */
274  virtual DataMem* getEdgeDataMemValue( const edge e ) const = 0;
275 
276  /**
277  * @brief Returns the value in a DataMem if it is not default, otherwise returns NULL.
278  * @param n The node to get the value of.
279  * @return The value of the node 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 node n ) const = 0;
284 
285  /**
286  * @brief Returns the value in a DataMem if it is not default, otherwise returns NULL.
287  * @param e The edge to get the value of.
288  * @return The value of the edge if it is not default, or NULL.
289  *
290  * @warning The ownership of this pointer is given to the caller.
291  */
292  virtual DataMem* getNonDefaultDataMemValue( const edge e ) const = 0;
293 
294  /**
295  * @brief Sets the node value.
296  * @param n The node to set the value of.
297  * @param value The value to set to this node.
298  */
299  virtual void setNodeDataMemValue( const node n, const DataMem* value) = 0;
300 
301  /**
302  * @brief Sets the edge value.
303  * @param e The edge to set the value of.
304  * @param value The value to set to this edge.
305  */
306  virtual void setEdgeDataMemValue( const edge e, const DataMem* v) = 0;
307 
308  /**
309  * @brief Gets an Iterator on all non-default valuated nodes.
310  * When given a Graph as parameter, only nodes belonging to this graph are iterated over.
311  * @return An Iterator over nodes whose value is not default.
312  *
313  * @warning The ownership of the iterator is given to the caller.
314  */
315  virtual tlp::Iterator<node>* getNonDefaultValuatedNodes(const Graph* = NULL) const = 0;
316 
317  /**
318  * @brief Returns the number of nodes with a non default value.
319  * When given a Graph as parameter, only the number of nodes with a non default value belonging to this graph is returned.
320  * @return the number of nodes with a non default value.
321  *
322  */
323  virtual unsigned int numberOfNonDefaultValuatedNodes(const Graph* = NULL) const = 0;
324 
325  /**
326  * @brief Gets an Iterator on all non-default valuated edges.
327  * When given a Graph as parameter, only edges belonging to this graph are iterated over.
328  * @return An Iterator over edges whose value is not default.
329  *
330  * @warning The ownership of the iterator is given to the caller.
331  */
332  virtual tlp::Iterator<edge>* getNonDefaultValuatedEdges(const Graph* = NULL) const = 0;
333 
334  /**
335  * @brief Returns the number of edges with a non default value.
336  * @return the number of edges with a non default value.
337  *
338  */
339  virtual unsigned int numberOfNonDefaultValuatedEdges(const Graph* = NULL) const = 0;
340 
341  /**
342  * @brief Returns the size in bytes of a node's value.
343  * @return the size of a node's value (0 means the size is not fixed)
344  *
345  */
346  virtual unsigned int nodeValueSize() const = 0;
347 
348  /**
349  * @brief Writes the nodes default value
350  *
351  */
352  virtual void writeNodeDefaultValue(std::ostream&) const = 0;
353 
354  /**
355  * @brief Writes the value of a node
356  *
357  */
358  virtual void writeNodeValue(std::ostream&, node) const = 0;
359 
360  /**
361  * @brief Reads the nodes default value
362  *
363  */
364  virtual bool readNodeDefaultValue(std::istream&) = 0;
365 
366  /**
367  * @brief Reads the value of a node
368  *
369  */
370  virtual bool readNodeValue(std::istream&, node) = 0;
371 
372  /**
373  * @brief Returns the size in bytes of an edge's value.
374  * @return the size of a node's value (0 means the size is not fixed)
375  *
376  */
377  virtual unsigned int edgeValueSize() const = 0;
378 
379  /**
380  * @brief Writes the edges default value
381  *
382  */
383  virtual void writeEdgeDefaultValue(std::ostream&) const = 0;
384 
385  /**
386  * @brief Writes the value of an edge
387  *
388  */
389  virtual void writeEdgeValue(std::ostream&, edge) const = 0;
390 
391  /**
392  * @brief Reads the edges default value
393  *
394  */
395  virtual bool readEdgeDefaultValue(std::istream&) = 0;
396 
397  /**
398  * @brief Reads the value of an edge
399  *
400  */
401  virtual bool readEdgeValue(std::istream&, edge) = 0;
402 
403  /**
404  * @brief Sets the value of the metanode to a computed value.
405  *
406  * The value is computed by this property's MetaValueCalculator.
407  * @param metaNode The metanode to compute a value on.
408  * @param subgraph The subgraph pointed by the metanode.
409  * @param metaGraph The graph who owns the meta node.
410  */
411  virtual void computeMetaValue(node metaNode, const Graph* subgraph, const Graph* metaGraph)=0;
412 
413  /**
414  * @brief Sets the value of the metaedge to a computed value.
415  * @param metaEdge The meta edge to compute a value on.
416  * @param it The edges represented by the meta edge.
417  * @param metaGraph The graph who owns the meta edge.
418  */
419  virtual void computeMetaValue(edge metaEdge, tlp::Iterator<edge>* it, const Graph* metaGraph)=0;
420 
421  /**
422  * @brief Base class for computing values on meta nodes and edges.
423  */
425  public:
426  virtual ~MetaValueCalculator() {}
427  };
428 
429  /**
430  * @brief Gets the MetaValueCalculator of this property.
431  * @return The MetaValueCalculator of this property
432  */
434  return metaValueCalculator;
435  }
436 
437  /**
438  * @brief Sets the Calculator for meta nodes and edges.
439  * @param calculator The object containing the logic for computing the meta values for the nodes and edges.
440  *
441  * @warning The ownership of the MetaValueCalculator is not taken by the property.
442  */
443  virtual void setMetaValueCalculator(MetaValueCalculator* calculator) {
444  metaValueCalculator = calculator;
445  }
446 
447  /**
448  * @brief Compares the value this property holds for the two given nodes.
449  * @param n1 The first node to compare the value of.
450  * @param n2 The second node to compare the value of.
451  * @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.
452  */
453  virtual int compare(const node n1,const node n2) const = 0;
454 
455  /**
456  * @brief Compares the value this property holds for the two given edges.
457  * @param e1 The first edge to compare the value of.
458  * @param e2 The second edge to compare the value of.
459  * @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.
460  */
461  virtual int compare(const edge e1,const edge e2) const = 0;
462 
463 protected:
464  MetaValueCalculator* metaValueCalculator;
465 
466  // for notification of PropertyObserver
467  void notifyBeforeSetNodeValue(const node n);
468  void notifyAfterSetNodeValue(const node n);
469  void notifyBeforeSetEdgeValue(const edge e);
470  void notifyAfterSetEdgeValue(const edge e);
471  void notifyBeforeSetAllNodeValue();
472  void notifyAfterSetAllNodeValue();
473  void notifyBeforeSetAllEdgeValue();
474  void notifyAfterSetAllEdgeValue();
475  void notifyDestroy();
476  void notifyRename(const std::string& newName);
477 };
478 
479 /**
480  * @ingroup Graph
481  * @brief VectorPropertyInterface describes the interface of a graph property whose holded value is a vector (std::vector)
482  *
483  */
485 public:
487 
489 
490  /**
491  * @brief Sets a new vector represented by the string parameter as the node value.
492  * @param n The node on which to set the new value.
493  * @param value A string listing the elements of the vector to set on the node.
494  * @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.
495  * @param sepChar an optional character separing the elements of the list. Default value is ','.
496  * @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.
497  * @return Whether the string was a correct representation for this property's type. If not, the value is not set.
498  */
499  virtual bool setNodeStringValueAsVector(const node n, const std::string & value, char openChar = '(', char sepChar = ',', char closeChar = ')') = 0;
500 
501  /**
502  * @brief Sets a new vector represented by the string parameter as the edge value.
503  * @param e The edge on which to set value on.
504  * @param value A string listing the elements of the vector to set on the edge.
505  * @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.
506  * @param sepChar an optional character separing the elements of the list. Default value is ','.
507  * @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.
508  * @return Whether the string was a correct representation for this property's type. If not, the value is not set.
509  */
510  virtual bool setEdgeStringValueAsVector(const edge e, const std::string & value, char openChar = '(', char sepChar = ',', char closeChar = ')') = 0;
511 };
512 
513 /**
514  * @ingroup Observation
515  * @brief Contains additional information about events on a property,
516  * such as the property it happened on, the node/edge eventually concerned and such.
517  * It also contains the detailed type of the event.
518  */
519 class TLP_SCOPE PropertyEvent :public Event {
520 public:
521 
522  // be careful about the ordering of the constants
523  // in the enum below because it is used in some assertions
524  enum PropertyEventType {TLP_BEFORE_SET_NODE_VALUE = 0,
525  TLP_AFTER_SET_NODE_VALUE,
526  TLP_BEFORE_SET_ALL_NODE_VALUE,
527  TLP_AFTER_SET_ALL_NODE_VALUE,
528  TLP_BEFORE_SET_ALL_EDGE_VALUE,
529  TLP_AFTER_SET_ALL_EDGE_VALUE,
530  TLP_BEFORE_SET_EDGE_VALUE,
531  TLP_AFTER_SET_EDGE_VALUE
532  };
533  PropertyEvent(const PropertyInterface& prop, PropertyEventType propEvtType,
534  Event::EventType evtType = Event::TLP_MODIFICATION,
535  unsigned int id = UINT_MAX)
536  : Event(prop, evtType), evtType(propEvtType), eltId(id) {}
537 
538  PropertyInterface* getProperty() const {
539  return reinterpret_cast<PropertyInterface *>(sender());
540  }
541 
542  node getNode() const {
543  assert(evtType < TLP_BEFORE_SET_ALL_NODE_VALUE);
544  return node(eltId);
545  }
546 
547  edge getEdge() const {
548  assert(evtType > TLP_AFTER_SET_ALL_EDGE_VALUE);
549  return edge(eltId);
550  }
551 
552  PropertyEventType getType() const {
553  return evtType;
554  }
555 
556 protected:
557  PropertyEventType evtType;
558  unsigned int eltId;
559 };
560 }
561 
562 //================================================================================
563 // these functions allow to use tlp::PropertyInterface as a key in a hash-based data structure (e.g. hashmap).
564 //================================================================================
565 
566 ///@cond DOXYGEN_HIDDEN
567 TLP_BEGIN_HASH_NAMESPACE {
568  template <>
569  struct TLP_SCOPE hash<const tlp::PropertyInterface *> {
570  size_t operator()(const tlp::PropertyInterface *prop) const {return size_t(prop);}
571  };
572  template <>
573  struct TLP_SCOPE hash<tlp::PropertyInterface *> {
574  size_t operator()(tlp::PropertyInterface *prop) const {return size_t(prop);}
575  };
576 } TLP_END_HASH_NAMESPACE
577 ///@endcond
578 
579 #endif // PROPERTY_INTERFACE_H
PropertyInterface describes the interface of a graph property.
Interface for Tulip iterators. Allows basic iteration operations only.
Definition: Iterator.h:39
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&#39;s observation system.
Definition: Observable.h:123