Plug-ins development

Tulip has been built to be easily extensible. Therefore a mechanism of plug-ins has been set up. It enables to directly add new functionalities into the Tulip kernel. One must keeps in mind that a plug-in have access to all the parts of Tulip. Thus, plug-ins have to be written very carefully to prevent memory leak, errors and “core dump”.

To enable the use of plug-ins, a program must call the initialization functions of the plug-ins. This function loads dynamically all the plug-ins and register them into a factory that will enable to direct access to it.

To develop a plug-in, you need to create a new class that will inherits from a specific algorithm class. They are separated in 4 different types:

  • Property algorithms: This kind of plug-ins will only affect a specific property of any type. See the section called The PropertyAlgorithm class.
  • Generic algorithms: This kind of plug-ins can be used to modify the entire graph. In other case it is preferable to use a specific class of algorithms to implement your plug-in. See the section called The Algorithm class.
  • Import algorithms: Plug-ins to import a specific graph. For example a plug-in that will create a graph from a file directory system. See the section called Import plug-ins.
  • Export algorithms: Plug-ins to save a graph to a specific type of file. See the section called Export plug-ins.

The PropertyAlgorithm class

The PropertyAlgorithm class (which inherits of the Algorithm class), is the ârent class of different types of algorithms such as the BooleanAlgorithm class or the LayoutAlgorithm class. This class is important as most of the specific algorithms developed will have to inherit from it. For example, if you write a plug-in to update the graph layout, your class will have to inherit from the LayoutAlgorithm class which, itself, inherits from the PropertyAlgorithm class.

Following is a table showing the subclasses of PropertyAlgorithm, with the corresponding, class of result property, the default graph property and the ‘Algorithms’ group in the GUI :
Class name Result class name Graph property replaced (by default) Algorithms group
BooleanAlgorithm BooleanProperty viewSelection Selection
ColorAlgorithm ColorProperty viewColor Coloring
DoubleAlgorithm DoubleProperty viewMetric Measure
IntegerAlgorithm IntegerProperty NA Measure
LayoutAlgorithm LayoutProperty viewLayout Layout
SizeAlgorithm SizeProperty viewSize Resizing
StringAlgorithm StringProperty viewLabel Labeling

Each one of classes presented above has a public member:

*TypeName*Property result;

which is the data member that have to be computed by your plug-in. After a successful run Tulip will automatically copy this data member into the corresponding property of the graph.

Note that at anytime, if the user clicks on the “cancel” button (see the Plugin Progress class for more details ), none of your algorithm’s actions will changes the graph since the result data member is not copied in the corresponding property.

A quick overview of the functions and data members of the class PropertyAlgorithm is needed in order to have a generic understanding of its derived classes.

Public members

Following is a list of all public members:

  • PropertyAlgorithm (const tlp::PluginContext& context): Even if the constructor is used to initialize the inner variables, it is also the right place to declare the parameters needed by the algorithm and to specify how we are going to use them (consult the Parameter section).

    If needed, some dependencies can also be specified between two algorithms using the method:

    void addDependency(const char *name, const char *release);
    

    which allows to declare that the current PropertyAlgorithm depends (in terms of programming call) from the release version of the Algorithm release named name. .

  • ~PropertyAlgorithm (): Destructor of the class.

  • bool run (): This is the main method:

    • It will be called out if the pre-condition method (bool check (..)) returned true.
    • It is the starting point of your algorithm. The returned value must be true if your algorithm succeeded.
  • bool check (std::string& errMsg) {return true;}: This method can be used to check the graph about its topological properties, metric properties on graph elements or any other requirement for the algorithm to run flawlessly. The default implementation inherited from the class PropertyAlgorithm returns true;

Protected members

Following is a list of all protected members. Each of those are transmitted to the plugin through the PluginContext and then restored into the following temporary variables:

  • Graph * graph: This graph is the one on which the algorithm will be applied.
  • PluginProgress * pluginProgress: This instance of the class PluginProgress can be used to have an interaction between the user and our algorithm. See the next section for more details.
  • DataSet * dataSet: This member contains all the parameters needed to run the algorithm. The class DataSet is a container which allows insertion of values of different types. The inserted data must have a copy-constructor well done. See the section called DataSet for more details.

The methods of the TypeName Algorithm class, will be redefined in your plug-in as shown in the plugin skeleton.

Adding parameters to an algorithm

Your algorithm may need some parameters, for example a boolean or a property name, that must be filled in by the user just before being launched. In this section, we will look at the methods and techniques to do so.

