Tulip
4.6.0
Better Visualization Through Research
|
00001 /* 00002 * 00003 * This file is part of Tulip (www.tulip-software.org) 00004 * 00005 * Authors: David Auber and the Tulip development Team 00006 * from LaBRI, University of Bordeaux 00007 * 00008 * Tulip is free software; you can redistribute it and/or modify 00009 * it under the terms of the GNU Lesser General Public License 00010 * as published by the Free Software Foundation, either version 3 00011 * of the License, or (at your option) any later version. 00012 * 00013 * Tulip is distributed in the hope that it will be useful, 00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 00016 * See the GNU General Public License for more details. 00017 * 00018 */ 00019 00020 #ifndef PROPERTY_INTERFACE_H 00021 #define PROPERTY_INTERFACE_H 00022 00023 #include <string> 00024 #include <iostream> 00025 #include <tulip/tulipconf.h> 00026 #include <tulip/Observable.h> 00027 #include <tulip/Node.h> 00028 #include <tulip/Edge.h> 00029 00030 namespace tlp { 00031 00032 struct DataMem; 00033 00034 class Graph; 00035 template<class itType > 00036 struct Iterator; 00037 00038 //============================================================= 00039 /** 00040 * @ingroup Graph 00041 * @brief PropertyInterface describes the interface of a graph property. 00042 * 00043 * The intent of a property is to hold a value for each node and edge (e.g. the degree of the nodes). 00044 * 00045 * A property can be used in two different ways : 00046 * Either it is attached to a graph; and in this case creating and deleting the property is handled by the graph 00047 * (@see Graph::getProperty()). 00048 * 00049 * Either is is detached from a graph, and you have to handle creation and deletion yourself. 00050 * This is most useful for some algorithms that need a temporary property, but do not want the property to appear on the graph 00051 * after the computation. 00052 */ 00053 class TLP_SCOPE PropertyInterface: public Observable { 00054 friend class PropertyManager; 00055 protected: 00056 // name of the property when registered as a property of a graph 00057 std::string name; 00058 // the graph for whom the property is registered 00059 Graph *graph; 00060 00061 public: 00062 PropertyInterface(); 00063 00064 virtual ~PropertyInterface(); 00065 00066 /** 00067 * @brief Erases the value stored for the given node. 00068 * The new value for the node is the default value. 00069 */ 00070 virtual void erase(const node) = 0; 00071 00072 /** 00073 * @brief Erases the value stored for the given edge. 00074 * The new value for the edge is the default value. 00075 */ 00076 virtual void erase(const edge) = 0; 00077 00078 /** 00079 * @brief Copies the value of a node in another property to a node in this property. 00080 * @param destination The node whose value will be set. 00081 * @param source The node whose value to copy. 00082 * @param property The property from which to copy the source node value. 00083 * @param ifNotDefault If true, the copy will only be performed if the source node's value is not the default value. 00084 * @return True if the copy was performed, false otherwise. 00085 */ 00086 virtual bool copy(const node destination, const node source, PropertyInterface *property, 00087 bool ifNotDefault = false) =0; 00088 /** 00089 * @brief Copies the value of an edge in another property to an edge in this property. 00090 * @param destination The edge whose value will be set. 00091 * @param source The edge whose value to copy. 00092 * @param property The property from which to copy the source edge value. 00093 * @param ifNotDefault If true, the copy will only be performed if the source edge's value is not the default value. 00094 * @return True if the copy was performed, false otherwise. 00095 */ 00096 virtual bool copy(const edge destination, const edge source, PropertyInterface *property, 00097 bool ifNotDefault = false) =0; 00098 00099 /** 00100 * @brief Copies the values of the passed property to this property. 00101 * @param source The property from which to copy values. 00102 */ 00103 virtual void copy(PropertyInterface* source) = 0; 00104 00105 /** 00106 * @brief Creates a property of the same type (e.g. tlp::DoubleProperty) in the graph. 00107 * The new property will not contain a copy of this property's values. 00108 * @param graph The Graph in which to create the new property. 00109 * @param name The name of the new property. 00110 * @return The newly created property. 00111 */ 00112 virtual PropertyInterface* clonePrototype(Graph *graph, const std::string& name) =0; 00113 00114 /** 00115 * @brief Gets a string describing the type of the property (e.g. "graph", "double", "layout", "string", "integer", "color", "size"). 00116 * @return The name of this property's type. 00117 */ 00118 virtual const std::string& getTypename() const = 0; 00119 00120 /** 00121 * @brief Gets the name of the property (e.g. viewLayout). 00122 * @return The name of this property. 00123 */ 00124 const std::string& getName() const { 00125 return name; 00126 } 00127 00128 /** 00129 * @brief Rename a property 00130 * @param the new name 00131 * @return returns true if the renaming succeed. 00132 * It may fails if a property with the given name already exists 00133 */ 00134 bool rename(const std::string& newName); 00135 /** 00136 * @cond DOXYGEN_HIDDEN 00137 * @brief Gets the graph on which this property has been defined. 00138 * This is an internal function and its behavior can change. 00139 * DO NOT USE UNLESS YOU KNOW WHAT YOU ARE DOING. 00140 * 00141 * Be wary that is might be a different graph that the one you used to get this property. 00142 * For instance: 00143 * @code 00144 * Graph* g = tlp::newGraph(); 00145 * Graph*sub = g->addCloneSubGraph(); 00146 * 00147 * IntegerProperty* prop = g->getProperty<IntegerProperty>("test"); 00148 * //prop->getGraph() returns g 00149 * 00150 * IntegerProperty* prop2 = sub->getProperty<IntegerProperty>("test"); 00151 * //prop2->getGraph() returns g 00152 * @endcode 00153 * 00154 * This is due to the inheritance system of the properties. 00155 * 00156 * @return The Graph this property is local to. 00157 * @endcond 00158 */ 00159 tlp::Graph * getGraph() const { 00160 return graph; 00161 } 00162 00163 /** 00164 * @brief Gets a string representation of the node default value. 00165 * @param n The node to get the value of. 00166 * @return A string representation of the node default value. 00167 */ 00168 virtual std::string getNodeStringValue( const node n ) const = 0; 00169 00170 /** 00171 * @brief Gets a string representation of the edge default value. 00172 * @param e The edge to get the value of. 00173 * @return A string representation of the edge default value. 00174 */ 00175 virtual std::string getEdgeStringValue( const edge e ) const = 0; 00176 00177 /** 00178 * @brief Sets a new value on the node, described by the string parameter. 00179 * @param n The node on which to set the new value. 00180 * @param value A string describing the value to set on the node. 00181 * @return Whether the string was a correct representation for this property's type. If not, the value is not set. 00182 */ 00183 virtual bool setNodeStringValue( const node n, const std::string & value ) = 0; 00184 00185 /** 00186 * @brief Sets a new value on the edge, described by the string parameter. 00187 * @param e The edge on which to set value on. 00188 * @param value A string describing the value to set on the edge. 00189 * @return Whether the string was a correct representation for this property's type. If not, the value is not set. 00190 */ 00191 virtual bool setEdgeStringValue( const edge e, const std::string & value ) = 0; 00192 00193 /** 00194 * @brief Gets a string representation of the node default value. 00195 * @return A string representation of the node default value. 00196 */ 00197 virtual std::string getNodeDefaultStringValue() const = 0; 00198 00199 /** 00200 * @brief Gets a string representation of the edge default value. 00201 * @return A string representation of the edge default value. 00202 */ 00203 virtual std::string getEdgeDefaultStringValue() const = 0; 00204 00205 /** 00206 * @brief Sets all the nodes value to the value described by the string. For some types, some parsing will be necessary (e.g. LayoutPorperty). 00207 * All previous values are lost. 00208 * @param value A string describing the new value to set on all the nodes. 00209 * @return Whether the given string was a correct representation for this property's type. If not, the values are not set. 00210 */ 00211 virtual bool setAllNodeStringValue( const std::string & value ) = 0; 00212 00213 /** 00214 * @brief Sets all the edges value to the value described by the string. For some types, some parsing will be necessary (e.g. LayoutPorperty). 00215 * All previous values are lost. 00216 * @param value A string describing the new value to set on all the edges. 00217 * @return Whether the given string was a correct representation for this property's type. If not, the values are not set. 00218 */ 00219 virtual bool setAllEdgeStringValue( const std::string & value ) = 0; 00220 00221 /** 00222 * @brief Gets a pointer to the tlp::DataMem structure that contains the node default value. 00223 * @return The DataMem structure containing the node default value. 00224 * @warning The ownership of this pointer is given to the caller. 00225 */ 00226 virtual DataMem* getNodeDefaultDataMemValue() const = 0; 00227 00228 /** 00229 * @brief Gets a pointer to the tlp::DataMem structure that contains the edge default value. 00230 * @return The DataMem structure containing the edge default value. 00231 * @warning The ownership of this pointer is given to the caller. 00232 */ 00233 virtual DataMem* getEdgeDefaultDataMemValue() const = 0; 00234 00235 /** 00236 * @brief Sets all the nodes value to the value contained in the given DataMem structure. 00237 * All previous values are lost. 00238 * @param value The value to set on all the nodes. 00239 */ 00240 virtual void setAllNodeDataMemValue(const DataMem* value) = 0; 00241 00242 /** 00243 * @brief Sets all the edges value to the value contained in the given DataMem structure. 00244 * All previous values are lost. 00245 * @param value The value to set on all the edges. 00246 */ 00247 virtual void setAllEdgeDataMemValue(const DataMem* v ) = 0; 00248 00249 /** 00250 * @brief Gets the node value, contained in a tlp::DataMem structure. 00251 * @param n The node to get the value of. 00252 * @return The value of the node, in a tlp::DataMem. 00253 * 00254 * @warning The ownership of this pointer is given to the caller. 00255 */ 00256 virtual DataMem* getNodeDataMemValue( const node n ) const = 0; 00257 00258 /** 00259 * @brief Gets the edge value, contained in a tlp::DataMem structure. 00260 * @param n The edge to get the value of. 00261 * @return The value of the edge, in a tlp::DataMem. 00262 * 00263 * @warning The ownership of this pointer is given to the caller. 00264 */ 00265 virtual DataMem* getEdgeDataMemValue( const edge e ) const = 0; 00266 00267 /** 00268 * @brief Returns the value in a DataMem if it is not default, otherwise returns NULL. 00269 * @param n The node to get the value of. 00270 * @return The value of the node if it is not default, or NULL. 00271 * 00272 * @warning The ownership of this pointer is given to the caller. 00273 */ 00274 virtual DataMem* getNonDefaultDataMemValue( const node n ) const = 0; 00275 00276 /** 00277 * @brief Returns the value in a DataMem if it is not default, otherwise returns NULL. 00278 * @param e The edge to get the value of. 00279 * @return The value of the edge if it is not default, or NULL. 00280 * 00281 * @warning The ownership of this pointer is given to the caller. 00282 */ 00283 virtual DataMem* getNonDefaultDataMemValue( const edge e ) const = 0; 00284 00285 /** 00286 * @brief Sets the node value. 00287 * @param n The node to set the value of. 00288 * @param value The value to set to this node. 00289 */ 00290 virtual void setNodeDataMemValue( const node n, const DataMem* value) = 0; 00291 00292 /** 00293 * @brief Sets the edge value. 00294 * @param e The edge to set the value of. 00295 * @param value The value to set to this edge. 00296 */ 00297 virtual void setEdgeDataMemValue( const edge e, const DataMem* v) = 0; 00298 00299 /** 00300 * @brief Gets an Iterator on all non-default valuated nodes. 00301 * When given a Graph as parameter, only nodes belonging to this graph are iterated over. 00302 * @return An Iterator over nodes whose value is not default. 00303 * 00304 * @warning The ownership of the iterator is given to the caller. 00305 */ 00306 virtual tlp::Iterator<node>* getNonDefaultValuatedNodes(const Graph* = NULL) const = 0; 00307 00308 /** 00309 * @brief Returns the number of nodes with a non default value. 00310 * @return the number of nodes with a non default value. 00311 * 00312 */ 00313 virtual unsigned int numberOfNonDefaultValuatedNodes() const = 0; 00314 00315 /** 00316 * @brief Gets an Iterator on all non-default valuated edges. 00317 * When given a Graph as parameter, only edges belonging to this graph are iterated over. 00318 * @return An Iterator over edges whose value is not default. 00319 * 00320 * @warning The ownership of the iterator is given to the caller. 00321 */ 00322 virtual tlp::Iterator<edge>* getNonDefaultValuatedEdges(const Graph* = NULL) const = 0; 00323 00324 /** 00325 * @brief Returns the number of edges with a non default value. 00326 * @return the number of edges with a non default value. 00327 * 00328 */ 00329 virtual unsigned int numberOfNonDefaultValuatedEdges() const = 0; 00330 00331 /** 00332 * @brief Returns the size in bytes of a node's value. 00333 * @return the size of a node's value (0 means the size is not fixed) 00334 * 00335 */ 00336 virtual unsigned int nodeValueSize() const = 0; 00337 00338 /** 00339 * @brief Writes the nodes default value 00340 * 00341 */ 00342 virtual void writeNodeDefaultValue(std::ostream&) const = 0; 00343 00344 /** 00345 * @brief Writes the value of a node 00346 * 00347 */ 00348 virtual void writeNodeValue(std::ostream&, node) const = 0; 00349 00350 /** 00351 * @brief Reads the nodes default value 00352 * 00353 */ 00354 virtual bool readNodeDefaultValue(std::istream&) = 0; 00355 00356 /** 00357 * @brief Reads the value of a node 00358 * 00359 */ 00360 virtual bool readNodeValue(std::istream&, node) = 0; 00361 00362 /** 00363 * @brief Returns the size in bytes of an edge's value. 00364 * @return the size of a node's value (0 means the size is not fixed) 00365 * 00366 */ 00367 virtual unsigned int edgeValueSize() const = 0; 00368 00369 /** 00370 * @brief Writes the edges default value 00371 * 00372 */ 00373 virtual void writeEdgeDefaultValue(std::ostream&) const = 0; 00374 00375 /** 00376 * @brief Writes the value of an edge 00377 * 00378 */ 00379 virtual void writeEdgeValue(std::ostream&, edge) const = 0; 00380 00381 /** 00382 * @brief Reads the edges default value 00383 * 00384 */ 00385 virtual bool readEdgeDefaultValue(std::istream&) = 0; 00386 00387 /** 00388 * @brief Reads the value of an edge 00389 * 00390 */ 00391 virtual bool readEdgeValue(std::istream&, edge) = 0; 00392 00393 /** 00394 * @brief Sets the value of the metanode to a computed value. 00395 * 00396 * The value is computed by this property's MetaValueCalculator. 00397 * @param metaNode The metanode to compute a value on. 00398 * @param subgraph The subgraph pointed by the metanode. 00399 * @param metaGraph The graph who owns the meta node. 00400 */ 00401 virtual void computeMetaValue(node metaNode, Graph* subgraph, Graph* metaGraph)=0; 00402 00403 /** 00404 * @brief Sets the value of the metaedge to a computed value. 00405 * @param metaEdge The meta edge to compute a value on. 00406 * @param it The edges represented by the meta edge. 00407 * @param metaGraph The graph who owns the meta edge. 00408 */ 00409 virtual void computeMetaValue(edge metaEdge, tlp::Iterator<edge>* it, Graph* metaGraph)=0; 00410 00411 /** 00412 * @brief Base class for computing values on meta nodes and edges. 00413 */ 00414 class MetaValueCalculator { 00415 public: 00416 virtual ~MetaValueCalculator() {} 00417 }; 00418 00419 /** 00420 * @brief Gets the MetaValueCalculator of this property. 00421 * @return The MetaValueCalculator of this property 00422 */ 00423 MetaValueCalculator* getMetaValueCalculator() { 00424 return metaValueCalculator; 00425 } 00426 00427 /** 00428 * @brief Sets the Calculator for meta nodes and edges. 00429 * @param calculator The object containing the logic for computing the meta values for the nodes and edges. 00430 * 00431 * @warning The ownership of the MetaValueCalculator is not taken by the property. 00432 */ 00433 virtual void setMetaValueCalculator(MetaValueCalculator* calculator) { 00434 metaValueCalculator = calculator; 00435 } 00436 00437 /** 00438 * @brief Compares the value this property holds for the two given nodes. 00439 * @param n1 The first node to compare the value of. 00440 * @param n2 The second node to compare the value of. 00441 * @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. 00442 */ 00443 virtual int compare(const node n1,const node n2) const = 0; 00444 00445 /** 00446 * @brief Compares the value this property holds for the two given edges. 00447 * @param e1 The first edge to compare the value of. 00448 * @param e2 The second edge to compare the value of. 00449 * @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. 00450 */ 00451 virtual int compare(const edge e1,const edge e2) const = 0; 00452 00453 protected: 00454 MetaValueCalculator* metaValueCalculator; 00455 00456 // for notification of PropertyObserver 00457 void notifyBeforeSetNodeValue(const node n); 00458 void notifyAfterSetNodeValue(const node n); 00459 void notifyBeforeSetEdgeValue(const edge e); 00460 void notifyAfterSetEdgeValue(const edge e); 00461 void notifyBeforeSetAllNodeValue(); 00462 void notifyAfterSetAllNodeValue(); 00463 void notifyBeforeSetAllEdgeValue(); 00464 void notifyAfterSetAllEdgeValue(); 00465 void notifyDestroy(); 00466 void notifyRename(const std::string& newName); 00467 }; 00468 00469 /** 00470 * @ingroup Graph 00471 * @brief VectorPropertyInterface describes the interface of a graph property whose holded value is a vector (std::vector) 00472 * 00473 */ 00474 class TLP_SCOPE VectorPropertyInterface: public PropertyInterface { 00475 public: 00476 VectorPropertyInterface(): PropertyInterface() {} 00477 00478 ~VectorPropertyInterface() {} 00479 00480 /** 00481 * @brief Sets a new vector described by the string parameter as the node value. 00482 * @param n The node on which to set the new value. 00483 * @param value A string listing the elements of the vector to set on the node. 00484 * @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. 00485 * @param sepChar an optional character separing the elements of the list. Default value is ','. 00486 * @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. 00487 * @return Whether the string was a correct representation for this property's type. If not, the value is not set. 00488 */ 00489 virtual bool setNodeStringValueAsVector(const node n, const std::string & value, char openChar = '(', char sepChar = ',', char closeChar = ')') = 0; 00490 00491 /** 00492 * @brief Sets a new vector described by the string parameter as the edge value. 00493 * @param e The edge on which to set value on. 00494 * @param value A string listing the elements of the vector to set on the edge. 00495 * @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. 00496 * @param sepChar an optional character separing the elements of the list. Default value is ','. 00497 * @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. 00498 * @return Whether the string was a correct representation for this property's type. If not, the value is not set. 00499 */ 00500 virtual bool setEdgeStringValueAsVector(const edge e, const std::string & value, char openChar = '(', char sepChar = ',', char closeChar = ')') = 0; 00501 }; 00502 00503 /** 00504 * @ingroup Observation 00505 * @brief Contains additional information about events on a property, 00506 * such as the property it happened on, the node/edge eventually concerned and such. 00507 * It also contains the detailed type of the event. 00508 */ 00509 class TLP_SCOPE PropertyEvent :public Event { 00510 public: 00511 00512 // be careful about the ordering of the constants 00513 // in the enum below because it is used in some assertions 00514 enum PropertyEventType {TLP_BEFORE_SET_NODE_VALUE = 0, 00515 TLP_AFTER_SET_NODE_VALUE, 00516 TLP_BEFORE_SET_ALL_NODE_VALUE, 00517 TLP_AFTER_SET_ALL_NODE_VALUE, 00518 TLP_BEFORE_SET_ALL_EDGE_VALUE, 00519 TLP_AFTER_SET_ALL_EDGE_VALUE, 00520 TLP_BEFORE_SET_EDGE_VALUE, 00521 TLP_AFTER_SET_EDGE_VALUE 00522 }; 00523 PropertyEvent(const PropertyInterface& prop, PropertyEventType propEvtType, 00524 Event::EventType evtType = Event::TLP_MODIFICATION, 00525 unsigned int id = UINT_MAX) 00526 : Event(prop, evtType), evtType(propEvtType), eltId(id) {} 00527 00528 PropertyInterface* getProperty() const { 00529 return reinterpret_cast<PropertyInterface *>(sender()); 00530 } 00531 00532 node getNode() const { 00533 assert(evtType < TLP_BEFORE_SET_ALL_NODE_VALUE); 00534 return node(eltId); 00535 } 00536 00537 edge getEdge() const { 00538 assert(evtType > TLP_AFTER_SET_ALL_EDGE_VALUE); 00539 return edge(eltId); 00540 } 00541 00542 PropertyEventType getType() const { 00543 return evtType; 00544 } 00545 00546 protected: 00547 PropertyEventType evtType; 00548 unsigned int eltId; 00549 }; 00550 } 00551 00552 //================================================================================ 00553 // these functions allow to use tlp::PropertyInterface as a key in a hash-based data structure (e.g. hashmap). 00554 //================================================================================ 00555 #ifndef DOXYGEN_NOTFOR_DEVEL 00556 00557 TLP_BEGIN_HASH_NAMESPACE { 00558 template <> 00559 struct TLP_SCOPE hash<const tlp::PropertyInterface *> { 00560 size_t operator()(const tlp::PropertyInterface *prop) const {return size_t(prop);} 00561 }; 00562 template <> 00563 struct TLP_SCOPE hash<tlp::PropertyInterface *> { 00564 size_t operator()(tlp::PropertyInterface *prop) const {return size_t(prop);} 00565 }; 00566 } TLP_END_HASH_NAMESPACE 00567 00568 #endif // DOXYGEN_NOTFOR_DEVEL 00569 00570 #endif // PROPERTY_INTERFACE_H