diff options
Diffstat (limited to 'Master/tlpkg/tlperl0/lib/Tk/place.pod')
| -rwxr-xr-x | Master/tlpkg/tlperl0/lib/Tk/place.pod | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/Tk/place.pod b/Master/tlpkg/tlperl0/lib/Tk/place.pod new file mode 100755 index 00000000000..8b3bff9816c --- /dev/null +++ b/Master/tlpkg/tlperl0/lib/Tk/place.pod @@ -0,0 +1,271 @@ +# Copyright (c) 1992 The Regents of the University of California. +# Copyright (c) 1994-1996 Sun Microsystems, Inc. +# See the file "license.terms" for information on usage and redistribution +# of this file, and for a DISCLAIMER OF ALL WARRANTIES. +# +# + +=head1 NAME + +Tk::place - Geometry manager for fixed or rubber-sheet placement + +=for category Tk Geometry Management + +=head1 SYNOPSIS + +S< >I<$widget>->B<place>?(I<-option>=>I<value>?, I<-option>=>I<value>, ...)? + +S< >I<$widget>->B<placeForget> + +S< >I<$widget>->B<placeInfo> + +S< >I<$master>->B<placeSlaves> + +=head1 DESCRIPTION + +The placer is a geometry manager for Tk. +It provides simple fixed placement of windows, where you specify +the exact size and location of one window, called the I<slave>, +within another window, called the I<$master>. +The placer also provides rubber-sheet placement, where you specify the +size and location of the slave in terms of the dimensions of +the master, so that the slave changes size and location +in response to changes in the size of the master. +Lastly, the placer allows you to mix these styles of placement so +that, for example, the slave has a fixed width and height but is +centered inside the master. + +=over 4 + +=item I<$slave>->B<place>?(I<-option>=>I<value>?, I<-option>=>I<value>, ...?)? + +The B<place> method arranges for the placer +to manage the geometry of I<$slave>. +The remaining arguments consist of one or more I<-option>=>I<value> +pairs that specify the way in which I<$slave>'s +geometry is managed. +If the placer is already managing I<$slave>, then the +I<-option>=>I<value> pairs modify the configuration for I<$slave>. +The B<place> method returns an empty string as result. +The following I<-option>=>I<value> pairs are supported: + +=over 8 + +=item B<-in> => I<$master> + +I<$master> is the reference to the window relative +to which I<$slave> is to be placed. +I<$master> must either be I<$slave>'s parent or a descendant +of I<$slave>'s parent. +In addition, I<$master> and I<$slave> must both be descendants +of the same top-level window. +These restrictions are necessary to guarantee +that I<$slave> is visible whenever I<$master> is visible. +If this option isn't specified then the master defaults to +I<$slave>'s parent. + +=item B<-x> => I<location> + +I<Location> specifies the x-coordinate within the master window +of the anchor point for I<$slave> widget. +The location is specified in screen units (i.e. any of the forms +accepted by B<Tk_GetPixels>) and need not lie within the bounds +of the master window. + +=item B<-relx> => I<location> + +I<Location> specifies the x-coordinate within the master window +of the anchor point for I<$slave> widget. +In this case the location is specified in a relative fashion +as a floating-point number: 0.0 corresponds to the left edge +of the master and 1.0 corresponds to the right edge of the master. +I<Location> need not be in the range 0.0-1.0. +If both B<-x> and B<-relx> are specified for a slave +then their values are summed. For example, "B<-relx>=>0.5, B<-x>=-2" +positions the left edge of the slave 2 pixels to the left of the +center of its master. + +=item B<-y> => I<location> + +I<Location> specifies the y-coordinate within the master window +of the anchor point for I<$slave> widget. +The location is specified in screen units (i.e. any of the forms +accepted by B<Tk_GetPixels>) and need not lie within the bounds +of the master window. + +=item B<-rely> => I<location> + +I<Location> specifies the y-coordinate within the master window +of the anchor point for I<$slave> widget. +In this case the value is specified in a relative fashion +as a floating-point number: 0.0 corresponds to the top edge +of the master and 1.0 corresponds to the bottom edge of the master. +I<Location> need not be in the range 0.0-1.0. +If both B<-y> and B<-rely> are specified for a slave +then their values are summed. For example, B<-rely>=>0.5, B<-x>=>3 +positions the top edge of the slave 3 pixels below the +center of its master. + +=item B<-anchor> => I<where> + +I<Where> specifies which point of I<$slave> is to be positioned +at the (x,y) location selected by the B<-x>, B<-y>, +B<-relx>, and B<-rely> options. +The anchor point is in terms of the outer area of I<$slave> +including its border, if any. +Thus if I<where> is B<se> then the lower-right corner of +I<$slave>'s border will appear at the given (x,y) location +in the master. +The anchor position defaults to B<nw>. + +=item B<-width> => I<size> + +I<Size> specifies the width for I<$slave> in screen units +(i.e. any of the forms accepted by B<Tk_GetPixels>). +The width will be the outer width of I<$slave> including its +border, if any. +If I<size> is an empty string, or if no B<-width> +or B<-relwidth> option is specified, then the width requested +internally by the window will be used. + +=item B<-relwidth> => I<size> + +I<Size> specifies the width for I<$slave>. +In this case the width is specified as a floating-point number +relative to the width of the master: 0.5 means I<$slave> will +be half as wide as the master, 1.0 means I<$slave> will have +the same width as the master, and so on. +If both B<-width> and B<-relwidth> are specified for a slave, +their values are summed. For example, B<-relwidth>=>1.0, B<-width>=>5 +makes the slave 5 pixels wider than the master. + +=item B<-height> => I<size> + +I<Size> specifies the height for I<$slave> in screen units +(i.e. any of the forms accepted by B<Tk_GetPixels>). +The height will be the outer dimension of I<$slave> including its +border, if any. +If I<size> is an empty string, or if no B<-height> or +B<-relheight> option is specified, then the height requested +internally by the window will be used. + +=item B<-relheight> => I<size> + +I<Size> specifies the height for I<$slave>. +In this case the height is specified as a floating-point number +relative to the height of the master: 0.5 means I<$slave> will +be half as high as the master, 1.0 means I<$slave> will have +the same height as the master, and so on. +If both B<-height> and B<-relheight> are specified for a slave, +their values are summed. For example, B<-relheight>=>1.0, B<-height>=>-2 +makes the slave 2 pixels shorter than the master. + +=item B<-bordermode> => I<mode> + +I<Mode> determines the degree to which borders within the +master are used in determining the placement of the slave. +The default and most common value is B<inside>. +In this case the placer considers the area of the master to +be the innermost area of the master, inside any border: +an option of B<-x>=>B<0> corresponds to an x-coordinate just +inside the border and an option of B<-relwidth>=>1.0 +means I<$slave> will fill the area inside the master's +border. +If I<mode> is B<outside> then the placer considers +the area of the master to include its border; +this mode is typically used when placing I<$slave> +outside its master, as with the options +B<-x>=>B<0>, B<-y>=>B<0>, B<-anchor>=>B<ne>. +Lastly, I<mode> may be specified as B<ignore>, in which +case borders are ignored: the area of the master is considered +to be its official X area, which includes any internal border but +no external border. A bordermode of B<ignore> is probably +not very useful. + +If the same value is specified separately with +two different options, such as B<-x> and B<-relx>, then +the most recent option is used and the older one is ignored. + +=back + +=item I<$slave>->B<placeSlaves> + +The B<placeSlaves> method returns a list of all the slave +windows for which I<$master> is the master. +If there are no slaves for I<$master> then an empty list is +returned. + +=item I<$slave>->B<placeForget> + +The B<placeForget> method causes the placer to stop managing +the geometry of I<$slave>. As a side effect of this method call +I<$slave> will be unmapped so that it doesn't appear on the +screen. +If I<$slave> isn't currently managed by the placer then the +method call has no effect. +B<placeForget> returns an empty string as result. + +=item I<$slave>->B<placeInfo> + +The B<placeInfo> method returns a list giving the current +configuration of I<$slave>. +The list consists of I<-option>=>I<value> pairs in exactly the +same form as might be specified to the B<place> +method. +If the configuration of a window has been retrieved with +B<placeInfo>, that configuration can be restored later by +first using B<placeForget> to erase any existing information +for the window and then invoking B<place> with +the saved information. + +=back + +=head1 FINE POINTS + +It is not necessary for the master window to be the parent +of the slave window. +This feature is useful in at least two situations. +First, for complex window layouts it means you can create a +hierarchy of subwindows whose only purpose +is to assist in the layout of the parent. +The ``I<real children>'' of the parent (i.e. the windows that +are significant for the application's user interface) can be +children of the parent yet be placed inside the windows +of the geometry-management hierarchy. +This means that the path names of the ``I<real children>'' +don't reflect the geometry-management hierarchy and users +can specify options for the real children +without being aware of the structure of the geometry-management +hierarchy. + +A second reason for having a master different than the slave's +parent is to tie two siblings together. +For example, the placer can be used to force a window always to +be positioned centered just below one of its +siblings by specifying the configuration + +S< >B<-in>=>I<$sibling>, B<-relx>=>0.5, B<-rely>=>1.0, +B<-anchor>=>'n', B<-bordermode>=>'outside' + +Whenever the I<$sibling> widget is repositioned in the future, the slave +will be repositioned as well. + +Unlike many other geometry managers (such as the packer) +the placer does not make any attempt to manipulate the geometry of +the master windows or the parents of slave windows (i.e. it doesn't +set their requested sizes). +To control the sizes of these windows, make them windows like +frames and canvases that provide configuration options for this purpose. + +=head1 SEE ALSO + +L<Tk::form|Tk::form> +L<Tk::grid|Tk::grid> +L<Tk::pack|Tk::pack> + +=head1 KEYWORDS + +geometry manager, height, location, master, place, rubber sheet, slave, width + +=cut + |