The class PropertyAlgorithm provides the following methods to declare a parameter:

template<typename T>
void addInParameter(const std::string &name,
                    const std::string &help,
                    const std::string &defaultValue,
                    bool isMandatory = true);

template<typename T>
void addOutParameter(const std::string &name,
                     const std::string &help=std::string(),
                     const std::string &defaultValue = std::string(),
                     bool isMandatory = true);

template<typename T>
void addInOutParameter(const std::string &name,
                       const std::string &help=std::string(),
                       const std::string &defaultValue = std::string(),
                       bool isMandatory = true);

The new parameters added to the plug-in are, by default, IN parameters. The OUT parameters are defined depending of the PropertyAlgorithm used. INOUT parameters gives the developer the abilities to extract additionnal information.

This methods have to be called in the constructor of your class. Following is a description of its fields :

  • name: Name of the new parameter.
  • help: This parameter will be used to add a documentation to the parameter (See example below).
  • defaultValue: Default value.
  • isMandatory: If false, the user have to set this parameter.

On the following example, we declare a character buffer that will contain the parameter descriptions of the ColorMapping algorithm:

static const char * paramHelp[] = {
  // type
  HTML_HELP_OPEN()         \
  HTML_HELP_DEF("type", "String Collection") \
  HTML_HELP_DEF("values", "linear <BR> uniform <BR> enumerated") \
  HTML_HELP_DEF("default", "linear")   \
  HTML_HELP_BODY() \
  "If linear, the input property must be a Double or Integer property." \
  "The minimum value is mapped to one end of the color scale," \
  "the maximum value is mapped to the other end, and a linear interpolation " \
  "is used between both.<BR>" \
  "If uniform, this is the same except for the interpolation: the value are sorted, " \
  "numbered, and a linear interpolation is used on those numbers" \
  "(in other words, only the order is taken into account, not the actual values).<BR>" \
  "Finally, if enumerated, the input property can be of any type. Each possible " \
  "value is mapped to a distinct color in no specific order." \
  HTML_HELP_CLOSE(),
  // property
  HTML_HELP_OPEN() \
  HTML_HELP_DEF("type", "PropertyInterface") \
  HTML_HELP_BODY() \
  "This property is used to get the values affected to graph items." \
  HTML_HELP_CLOSE(),
  // target
  HTML_HELP_CLOSE(),
  HTML_HELP_OPEN()         \
  HTML_HELP_DEF("type", "String Collection") \
  HTML_HELP_DEF("values", "nodes <BR> edges") \
  HTML_HELP_DEF("default", "nodes")  \
  HTML_HELP_BODY() \
  "Whether colors are computed for nodes or for edges."  \
  HTML_HELP_CLOSE(),
  // color
  HTML_HELP_OPEN() \
  HTML_HELP_DEF("type", "ColorScale") \
  HTML_HELP_BODY() \
  "Color scale used to transform a scalar into a color." \
  HTML_HELP_CLOSE(),
};

Then, we can add the parameters in the constructor by writing the following lines:

addInParameter<StringCollection>("type",
                                 paramHelp[0],
                                 "linear;uniform;enumerated");
addInParameter<PropertyInterface*>("input property",
                                   paramHelp[1],
                                   "viewMetric");
addInParameter<StringCollection>("target",
                                 paramHelp[2],
                                 "nodes;edges");
addInParameter<ColorScale>("colorScale",
                           paramHelp[3],
                           "((75, 75, 255, 200),
                           (156, 161, 255, 200),
                           (255, 255, 127, 200),
                           (255, 170, 0, 200),
                           (229, 40, 0, 200))");

Accessing a parameter

The class PropertyAlgorithm has a protected member called dataSet that contains all the parameters. The DataSet class implements a container which allows insertion of values of different types and implements the following methods:

  • Get:

    template<typename T> bool get(const std::string &key, T& value) const
    

    Returns a copy of the value of the variable with name. If the variable name doesn’t exist return false else true.

  • GetAndFree:

    template<typename T> bool getAndFree(const std::string &key, T& value)
    

    Returns a copy of the value of the variable with name name. If the variable name doesn’t exist return false else true. The data is removed after the call.

  • Set:

    template<typename T> void set(const std::string &key, const T& value)
    

    Set the value of the variable name.

  • Exist:

    bool exist(const std::string &str) const
    

    Returns true if name exists else false.

  • GetValues:

    tlp::Iterator< std::pair<std::string, DataType*> > *getValues() const
    

    Returns an iterator on all values.

