1place(3)              User Contributed Perl Documentation             place(3)
2
3
4

NAME

6       Tk::place - Geometry manager for fixed or rubber-sheet placement
7

SYNOPSIS

9          $widget->place?(-option=>value?, -option=>value, ...)?
10
11          $widget->placeForget
12
13          $widget->placeInfo
14
15          $master->placeSlaves
16

DESCRIPTION

18       The placer is a geometry manager for Tk.  It provides simple fixed
19       placement of windows, where you specify the exact size and location of
20       one window, called the slave, within another window, called the master.
21       The placer also provides rubber-sheet placement, where you specify the
22       size and location of the slave in terms of the dimensions of the
23       master, so that the slave changes size and location in response to
24       changes in the size of the master.  Lastly, the placer allows you to
25       mix these styles of placement so that, for example, the slave has a
26       fixed width and height but is centered inside the master.
27
28       $slave->place?(-option=>value?, -option=>value, ...?)?
29           The place method arranges for the placer to manage the geometry of
30           $slave.  The remaining arguments consist of one or more
31           -option=>value pairs that specify the way in which $slave's
32           geometry is managed. -option may have any of the values accepted by
33           the placeConfigure method.
34
35           The place method returns $slave.
36
37       $slave->placeConfigure?(-option=>value?, -option=>value, ...?)?
38           Query or modify the geometry options of the $slave. If no option is
39           specified, this method returns a list describing the available
40           options (see Tk_ConfigureInfo for information on the format of this
41           list). If option is specified with no value, then the command
42           returns a list describing the one named option (this list will be
43           identical to the corresponding sublist of the value returned if no
44           option is specified). If one or more option-value pairs are
45           specified, then the method modifies the given option(s) to have the
46           given value(s); in this case the command returns "undef".
47
48           The following -option=>value pairs are supported:
49
50           -anchor => where
51                   Where specifies which point of $slave is to be positioned
52                   at the (x,y) location selected by the -x, -y, -relx, and
53                   -rely options.  The anchor point is in terms of the outer
54                   area of $slave including its border, if any.  Thus if where
55                   is se then the lower-right corner of $slave's border will
56                   appear at the given (x,y) location in the master.  The
57                   anchor position defaults to nw.
58
59           -bordermode => mode
60                   Mode determines the degree to which borders within the
61                   master are used in determining the placement of the slave.
62                   The default and most common value is inside.  In this case
63                   the placer considers the area of the master to be the
64                   innermost area of the master, inside any border: an option
65                   of -x=>0 corresponds to an x-coordinate just inside the
66                   border and an option of -relwidth=>1.0 means $slave will
67                   fill the area inside the master's border.  If mode is
68                   outside then the placer considers the area of the master to
69                   include its border; this mode is typically used when
70                   placing $slave outside its master, as with the options
71                   -x=>0, -y=>0, -anchor=>ne.  Lastly, mode may be specified
72                   as ignore, in which case borders are ignored:  the area of
73                   the master is considered to be its official X area, which
74                   includes any internal border but no external border.  A
75                   bordermode of ignore is probably not very useful.
76
77           -height => size
78                   Size specifies the height for $slave in screen units (i.e.
79                   any of the forms accepted by Tk_GetPixels).  The height
80                   will be the outer dimension of $slave including its border,
81                   if any.  If size is an empty string, or if no -height or
82                   -relheight option is specified, then the height requested
83                   internally by the window will be used.
84
85           -in => $master
86                   $master is the reference to the window relative to which
87                   $slave is to be placed.  $master must either be $slave's
88                   parent or a descendant of $slave's parent.  In addition,
89                   $master and $slave must both be descendants of the same
90                   top-level window.  These restrictions are necessary to
91                   guarantee that $slave is visible whenever $master is
92                   visible.  If this option isn't specified then the master
93                   defaults to $slave's parent.
94
95           -relheight => size
96                   Size specifies the height for $slave.  In this case the
97                   height is specified as a floating-point number relative to
98                   the height of the master: 0.5 means $slave will be half as
99                   high as the master, 1.0 means $slave will have the same
100                   height as the master, and so on.  If both -height and
101                   -relheight are specified for a slave, their values are
102                   summed.  For example, -relheight=>1.0, -height=>-2 makes
103                   the slave 2 pixels shorter than the master.
104
105           -relwidth => size
106                   Size specifies the width for $slave.  In this case the
107                   width is specified as a floating-point number relative to
108                   the width of the master: 0.5 means $slave will be half as
109                   wide as the master, 1.0 means $slave will have the same
110                   width as the master, and so on.  If both -width and
111                   -relwidth are specified for a slave, their values are
112                   summed.  For example, -relwidth=>1.0, -width=>5 makes the
113                   slave 5 pixels wider than the master.
114
115           -relx => location
116                   Location specifies the x-coordinate within the master
117                   window of the anchor point for $slave widget.  In this case
118                   the location is specified in a relative fashion as a
119                   floating-point number:  0.0 corresponds to the left edge of
120                   the master and 1.0 corresponds to the right edge of the
121                   master.  Location need not be in the range 0.0-1.0.  If
122                   both -x and -relx are specified for a slave then their
123                   values are summed.  For example, "-relx=>0.5, -x=-2"
124                   positions the left edge of the slave 2 pixels to the left
125                   of the center of its master.
126
127           -rely => location
128                   Location specifies the y-coordinate within the master
129                   window of the anchor point for $slave widget.  In this case
130                   the value is specified in a relative fashion as a floating-
131                   point number:  0.0 corresponds to the top edge of the
132                   master and 1.0 corresponds to the bottom edge of the
133                   master.  Location need not be in the range 0.0-1.0.  If
134                   both -y and -rely are specified for a slave then their
135                   values are summed.  For example, -rely=>0.5, -x=>3
136                   positions the top edge of the slave 3 pixels below the
137                   center of its master.
138
139           -width => size
140                   Size specifies the width for $slave in screen units (i.e.
141                   any of the forms accepted by Tk_GetPixels).  The width will
142                   be the outer width of $slave including its border, if any.
143                   If size is an empty string, or if no -width or -relwidth
144                   option is specified, then the width requested internally by
145                   the window will be used.
146
147           -x => location
148                   Location specifies the x-coordinate within the master
149                   window of the anchor point for $slave widget.  The location
150                   is specified in screen units (i.e. any of the forms
151                   accepted by Tk_GetPixels) and need not lie within the
152                   bounds of the master window.
153
154           -y => location
155                   Location specifies the y-coordinate within the master
156                   window of the anchor point for $slave widget.  The location
157                   is specified in screen units (i.e. any of the forms
158                   accepted by Tk_GetPixels) and need not lie within the
159                   bounds of the master window.
160
161           If the same value is specified separately with two different
162           options, such as -x and -relx, then the most recent option is used
163           and the older one is ignored.
164
165       $slave->placeForget
166           The placeForget method causes the placer to stop managing the
167           geometry of $slave.  As a side effect of this method call $slave
168           will be unmapped so that it doesn't appear on the screen.  If
169           $slave isn't currently managed by the placer then the method call
170           has no effect.  placeForget returns an empty string as result.
171
172       $slave->placeInfo
173           The placeInfo method returns a list giving the current
174           configuration of $slave.  The list consists of -option=>value pairs
175           in exactly the same form as might be specified to the place method.
176
177       $slave->placeSlaves
178           The placeSlaves method returns a list of all the slave windows for
179           which $master is the master.  If there are no slaves for $master
180           then an empty list is returned.
181
182       If the configuration of a window has been retrieved with placeInfo,
183       that configuration can be restored later by first using placeForget to
184       erase any existing information for the window and then invoking place
185       with the saved information.
186

