Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Tk::Adjuster.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 "ADJUSTER 1"
.TH ADJUSTER 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Tk::Adjuster \- Allow size of packed widgets to be adjusted by user
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Tk::Adjuster;
.PP
\&\fI$adjuster\fR = \fI$widget\fR\->\fBAdjuster\fR\fI(?options?)\fR;
.SH "WIDGET-SPECIFIC OPTIONS"
.IX Header "WIDGET-SPECIFIC OPTIONS"
.IP "Name: \fBrestore\fR" 4
.IX Item "Name: restore"
.PD 0
.IP "Class: \fBRestore\fR" 4
.IX Item "Class: Restore"
.IP "Switch: \fB\-restore\fR" 4
.IX Item "Switch: -restore"
.PD
Specifies a boolean value that determines whether the Adjuster
should forcibly attempt to make room
for itself (by reducing the size of its managed widget) when it is
unmapped (for example, due to a size change in a top level window).
The default value is 1.
.IP "Name: \fBside\fR" 4
.IX Item "Name: side"
.PD 0
.IP "Class: \fBSide\fR" 4
.IX Item "Class: Side"
.IP "Switch: \fB\-side\fR" 4
.IX Item "Switch: -side"
.PD
Specifies the side on which the managed widget lies relative to the
Adjuster. In conjunction with the pack geometry manager, this relates to
the side of the master against which the managed widget and the Adjuster
are packed.
Must be \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. Defaults to \fBtop\fR. 
.IP "Name: \fBwidget\fR" 4
.IX Item "Name: widget"
.PD 0
.IP "Class: \fBWidget\fR" 4
.IX Item "Class: Widget"
.IP "Switch: \fB\-widget\fR" 4
.IX Item "Switch: -widget"
.PD
Specifies the widget which is to be managed by the Adjuster.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBTk::Adjuster\fR is a Frame containing a \*(L"line\*(R" and a \*(L"blob\*(R".
.PP
Dragging with Mouse Button\-1 results in a line being dragged
to indicate new size. Releasing Button\-1 submits GeometryRequests
on behalf of the managed widget which will cause the packer to change the
widget's size.
.PP
If Drag is done with Shift button down, then GeometryRequests are made
in \*(L"real time\*(R" so that text-flow effects can be seen, but as a lot more
work is done behaviour may be sluggish.
.PP
If widget is packed with \-side => left or \-side => right then width is
adjusted. If packed \-side => top or \-side => bottom then height is adjusted.
.PP
\&\fBpackPropagate\fR is turned off for the master window to prevent adjustment
changing overall window size. Similarly \fBpackPropagate\fR is turned off
for the managed widget if it has things packed inside it. This is so that
the GeometryRequests made by \fBTk::Adjuster\fR are not overridden by pack.
.PP
In addition, the managed widget is made non-expandable
to prevent the geometry manager reallocating freed space in the master
back to the managed widget.
Note however that expansion is turned off only after the Adjuster is mapped,
which allows the managed widget to expand naturally on window creation.
.PP
The Tk::Widget method, \fBpackAdjust\fR, calls pack on the widget, then
creates an instance of \fBTk::Adjuster\fR,
and packs that \*(L"after\*(R" the widget. Its use has two disadvantages however: the
Adjuster widget is not made available to the caller, and 
options cannot be set on the Adjuster. For these reasons, the Tk::Adjuster
method, \fBpackAfter\fR is preferred, but \fBpackAdjust\fR is retained
for backwards compatibility.
.SH "WIDGET METHODS"
.IX Header "WIDGET METHODS"
.IP "\fI$adjuster\fR\->\fBpackAfter\fR(\fImanaged_widget, ?pack_options?\fR)" 4
.IX Item "$adjuster->packAfter(managed_widget, ?pack_options?)"
This command configures the Adjuster's \fB\-widget\fR and \fB\-side\fR options
respectively to \fImanaged_widget\fR and the \fB\-side\fR value specified in
\&\fIpack_options\fR (\fBtop\fR if not specified). It then packs the Adjuster
after \fImanaged_widget\fR, with \fB\-fill\fR set to \fBx\fR or \fBy\fR as appropriate.
.IP "\fI$adjuster\fR\->\fBpackForget\fR\fI?(boolean)?\fR" 4
.IX Item "$adjuster->packForget?(boolean)?"
This command calls \fBTk::Widget::packForget\fR on the Adjuster.
If a parameter is provided and it has a true boolean value, then
\&\fBpackForget\fR is also called on the managed widget.
.IP "\fI$adjuster\fR\->\fBslave\fR" 4
.IX Item "$adjuster->slave"
This command returns the value \fI$adjuster\fR\->\fIcget('\-widget')\fR, ie. the
reference to the managed widget.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
\&\fBUsing an Adjuster to separate two widgets, whereby the left widget
is managed, and right widget expands to fill space on a window resize\fR
.PP
a) Using packAfter (preferred interface)
.PP
.Vb 2
\&  use Tk;
\&  use Tk::Adjuster;
.Ve
.PP
.Vb 4
\&  my $f = MainWindow->new;
\&  my $lst1 = $f->Listbox();
\&  my $adj1 = $f->Adjuster();
\&  my $lst2 = $f->Listbox();
.Ve
.PP
.Vb 5
\&  my $side = 'left';
\&  $lst1->pack(-side => $side, -fill => 'both', -expand => 1);
\&  $adj1->packAfter($lst1, -side => $side);
\&  $lst2->pack(-side => $side, -fill => 'both', -expand => 1);
\&  MainLoop;
.Ve
.PP
b) Using packAdjust
.PP
.Vb 2
\&  use Tk;
\&  use Tk::Adjuster;
.Ve
.PP
.Vb 3
\&  my $f = MainWindow->new;
\&  my $lst1 = $f->Listbox();
\&  my $lst2 = $f->Listbox();
.Ve
.PP
.Vb 4
\&  my $side = 'left';
\&  $lst1->packAdjust(-side => $side, -fill => 'both');
\&  $lst2->pack      (-side => $side, -fill => 'both', -expand => 1);
\&  MainLoop;
.Ve
.PP
c) Using the standard Tk::Widget::pack
.PP
.Vb 2
\&  use Tk;
\&  use Tk::Adjuster;
.Ve
.PP
.Vb 5
\&  my $f = MainWindow->new;
\&  my $side = 'left';
\&  my $lst1 = $f->Listbox();
\&  my $adj  = $f->Adjuster(-widget => $lst1, -side => $side);
\&  my $lst2 = $f->Listbox();
.Ve
.PP
.Vb 3
\&  $lst1->pack(-side => $side, -fill => 'both', -expand => 1);
\&  $adj->pack (-side => $side, -fill => 'y');
\&  $lst2->pack(-side => $side, -fill => 'both', -expand => 1);
.Ve
.PP
.Vb 1
\&  MainLoop;
.Ve
.PP
Changing the above examples so that \f(CW$side\fR has the value 'right' means the
left widget expands to fill space on a window resize.
.PP
Changing the above examples so that \f(CW$side\fR has the value 'top'
produces a testcase with a horizontal Adjuster.
Here the bottom widget expands to fill space on a window resize.
Packing to the 'bottom' makes the top widget expand to fill space on window
resize.
.PP
\&\fBUsing \-restore => 0 for multiple columns\fR
.PP
In the case of multiple columns (or rows) the \*(L"restore\*(R" functionality of the
Adjuster can be inconvenient. When the user adjusts the width of one column
and thereby pushes the Adjuster of another column off the window, this
adjuster tries to restore itself by reducing the size of its managed widget.
This has the effect that column widths shrink; and the original size
is not restored when
the user reverses the originating change. The \fB\-restore\fR option can be
used to turn off this functionality. (It makes some sense, however, to
leave \fB\-restore\fR
turned on for the first-packed Adjuster, so that at least one Adjuster
always remains visible.)
.PP
.Vb 8
\&  use Tk;
\&  use Tk::Adjuster;
\&  my $f = MainWindow->new;
\&  my $lst1 = $f->Listbox();
\&  my $adj1 = $f->Adjuster();
\&  my $lst2 = $f->Listbox();
\&  my $adj2 = $f->Adjuster(-restore => 0);
\&  my $lst3 = $f->Listbox();
.Ve
.PP
.Vb 6
\&  my $side = 'left';
\&  $lst1->pack(-side => $side, -fill => 'both', -expand => 1);
\&  $adj1->packAfter($lst1, -side => $side);
\&  $lst2->pack(-side => $side, -fill => 'both', -expand => 1);
\&  $adj2->packAfter($lst2, -side => $side);
\&  $lst3->pack(-side => $side, -fill => 'both', -expand => 1);
.Ve
.PP
.Vb 1
\&  MainLoop;
.Ve
.SH "BUGS"
.IX Header "BUGS"
It is currently not possible to configure the appearance of the Adjuster.
It would be nice to be able to set the width and relief of the Adjuster \*(L"line\*(R"
and the presence/absence of the \*(L"blob\*(R" on the Adjuster.
.PP
Tk::Adjuster works theoretically with the grid geometry manager but there
are currently some problems which seem to be due to bugs in grid:
.PP
.Vb 6
\&  a) There's never an Unmap event for the adjuster, so the "restore"
\&     functionality has no effect.
\&  b) After adjusting, widgets protrude into the border of the master.
\&  c) grid('Propagate', 0) on MainWindow has no effect - window shrinks/grows
\&     when widgets are adjusted.
\&  d) Widgets shuffle to correct position on startup
.Ve