The methods described above are just the core of the functionalities. Consult the Doxygen documentation or the sources for an exhaustive listing.

The PluginProgress class

The class PluginProgress can be used to interact with the user. Following is a list of its members.

Public members

Following is a list of some Public members:

  • ProgressState progress (int step, int max_step): This method can be used to know the global progress of an algorithm (the number of steps accomplished).
  • void showPreview (bool showPreview): Enables to specify if the preview check box has to be visible or not.
  • bool isPreviewMode () const: Enables to know if the user has checked the preview box.
  • ProgressState state () const: Indicates the state of the ‘Cancel’, ‘Stop’ buttons of the dialog
  • void setError (const std::string& error): Shows an error message to the user
  • void setComment (const std::string& msg): Shows a comment message to the user

Plugin Progress example

In the following small example, we will iterate all the nodes and notify the user of the progression.

unsigned int i=0;
unsigned int nbNodes = graph->numberOfNodes ();
const unsigned int STEP = 10;
node n;
forEach(n, graph->getNodes(n)) {
  ...
  ... // Do what you want
  ...
  if(i%STEP==0) {
     pluginProgress->progress(i, nbNodes); //Says to the user that the algorithm has progressed.
     //exit if the user has pressed on Cancel or Stop
     if(pluginProgress->state() != TLP_CONTINUE) {
        returnForEach pluginProgress->state()!=TLP_CANCEL;
     }
  }
  i++;
}

Before exiting, we check if the user pressed stop or cancel. If he pressed “cancel”, the graph will not be modified. If he pressed “stop”, all values computed till now will be saved to the graph.

Example of a PropertyAlgorithm skeleton

Following is an example of a dummy color algorithm:

#include <tulip/TulipPluginHeaders.h>
#include <string>

using namespace std;
using namespace tlp;

/** Algorithm documentation */
// MyColorAlgorithm is just an example

class MyColorAlgorithm:public ColorAlgorithm {
public:

p">(),

  (" Name of theCcurrentrAlgorithe",
                    >" Name of theAuthoar",
                    >"13/13/13r",
                    >"A fewr words descriwing what kind ofraction the plug-inreializes",
                    >" Plug-i> versioe",
                    >" Name of theSub-gmenc unden which the plug-inshouldo be clasdifiee")

p">(),

  //iIt is the right place to declare the parameter,
  // needed by the algorith),
  //  >addInParamete <nParameteaTypg>(>" Nam>"e,"mHel ;string"e," Default valu>");
  // and declare the algorithm dependenciestoon}
  //  >addDependenc(>"nNam>"ee " versioe");
  MyColorAlgorithm(const PluginContext* ):() {
  

p">(),

  //~>MyColorAlgorith() >{
  //})

p">(),

  //Itd can be used to check topological propertiey of the grap),
  // metric properties on graph elements or an thing else you neen}
  //>bool chec (std::strin g& errorMsg) }
  //   errorMs=e"e");
  //  {return true{
  //})

p">(),

  //    - >It will be called out if the pre-condition method (bool check (..)) returned true.
  //    - >It is the starting point of your algorithm.
  // The returned value must be true if your algorithm succeeded.
  bool () {
   > true
  }
t;

(MyColorAlgorithm)

directory in the sources also proossesar more dnlse-skeletoy in the>lpaAlgorithmfolnden rit out all the commenes andreidys to be transforred intoa br and new Plugi>.

The-clase Algorithm is the-clase from which your algorithm will inherits if you tant to write a more genecal algorithm.Ionshead of modiysing just o specific property,itd can be used to modiys"svnecal of thmd. In this section, we will list some of its memberr to have a global overview ng what we can use oe develos such t plug-in}

Public members

Following is a list of all public members :

  • PluginContex *; context):Ase prevouslys describe,n the constructor is the right place to declare the parameter/ needed by the algoriths:

    addInParameter<DoubleProperty>("mMetric", paramHelp[0], 0);
    
    addDependency("MyGgenecarAlgorithe","QquoirentClusftering"0);
    
  • yAlgorithm (): Destructor of the class.

  • bool run (): This is the main method:

