NAME¶
Tk::form - Geometry manager based on attachment rules
SYNOPSIS¶
$widget->
form?(
args)?
$widget->
formOption?(
args)?
DESCRIPTION¶
The
form method is used to communicate with the
form Geometry
Manager, a geometry manager that arranges the geometry of the children in a
parent window according to attachment rules. The
form geometry manager
is very flexible and powerful; it can be used to emulate all the existing
features of the Tk packer and placer geometry managers (see pack, place). The
form method can have any of several forms, depending on
Option:
- $slave->form?(options)?
- Sets or adjusts the attachment values of the slave window according to the
-option=>value argument pairs.
- -b => attachment
- Abbreviation for the -bottom option.
- -bottom => attachment
- Specifies an attachment for the bottom edge of the slave window. The
attachment must specified according to "SPECIFYING ATTACHMENTS"
below.
- -bottomspring => weight
- Specifies the weight of the spring at the bottom edge of the slave window.
See "USING SPRINGS" below.
- -bp => value
- Abbreviation for the -padbottom option.
- -bs => weight
- Abbreviation for the -bottomspring option.
- -fill => style
- Specifies the fillings when springs are used for this widget. The value
must be x, y, both or none.
- -in => $master
- Places the slave window into the specified $master
window. If the slave was originally in another master window, all
attachment values with respect to the original master window are
discarded. Even if the attachment values are the same as in the original
master window, they need to be specified again. The -in flag, when
needed, must appear as the first flag of options. Otherwise an
error is generated.
- -l => attachment
- Abbreviation for the -left option.
- -left => attachment
- Specifies an attachment for the left edge of the slave window. The
attachment must specified according to "SPECIFYING ATTACHMENTS"
below.
- -leftspring => weight
- Specifies the weight of the spring at the left edge of the slave window.
See "USING SPRINGS" below.
- -lp => value
- Abbreviation for the -padleft option.
- -ls => weight
- Abbreviation for the -leftspring option.
- -padbottom => value
- Specifies the amount of external padding to leave on the bottom side of
the slave. The value may have any of the forms acceptable to
Tk_GetPixels.
- -padleft => value
- Specifies the amount of external padding to leave on the left side of the
slave.
- -padright => value
- Specifies the amount of external padding to leave on the right side of the
slave.
- -padtop => value
- Specifies the amount of external padding to leave on the top side of the
slave.
- -padx => value
- Specifies the amount of external padding to leave on both the left and the
right sides of the slave.
- -pady => value
- Specifies the amount of external padding to leave on both the top and the
bottom sides of the slave.
- -r => attachment
- Abbreviation for the -right option.
- -right => attachment
- Specifies an attachment for the right edge of the slave window. The
attachment must specified according to "SPECIFYING ATTACHMENTS"
below.
- -rightspring => weight
- Specifies the weight of the spring at the right edge of the slave window.
See "USING SPRINGS" below.
- -rp => value
- Abbreviation for the -padright option.
- -rs => weight
- Abbreviation for the -rightspring option.
- -t => attachment
- Abbreviation for the -top option.
- -top => attachment
- Specifies an attachment for the top edge of the slave window. The
attachment must specified according to "SPECIFYING ATTACHMENTS"
below.
- -topspring => weight
- Specifies the weight of the spring at the top edge of the slave window.
See "USING SPRINGS" below.
- -tp => value
- Abbreviation for the -padtop option.
- -ts => weight
- Abbreviation for the -topspring option.
- $master->formCheck
- This method checks whether there is circular dependency in the attachments
of the master's slaves (see "CIRCULAR DEPENDENCY" below). It
returns the Boolean value TRUE if it discover circular dependency
and FALSE otherwise.
- $slave->formForget
- Removes the slave from its master and unmaps its window. The slave will no
longer be managed by form. All attachment values with respect to its
master window are discarded. If another slave is attached to this slave,
then the attachment of the other slave will be changed to grid attachment
based on its geometry.
- $master->formGrid?(x_size,
y_size)?
- When x_size and y_size are given, this method returns the
number of grids of the $master window in a pair of
integers of the form ( x_size, y_size). When both x_size and
y_size are given, this method changes the number of horizontal and
vertical grids on the master window.
- $slave->formInfo?(-option)?
- Queries the attachment options of a slave window. -option can be
any of the options accepted by the form method. If -option
is given, only the value of that option is returned. Otherwise, this
method returns a list whose elements are the current configuration state
of the slave given in the same option-value form that might be
specified to form. The first two elements in this list list are
" -in=>$master" where
$master is the slave's master window.
- $master->formSlaves
- Returns a list of all of the slaves for the master window. The order of
the slaves in the list is the same as their order in the packing order. If
master has no slaves then an empty string is returned.
SPECIFYING ATTACHMENTS¶
One can specify an attachment for each side of a slave window managed by form.
An attachment is specified in the the form "-
side => [
anchor_point,
offset]". -
side can be one of
-top,
-bottom,
-left or
-right.
Offset is given in screen units (i.e. any of the forms acceptable to
Tk_GetPixels). A positive offset indicates shifting to a position to
the right or bottom of an anchor point. A negative offset indicates shifting
to a position to the left or top of an anchor point.
Anchor_point can be given in one of the following forms:
- Grid Attachment
- The master window is divided into a number of horizontal and vertical
grids. By default the master window is divided into 100x100 grids; the
number of grids can be adjusted by the formGrid method. A grid
attachment anchor point is given by a % sign followed by an integer
value. For example, '%0' specifies the first grid line (the top or
left edge of the master window). '%100' specifies the last grid
line (the bottom or right edge of the master window).
- Opposite Side Attachment
- Opposite attachment specifies an anchor point located on the
opposite side of another slave widget, which must be managed by
form in the same master window. An opposite attachment anchor point is
given by the name of another widget. For example, "
$b->form(-top=>[$a,0])"
attaches the top side of the widget $b to the bottom
of the widget $a.
- Parallel Side Attachment
- Opposite attachment specifies an anchor point located on the same
side of another slave widget, which must be managed by form in the same
master window. An parallel attachment anchor point is given by the sign
& follwed by the name of another widget. For example, "
$b->form(-top=>['&',$a,0])"
attaches the top side of the widget $b to the top of
the widget $a, making the top sides of these two
widgets at the same vertical position in their parent window.
- No Attachment
- Specifies a side of the slave to be attached to nothing, indicated by the
keyword none. When the none anchor point is given, the
offset must be zero (or not present). When a side of a slave is attached
to ['none', 0], the position of this side is calculated by the
position of the other side and the natural size of the slave. For example,
if a the left side of a widget is attached to ['%0', 100], its
right side attached to ['none', 0], and the natural size of the
widget is 50 pixels, the right side of the widget will be
positioned at pixel ['%0', 149]. When both -top and
-bottom are attached to none, then by default -top
will be attached to ['%0', 0]. When both -left and
-right are attached to none, then by default -left will be
attached to ['%0', 0].
Shifting effects can be achieved by specifying a non-zero offset with an anchor
point. In the following example, the top side of widget
\$b is attached
to the bottom of
\$a; hence
\$b always appears below
\$a.
Also, the left edge of
\$b is attached to the left side of
\$a
with a 10 pixel offest. Therefore, the left edge of
\$b is always
shifted 10 pixels to the right of
\$a's left edge:
$b->
form(
-left=>[
$a,10],
-top=>[
$a,0]);
ABBREVIATIONS:¶
Certain abbreviations can be made on the attachment specifications: First an
offset of zero can be omitted. Thus, the following two lines are equivalent:
$b->
form(
-top=>[
$a,0],
-right=>['%100',0]);
$b->
form(
-top=>[
$a],
-right=>'%100');
In the second case, when the anchor point is omitted, the offset must be given.
A default anchor point is chosen according to the value of the offset. If the
anchor point is
0 or positive, the default anchor point %0 is used;
thus, "
$b->
form(
-top=>15)"
attaches the top edge of
$b to a position 15 pixels below
the top edge of the master window. If the anchor point is "
-0" or negative, the default anchor point
%100 is used; thus, "
$a->
form(
-right=>-2)" attaches
the right edge of
\$a to a position 2 pixels to the left of the master
window's right edge. An further example below shows a method with its
equivalent abbreviation.
$b->
form(
-top=>['%0',10],
-bottom=>['%100',0]);
$b->
form(
-top=>10,
-bottom=>-0);
USING SPRINGS¶
To be written.
form starts with any slave in the list of slaves of the master window.
Then it tries to determine the position of each side of the slave.
If the attachment of a side of the slave is grid attachment, the position of the
side is readily determined.
If the attachment of this side is
none, then form tries to determine the
position of the opposite side first, and then use the position of the opposite
side and the natural size of the slave to determine the position of this side.
If the attachment is opposite or parallel widget attachments, then form tries to
determine the positions of the other widget first, and then use the positions
of the other widget and the natural size of the slave determine the position
of this side. This recursive algorithmis carried on until the positions of all
slaves are determined.
CIRCULAR DEPENDENCY¶
The algorithm of form will fail if a circular dependency exists in the
attachments of the slaves. For example:
$c->
form(
-left=>
$b);
$b->
form(
-right=>
$c);
In this example, the position of the left side of
$b
depends on the right side of
$c, which in turn depends on
the left side of
$b.
When a circular dependency is discovered during the execution of the form
algorithm, form will generate a background error and the geometry of the
slaves are undefined (and will be arbitrary). Notice that form only executes
the algorithm when the specification of the slaves' attachments is complete.
Therefore, it allows intermediate states of circular dependency during the
specification of the slaves' attachments. Also, unlike the Motif Form manager
widget, form defines circular dependency as ``
dependency in the same
dimension''. Therefore, the following code fragment will does not have
circular dependency because the two widgets do not depend on each other in the
same dimension (
$b depends
$c in
the horizontal dimension and
$c depends on
$b in the vertical dimension):
$b->
form(
-left=>
$c);
$c->
form(
-top=>
$b);
BUGS¶
Springs have not been fully implemented yet.
SEE ALSO¶
Tk::grid Tk::pack Tk::place
KEYWORDS¶
geometry manager, form, attachment, spring, propagation, size, pack, tix,
master, slave