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