| 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 | |