Tulip  4.3.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  * @cond DOXYGEN_HIDDEN
129  * @brief Gets the graph on which this property has been defined.
130  * This is an internal function and its behavior can change.
131  * DO NOT USE UNLESS YOU KNOW WHAT YOU ARE DOING.
132  *
133  * Be wary that is might be a different graph that the one you used to get this property.
134  * For instance:
135  * @code
136  * Graph* g = tlp::newGraph();
137  * Graph*sub = g->addCloneSubGraph();
138  *
139  * IntegerProperty* prop = g->getProperty<IntegerProperty>("test");
140  * //prop->getGraph() returns g
141  *
142  * IntegerProperty* prop2 = sub->getProperty<IntegerProperty>("test");
143  * //prop2->getGraph() returns g
144  * @endcode
145  *
146  * This is due to the inheritance system of the properties.
147  *
148  * @return The Graph this property is local to.
149  * @endcond
150  */
151  tlp::Graph * getGraph() const {
152  return graph;
153  }
154 
155  /**
156  * @brief Gets a string representation of the node default value.
157  * @param n The node to get the value of.
158  * @return A string representation of the node default value.
159  */
160  virtual std::string getNodeStringValue( const node n ) const = 0;
161 
162  /**
163  * @brief Gets a string representation of the edge default value.
164  * @param e The edge to get the value of.
165  * @return A string representation of the edge default value.
166  */
167  virtual std::string getEdgeStringValue( const edge e ) const = 0;
168 
169  /**
170  * @brief Sets a new value on the node, described by the string parameter.
171  * @param n The node on which to set the new value.
172  * @param value A string describing the value to set on the node.
173  * @return Whether the string was a correct representation for this property's type. If not, the value is not set.
174  */
175  virtual bool setNodeStringValue( const node n, const std::string & value ) = 0;
176 
177  /**
178  * @brief Sets a new value on the edge, described by the string parameter.
179  * @param e The edge on which to set value on.
180  * @param value A string describing the value to set on the edge.
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 setEdgeStringValue( const edge e, const std::string & value ) = 0;
184 
185  /**
186  * @brief Gets a string representation of the node default value.
187  * @return A string representation of the node default value.
188  */
189  virtual std::string getNodeDefaultStringValue() const = 0;
190 
191  /**
192  * @brief Gets a string representation of the edge default value.
193  * @return A string representation of the edge default value.
194  */
195  virtual std::string getEdgeDefaultStringValue() const = 0;
196 
197  /**
198  * @brief Sets all the nodes value to the value described by the string. For some types, some parsing will be necessary (e.g. LayoutPorperty).
199  * All previous values are lost.
200  * @param value A string describing the new value to set on all the nodes.
201  * @return Whether the given string was a correct representation for this property's type. If not, the values are not set.
202  */
203  virtual bool setAllNodeStringValue( const std::string & value ) = 0;
204 
205  /**
206  * @brief Sets all the edges 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 edges.
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 setAllEdgeStringValue( const std::string & value ) = 0;
212 
213  /**
214  * @brief Gets a pointer to the tlp::DataMem structure that contains the node default value.
215  * @return The DataMem structure containing the node default value.
216  * @warning The ownership of this pointer is given to the caller.
217  */
218  virtual DataMem* getNodeDefaultDataMemValue() const = 0;
219 
220  /**
221  * @brief Gets a pointer to the tlp::DataMem structure that contains the edge default value.
222  * @return The DataMem structure containing the edge default value.
223  * @warning The ownership of this pointer is given to the caller.
224  */
225  virtual DataMem* getEdgeDefaultDataMemValue() const = 0;
226 
227  /**
228  * @brief Sets all the nodes value to the value contained in the given DataMem structure.
229  * All previous values are lost.
230  * @param value The value to set on all the nodes.
231  */
232  virtual void setAllNodeDataMemValue(const DataMem* value) = 0;
233 
234  /**
235  * @brief Sets all the edges 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 edges.
238  */
239  virtual void setAllEdgeDataMemValue(const DataMem* v ) = 0;
240 
241  /**
242  * @brief Gets the node value, contained in a tlp::DataMem structure.
243  * @param n The node to get the value of.
244  * @return The value of the node, in a tlp::DataMem.
245  *
246  * @warning The ownership of this pointer is given to the caller.
247  */
248  virtual DataMem* getNodeDataMemValue( const node n ) const = 0;
249 
250  /**
251  * @brief Gets the edge value, contained in a tlp::DataMem structure.
252  * @param n The edge to get the value of.
253  * @return The value of the edge, in a tlp::DataMem.
254  *
255  * @warning The ownership of this pointer is given to the caller.
256  */
257  virtual DataMem* getEdgeDataMemValue( const edge e ) const = 0;
258 
259  /**
260  * @brief Returns the value in a DataMem if it is not default, otherwise returns NULL.
261  * @param n The node to get the value of.
262  * @return The value of the node if it is not default, or NULL.
263  *
264  * @warning The ownership of this pointer is given to the caller.
265  */
266  virtual DataMem* getNonDefaultDataMemValue( const node n ) const = 0;
267 
268  /**
269  * @brief Returns the value in a DataMem if it is not default, otherwise returns NULL.
270  * @param e The edge to get the value of.
271  * @return The value of the edge 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 edge e ) const = 0;
276 
277  /**
278  * @brief Sets the node value.
279  * @param n The node to set the value of.
280  * @param value The value to set to this node.
281  */
282  virtual void setNodeDataMemValue( const node n, const DataMem* value) = 0;
283 
284  /**
285  * @brief Sets the edge value.
286  * @param e The edge to set the value of.
287  * @param value The value to set to this edge.
288  */
289  virtual void setEdgeDataMemValue( const edge e, const DataMem* v) = 0;
290 
291  /**
292  * @brief Gets an Iterator on all non-default valuated nodes.
293  * When given a Graph as parameter, only nodes belonging to this graph are iterated over.
294  * @return An Iterator over nodes whose value is not default.
295  *
296  * @warning The ownership of the iterator is given to the caller.
297  */
298  virtual tlp::Iterator<node>* getNonDefaultValuatedNodes(const Graph* = NULL) const = 0;
299 
300  /**
301  * @brief Gets an Iterator on all non-default valuated edges.
302  * When given a Graph as parameter, only edges belonging to this graph are iterated over.
303  * @return An Iterator over edges whose value is not default.
304  *
305  * @warning The ownership of the iterator is given to the caller.
306  */
307  virtual tlp::Iterator<edge>* getNonDefaultValuatedEdges(const Graph* = NULL) const = 0;
308 
309  /**
310  * @brief Sets the value of the metanode to a computed value.
311  *
312  * The value is computed by this property's MetaValueCalculator.
313  * @param metaNode The metanode to compute a value on.
314  * @param subgraph The subgraph pointed by the metanode.
315  * @param metaGraph The graph who owns the meta node.
316  */
317  virtual void computeMetaValue(node metaNode, Graph* subgraph, Graph* metaGraph)=0;
318 
319  /**
320  * @brief Sets the value of the metaedge to a computed value.
321  * @param metaEdge The meta edge to compute a value on.
322  * @param it The edges represented by the meta edge.
323  * @param metaGraph The graph who owns the meta edge.
324  */
325  virtual void computeMetaValue(edge metaEdge, tlp::Iterator<edge>* it, Graph* metaGraph)=0;
326 
327  /**
328  * @brief Base class for computing values on meta nodes and edges.
329  */
331  public:
332  virtual ~MetaValueCalculator() {}
333  };
334 
335  /**
336  * @brief Gets the MetaValueCalculator of this property.
337  * @return The MetaValueCalculator of this property
338  */
340  return metaValueCalculator;
341  }
342 
343  /**
344  * @brief Sets the Calculator for meta nodes and edges.
345  * @param calculator The object containing the logic for computing the meta values for the nodes and edges.
346  *
347  * @warning The ownership of the MetaValueCalculator is not taken by the property.
348  */
349  virtual void setMetaValueCalculator(MetaValueCalculator* calculator) {
350  metaValueCalculator = calculator;
351  }
352 
353  /**
354  * @brief Compares the value this property holds for the two given nodes.
355  * @param n1 The first node to compare the value of.
356  * @param n2 The second node to compare the value of.
357  * @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.
358  */
359  virtual int compare(const node n1,const node n2) const = 0;
360 
361  /**
362  * @brief Compares the value this property holds for the two given edges.
363  * @param e1 The first edge to compare the value of.
364  * @param e2 The second edge to compare the value of.
365  * @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.
366  */
367  virtual int compare(const edge e1,const edge e2) const = 0;
368 
369 protected:
370  MetaValueCalculator* metaValueCalculator;
371 
372  // for notification of PropertyObserver
373  void notifyBeforeSetNodeValue(const node n);
374  void notifyAfterSetNodeValue(const node n);
375  void notifyBeforeSetEdgeValue(const edge e);
376  void notifyAfterSetEdgeValue(const edge e);
377  void notifyBeforeSetAllNodeValue();
378  void notifyAfterSetAllNodeValue();
379  void notifyBeforeSetAllEdgeValue();
380  void notifyAfterSetAllEdgeValue();
381  void notifyDestroy();
382 };
383 
384 /**
385  * @ingroup Observation
386  * @brief Contains additional informations about events on a property,
387  * such as the property it happened on, the node/edge eventually concerned and such.
388  * It also contains the detailed type of the event.
389  */
390 class TLP_SCOPE PropertyEvent :public Event {
391 public:
392 
393  // be careful about the ordering of the constants
394  // in the enum below because it is used in some assertions
395  enum PropertyEventType {TLP_BEFORE_SET_NODE_VALUE = 0,
396  TLP_AFTER_SET_NODE_VALUE,
397  TLP_BEFORE_SET_ALL_NODE_VALUE,
398  TLP_AFTER_SET_ALL_NODE_VALUE,
399  TLP_BEFORE_SET_ALL_EDGE_VALUE,
400  TLP_AFTER_SET_ALL_EDGE_VALUE,
401  TLP_BEFORE_SET_EDGE_VALUE,
402  TLP_AFTER_SET_EDGE_VALUE
403  };
404  PropertyEvent(const PropertyInterface& prop, PropertyEventType propEvtType,
405  Event::EventType evtType = Event::TLP_MODIFICATION,
406  unsigned int id = UINT_MAX)
407  : Event(prop, evtType), evtType(propEvtType), eltId(id) {}
408 
409  PropertyInterface* getProperty() const {
410  return reinterpret_cast<PropertyInterface *>(sender());
411  }
412 
413  node getNode() const {
414  assert(evtType < TLP_BEFORE_SET_ALL_NODE_VALUE);
415  return node(eltId);
416  }
417 
418  edge getEdge() const {
419  assert(evtType > TLP_AFTER_SET_ALL_EDGE_VALUE);
420  return edge(eltId);
421  }
422 
423  PropertyEventType getType() const {
424  return evtType;
425  }
426 
427 protected:
428  PropertyEventType evtType;
429  unsigned int eltId;
430 };
431 }
432 
433 //================================================================================
434 // these functions allow to use tlp::PropertyInterface as a key in a hash-based data structure (e.g. hashmap).
435 //================================================================================
436 #ifndef DOXYGEN_NOTFOR_DEVEL
437 
438 TLP_BEGIN_HASH_NAMESPACE {
439  template <>
440  struct TLP_SCOPE hash<const tlp::PropertyInterface *> {
441  size_t operator()(const tlp::PropertyInterface *prop) const {return size_t(prop);}
442  };
443  template <>
444  struct TLP_SCOPE hash<tlp::PropertyInterface *> {
445  size_t operator()(tlp::PropertyInterface *prop) const {return size_t(prop);}
446  };
447 } TLP_END_HASH_NAMESPACE
448 
449 #endif // DOXYGEN_NOTFOR_DEVEL
450 
451 #endif // PROPERTY_INTERFACE_H