Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Tk::WorldCanvas.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "WorldCanvas 3"
.TH WorldCanvas 3 "2002-11-19" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Tk::WorldCanvas \- Autoscaling Canvas widget with zoom, viewAll, viewArea, viewFit, and center.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    $worldcanvas = $parent->WorldCanvas(?options?);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a wrapper around the Canvas widget that maps the
user's coordinate system to the now mostly hidden coordinate system of
the Canvas widget.  In world coordinates the y\-axis increases in
the upward direction.
.PP
\&\fIWorldCanvas\fR is meant to be a replacement for Canvas.  It's not
quite a \*(L"drop in\*(R" replacement though because the y\-axis is inverted
compared to Canvas.  Usually to convert you will have to invert all
y\-coordinates used to create objects.  Typically, you should call
\&\f(CW$worldcanvas\fR\->viewAll (or \f(CW$worldcanvas\fR\->viewArea(@box)) before calling
MainLoop.
.PP
Most of the \fIWorldCanvas\fR methods are the same as the \fICanvas\fR
methods except that they accept and return world coordinates instead
of widget coordinates.
.SH "INSTALLATION"
.IX Header "INSTALLATION"
.Vb 1
\&    Standard method:
.Ve
.PP
.Vb 4
\&    perl Makefile.PL
\&    make
\&    make test
\&    make install
.Ve
.PP
.Vb 1
\&    The last step requires proper permissions.
.Ve
.PP
.Vb 2
\&    Or you can copy the WorldCanvas.pm file to a local directory and
\&    skip the formalities.
.Ve
.SH "NEW METHODS"
.IX Header "NEW METHODS"
.IP "\fI$worldcanvas\fR\->\fBzoom\fR(\fIzoom factor\fR)" 4
.IX Item "$worldcanvas->zoom(zoom factor)"
Zooms the display by the specified amount.  Example:
.Sp
.Vb 2
\&    $worldcanvas->CanvasBind('<i>' => sub {$worldcanvas->zoom(1.25)});
\&    $worldcanvas->CanvasBind('<o>' => sub {$worldcanvas->zoom(0.8)});
.Ve
.Sp
.Vb 6
\&    # If you are using the 'Scrolled' constructor as in:
\&    my $worldcanvas = $main->Scrolled('WorldCanvas', -scrollbars => 'nw', ... )
\&    # you want to bind the key-presses to the 'worldcanvas' Subwidget of Scrolled.
\&    my $scrolled_canvas = $worldcanvas->Subwidget('worldcanvas'); # note the lower case 'worldcanvas'
\&    $scrolled_canvas->CanvasBind('<i>' => sub {$scrolled_canvas->zoom(1.25)});
\&    $scrolled_canvas->CanvasBind('<o>' => sub {$scrolled_canvas->zoom(0.8)});
.Ve
.Sp
.Vb 4
\&    # I don't like the scrollbars taking the focus when I
\&    # <ctrl>-tab through the windows, so I:
\&    $worldcanvas->Subwidget('xscrollbar')->configure(-takefocus => 0);
\&    $worldcanvas->Subwidget('yscrollbar')->configure(-takefocus => 0);
.Ve
.IP "\fI$worldcanvas\fR\->\fBcenter\fR(\fIx, y\fR)" 4
.IX Item "$worldcanvas->center(x, y)"
Centers the display around world coordinates x, y.
Example:
.Sp
.Vb 6
\&    $worldcanvas->CanvasBind('<2>' =>
\&        sub {
\&            $worldcanvas->CanvasFocus;
\&            $worldcanvas->center($worldcanvas->eventLocation);
\&        }
\&    );
.Ve
.IP "\fI$worldcanvas\fR\->\fBcenterTags\fR([\-exact => {0 | 1}], \fITagOrID, [TagOrID, ...]\fR)" 4
.IX Item "$worldcanvas->centerTags([-exact => {0 | 1}], TagOrID, [TagOrID, ...])"
Centers the display around the center of the bounding box
containing the specified TagOrID's without changing the current
magnification of the display.
.Sp
\&'\-exact => 1' will cause the canvas to be scaled twice to get
an accurate bounding box.  This will be expensive if the canvas
contains a large number of objects.
.IP "\fI$worldcanvas\fR\->\fBeventLocation\fR()" 4
.IX Item "$worldcanvas->eventLocation()"
Returns the world coordinates (x, y) of the last Xevent.
.IP "\fI$worldcanvas\fR\->\fBpanWorld\fR(\fIdx, dy\fR)" 4
.IX Item "$worldcanvas->panWorld(dx, dy)"
Pans the display by the specified world distances.  \fBpanWorld\fR
is not meant to replace the xview/yview panning methods.  Most
user interfaces will want the arrow keys tied to the xview/yview
panning methods (the default bindings), which pan in widget
coordinates.
.Sp
If you do want to change the arrow key-bindings to pan in world
coordinates using \fBpanWorld\fR you must disable the default arrow
key\-bindings.
.Sp
.Vb 1
\&    Example:
.Ve
.Sp
.Vb 4
\&    $mainwindow->bind('WorldCanvas',    '<Up>' => "");
\&    $mainwindow->bind('WorldCanvas',  '<Down>' => "");
\&    $mainwindow->bind('WorldCanvas',  '<Left>' => "");
\&    $mainwindow->bind('WorldCanvas', '<Right>' => "");
.Ve
.Sp
.Vb 4
\&    $worldcanvas->CanvasBind(   '<Up>' => sub {$worldcanvas->panWorld(0,  100);});
\&    $worldcanvas->CanvasBind( '<Down>' => sub {$worldcanvas->panWorld(0, -100);});
\&    $worldcanvas->CanvasBind( '<Left>' => sub {$worldcanvas->panWorld(-100, 0);});
\&    $worldcanvas->CanvasBind('<Right>' => sub {$worldcanvas->panWorld( 100, 0);});
.Ve
.Sp
This is not usually desired, as the percentage of the display that
is shifted will be dependent on the current display magnification.
.IP "\fI$worldcanvas\fR\->\fBpixelSize\fR()" 4
.IX Item "$worldcanvas->pixelSize()"
Returns the width (in world coordinates) of a pixel (at the current magnification).
.IP "\fI$worldcanvas\fR\->\fBrubberBand\fR(\fI{0|1|2}\fR)" 4
.IX Item "$worldcanvas->rubberBand({0|1|2})"
Creates a rubber banding box that allows the user to graphically
select a region.  \fBrubberBand\fR is called with a step parameter
\&'0', '1', or '2'.  '0' to start a new box, '1' to stretch the box,
and '2' to finish the box.  When called with '2', the specified
box is returned (x1, y1, x2, y2)
.Sp
The band color is set with the \fIWorldCanvas\fR option '\-bandColor'.
The default color is 'red'
.Sp
Example, specify a region to delete:
.Sp
.Vb 11
\&    $worldcanvas->configure(-bandColor => 'purple');
\&    $worldcanvas->CanvasBind('<3>'               => sub {$worldcanvas->CanvasFocus;
\&                                                         $worldcanvas->rubberBand(0)
\&                                                        });
\&    $worldcanvas->CanvasBind('<B3-Motion>'       => sub {$worldcanvas->rubberBand(1)});
\&    $worldcanvas->CanvasBind('<ButtonRelease-3>' => sub {my @box = $worldcanvas->rubberBand(2);
\&                                                         my @ids = $worldcanvas->find('enclosed', @box);
\&                                                         foreach my $id (@ids) {$worldcanvas->delete($id)}
\&                                                        });
\&    # Note: '<B3-ButtonRelease>' will be called for any ButtonRelease!
\&    # You should use '<ButtonRelease-3>' instead.
.Ve
.Sp
.Vb 2
\&    # If you want the rubber band to look smooth during panning and
\&    # zooming, add rubberBand(1) update calls to the appropriate key-bindings:
.Ve
.Sp
.Vb 6
\&    $worldcanvas->CanvasBind(   '<Up>' => sub {$worldcanvas->rubberBand(1);});
\&    $worldcanvas->CanvasBind( '<Down>' => sub {$worldcanvas->rubberBand(1);});
\&    $worldcanvas->CanvasBind( '<Left>' => sub {$worldcanvas->rubberBand(1);});
\&    $worldcanvas->CanvasBind('<Right>' => sub {$worldcanvas->rubberBand(1);});
\&    $worldcanvas->CanvasBind('<i>' => sub {$worldcanvas->zoom(1.25); $worldcanvas->rubberBand(1);});
\&    $worldcanvas->CanvasBind('<o>' => sub {$worldcanvas->zoom(0.8);  $worldcanvas->rubberBand(1);});
.Ve
.Sp
This box avoids the overhead of bounding box calculations
that can occur if you create your own rubberBand outside of \fIWorldCanvas\fR.
.IP "\fI$worldcanvas\fR\->\fBviewAll\fR([\-border => number])" 4
.IX Item "$worldcanvas->viewAll([-border => number])"
Displays at maximum possible zoom all objects centered in the
\&\fIWorldCanvas\fR.  The switch '\-border' specifies, as a percentage
of the screen, the minimum amount of white space to be left on
the edges of the display.  Default '\-border' is 0.02.
.IP "\fI$worldcanvas\fR\->\fBviewArea\fR(x1, y1, x2, y2, [\-border => number]))" 4
.IX Item "$worldcanvas->viewArea(x1, y1, x2, y2, [-border => number]))"
Displays at maximum possible zoom the specified region centered
in the \fIWorldCanvas\fR.
.IP "\fI$worldcanvas\fR\->\fBviewFit\fR([\-border => number], \fITagOrID\fR, [\fITagOrID\fR, ...])" 4
.IX Item "$worldcanvas->viewFit([-border => number], TagOrID, [TagOrID, ...])"
Adjusts the worldcanvas to display all of the specified tags.  The '\-border'
switch specifies (as a percentage) how much extra surrounding space should be shown.
.IP "\fI$worldcanvas\fR\->\fBgetView\fR()" 4
.IX Item "$worldcanvas->getView()"
Returns the rectangle of the current view (x1, y1, x2, y2)
.IP "\fI$worldcanvas\fR\->\fBwidgetx\fR(\fIx\fR)" 4
.IX Item "$worldcanvas->widgetx(x)"
.PD 0
.IP "\fI$worldcanvas\fR\->\fBwidgety\fR(\fIy\fR)" 4
.IX Item "$worldcanvas->widgety(y)"
.IP "\fI$worldcanvas\fR\->\fBwidgetxy\fR(\fIx, y\fR)" 4
.IX Item "$worldcanvas->widgetxy(x, y)"
.PD
Convert world coordinates to widget coordinates.
.IP "\fI$worldcanvas\fR\->\fBworldx\fR(\fIx\fR)" 4
.IX Item "$worldcanvas->worldx(x)"
.PD 0
.IP "\fI$worldcanvas\fR\->\fBworldy\fR(\fIy\fR)" 4
.IX Item "$worldcanvas->worldy(y)"
.IP "\fI$worldcanvas\fR\->\fBworldxy\fR(\fIx, y\fR)" 4
.IX Item "$worldcanvas->worldxy(x, y)"
.PD
Convert widget coordinates to world coordinates.
.SH "CHANGED METHODS"
.IX Header "CHANGED METHODS"
.RS 4
World coordinates are supplied and returned to \fBWorldCanvas\fR methods
instead of widget coordinates unless otherwise specified.  (ie. These
methods take and return world coordinates: center, panWorld, viewArea,
find, coords, scale, move, bbox, rubberBand, eventLocation, pixelSize,
and create*)
.RE
.IP "\fI$worldcanvas\fR\->\fBbbox\fR([\-exact => {0 | 1}], \fITagOrID\fR, [\fITagOrID\fR, ...])" 4
.IX Item "$worldcanvas->bbox([-exact => {0 | 1}], TagOrID, [TagOrID, ...])"
\&'\-exact => 1' is only needed if the TagOrID is not 'all'.  It
will cause the canvas to be scaled twice to get an accurate
bounding box.  This will be expensive if the canvas contains
a large number of objects.
.Sp
Neither setting of exact will produce exact results because
the underlying canvas bbox method returns a slightly larger box
to insure that everything is contained.  It appears that a number
close to '2' is added or subtracted.  The '\-exact => 1' zooms
in to reduce this error.
.Sp
If the underlying canvas \fBbbox\fR method returns a bounding box
that is small (high error percentage) then '\-exact => 1' is done
automatically.
.IP "\fI$worldcanvas\fR\->\fBscale\fR(\fI'all', xOrigin, yOrigin, xScale, yScale\fR)" 4
.IX Item "$worldcanvas->scale('all', xOrigin, yOrigin, xScale, yScale)"
\&\fBScale\fR should not be used to 'zoom' the display in and out as it will
change the world coordinates of the scaled objects.  Methods \fBzoom\fR,
\&\fBviewArea\fR, and \fBviewAll\fR should be used to change the
scale of the display without affecting the dimensions of the objects.
.SH "VIEW AREA CHANGE CALLBACK"
.IX Header "VIEW AREA CHANGE CALLBACK"
\&\fITk::WorldCanvas\fR option '\-changeView' can be used to specify
a callback for a change of the view area.  This is useful for
updating a second worldcanvas which is displaying the view region
of the first worldcanvas.
.PP
The callback subroutine will be passed the coordinates of the
displayed box (x1, y1, x2, y2).  These arguments are added after
any extra arguments specifed by the user calling 'configure'.
.PP
.Vb 1
\&    Example:
.Ve
.PP
.Vb 3
\&    $worldcanvas->configure(-changeView => [\e&changeView, $worldcanvas2]);
\&    # viewAll if worldcanvas2 widget is resized.
\&    $worldcanvas2->CanvasBind('<Configure>' => sub {$worldcanvas2->viewAll});
.Ve
.PP
.Vb 4
\&    {
\&        my $viewBox;
\&        sub changeView {
\&            my ($canvas2, @coords) = @_;
.Ve
.PP
.Vb 4
\&            $canvas2->delete($viewBox) if $viewBox;
\&            $viewBox = $canvas2->createRectangle(@coords, -outline => 'orange');
\&        }
\&    }
.Ve
.SH "SCROLL REGION NOTES"
.IX Header "SCROLL REGION NOTES"
(1) The underlying \fITk::Canvas\fR has a '\-confine' option which is set
to '1' by default.  With '\-confine => 1' the canvas will not allow
the display to go outside of the scroll region causing some methods
to not work accurately.  For example, the 'center' method will not be
able to center on coordinates near to the edge of the scroll region;
\&'zoom out' near the edge will zoom out and pan towards the center.
.PP
\&\fITk::WorldCanvas\fR sets '\-confine => 0' by default to avoid these
problems.  You can change it back with:
.PP
.Vb 1
\&    $worldcanvas->configure(-confine => 1);
.Ve
.PP
(2) '\-scrollregion' is maintained by \fIWorldCanvas\fR to include all
objects on the canvas.  '\-scrollregion' will be adjusted automatically
as objects are added, deleted, scaled, moved, etc.  (You can create a
static scrollregion by adding a border rectangle to the canvas.)
.PP
(3) The bounding box of all objects is required to set the scroll region.
Calculating this bounding box is expensive if the canvas has a large
number of objects.  So for performance reasons these operations will
not immediately change the bounding box if they potentially shrink it:
.PP
.Vb 4
\&    coords
\&    delete
\&    move
\&    scale
.Ve
.PP
Instead they will mark the bounding box as invalid, and it will be
updated at the next zoom or pan operation.  The only downside to this
is that the scrollbars will be incorrect until the update.
.PP
If these operations increase the size of the box, changing the box is
trivial and the update is immediate.
.SH "AUTHOR"
.IX Header "AUTHOR"
Joseph Skrovan (\fIjoseph@skrovan.com\fR)
.PP
Note: based on an earlier implementation by Rudy Albachten (\fIrudy@albachten.com\fR)
.PP
If you use and enjoy \fIWorldCanvas\fR please let me know.
.SH "COPYRIGHTS"
.IX Header "COPYRIGHTS"
.Vb 3
\&    Copyright (c) 2002 Joseph Skrovan. All rights reserved.
\&    This program is free software; you can redistribute it and/or modify it
\&    under the same terms as Perl itself.
.Ve