From 9fc19ef8e2dcd8bcf6a1d034b95c1de2b88e485c Mon Sep 17 00:00:00 2001 From: Siep Kroonenberg Date: Thu, 17 Feb 2011 15:05:13 +0000 Subject: New tlperl part II git-svn-id: svn://tug.org/texlive/trunk@21424 c570f23f-e606-0410-a88d-b1316a301751 --- Master/tlpkg/tlperl/lib/Tk/place.pod | 283 +++++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 Master/tlpkg/tlperl/lib/Tk/place.pod (limited to 'Master/tlpkg/tlperl/lib/Tk/place.pod') diff --git a/Master/tlpkg/tlperl/lib/Tk/place.pod b/Master/tlpkg/tlperl/lib/Tk/place.pod new file mode 100644 index 00000000000..9f7e74f210f --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/place.pod @@ -0,0 +1,283 @@ +# 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?(I<-option>=>I?, I<-option>=>I, ...)? + +S< >I<$widget>->B + +S< >I<$widget>->B + +S< >I<$master>->B + +=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, +within another window, called the I. +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?(I<-option>=>I?, I<-option>=>I, ...?)? + +The B method arranges for the placer +to manage the geometry of I<$slave>. +The remaining arguments consist of one or more I<-option>=>I +pairs that specify the way in which I<$slave>'s +geometry is managed. I<-option> may have any of the values accepted +by the L<< placeConfigure|/$slave->placeConfigure >> method. + +The B method returns I<$slave>. + +=item I<$slave>->B?(I<-option>=>I?, I<-option>=>I, ...?)? + +Query or modify the geometry options of the I<$slave>. If no option is +specified, this method returns a list describing the available +options (see Tk_ConfigureInfo for information on the format of this +list). If option is specified with no value, then the command returns +a list describing the one named option (this list will be identical to +the corresponding sublist of the value returned if no option is +specified). If one or more option-value pairs are specified, then the +method modifies the given option(s) to have the given value(s); in +this case the command returns C. + +The following I<-option>=>I pairs are supported: + +=over 8 + +=item B<-anchor> => I + +I 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 is B 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. + +=item B<-bordermode> => I + +I 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. +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 is B 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. +Lastly, I may be specified as B, 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 is probably +not very useful. + +=item B<-height> => I + +I specifies the height for I<$slave> in screen units +(i.e. any of the forms accepted by B). +The height will be the outer dimension of I<$slave> including its +border, if any. +If I 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<-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<-relheight> => I + +I 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<-relwidth> => I + +I 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<-relx> => I + +I 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 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<-rely> => I + +I 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 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<-width> => I + +I specifies the width for I<$slave> in screen units +(i.e. any of the forms accepted by B). +The width will be the outer width of I<$slave> including its +border, if any. +If I 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<-x> => I + +I 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) and need not lie within the bounds +of the master window. + +=item B<-y> => I + +I 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) and need not lie within the bounds +of the master window. + +=back + +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. + +=item I<$slave>->B + +The B 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 returns an empty string as result. + +=item I<$slave>->B + +The B method returns a list giving the current +configuration of I<$slave>. +The list consists of I<-option>=>I pairs in exactly the +same form as might be specified to the B +method. + +=item I<$slave>->B + +The B 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. + +=back + +If the configuration of a window has been retrieved with +B, that configuration can be restored later by +first using B to erase any existing information +for the window and then invoking B with +the saved information. + +=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'' 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'' +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, L, L + +=head1 KEYWORDS + +geometry manager, height, location, master, place, rubber sheet, slave, width + +=cut + -- cgit v1.2.3