    • It will be called out if the pre-condition method (bool check (..)) returned true.
    • It is the starting point of your algorithm. The returned value must be true if your algorithm succeeded.
  • bool check (std::strin)p: This method can be used to check what you needessed1 topological propertiey of the grap)/ metric properties on graph elements or an thing elss.

  • The methods belos, will be redefined inyour plu in (See section plug-insskeleto)>.

    Protected members

    Following is a list of all protected member, "siialar to the nhe fundy in the>PropertyAlgorithm class:

    Public members

    Following is a list of all public members :

  • :Agtai,e the parameter/ needed by the algorithe must be declared into the constructor( example of>

    addInParameter<unsigned int>("Mminimumslize",paramHelp[0],"100s");
    addInParameter<unsigned int>("Mmaximumslize",paramHelp[1],"1000s");
    addInParameter<bool>("tree la yoet",paramHelp[2]," falsg"0);
    
    addDependency("Tree Leafe","1.0s");
    
  • IempotModule ((): Destructor of the class.

  • booliempotn (const std::strinf nam(): This is the main metho,s the starting point of your algorithm. The returned value must be true if your algorithm succeees.

  • The methods above must be redefined inyour plu in as shown in the>.

    Protected members

    Following is a list of all protected members :

    #include <tulipIempotModulen.h>
    #include <string>
    
    using namespace std;
    using namespace tlp;
    
    /**Iempotnmodule adocumentation */
    // MIempotModule  is just an example
    
    class MIempotModule):public  {
    public:
    
    p">(),
    
      (" Name of theCcurrentIempotnrAlgorithe",
                        >" Name of theAuthoar",
                        >"13/13/13r",
                        >"A fewr words descriwing what kind ofiempotn the plug-inreializes",
                        >" Plug-i> versioe",
                        >" Name of theSub-gmenc unden which the plug-inshouldo be clasdifiee")
    
    p">(),
    
      //iIt is the right place to declare the parameter,
      // needed by the algorith),
      //  >addInParamete <nParameteaTypg>(>" Nam>"e,"mHel ;string"e," Default valu>");
      // and declare the algorithm dependenciestoon}
      //  >addDependenc(>"nNam>"ee " versioe");
      MIempotModule)(tlp::PluginContext* ):() {
      
    
    p">(),
    
      //~>MIempotModule() >{
      //})
    
    p">(),
    
      // The returned value must be true ifiIt succeeded.
      bool () {
       > true
      }
    t;
    
    (MIempotModule))
    
    PropertyAlgorithmlpiempotmfolnden in the source,c unden the> directorh.

    Empotn plug-irs

    EmpotModule)<

    Public members

    Following is a list of the utual public members :

  • EmpotModule (>lp::>PluginContex *; context):>Following the examplis senk to this poinn, wes till have to use The constructor to add the parameters:

    addInParameter<>(" Nam>","mHel ;string"," Default valu>"0);
    
    addDependency("nNam>"," versioe");
    
  • >EmpotModule ((): Destructor of the class.

  • bool"empotGgrap (std:oesteam g&os(): This is the main metho,s the starting point of your algorithm. The returned value must be true if your algorithm succeeded.

  • The methods above will be redefined inyour plu in (seetthe .

    Protected members

    Following is a list of all protected members :

    EmpotModule adeivedm class
    #include <tulip>EmpotModulen.h>
    #include <string>
    #include <ioesteamg>
    
    using namespace std;
    using namespace tlp;
    
    **n>Empotnmodule adocumentation */
    // M>EmpotModule  is just an example
    
    class M>EmpotModule):public EmpotModule) {
    public:
    ">(),
     (" Name of theCcurrent>EmpotnrAlgorithe",
                      >" Name of theAuthoar",
                      >"13/13/13r",
                      >"A fewr words descriwing what kind ofeEmpotn the plug-inreializes",
                      >" Plug-i> versioe",
                      >" Name of theSub-gmenc unden which the plug-inshouldo be clasdifiee")
    
    p">(),
    
      //iIt is the right place to declare the parameter,
      // needed by the algorith),
      //  >addInParamete <nParameteaTypg>(>" Nam>"e,"mHel ;string"e," Default valu>");
      // and declare the algorithm dependenciestoon}
      //  >addDependenc(>"nNam>"ee " versioe");
      M>EmpotModule)(tlp::PluginContext* ):EmpotModule)() {
      
    
    p">(),
    
      //~>M>EmpotModule() >{
      //})
    
    p">(),
    
      // The returned value must be true ifiIt succeeded.
      bool ( &) {
       > true
      }
    t;
    
    (M>EmpotModule))
    
    tl"empotmfolnden in the source,c in the> directorh.

    >