1Tk::GraphViz(3) User Contributed Perl Documentation Tk::GraphViz(3)
2
6 Tk::GraphViz - Render an interactive GraphViz graph
7
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
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 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 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
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 - 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 show() will recognize some options that control how the graph is
41 rendered, etc. The recognized options:
42 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 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 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 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 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 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 {
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 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 This feature is experimental as of 1.10, and the data-structure
107 shape or interface may change.
108 For example, to use neato to generate a layout with non-overlapping
110 nodes and spline edges:
111 $gv->show ( $file, layout => 'neato',
113 graphattrs => [qw( overlap false spline true )] );
114 $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 -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 -zoom => spec
129 This will bind zooming to an alternative event sequence. Examples:
130 -zoom => '<1>' # Zoom on mouse button 1
132 -zoom => '<Ctrl-3>' # Zoom on Ctrl + mouse button 3
133 -scroll => true
135 Creates the default bindings for scrolling / panning. Scrolling
136 the canvas will be bound to <2> (Mouse button 2).
137 -scroll => spec
139 This will bind scrolling to an alternative event sequence.
140 Examples:
141 -scroll => '<1>' # Scroll on mouse button 1
143 -scroll => '<Ctrl-3>' # Scroll on Ctrl + mouse button 3
144 -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 $gv->fit()
153 Scales all of the elements in the canvas to fit the canvas' width and
154 height.
155 $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 $gv->zoom( -out => factor )
161 Zoom out by scaling everything down by the given scale factor. This is
162 equivalent to
163 $gv->zoom ( -in => 1/factor )
165 The factor should be > 1.0 in order to get reasonable behavior.
167 $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 $gv->nodes
173 Returns a list of the names of the graph's nodes, as identified by
174 being tagged with "node".
175 $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
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 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 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 Nodes
200 Node elements are identified with a 'node' tag. For example, to bind
201 something to all nodes in a graph:
202 $gv->bind ( 'node', '<Any-Enter>', sub { ... } );
204 Edges
206 Edge elements are identified with a 'edge' tag. For example, to bind
207 something to all edges in a graph:
208 $gv->bind ( 'edge', '<Any-Enter>', sub { ... } );
210 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 Subgraphs
218 Subgraph elements are identified with a 'subgraph' tag.
219
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 use GraphViz;
226 use Tk;
227 my $mw = MainWindow->new();
229 my $gv = $mw->Scrolled ( 'GraphViz',
230 -background => 'white',
231 -scrollbars => 'sw' )
232 ->pack ( -expand => '1', -fill => 'both' );
233 $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 $gv->show ( shift );
242 MainLoop;
243
245 Lots of DOT language features not yet implemented
246 Various node shapes and attributes: polygon, skew, ...
248 Edge arrow head types
249
251 See <http://www.graphviz.org/> for more info on the graphviz tools.
252
254 Jeremy Slade <jeremy@jkslade.net>
255 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 This library is free software; you can redistribute it and/or modify it
263 under the same terms as Perl itself.
264perl v5.36.0 2022-07-22 Tk::GraphViz(3)