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