1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
|
<chapter id="plugins-development"><title>Plug-ins development</title>
<para>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, one must write plug-ins very carefully to prevent memory leak and also
errors. A bug in plug-in can result in a "core dump" in the software that uses it. 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 directly access to it.</para>
<para>To develop a plug-in, you need to create a new class that will inherits from a specific algorithm class. Algorithms classes are separated in 4 different types :</para>
<itemizedlist>
<title>Basic classes :</title>
<listitem> <para><code> Property algorithms :</code> </para>
<para>This kind of plug-ins will only affect a specific property of any type. See <xref linkend="propertyalgorithm-class" />.</para>
</listitem>
<listitem> <para><code>Generic algorithms :</code></para>
<para>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 <xref linkend="algorithm-class" />.</para>
</listitem>
<listitem> <para> <code>Importation algorithms :</code></para>
<para>Plug-ins to import a specific graph. For example a plug-in that will create a graph from a file directory system. See <xref linkend="importModule" />.</para>
</listitem>
<listitem> <para><code> Export algorithms :</code> </para>
<para>Plug-ins to save a graph to a specific type of file. See <xref linkend="exportModule" />. </para>
</listitem>
</itemizedlist>
<sect1 id="propertyalgorithm-class"><title>The PropertyAlgorithm class.</title>
<para>The PropertyAlgorithm class, is the class from which inherits different types of algorithms such as the BooleanAlgorithm class or the LayoutAlgorithm class (see picture below). This class is important in the way that every specific algorithm that you will develop will have to inherit from one of those classes. For example, if you write a plug-in to update the graph layout, your new class will have to inherit from the LayoutAlgorithm class which inherits from this PropertyAlgorithm class. </para>
<graphic fileref="../doxygen/tulip-lib/classtlp_1_1PropertyAlgorithm__inherit__graph.png" />
<para>Each one of the 8 classes presented above has a public member, <emphasis>TypeName</emphasis><code>Property</code>* <emphasis>typeName</emphasis><code>Result</code>, which is the data member that which have to be updated by your plug-in. After a successful run tulip will automatically copy this data member into the corresponding property of the graph. Following is a table showing the data member, graph property and 'Algorithms' GUI submenu corresponding to each subclass of Algorithm :</para>
<informaltable frame="all">
<tgroup cols="4">
<thead>
<row>
<entry>Class name</entry>
<entry>Data member</entry>
<entry>Graph property replaced</entry>
<entry>Algorithms GUI submenu</entry>
</row>
</thead>
<tbody>
<row>
<entry>BooleanAlgorithm</entry>
<entry>booleanResult</entry>
<entry>viewSelection</entry>
<entry>Selection</entry>
</row>
<row>
<entry>ColorAlgorithm</entry>
<entry>colorResult</entry>
<entry>viewColor</entry>
<entry>Color</entry>
</row>
<row>
<entry>DoubleAlgorithm</entry>
<entry>doubleResult</entry>
<entry>viewMetric</entry>
<entry>Measure</entry>
</row>
<row>
<entry>Algorithm</entry>
<entry>NA</entry>
<entry>NA</entry>
<entry>General</entry>
</row>
<row>
<entry>IntegerAlgorithm</entry>
<entry>integerResult</entry>
<entry>viewInt</entry>
<entry>Integer</entry>
</row>
<row>
<entry>LayoutAlgorithm</entry>
<entry>layoutResult</entry>
<entry>viewLayout</entry>
<entry>Layout</entry>
</row>
<row>
<entry>SizeAlgorithm</entry>
<entry>sizeResult</entry>
<entry>viewSize</entry>
<entry>Size</entry>
</row>
<row>
<entry>StringAlgorithm</entry>
<entry>stringResult</entry>
<entry>viewLabel</entry>
<entry>Label</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para> Note that at anytime, if the user clicks on the "cancel" button ( see <xref linkend="pluginprogress-class" /> for more details ), none of your algorithm's actions will changes the graph since the variable <emphasis>typeName</emphasis>Result is not copied in the corresponding property.</para>
<sect2 id="algoprop-quick-desc"><title>Overview of the class</title>
<para>A quick overview of the functions and data members of the class PropertyAlgorithm is needed in order to have a generic understanding of its 8 derived classes. </para>
<sect3 id="algoprop-public-atributes"><title>Public members</title>
<para>
Following is a list of all public members :
</para>
<itemizedlist>
<listitem><para>
<methodname>PropertyAlgorithm (const PropertyContext& context)</methodname> :</para>
<para>The constructor is the right place to declare the parameters needed by the algorithm.</para>
<para><code> addParameter<DoubleProperty>("metric", paramHelp[0], 0, false);</code></para>
<para> And to declare the algorithm dependencies.</para> <para><code>addDependency<Algorithm>("Quotient Clustering", "1.0");</code></para>
</listitem>
<listitem><para>
<methodname>~PropertyAlgorithm () </methodname> : Destructor of the class.
</para></listitem>
<listitem><para>
<methodname>bool run ()</methodname> :</para><para> This is the main method :</para>
<para> - It will be called out if the pre-condition method (bool check (..)) returned true.</para>
<para> - It is the starting point of your algorithm.</para>
<para> The returned value must be true if your algorithm succeeded.</para>
</listitem>
<listitem><para>
<methodname>bool check (std::string& errMsg)</methodname> :</para><para> This method can be used to check what you need about topological properties of the graph, metric properties on graph elements or anything else.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="algoprop-protected-atributes"><title>Protected members</title>
<para>
Following is a list of all protected members :
</para>
<itemizedlist>
<listitem><para>
<methodname>Graph* graph </methodname> :</para>
<para>This graph is the one given in parameters, the one on which the algorithm will be applied.</para>
</listitem>
<listitem><para>
<methodname>PluginProgress* pluginProgress </methodname> :</para>
<para> 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.</para>
</listitem>
<listitem><para>
<methodname>DataSet* dataSet </methodname> :</para><para>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.</para>
</listitem>
</itemizedlist>
<para>The methods of the <emphasis>TypeName</emphasis>Algorithm class, will be redefined in your plug-in as shown in <xref linkend="algoprop-example" />.</para>
</sect3>
</sect2>
<sect2 id="dataset-class"><title>Parameters :</title>
<para>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.
</para>
<sect3 id="algoprop-param-declare"><title>Adding parameters to an algorithm</title>
<para>The class PropertyAlgorithm inherits from a class called WithParameters that has a member function named <methodname>template<typename Type> void addParameter (const char *name, const char *inHelp=0, const char *inDefValue=0, bool isMandatory=true)</methodname> which is capable of adding a parameter. This method has to be called in the constructor of your class.</para>
<para>Following is a description of its parameters :</para>
<itemizedlist>
<listitem><para> name : Name of the new parameter.
</para></listitem>
<listitem><para> inHelp : This parameter can be used to add a documentation to the parameter (See example below).
</para></listitem>
<listitem><para> inDefValue : Default value.
</para></listitem>
<listitem><para> isMandatory : If false, the user must give a value.
</para></listitem>
</itemizedlist>
<para>On the following example, we declare a character buffer that will contain the documentation of our parameters. </para>
<programlisting role="C">
<![CDATA[
namespace {
const char * paramHelp[] = {
// property
HTML_HELP_OPEN() \
HTML_HELP_DEF( "type", "DoubleProperty" ) \
HTML_HELP_BODY() \
"This metric is used to affect scalar values to graph items." \
"The meaning of theses values depends of the choosen color model." \
HTML_HELP_CLOSE(),
// colormodel
HTML_HELP_OPEN() \
HTML_HELP_DEF( "type", "int" ) \
HTML_HELP_DEF( "values", "[0,1]" ) \
HTML_HELP_DEF( "default", "0" ) \
HTML_HELP_BODY() \
"This value defines the type of color interpolation. Following values are valid :" \
"<ul><li>0: HSV interpolation ;</li><li>1: RGB interpolation</li></ul>" \
HTML_HELP_CLOSE(),
// color1
HTML_HELP_OPEN() \
HTML_HELP_DEF( "type", "Color" ) \
HTML_HELP_DEF( "values", "[0,255]^4" ) \
HTML_HELP_DEF( "default", "red" ) \
HTML_HELP_BODY() \
"This is the start color used in the interpolation process." \
HTML_HELP_CLOSE(),
// color2
HTML_HELP_OPEN() \
HTML_HELP_DEF( "type", "Color" ) \
HTML_HELP_DEF( "values", "[0,255]^4" ) \
HTML_HELP_DEF( "default", "green" ) \
HTML_HELP_BODY() \
"This is the end color used in the interpolation process." \
HTML_HELP_CLOSE(),
// Mapping type
HTML_HELP_OPEN() \
HTML_HELP_DEF( "type", "Boolean" ) \
HTML_HELP_DEF( "values", "true / false" ) \
HTML_HELP_DEF( "default", "true" ) \
HTML_HELP_BODY() \
"This value defines the type of mapping. Following values are valid :" \
"<ul><li>true : linear mapping</li><li>false: uniform quantification</li></ul>" \
HTML_HELP_CLOSE(),
};
}]]>
</programlisting>
<para>Then, we can add the parameters in the constructor by writing the following lines:</para>
<programlisting role="C">
<![CDATA[
addParameter<DoubleProperty>("property",paramHelp[0],"viewMetric");
addParameter<int>("colormodel",paramHelp[1],"1");
addParameter<bool>("type",paramHelp[4],"true");
addParameter<Color>("color1",paramHelp[2],"(255,255,0,128)");
addParameter<Color>("color2",paramHelp[3],"(0,0,255,228)");]]>
</programlisting>
<para>The picture below is the result of the sample of code above.</para>
<graphic fileref="images/plugin_doc_add_parameter_1.png" />
</sect3>
<sect3 id="dataset-param"><title>Accessing a parameter</title>
<para>The class PropertyAlgorithm has a protected member called <emphasis>dataSet</emphasis> that contains all the parameters value.The DataSet class implements a container which allows insertion of values of different types and implements the following methods :</para>
<itemizedlist>
<listitem><para>
<methodname>template<typename T> bool get (const std::string& name, T value) const</methodname> :</para>
<para>Returns a copy of the value of the variable with name name. If the variable name doesn't exist return false else true. </para>
</listitem>
<listitem><para>
<methodname>template<typename T> bool getAndFree (const std::string& name, T value)</methodname> :</para>
<para> 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. </para>
</listitem>
<listitem><para>
<methodname>template<typename T> void set (const std::string& name, const T value)</methodname> :</para>
<para>Set the value of the variable name.</para>
</listitem>
<listitem><para>
<methodname>bool exist (const std::string& name) const</methodname> :</para>
<para>Returns true if name exists else false.</para>
</listitem>
<listitem><para>
<methodname>Iterator<std::pair<std::string, DataType> >* getValues () const</methodname> :</para>
<para>Returns an iterator on all values </para>
</listitem>
</itemizedlist>
<para>Has you could have guess, the one important to access a parameter is get() which allows to access to a specific parameter. Following is an example of its use :</para>
<programlisting role="C">
<![CDATA[
DoubleProperty* metricS;
int colorModel;
Color color1;
Color color2;
bool mappingType = true;
if ( dataSet!=0 ) {
dataSet->get("property", metricS);
dataSet->get("colormodel", colorModel);
dataSet->get("color1", color1);
dataSet->get("color2", color2);
dataSet->get("type", mappingType);
}]]>
</programlisting>
</sect3>
</sect2>
<sect2 id="pluginprogress-class"><title>The PluginProgress class.</title>
<para>
The class PluginProgress can be used to interact with the user. Following is a list of its members
</para>
<sect3 id="pluginprog-public-atributes"><title>Public members</title>
<para>
Following is a list of all Public members :
</para>
<itemizedlist>
<!--
<listitem>
<methodname>PluginProgress () </methodname> :
<para>Constructor of the class.</para>
</listitem>
<listitem>
<methodname>~PluginProgress ()</methodname> :<para>Destructor</para>
</listitem>
!-->
<listitem><para>
<methodname>ProgressState progress (int step, int max_step)</methodname> :</para><para> This method can be used to know the global progress of or algorithm, the number of steps accomplished.</para>
</listitem>
<listitem><para>
<methodname> void showPreview (bool)</methodname> :</para>
<para> Enables to specify if the preview check box has to be visible or not. </para>
</listitem>
<listitem><para>
<methodname> bool isPreviewMode ()</methodname> :</para>
<para> Enables to know if the user has checked the preview box. </para>
</listitem>
<listitem><para>
<methodname>ProgressState state () const </methodname> :</para>
<para> Indicates the state of the 'Cancel', 'Stop' buttons of the dialog</para>
</listitem>
<listitem><para>
<methodname>void setError (std::string error)</methodname> :</para>
<para>Shows an error message to the user</para>
</listitem>
<listitem><para>
<methodname>void setComment (std::string msg)</methodname> :</para>
<para>Shows a comment message to the user </para>
</listitem>
</itemizedlist>
<para></para>
</sect3>
<sect3 id="exemple-pluginprogress"><title>PluginProgress example</title>
<para>In following small example, we will iterate over all nodes and notify the user of the progression. </para>
<programlisting role="C">
<![CDATA[
unsigned int i=0;
unsigned int nbNodes = graph->numberOfNodes ();
const unsigned int STEP = 10;
node n;
forEach(n, graph->getInEdges(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++;
}]]>
</programlisting>
<para>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.</para>
</sect3>
</sect2>
<sect2 id="algoprop-example"><title>Example of a plugin skeleton</title>
<para>Following is an example of a dummy color algorithm ( you can find more example in the tulip tarball ):</para>
<programlisting role="C">
<![CDATA[
#include <tulip/TulipPlugin.h>
#include <string>
using namespace std;
using namespace tlp;
/** Algorithm documentation */
// MyColorAlgorithm is just an example
/*@{*/
class MyColorAlgorithm:public ColorAlgorithm {
public:
// The constructor below has to be defined,
// it is the right place to declare the parameters
// needed by the algorithm,
// addParameter<DoubleProperty>("metric", paramHelp[0], 0, false);
// and declare the algorithm dependencies too.
// addDependency<Algorithm>("Quotient Clustering", "1.0");
MyColorAlgorithm(PropertyContext& context):ColorAlgorithm(context) {
}
// Define the destructor only if needed
// ~MyColorAlgorithm() {
// }
// Define the check method only if needed.
// It can be used to check topological properties of the graph,
// metric properties on graph elements or anything else you need.
// bool check(string& errorMsg) {
// errorMsg="";
// return true;
// }
// The run method 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 run() {
return true;
}
};
/*@}*/
// This line is very important because it's the only way to register your algorithm in tulip.
// It automatically builds the plugin object that will embed the algorithm.
COLORPLUGIN(MyColorAlgorithm, "My Color Algorithm", "Authors", "07/07/07", "Comments", "1.0")
// If you want to present your algorithm in a dedicated submenu of the Tulip GUI,
// use the declaration below where the last parameter specified the name of submenu.
// COLORPLUGINOFGROUP(MyColorAlgorithm, "My Color Algorithm", "Authors", "07/07/07", "Comments", "1.0", "My algorithms");]]>
</programlisting>
</sect2>
</sect1>
<!-- ///////////////////////////////////////////////////Algorithm class//////////////////////////////////////////////////// !-->
<sect1 id="algorithm-class"><title>The Algorithm class.</title>
<para>
The class Algorithm is the class from which your algorithm will inherits if you want to write a more general algorithm. Instead of modifying just a specific property, it can be used to modify the entire graph. In this section, we will list all its members to have a global overview on what we can use to develop such a plug-in.
</para>
<sect2 id="algo-public-atributes"><title>Public members</title>
<para>
Following is a list of all public members :
</para>
<itemizedlist>
<listitem><para>
<methodname>Algorithm (AlgorithmContext context)</methodname> :</para>
<para>The constructor is the right place to declare the parameters needed by the algorithm.</para>
<para><code> addParameter<DoubleProperty>("metric", paramHelp[0], 0, false);</code></para>
<para> And to declare the algorithm dependencies.</para> <para><code>addDependency<Algorithm>("Quotient Clustering", "1.0");</code></para>
</listitem>
<listitem><para>
<methodname>~Algorithm () </methodname> :</para><para>Destructor of the class.</para>
</listitem>
<listitem><para>
<methodname>bool run ()</methodname> :</para><para> This is the main method :</para>
<para> - It will be called out if the pre-condition method (bool check (..)) returned true.</para>
<para> - It is the starting point of your algorithm.</para>
<para> The returned value must be true if your algorithm succeeded.</para>
</listitem>
<listitem><para>
<methodname>bool check (std::string)</methodname> :</para><para> This method can be used to check what you need about topological properties of the graph, metric properties on graph elements or anything else.</para>
</listitem>
</itemizedlist>
<para>The methods below, will be redefined in our plugin (See section plug-in skeleton).</para>
</sect2>
<sect2 id="algo-protected-atributes"><title>Protected members</title>
<para>
Following is a list of all protected members :
</para>
<itemizedlist>
<listitem><para>
<methodname>Graph* graph </methodname> :</para>
<para>This graph is the one given in parameters, the one on which the algorithm will be applied.</para>
</listitem>
<listitem><para>
<methodname>PluginProgress* pluginProgress </methodname> :</para>
<para> The class PluginProgress can be used to have an interaction between the user and our algorithm. See <xref linkend="pluginprogress-class" /> for more details. </para>
</listitem>
<listitem><para>
<methodname>DataSet* dataSet </methodname> :</para><para>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.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- ///////////////////////////////////////////////Import Export////////////////////////////////////////////////////////// !-->
<sect1 id="importModule"><title>Import plug-ins</title>
<para>
In this section, we will learn how to create import plug-ins. Those plug-ins will inherit from ImportModule.
</para>
<para>Following is a small description of the class ImportModule : </para>
<sect2 id="importprop-public"><title>Public members</title>
<para>
Following is a list of all public members :
</para>
<itemizedlist>
<listitem><para>
<methodname>ImportModule (AlgorithmContext context)</methodname> :</para>
<para>The constructor is the right place to declare the parameters needed by the algorithm.</para>
<para><code> addParameter<DoubleProperty>("metric", paramHelp[0], 0, false);</code></para>
<para> And to declare the algorithm dependencies.</para> <para><code>addDependency<Algorithm>("Quotient Clustering", "1.0");</code></para>
</listitem>
<listitem><para>
<methodname>~ImportModule () </methodname> :</para><para>Destructor of the class.</para>
</listitem>
<listitem><para>
<methodname>bool import (const std::string name)</methodname> :</para><para> This is the main method, the starting point of your algorithm.</para>
<para> The returned value must be true if your algorithm succeeds.</para>
</listitem>
</itemizedlist>
<para>The methods below, will be redefined in our plugin (See section plug-in skeleton).</para>
</sect2>
<sect2 id="import-protected"><title>Protected members</title>
<para>
Following is a list of all protected members :
</para>
<itemizedlist>
<listitem><para>
<methodname>Graph* graph </methodname> :</para>
<para>This graph is the one given in parameters, the one on which the algorithm will be applied.</para>
</listitem>
<listitem><para>
<methodname>PluginProgress* pluginProgress </methodname> :</para>
<para> The class PluginProgress can be used to have an interaction between the user and our algorithm. See <xref linkend="pluginprogress-class" /> for more details. </para>
</listitem>
<listitem><para>
<methodname>DataSet* dataSet </methodname> :</para><para>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.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="import-skeleton"><title>Skeleton an ImportModule derived class</title>
<programlisting role="C">
<![CDATA[#include <tulip/TulipPlugin.h>
#include <string>
using namespace std;
using namespace tlp;
/** Import module documentation */
// MyImportModule is just an example
/*@{*/
class MyImportModule:public ImportModule {
public:
// The constructor below has to be defined,
// it is the right place to declare the parameters
// needed by the algorithm,
// addParameter<DoubleProperty>("metric", paramHelp[0], 0, false);
// and declare the algorithm dependencies too.
// addDependency<Algorithm>("Quotient Clustering", "1.0");
MyImportModule(AlgorithmContext context):ImportModule(context) {
}
// Define the destructor only if needed
// ~MyImportModule() {
// }
// The import method is the starting point of your import module.
// The returned value must be true if it succeeded.
bool import(const string &name) {
return true;
}
};
/*@}*/
// This line is very important because it's the only way to register your import module in tulip.
// It automatically builds the plugin object that will embed the algorithm.
IMPORTPLUGIN(MyImportModule, "My Import Module", "Authors", "07/07/07", "Comments", "1.0")
// If you want to present your algorithm in a dedicated submenu of the Tulip GUI,
// use the declaration below where the last parameter specified the name of submenu.
// IMPORTPLUGINOFGROUP(MyImportModule, "My Import Module", "Authors", "07/07/07", "Comments", "1.0", "My algorithms");]]>
</programlisting>
</sect2>
</sect1>
<sect1 id="exportModule"><title>Export plug-ins</title>
<para>
In this section, we will learn how to create export plug-ins. Those plug-ins will inherit from ExportModule.
</para>
<para>Following is a small description of the class ExportModule : </para> <sect2 id="public-attributes"><title>Public members</title>
<para>
Following is a list of all public members :
</para>
<itemizedlist>
<listitem><para>
<methodname>ExportModule (AlgorithmContext context)</methodname> :</para>
<para>The constructor is the right place to declare the parameters needed by the algorithm.</para>
<para><code> addParameter<DoubleProperty>("metric", paramHelp[0], 0, false);</code></para>
<para> And to declare the algorithm dependencies.</para> <para><code>addDependency<Algorithm>("Quotient Clustering", "1.0");</code></para>
</listitem>
<listitem><para>
<methodname>~ExportModule () </methodname> :</para><para>Destructor of the class.</para>
</listitem>
<listitem><para>
<methodname>bool import (const std::string name)</methodname> :</para><para> This is the main method, the starting point of your algorithm.</para>
<para> The returned value must be true if your algorithm succeeded.</para>
</listitem>
</itemizedlist>
<para>The methods below, will be redefined in our plugin (See section plug-in skeleton).</para>
</sect2>
<sect2 id="protected-atributes"><title>Protected members</title>
<para>
Following is a list of all protected members :
</para>
<itemizedlist>
<listitem><para>
<methodname>Graph* graph </methodname> :</para>
<para>This graph is the one given in parameters, the one on which the algorithm will be applied.</para>
</listitem>
<listitem><para>
<methodname>PluginProgress* pluginProgress </methodname> :</para>
<para> The class PluginProgress can be used to have an interaction between the user and our algorithm. See <xref linkend="pluginprogress-class" /> for more details. </para>
</listitem>
<listitem><para>
<methodname>DataSet* dataSet </methodname> :</para><para>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.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="example-plugin-export"><title>Skeleton of an ExportModule derived class</title>
<programlisting role="C">
<![CDATA[
#include <tulip/TulipPlugin.h>
#include <string>
#include <iostream>
using namespace std;
using namespace tlp;
/** Export module documentation */
// MyExportModule is just an example
/*@{*/
class MyExportModule:public ExportModule {
public:
// The constructor below has to be defined,
// it is the right place to declare the parameters
// needed by the algorithm,
// addParameter<DoubleProperty>("metric", paramHelp[0], 0, false);
// and declare the algorithm dependencies too.
// addDependency<Algorithm>("Quotient Clustering", "1.0");
MyExportModule(AlgorithmContext context):ExportModule(context) {
}
// Define the destructor only if needed
// ~MyExportModule() {
// }
// The exportGraph method is the starting point of your export module.
// The returned value must be true if it succeeded.
bool exportGraph(ostream &os,Graph *graph) {
return true;
}
};
/*@}*/
// This line is very important because it's the only way to register your export module in tulip.
// It automatically builds the plugin object that will embed the algorithm.
EXPORTPLUGIN(MyExportModule, "My Export Module", "Authors", "07/07/07", "Comments", "1.0")
// If you want to present your algorithm in a dedicated submenu of the Tulip GUI,
// use the declaration below where the last parameter specified the name of submenu.
// EXPORTPLUGINOFGROUP(MyExportModule, "My Export Module", "Authors", "07/07/07", "Comments", "1.0", "My algorithms");
]]>
</programlisting>
</sect2>
</sect1>
<sect1 id="plugin-skeleton"><title>Compilation ( Makefiles )</title>
<para>You can download plugins skeletons <ulink url="http://tulip.labri.fr/samples/plugintemplates.tar.gz">here</ulink> .</para>
<para>Following is a Makefile that compiles a plug-in :</para>
<programlisting role="C">
<![CDATA[# Update the line below according to the tulip installation directory you choosed
TULIP_DIR=/usr/local/bin
TULIP_CONFIG=$(TULIP_DIR)/tulip-config
TULIP_VERSION=$(shell ${TULIP_CONFIG} --version)
LIB_EXTENSION=$(shell ${TULIP_CONFIG} --pluginextension)
# To limit, crash problems when loading a plugin library
# Tulip only load those whose names end with a compatible version number
TARGET= libmyalgorithm-$(TULIP_VERSION).$(LIB_EXTENSION)
# a plugin library may contain more than one algorithm
# so you can have several source files on the line below
SRCS = MyGeneralAlgorithm.cpp
CXX=g++
CXXFLAGS = -O3 -Wall -DNDEBUG `${TULIP_CONFIG} --cxxflags --plugincxxflags`
LDFLAGS= `${TULIP_CONFIG} --pluginldflags` `${TULIP_CONFIG} --libs`
OBJS=$(SRCS:.cpp=.o)
DEPS=$(SRCS:.cpp=.d)
all: $(TARGET)
$(TARGET): $(OBJS)
$(CXX) $(OBJS) -o $@ $(LDFLAGS) $(LIBS)
clean :
-rm -f $(TARGET) *.o *.d
install: all
install $(TARGET) `${TULIP_CONFIG} --pluginpath`
%.d: %.cpp
$(CXX) -M $(CXXFLAGS) $< \
| sed 's!\($*\)\.o[ :]*!\1.o $@ : !g' > $@; \
[ -s $@ ] 2>/dev/null || rm $@
-include $(DEPS)]]>
</programlisting>
<procedure><title>Compile and install your plugin</title>
<step>
<screen><prompt>[user@localhost ]$ </prompt><userinput>make</userinput>
</screen>
<para>Type make in a terminal.</para>
</step>
<step>
<screen><prompt> [user@localhost ]$ </prompt><userinput>make install</userinput>
</screen>
<para>Type make install in a terminal. Be careful that you may need root privileges to do this.</para>
</step>
<step>
<screen><prompt>[user@localhost ]$ </prompt><userinput>make clean</userinput>
</screen>
<para>'make clean', will remove all generated files (libraries, *.o , ...)</para>
</step>
</procedure>
</sect1>
</chapter>
|
