home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _ed637d64af7ff555143a32224aed631b < prev    next >
Encoding:
Text File  |  2004-06-01  |  7.1 KB  |  224 lines
  1.  
  2. =head1 NAME
  3.  
  4. Tk::Adjuster - Allow size of packed widgets to be adjusted by user
  5.  
  6. =for pm Tk/Adjuster.pm
  7.  
  8. =for category Tk Geometry Management
  9.  
  10. =head1 SYNOPSIS
  11.  
  12. use Tk::Adjuster;
  13.  
  14. I<$adjuster> = I<$widget>->B<Adjuster>I<(?options?)>;
  15.  
  16. =head1 WIDGET-SPECIFIC OPTIONS
  17.  
  18. =over 4
  19.  
  20. =item Name: B<restore>
  21.  
  22. =item Class: B<Restore>
  23.  
  24. =item Switch: B<-restore>
  25.  
  26. Specifies a boolean value that determines whether the Adjuster
  27. should forcibly attempt to make room
  28. for itself (by reducing the size of its managed widget) when it is
  29. unmapped (for example, due to a size change in a top level window).
  30. The default value is 1.
  31.  
  32. =item Name: B<side>
  33.  
  34. =item Class: B<Side>
  35.  
  36. =item Switch: B<-side>
  37.  
  38. Specifies the side on which the managed widget lies relative to the
  39. Adjuster. In conjunction with the pack geometry manager, this relates to
  40. the side of the master against which the managed widget and the Adjuster
  41. are packed.
  42. Must be B<left>, B<right>, B<top>, or B<bottom>. Defaults to B<top>.
  43.  
  44. =item Name: B<widget>
  45.  
  46. =item Class: B<Widget>
  47.  
  48. =item Switch: B<-widget>
  49.  
  50. Specifies the widget which is to be managed by the Adjuster.
  51.  
  52. =back
  53.  
  54. =head1 DESCRIPTION
  55.  
  56. B<Tk::Adjuster> is a Frame containing a "line" and a "blob".
  57.  
  58. Dragging with Mouse Button-1 results in a line being dragged
  59. to indicate new size. Releasing Button-1 submits GeometryRequests
  60. on behalf of the managed widget which will cause the packer to change the
  61. widget's size.
  62.  
  63. If Drag is done with Shift button down, then GeometryRequests are made
  64. in "real time" so that text-flow effects can be seen, but as a lot more
  65. work is done behaviour may be sluggish.
  66.  
  67. If widget is packed with -side => left or -side => right then width is
  68. adjusted. If packed -side => top or -side => bottom then height is adjusted.
  69.  
  70. B<packPropagate> is turned off for the master window to prevent adjustment
  71. changing overall window size. Similarly B<packPropagate> is turned off
  72. for the managed widget if it has things packed inside it. This is so that
  73. the GeometryRequests made by B<Tk::Adjuster> are not overridden by pack.
  74.  
  75. In addition, the managed widget is made non-expandable
  76. to prevent the geometry manager reallocating freed space in the master
  77. back to the managed widget.
  78. Note however that expansion is turned off only after the Adjuster is mapped,
  79. which allows the managed widget to expand naturally on window creation.
  80.  
  81. The Tk::Widget method, B<packAdjust>, calls pack on the widget, then
  82. creates an instance of B<Tk::Adjuster>,
  83. and packs that "after" the widget. Its use has two disadvantages however: the
  84. Adjuster widget is not made available to the caller, and
  85. options cannot be set on the Adjuster. For these reasons, the Tk::Adjuster
  86. method, B<packAfter> is preferred, but B<packAdjust> is retained
  87. for backwards compatibility.
  88.  
  89. =head1 WIDGET METHODS
  90.  
  91. =over 4
  92.  
  93. =item I<$adjuster>->B<packAfter>(I<managed_widget, ?pack_options?>)
  94.  
  95. This command configures the Adjuster's B<-widget> and B<-side> options
  96. respectively to I<managed_widget> and the B<-side> value specified in
  97. I<pack_options> (B<top> if not specified). It then packs the Adjuster
  98. after I<managed_widget>, with B<-fill> set to B<x> or B<y> as appropriate.
  99.  
  100. =item I<$adjuster>->B<packForget>I<?(boolean)?>
  101.  
  102. This command calls B<Tk::Widget::packForget> on the Adjuster.
  103. If a parameter is provided and it has a true boolean value, then
  104. B<packForget> is also called on the managed widget.
  105.  
  106. =item I<$adjuster>->B<slave>
  107.  
  108. This command returns the value I<$adjuster>->I<cget('-widget')>, ie. the
  109. reference to the managed widget.
  110.  
  111. =back
  112.  
  113. =head1 EXAMPLES
  114.  
  115. B<Using an Adjuster to separate two widgets, whereby the left widget
  116. is managed, and right widget expands to fill space on a window resize>
  117.  
  118. a) Using packAfter (preferred interface)
  119.  
  120.   use Tk;
  121.   use Tk::Adjuster;
  122.  
  123.   my $f = MainWindow->new;
  124.   my $lst1 = $f->Listbox();
  125.   my $adj1 = $f->Adjuster();
  126.   my $lst2 = $f->Listbox();
  127.  
  128.   my $side = 'left';
  129.   $lst1->pack(-side => $side, -fill => 'both', -expand => 1);
  130.   $adj1->packAfter($lst1, -side => $side);
  131.   $lst2->pack(-side => $side, -fill => 'both', -expand => 1);
  132.   MainLoop;
  133.  
  134. b) Using packAdjust
  135.  
  136.   use Tk;
  137.   use Tk::Adjuster;
  138.  
  139.   my $f = MainWindow->new;
  140.   my $lst1 = $f->Listbox();
  141.   my $lst2 = $f->Listbox();
  142.  
  143.   my $side = 'left';
  144.   $lst1->packAdjust(-side => $side, -fill => 'both');
  145.   $lst2->pack      (-side => $side, -fill => 'both', -expand => 1);
  146.   MainLoop;
  147.  
  148. c) Using the standard Tk::Widget::pack
  149.  
  150.   use Tk;
  151.   use Tk::Adjuster;
  152.  
  153.   my $f = MainWindow->new;
  154.   my $side = 'left';
  155.   my $lst1 = $f->Listbox();
  156.   my $adj  = $f->Adjuster(-widget => $lst1, -side => $side);
  157.   my $lst2 = $f->Listbox();
  158.  
  159.   $lst1->pack(-side => $side, -fill => 'both', -expand => 1);
  160.   $adj->pack (-side => $side, -fill => 'y');
  161.   $lst2->pack(-side => $side, -fill => 'both', -expand => 1);
  162.  
  163.   MainLoop;
  164.  
  165. Changing the above examples so that $side has the value 'right' means the
  166. left widget expands to fill space on a window resize.
  167.  
  168. Changing the above examples so that $side has the value 'top'
  169. produces a testcase with a horizontal Adjuster.
  170. Here the bottom widget expands to fill space on a window resize.
  171. Packing to the 'bottom' makes the top widget expand to fill space on window
  172. resize.
  173.  
  174. B<Using -restore =E<gt> 0 for multiple columns>
  175.  
  176. In the case of multiple columns (or rows) the "restore" functionality of the
  177. Adjuster can be inconvenient. When the user adjusts the width of one column
  178. and thereby pushes the Adjuster of another column off the window, this
  179. adjuster tries to restore itself by reducing the size of its managed widget.
  180. This has the effect that column widths shrink; and the original size
  181. is not restored when
  182. the user reverses the originating change. The B<-restore> option can be
  183. used to turn off this functionality. (It makes some sense, however, to
  184. leave B<-restore>
  185. turned on for the first-packed Adjuster, so that at least one Adjuster
  186. always remains visible.)
  187.  
  188.   use Tk;
  189.   use Tk::Adjuster;
  190.   my $f = MainWindow->new;
  191.   my $lst1 = $f->Listbox();
  192.   my $adj1 = $f->Adjuster();
  193.   my $lst2 = $f->Listbox();
  194.   my $adj2 = $f->Adjuster(-restore => 0);
  195.   my $lst3 = $f->Listbox();
  196.  
  197.   my $side = 'left';
  198.   $lst1->pack(-side => $side, -fill => 'both', -expand => 1);
  199.   $adj1->packAfter($lst1, -side => $side);
  200.   $lst2->pack(-side => $side, -fill => 'both', -expand => 1);
  201.   $adj2->packAfter($lst2, -side => $side);
  202.   $lst3->pack(-side => $side, -fill => 'both', -expand => 1);
  203.  
  204.   MainLoop;
  205.  
  206. =head1 BUGS
  207.  
  208. It is currently not possible to configure the appearance of the Adjuster.
  209. It would be nice to be able to set the width and relief of the Adjuster "line"
  210. and the presence/absence of the "blob" on the Adjuster.
  211.  
  212. Tk::Adjuster works theoretically with the grid geometry manager but there
  213. are currently some problems which seem to be due to bugs in grid:
  214.  
  215.   a) There's never an Unmap event for the adjuster, so the "restore"
  216.      functionality has no effect.
  217.   b) After adjusting, widgets protrude into the border of the master.
  218.   c) grid('Propagate', 0) on MainWindow has no effect - window shrinks/grows
  219.      when widgets are adjusted.
  220.   d) Widgets shuffle to correct position on startup
  221.  
  222. =cut
  223.  
  224.