summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/place.pod
diff options
context:
space:
mode:
authorSiep Kroonenberg <siepo@cybercomm.nl>2011-02-17 15:05:13 +0000
committerSiep Kroonenberg <siepo@cybercomm.nl>2011-02-17 15:05:13 +0000
commit9fc19ef8e2dcd8bcf6a1d034b95c1de2b88e485c (patch)
treeee28de37fe0de6137d535fee2e64ecafaffefb91 /Master/tlpkg/tlperl/lib/Tk/place.pod
parent73b942cfb4ccf168f9c2b7f20a289b06f1f54a4b (diff)
New tlperl part II
git-svn-id: svn://tug.org/texlive/trunk@21424 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/place.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/place.pod283
1 files changed, 283 insertions, 0 deletions
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<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. I<-option> may have any of the values accepted
+by the L<< placeConfigure|/$slave->placeConfigure >> method.
+
+The B<place> method returns I<$slave>.
+
+=item I<$slave>->B<placeConfigure>?(I<-option>=>I<value>?, I<-option>=>I<value>, ...?)?
+
+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<undef>.
+
+The following I<-option>=>I<value> pairs are supported:
+
+=over 8
+
+=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<-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.
+
+=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<-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<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<-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<-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<-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<-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<-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<-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.
+
+=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<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.
+
+=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.
+
+=back
+
+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.
+
+=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>, L<Tk::grid>, L<Tk::pack>
+
+=head1 KEYWORDS
+
+geometry manager, height, location, master, place, rubber sheet, slave, width
+
+=cut
+