Commit | Line | Data |
---|---|---|
86530b38 AT |
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 |