1Tk::GraphViz(3)       User Contributed Perl Documentation      Tk::GraphViz(3)
2
3
4

NAME

6       Tk::GraphViz - Render an interactive GraphViz graph
7

SYNOPSIS

9           use Tk::GraphViz;
10           my $gv = $mw->GraphViz ( qw/-width 300 -height 300/ )
11             ->pack ( qw/-expand yes -fill both/ );
12           $gv->show ( $dotfile );
13

DESCRIPTION

15       The GraphViz widget is derived from Tk::Canvas.  It adds the ability to
16       render graphs in the canvas.  The graphs can be specified either using
17       the DOT graph-description language, or using via a GraphViz or
18       GraphViz2 object.
19
20       When show() is called, the graph is passed to the dot command to
21       generate the layout info.  That info is then used to create rectangles,
22       lines, etc in the canvas that reflect the generated layout.
23
24       Once the items have been created in the graph, they can be used like
25       any normal canvas items: events can be bound, etc.  In this way,
26       interactive graphing applications can be created very easily.
27

METHODS

29   $gv->show ( graph, ?opt => val, ...? )
30       Renders the given graph in the canvas.  The graph itself can be
31       specified in a number of formats.  'graph' can be one of the following:
32
33       - An instance of the GraphViz class (or subclass thereof)
34       - A scalar containing a graph in DOT format.  The scalar must match
35       /^\s*(?:di)?graph /.
36       - An instance of the IO::Handle class (or subclass thereof), from which
37       to read a graph in DOT format.
38       - The name / path of a file that contains a graph in DOT format.
39
40       show() will recognize some options that control how the graph is
41       rendered, etc.  The recognized options:
42
43       layout => CMD
44           Specifies an alternate command to invoke to generate the layout of
45           the graph.  If not given, then default is 'dot'.  This can be used,
46           for example, to use 'neato' instead of 'dot'.
47
48       graphattrs => [ name => value, ... ]
49           Allows additional default graph attributes to be specified.  Each
50           name => value pair will be passed to dot as '-Gname=value' on the
51           command-line.
52
53       nodeattrs => [ name => value, ... ]
54           Allows additional default node attributes to be specified.  Each
55           name => value pair will be passed to dot as '-Nname=value' on the
56           command-line.
57
58       edgeattrs => [ name => value, ... ]
59           Allows additional default edge attributes to be specified.  Each
60           name => value pair will be passed to dot as '-Ename=value' on the
61           command-line.
62
63       fit => $boolean
64           If true, calls the "$gv->fit()" method after parsing the DOT
65           output.  As of 1.05, this no longer defaults to true.
66
67       prerender => \&coderef
68           If given, the code-ref will be called with the graph description
69           data before the actual drawing on a canvas begins, in a hash-ref,
70           e.g. for the file "digraph G { a -> b }":
71
72             {
73               edge => {
74                 a => {
75                   b => [
76                     {
77                       pos => [
78                         { e => 1 },
79                         [
80                           [ '27', '71.697' ],
81                           [ '27', '63.983' ],
82                           [ '27', '54.712' ],
83                           [ '27', '46.112' ],
84                           [ '27', '36.104' ],
85                         ]
86                       ]
87                     }
88                   ]
89                 }
90               },
91               global => { dpi => 72 }, # default value, might be overridden
92               node => {
93                 a => { height => '0.5', label => '\\N', pos => '27,90', width => '0.75' },
94                 b => { height => '0.5', label => '\\N', pos => '27,18', width => '0.75' }
95               },
96               subgraph => [
97                 [ '0', '0', '54', '108' ]
98               ]
99             }
100
101           The code's return value needs to be a hash-ref structured similarly
102           to the above, which will be used to render the graph. Coordinates
103           increase upwards and to the right. Nodes' "pos" are at their
104           centre.
105
106           This feature is experimental as of 1.10, and the data-structure
107           shape or interface may change.
108
109       For example, to use neato to generate a layout with non-overlapping
110       nodes and spline edges:
111
112           $gv->show ( $file, layout => 'neato',
113                       graphattrs => [qw( overlap false spline true )] );
114
115   $gv->createBindings ( ?option => value? )
116       The Tk::GraphViz canvas can be configured with some bindings for
117       standard operations.  If no options are given, the default bindings for
118       zooming and scrolling will be enabled.  Alternative bindings can be
119       specified via these options:
120
121       -zoom => true
122           Creates the default bindings for zooming.  Zooming in or out in the
123           canvas will be bound to <Shift-2> (Shift + mouse button 2).  To
124           zoom in, click and drag out a zoom rectangle from top left to
125           bottom right.  To zoom out, click and drag out a zoom rectangle
126           from bottom left to top right.
127
128       -zoom => spec
129           This will bind zooming to an alternative event sequence.  Examples:
130
131               -zoom => '<1>'      # Zoom on mouse button 1
132               -zoom => '<Ctrl-3>' # Zoom on Ctrl + mouse button 3
133
134       -scroll => true
135           Creates the default bindings for scrolling / panning.  Scrolling
136           the canvas will be bound to <2> (Mouse button 2).
137
138       -scroll => spec
139           This will bind scrolling to an alternative event sequence.
140           Examples:
141
142               -scroll => '<1>'      # Scroll on mouse button 1
143               -scroll => '<Ctrl-3>' # Scroll on Ctrl + mouse button 3
144
145       -keypad => true
146           Binds the keypad arrow / number keys to scroll the canvas, and the
147           keypad +/- keys to zoom in and out.  Note that the canvas must have
148           the keyboard focus for these bindings to be activated.  This is
149           done by default when createBindings() is called without any
150           options.
151
152   $gv->fit()
153       Scales all of the elements in the canvas to fit the canvas' width and
154       height.
155
156   $gv->zoom( -in => factor )
157       Zoom in by scaling everything up by the given scale factor.  The factor
158       should be > 1.0 in order to get reasonable behavior.
159
160   $gv->zoom( -out => factor )
161       Zoom out by scaling everything down by the given scale factor.  This is
162       equivalent to
163
164           $gv->zoom ( -in => 1/factor )
165
166       The factor should be > 1.0 in order to get reasonable behavior.
167
168   $gv->scrollTo(nodename)
169       If the given node (identified by being tagged with "node" and that
170       nodename) exists, the viewport is moved to have that at the centre.
171
172   $gv->nodes
173       Returns a list of the names of the graph's nodes, as identified by
174       being tagged with "node".
175
176   $gv->edges
177       Returns a list of the graph's edges, as identified by being tagged with
178       "edge", as array-refs with the incident nodes' names.
179

