Tulip  4.6.0
Better Visualization Through Research
library/tulip-core/include/tulip/PropertyInterface.h
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
 All Classes Files Functions Variables Enumerations Enumerator Properties