Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1992 The Regents of the University of California. |
2 | # Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
3 | # See the file "license.terms" for information on usage and redistribution | |
4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
5 | # | |
6 | # | |
7 | ||
8 | =head1 NAME | |
9 | ||
10 | Tk::place - Geometry manager for fixed or rubber-sheet placement | |
11 | ||
12 | =for category Tk Geometry Management | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | S< >I<$widget>->B<place>?(I<-option>=>I<value>?, I<-option>=>I<value>, ...)? | |
17 | ||
18 | S< >I<$widget>->B<placeForget> | |
19 | ||
20 | S< >I<$widget>->B<placeInfo> | |
21 | ||
22 | S< >I<$master>->B<placeSlaves> | |
23 | ||
24 | =head1 DESCRIPTION | |
25 | ||
26 | The placer is a geometry manager for Tk. | |
27 | It provides simple fixed placement of windows, where you specify | |
28 | the exact size and location of one window, called the I<slave>, | |
29 | within another window, called the I<$master>. | |
30 | The placer also provides rubber-sheet placement, where you specify the | |
31 | size and location of the slave in terms of the dimensions of | |
32 | the master, so that the slave changes size and location | |
33 | in response to changes in the size of the master. | |
34 | Lastly, the placer allows you to mix these styles of placement so | |
35 | that, for example, the slave has a fixed width and height but is | |
36 | centered inside the master. | |
37 | ||
38 | =over 4 | |
39 | ||
40 | =item I<$slave>->B<place>?(I<-option>=>I<value>?, I<-option>=>I<value>, ...?)? | |
41 | ||
42 | The B<place> method arranges for the placer | |
43 | to manage the geometry of I<$slave>. | |
44 | The remaining arguments consist of one or more I<-option>=>I<value> | |
45 | pairs that specify the way in which I<$slave>'s | |
46 | geometry is managed. | |
47 | If the placer is already managing I<$slave>, then the | |
48 | I<-option>=>I<value> pairs modify the configuration for I<$slave>. | |
49 | The B<place> method returns an empty string as result. | |
50 | The following I<-option>=>I<value> pairs are supported: | |
51 | ||
52 | =over 8 | |
53 | ||
54 | =item B<-in> => I<$master> | |
55 | ||
56 | I<$master> is the reference to the window relative | |
57 | to which I<$slave> is to be placed. | |
58 | I<$master> must either be I<$slave>'s parent or a descendant | |
59 | of I<$slave>'s parent. | |
60 | In addition, I<$master> and I<$slave> must both be descendants | |
61 | of the same top-level window. | |
62 | These restrictions are necessary to guarantee | |
63 | that I<$slave> is visible whenever I<$master> is visible. | |
64 | If this option isn't specified then the master defaults to | |
65 | I<$slave>'s parent. | |
66 | ||
67 | =item B<-x> => I<location> | |
68 | ||
69 | I<Location> specifies the x-coordinate within the master window | |
70 | of the anchor point for I<$slave> widget. | |
71 | The location is specified in screen units (i.e. any of the forms | |
72 | accepted by B<Tk_GetPixels>) and need not lie within the bounds | |
73 | of the master window. | |
74 | ||
75 | =item B<-relx> => I<location> | |
76 | ||
77 | I<Location> specifies the x-coordinate within the master window | |
78 | of the anchor point for I<$slave> widget. | |
79 | In this case the location is specified in a relative fashion | |
80 | as a floating-point number: 0.0 corresponds to the left edge | |
81 | of the master and 1.0 corresponds to the right edge of the master. | |
82 | I<Location> need not be in the range 0.0-1.0. | |
83 | If both B<-x> and B<-relx> are specified for a slave | |
84 | then their values are summed. For example, "B<-relx>=>0.5, B<-x>=-2" | |
85 | positions the left edge of the slave 2 pixels to the left of the | |
86 | center of its master. | |
87 | ||
88 | =item B<-y> => I<location> | |
89 | ||
90 | I<Location> specifies the y-coordinate within the master window | |
91 | of the anchor point for I<$slave> widget. | |
92 | The location is specified in screen units (i.e. any of the forms | |
93 | accepted by B<Tk_GetPixels>) and need not lie within the bounds | |
94 | of the master window. | |
95 | ||
96 | =item B<-rely> => I<location> | |
97 | ||
98 | I<Location> specifies the y-coordinate within the master window | |
99 | of the anchor point for I<$slave> widget. | |
100 | In this case the value is specified in a relative fashion | |
101 | as a floating-point number: 0.0 corresponds to the top edge | |
102 | of the master and 1.0 corresponds to the bottom edge of the master. | |
103 | I<Location> need not be in the range 0.0-1.0. | |
104 | If both B<-y> and B<-rely> are specified for a slave | |
105 | then their values are summed. For example, B<-rely>=>0.5, B<-x>=>3 | |
106 | positions the top edge of the slave 3 pixels below the | |
107 | center of its master. | |
108 | ||
109 | =item B<-anchor> => I<where> | |
110 | ||
111 | I<Where> specifies which point of I<$slave> is to be positioned | |
112 | at the (x,y) location selected by the B<-x>, B<-y>, | |
113 | B<-relx>, and B<-rely> options. | |
114 | The anchor point is in terms of the outer area of I<$slave> | |
115 | including its border, if any. | |
116 | Thus if I<where> is B<se> then the lower-right corner of | |
117 | I<$slave>'s border will appear at the given (x,y) location | |
118 | in the master. | |
119 | The anchor position defaults to B<nw>. | |
120 | ||
121 | =item B<-width> => I<size> | |
122 | ||
123 | I<Size> specifies the width for I<$slave> in screen units | |
124 | (i.e. any of the forms accepted by B<Tk_GetPixels>). | |
125 | The width will be the outer width of I<$slave> including its | |
126 | border, if any. | |
127 | If I<size> is an empty string, or if no B<-width> | |
128 | or B<-relwidth> option is specified, then the width requested | |
129 | internally by the window will be used. | |
130 | ||
131 | =item B<-relwidth> => I<size> | |
132 | ||
133 | I<Size> specifies the width for I<$slave>. | |
134 | In this case the width is specified as a floating-point number | |
135 | relative to the width of the master: 0.5 means I<$slave> will | |
136 | be half as wide as the master, 1.0 means I<$slave> will have | |
137 | the same width as the master, and so on. | |
138 | If both B<-width> and B<-relwidth> are specified for a slave, | |
139 | their values are summed. For example, B<-relwidth>=>1.0, B<-width>=>5 | |
140 | makes the slave 5 pixels wider than the master. | |
141 | ||
142 | =item B<-height> => I<size> | |
143 | ||
144 | I<Size> specifies the height for I<$slave> in screen units | |
145 | (i.e. any of the forms accepted by B<Tk_GetPixels>). | |
146 | The height will be the outer dimension of I<$slave> including its | |
147 | border, if any. | |
148 | If I<size> is an empty string, or if no B<-height> or | |
149 | B<-relheight> option is specified, then the height requested | |
150 | internally by the window will be used. | |
151 | ||
152 | =item B<-relheight> => I<size> | |
153 | ||
154 | I<Size> specifies the height for I<$slave>. | |
155 | In this case the height is specified as a floating-point number | |
156 | relative to the height of the master: 0.5 means I<$slave> will | |
157 | be half as high as the master, 1.0 means I<$slave> will have | |
158 | the same height as the master, and so on. | |
159 | If both B<-height> and B<-relheight> are specified for a slave, | |
160 | their values are summed. For example, B<-relheight>=>1.0, B<-height>=>-2 | |
161 | makes the slave 2 pixels shorter than the master. | |
162 | ||
163 | =item B<-bordermode> => I<mode> | |
164 | ||
165 | I<Mode> determines the degree to which borders within the | |
166 | master are used in determining the placement of the slave. | |
167 | The default and most common value is B<inside>. | |
168 | In this case the placer considers the area of the master to | |
169 | be the innermost area of the master, inside any border: | |
170 | an option of B<-x>=>B<0> corresponds to an x-coordinate just | |
171 | inside the border and an option of B<-relwidth>=>1.0 | |
172 | means I<$slave> will fill the area inside the master's | |
173 | border. | |
174 | If I<mode> is B<outside> then the placer considers | |
175 | the area of the master to include its border; | |
176 | this mode is typically used when placing I<$slave> | |
177 | outside its master, as with the options | |
178 | B<-x>=>B<0>, B<-y>=>B<0>, B<-anchor>=>B<ne>. | |
179 | Lastly, I<mode> may be specified as B<ignore>, in which | |
180 | case borders are ignored: the area of the master is considered | |
181 | to be its official X area, which includes any internal border but | |
182 | no external border. A bordermode of B<ignore> is probably | |
183 | not very useful. | |
184 | ||
185 | If the same value is specified separately with | |
186 | two different options, such as B<-x> and B<-relx>, then | |
187 | the most recent option is used and the older one is ignored. | |
188 | ||
189 | =back | |
190 | ||
191 | =item I<$slave>->B<placeSlaves> | |
192 | ||
193 | The B<placeSlaves> method returns a list of all the slave | |
194 | windows for which I<$master> is the master. | |
195 | If there are no slaves for I<$master> then an empty list is | |
196 | returned. | |
197 | ||
198 | =item I<$slave>->B<placeForget> | |
199 | ||
200 | The B<placeForget> method causes the placer to stop managing | |
201 | the geometry of I<$slave>. As a side effect of this method call | |
202 | I<$slave> will be unmapped so that it doesn't appear on the | |
203 | screen. | |
204 | If I<$slave> isn't currently managed by the placer then the | |
205 | method call has no effect. | |
206 | B<placeForget> returns an empty string as result. | |
207 | ||
208 | =item I<$slave>->B<placeInfo> | |
209 | ||
210 | The B<placeInfo> method returns a list giving the current | |
211 | configuration of I<$slave>. | |
212 | The list consists of I<-option>=>I<value> pairs in exactly the | |
213 | same form as might be specified to the B<place> | |
214 | method. | |
215 | If the configuration of a window has been retrieved with | |
216 | B<placeInfo>, that configuration can be restored later by | |
217 | first using B<placeForget> to erase any existing information | |
218 | for the window and then invoking B<place> with | |
219 | the saved information. | |
220 | ||
221 | =back | |
222 | ||
223 | =head1 FINE POINTS | |
224 | ||
225 | It is not necessary for the master window to be the parent | |
226 | of the slave window. | |
227 | This feature is useful in at least two situations. | |
228 | First, for complex window layouts it means you can create a | |
229 | hierarchy of subwindows whose only purpose | |
230 | is to assist in the layout of the parent. | |
231 | The ``I<real children>'' of the parent (i.e. the windows that | |
232 | are significant for the application's user interface) can be | |
233 | children of the parent yet be placed inside the windows | |
234 | of the geometry-management hierarchy. | |
235 | This means that the path names of the ``I<real children>'' | |
236 | don't reflect the geometry-management hierarchy and users | |
237 | can specify options for the real children | |
238 | without being aware of the structure of the geometry-management | |
239 | hierarchy. | |
240 | ||
241 | A second reason for having a master different than the slave's | |
242 | parent is to tie two siblings together. | |
243 | For example, the placer can be used to force a window always to | |
244 | be positioned centered just below one of its | |
245 | siblings by specifying the configuration | |
246 | ||
247 | S< >B<-in>=>I<$sibling>, B<-relx>=>0.5, B<-rely>=>1.0, | |
248 | B<-anchor>=>'n', B<-bordermode>=>'outside' | |
249 | ||
250 | Whenever the I<$sibling> widget is repositioned in the future, the slave | |
251 | will be repositioned as well. | |
252 | ||
253 | Unlike many other geometry managers (such as the packer) | |
254 | the placer does not make any attempt to manipulate the geometry of | |
255 | the master windows or the parents of slave windows (i.e. it doesn't | |
256 | set their requested sizes). | |
257 | To control the sizes of these windows, make them windows like | |
258 | frames and canvases that provide configuration options for this purpose. | |
259 | ||
260 | =head1 SEE ALSO | |
261 | ||
262 | L<Tk::form|Tk::form> | |
263 | L<Tk::grid|Tk::grid> | |
264 | L<Tk::pack|Tk::pack> | |
265 | ||
266 | =head1 KEYWORDS | |
267 | ||
268 | geometry manager, height, location, master, place, rubber sheet, slave, width | |
269 | ||
270 | =cut | |
271 |