TAGS

181       In order to facilitate binding, etc, all of the graph elements (nodes,
182       edges, subgraphs) that are created in the canvas will be tagged.  Prior
183       to version 1.09, this was done in pairs of tags, but that is not how
184       tags in Tk work: they are individual things.
185
186       Each element is composed of several parts, typically at least a shape,
187       and text. Each of these parts will be tagged with its element type
188       (e.g. "node"), so that all of the visible area will be bindable as
189       such. They will also all be tagged with e.g. "node=thisNodeName", for
190       use together with "gettags". Only the outermost (or for a record, the
191       first) will be tagged with "outermost", so that a single part can be
192       found with e.g. a "withtags "outermost&&node=thisNodeName"", such as to
193       find the coordinates of the whole element.
194
195       Additionally, all attributes attached to an element in the graph
196       description (e.g. "color", "style", "label") will be included as tags,
197       in the form e.g. "color=red".
198
199   Nodes
200       Node elements are identified with a 'node' tag.  For example, to bind
201       something to all nodes in a graph:
202
203           $gv->bind ( 'node', '<Any-Enter>', sub { ... } );
204
205   Edges
206       Edge elements are identified with a 'edge' tag.  For example, to bind
207       something to all edges in a graph:
208
209           $gv->bind ( 'edge', '<Any-Enter>', sub { ... } );
210
211       The "naming tag" will be string of the form "edge=node1 node2", where
212       node1 and node2 are the names of the respective nodes.  To make it
213       convenient to get the individual node names, the edge also has tags
214       'node1' and 'node2', which give the node names separately. Components
215       of edges do not have an "outermost" tag.
216
217   Subgraphs
218       Subgraph elements are identified with a 'subgraph' tag.
219

EXAMPLES

221       The following example creates a GraphViz widgets to display a graph
222       from a file specified on the command line.  Whenever a node is clicked,
223       the node name and label are printed to stdout:
224
225           use GraphViz;
226           use Tk;
227
228           my $mw = MainWindow->new();
229           my $gv = $mw->Scrolled ( 'GraphViz',
230                                    -background => 'white',
231                                    -scrollbars => 'sw' )
232             ->pack ( -expand => '1', -fill => 'both' );
233
234           $gv->bind ( 'node', '<Button-1>', sub {
235               my @tags = $gv->gettags('current');
236               my ($label) = map /^label=(.*)/, @tags;
237               my ($node) = map /^node=(.*)/, @tags;
238               printf ( "Clicked node: '%s' => %s\n", $node, $label );
239           } );
240
241           $gv->show ( shift );
242           MainLoop;
243

BUGS AND LIMITATIONS

245       Lots of DOT language features not yet implemented
246
247       Various node shapes and attributes: polygon, skew, ...
248       Edge arrow head types
249

ACKNOWLEDGEMENTS

251       See <http://www.graphviz.org/> for more info on the graphviz tools.
252

AUTHOR

254       Jeremy Slade <jeremy@jkslade.net>
255
256       Other contributors: Mike Castle, John Cerney, Phi Kasten, Jogi
257       Kuenstner Tobias Lorenz, Charles Minc, Reinier Post, Slaven Rezic
258
260       Copyright 2003-2008 by Jeremy Slade
261
262       This library is free software; you can redistribute it and/or modify it
263       under the same terms as Perl itself.
264
265
266
267perl v5.36.0                      2022-07-22                   Tk::GraphViz(3)
Impressum