FINE POINTS

188       It is not necessary for the master window to be the parent of the slave
189       window.  This feature is useful in at least two situations.  First, for
190       complex window layouts it means you can create a hierarchy of
191       subwindows whose only purpose is to assist in the layout of the parent.
192       The ``real children'' of the parent (i.e. the windows that are
193       significant for the application's user interface) can be children of
194       the parent yet be placed inside the windows of the geometry-management
195       hierarchy.  This means that the path names of the ``real children''
196       don't reflect the geometry-management hierarchy and users can specify
197       options for the real children without being aware of the structure of
198       the geometry-management hierarchy.
199
200       A second reason for having a master different than the slave's parent
201       is to tie two siblings together.  For example, the placer can be used
202       to force a window always to be positioned centered just below one of
203       its siblings by specifying the configuration
204
205           -in=>$sibling, -relx=>0.5, -rely=>1.0, -anchor=>'n',
206       -bordermode=>'outside'
207
208       Whenever the $sibling widget is repositioned in the future, the slave
209       will be repositioned as well.
210
211       Unlike many other geometry managers (such as the packer) the placer
212       does not make any attempt to manipulate the geometry of the master
213       windows or the parents of slave windows (i.e. it doesn't set their
214       requested sizes).  To control the sizes of these windows, make them
215       windows like frames and canvases that provide configuration options for
216       this purpose.
217

SEE ALSO

219       Tk::form, Tk::grid, Tk::pack
220

KEYWORDS

222       geometry manager, height, location, master, place, rubber sheet, slave,
223       width
224
225
226
227perl v5.16.3                      2014-06-10                          place(3)
Impressum