treegraph(3)
NAME
Tk::TreeGraph - Tk widget to draw a tree in a Canvas
SYNOPSIS
use Tk ;
use Tk::TreeGraph ;
use strict ;
my $mw = MainWindow-> new ;
my $tg = $mw -> Scrolled('TreeGraph') ->
pack(-expand => 1, -fill => 'both');
$tg -> addLabel (text => 'some tree');
my $ref = [qw/some really_silly text/];
$tg -> addNode
(
nodeId => '1.0',
text => $ref
) ;
# EITHER add the arrow and the node
$tg -> addDirectArrow
(
from => '1.0',
to => '1.1'
) ;
$tg->addNode
(
nodeId => '1.1',
text => ['some','text']
) ;
# OR add a node after another one, in this case the widget
# will draw the arrow
$tg->addNode
(
after =>'1.0',
nodeId => '1.1',
text => ['some','text']
);
$tg->arrowBind
(
button => '<1>',
color => 'orange',
command => sub{my %h = @_;
warn "clicked 1 arrow $h{from} ->
$h{to}0;}
);
$tg->nodeBind
(
button => '<2>',
color => 'red',
command => sub {my %h = @_;
warn "clicked 2 node $h{nodeId}0;}
);
$tg->command( on => 'arrow', label => 'dummy 2',
command => sub{warn "arrow menu dummy20;});
$tg->arrowBind(button => '<3>', color => 'green',
command => sub{$tg->popupMenu(@_);});
$tg->command(on => 'node', label => 'dummy 1',
command => sub{warn "node menu dummy10;});
$tg->nodeBind(button => '<3>', color => 'green',
command => sub{$tg->popupMenu(@_);});
# adjust scrolled area with some margin
my @array = $tg->bbox("all") ;
$tg->configure(-scrollregion =>
[0, 0, $array[2] + 50, $array[3] + 50 ]);
MainLoop ; # Tk's
DESCRIPTION
Tk::TreeGraph is a Canvas specialized to draw trees on a
Canvas using arrows and nodes. A node is simply some text
imbedded in a rectangular shape.
TreeGraph is able to draw the following items:
· node: some text in a rectangular shape.
- · direct arrow: an arrow to go from one node to the fol
- lowing one.
- · slanted arrow: an arrow to make a new branch.
- · shortcuts arrow: an arrow to represent a shortcut
- between 2 nodes from different branches.
- TreeGraph also provides :
- · a binding on nodes on button 1 to 'select' them.
- · Methods to bind nodes and arrows on user's call-back.
CAVEATS
You might say that the tree is a weird tree since it is
drawn downward and assymetric and adding branches leaves a
some void between them.
You'd be right. I'm not a specialist in tree drawing algo
rithms but the crude algorithm used here works quite fine
with drawing id trees for VCS system. But as usual, I'm
always listening for suggestions or even better, patches
;-) .
Note that the tree MUST be drawn from top to bottom and
from left to right. Unless you may get a very confusing
drawing of a tree.
About Scrolling
First versions of TreeGraph used to tinker with a -scroll
region option each time addNode was called. This was not
consistent since the scrollbars are added by the user when
calling TreeGraph (using Scrolled('TreeGraph')). Hence
from now on, it will be the responsability of the user to
set a satisfying -scrollregion.
- The user may write this after all nodes are drawn to set
the scrollregion : - my @array = $tg->bbox("all") ;
$tg->configure(-scrollregion => [0, 0, $array[2] + 50, - $array[3] + 50 ]);
- Furthermore, since configure will called only once, the
resulting code will be faster.
Widget Options
- -nodeColor:
- Color of the node rectangle.
- -nodeTextColor:
- Color of the text within the nodes
- -labelColor
- Color of the label.
- -arrowColor
- Color of the arrow.
- -shortcutColor:
- Color of the shortcut arrow (default 'orange')
- -shortcutStyle:
- Style of the shortcut arrow. The arrow can be drawn as
a 'straight' arrow or a 'spline'. (default 'straight') - -nodeTag:
- Boolean. By default the nodeId is added at the begin
ning of the node text. - -arrowDeltaY:
- Length of direct arrows (downward). default 40
- -branchSeparation:
- Minimum width between 2 branches of the tree (default
120) - -x_start:
- x coordinate of the root of the tree. (default 100)
- -y_start:
- y coordinate of the root of the tree.(default 100)
- -animation:
- Delay (in ms), if delay is positive, TreeGraph will
update the canvas widget any time the addNode method
is called and wait delay ms. This enable to make
pretty animation when drawing complex trees. This fea
ture will work only if a scrollregion is set before
calling addNode.
Drawing Methods added to Canvas
You draw the tree node after node with addNode using the
'after' parameter. Then the object will infer the kind of
arrow needed between the 2 nodes. Using the 'after' param
eter, you no longer need to call youself the addSlantedAr
row or addDirectArrow methods.
addNode(...)
Parameters are:
· nodeId: string to identify this node.
- · text: text string or array ref. This text will be
- written inside the rectangle
- · after: Either a [x,y] array ref setting the coordinate
- of the root of the tree (this can be used to draw the
a first tree in the canvas and/or to draw a second
tree in the canvas). If after is a nodeId, an arrow
(direct or slanted) will be drawn from the 'after'
node to this new node. - Will add a new node (made of a rectangle with the text
inside). - Note that this method will add the nodeId on top of the
passed text ('text' parameter). - modifyNode(...)
- Parameters are:
- · nodeId: string to identify the node to modify (manda
- tory).
- · text: text string or array ref. This text will be
- overwritten inside the rectangle. Note that modifyNode
will refuse to change the text if the new text has
more lines than the older text (because the text would
not fit in the rectangle). - · nodeColor: new color of the outline of the rectangle.
- · nodeTextColor: new color of the text of the node.
- · nodeFill: new color filling the rectangle.
- Will modify an existing node. Note that the geometry of
the node will not be changed. - viewNode(nodeId)
- Will move the canvas so that the node is visible within
the scrolled area. (do nothing if the scroll region is
not defined TBD XXX) - flashNode(...)
- Parameters are:
- · nodeId: string to identify the node to modify (manda
- tory).
- · time: time in ms between each flash (default 500 ms)
- · nodeColor: new color of the outline of the rectangle.
- · nodeTextColor: new color of the text of the node.
- · nodeFill: new color filling the rectangle.
- Will make an existing node flash. Calling a second time
this method on a node will make the flashing stop. - addDirectArrow(...)
- You can use this method if you want to change the default
aspect of the direct arrow. In this case do not use the
'after' parameter of the addNode() method. Parameters are: - · from: node id where the arrow starts
- · to: node id where the arrow ends
- Add a new straight (i.e. vertical) arrow starting from a
node. Note that the 'from' nodeId must be defined. The
'to' nodeId must NOT be defined. (Remember that you must
draw the tree from top to bottom) - addSlantedArrow(...)
- You can use this method if you want to change the default
aspect of the slanted arrow. In this case do not use the
'after' parameter of the addNode() method. - Parameters are:
- · from: node id where the arrow starts
- · to: node id where the arrow ends
- Add a new branch connecting node 'id' to node 'id2'. Note
that the 'from' nodeId must be defined. The 'to' nodeId
must NOT be defined. (Remember that you must draw the
tree from left to right) - addLabel(...)
- Put some text on the top of the graph. Parameters are:
- · text: text to be inserted on the top of the graph.
- addShortcutInfo(...)
- Parameters are:
- · from: node id where the arrow starts
- · to: node id where the arrow ends
- Declare that a shortcut arrow will be drawn from node
'arrow_start' and 'arrow_end'. - addAllShortcuts()
- This method is to be called once all nodes, direct arrow
and branch arrows are drawn and all relevant calls to
addShortcutInfo are done. - It will draw shortcut arrows between the ids declared with
the addShortcutInfo method. - clear()
- Clear the graph.
Management methods
nodeBind(...)
Parameters are:
· button: button name to bind (e.g. '<1>')
· color: color of the node when it is clicked on.
· command: sub ref
- Bind the 'button' on all nodes. When 'button' is clicked,
the node text color will change to 'color' and the call
back sub will be called with these parameters: - (on => 'node', nodeId => $nodeId)
- arrowBind(...)
- Parameters are:
- · button: button name to bind (e.g. '<1>')
- · color: color of the node when it is clicked on.
- · command: sub ref
- Bind the 'button' on arrows. When 'button' is clicked, the
arrow color will change to 'color' and the callback sub
will be called with these parameters:
(on => 'arrow',
from => nodeId_on_arrow_start,
to => nodeId_on_arrow_tip- )
- unselectAllNodes()
- Unselect all previously selected nodes (see button <1>
binding) - getSelectedNodes()
- Return an array containing nodeIds of all nodes currently
selected. - getNodeRectangle(...)
- Returns the rectangle reference of the passed nodeId or of
the node selected by the user. - Parameters are :
- · nodeId: nodeId attached to the rectangle
- command(...)
- This will add a new entry on a Popup menu which can be
raised on a node or an arrow. - Parameters are :
- · on: either 'node' or 'arrow'
- · label: Label of the Popup menu entry
- · command: sub ref runned when the menu is invoked
- The callback will be invoked with these parameters when
the command is set for nodes :
(on => 'node', nodeId => $nodeId)- The callback will be invoked with these parameters when
the command is set for arrows :
(on => 'arrow',
from => nodeId_on_arrow_start,
to => nodeId_on_arrow_tip- )
Private methods
These functions are documented only for people wanting to
improve or inherit this widget.
setArrow(...)
Parameters are:
· color: color of the arrow when selected.
Reset any previously selected arrow to default color and
set the current arrow to the color. This function should
be used with a bind.
Returns (from => $endNodeId, to => $tipNodeId) to specify
the nodes the arrow is attached to.
setNode()
Parameters are:
· color: color of the arrow when selected.
- · nodeId: nodeId to select (optional, default to the
- node under the mouse pointer)
- Set node either from passed nodeId or from the mouse
pointer. When a node is set, only the text is highlighted - Returns the nodeId of the current node (i.e. the node
clicked by the user if this function was used in a bind) - toggleNode(...)
- Parameters are:
- · color: color of the arrow when selected.
- · nodeId: nodeId to select (optional, default to the
- node under the mouse pointer)
- Will toggle the node rectangle between 'color' and
default.
AUTHOR
Dominique Dumont, Dominique_Dumont@grenoble.hp.com
Copyright (c) 1998-2001 Dominique Dumont. All rights
reserved. This program is free software; you can redis
tribute it and/or modify it under the same terms as Perl
itself.
SEE ALSO
- Tk, Tk::Canvas