* doc/SetOptions.3: Updated documentation to reflect support for

TK_OPTION_NULL_OK for TK_OPTION_DOUBLE and TK_OPTION_PIXELS.

* generic/tkConfig.c: Added for TK_OPTION_NULL_OK support for
TK_OPTION_DOUBLE and TK_OPTION_PIXELS.

* doc/place.n: Updated, reformatted manual entry.

* tests/place.test: Added many tests.

* generic/tkPlace.c (Tk_PlaceObjCmd): Updated to use Tk
widget-option management facilities to manage place options (-x,
-y, etc.), which simplifies the placer code.  Added support for
[place configure pathName] and [place configure pathName -option],
similar to the behavior of the configure subcommand supported by
widgets.


FossilOrigin-Name: 375354145259dc80ebd6b9e71d049edc3000944e

2 files changed, 119 insertions, 103 deletions

diff --git a/doc/SetOptions.3 b/doc/SetOptions.3
index 8393085..29f6e72 100644
--- a/doc/SetOptions.3
+++ b/doc/SetOptions.3
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: SetOptions.3,v 1.3 2000/05/17 21:17:19 ericm Exp $
+'\" RCS: @(#) $Id: SetOptions.3,v 1.4 2000/08/10 00:21:06 ericm Exp $
 '\" 
 .so man.macros
 .TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures"
@@ -311,8 +311,8 @@ The \fIflags\fR field consists of one or more bits ORed together.  At
 present only a single flag is supported: TK_OPTION_NULL_OK.  If
 this bit is set for an option then an empty string will be accepted as
 the value for the option and the resulting internal form will be a
-NULL pointer or \fBNone\fR, depending on the type of the option.
-If the flag is not set then empty strings will result
+NULL pointer, a zero value, or \fBNone\fR, depending on the type of
+the option.  If the flag is not set then empty strings will result
 in errors.
 TK_OPTION_NULL_OK is typically used to allow a
 feature to be turned off entirely, e.g. set a cursor value to
@@ -371,7 +371,8 @@ option type also supports the TK_OPTION_NULL_OK flag.
 \fBTK_OPTION_DOUBLE\fR
 The string value must be a floating-point number in
 the format accepted by \fBstrtol\fR.  The internal form is a C
-\fBdouble\fR value.
+\fBdouble\fR value.  This option type supports the TK_OPTION_NULL_OK
+flag; if a NULL value is set, the internal representation is set to zero.
 .TP
 \fBTK_OPTION_END\fR
 Marks the end of the template.  There must be a Tk_OptionSpec structure
@@ -406,7 +407,9 @@ The internal form is an integer value giving a
 distance in pixels, like the values returned by
 \fBTk_GetPixelsFromObj\fR.  Note: if the \fIobjOffset\fR field isn't
 used then information about the original value of this option will be lost.
-See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details.
+See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details.  This option
+type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the
+internal representation is set to zero.
 .TP
 \fBTK_OPTION_RELIEF\fR
 The value must be standard relief such as \fBraised\fR.
diff --git a/doc/place.n b/doc/place.n
index b51e996..3a256e1 100644
--- a/doc/place.n
+++ b/doc/place.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: place.n,v 1.2 1998/09/14 18:22:59 stanton Exp $
+'\" RCS: @(#) $Id: place.n,v 1.3 2000/08/10 00:21:06 ericm Exp $
 '\" 
 .so man.macros
 .TH place n "" Tk "Tk Built-In Commands"
@@ -16,7 +16,7 @@ place \- Geometry manager for fixed or rubber-sheet placement
 .SH SYNOPSIS
 \fBplace \fIwindow option value \fR?\fIoption value ...\fR?
 .sp
-\fBplace configure \fIwindow option value \fR?\fIoption value ...\fR?
+\fBplace configure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR?
 .sp
 \fBplace forget \fIwindow\fR
 .sp
@@ -39,16 +39,69 @@ 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.
 .PP
-If the first argument to the \fBplace\fR command is a window path
-name or \fBconfigure\fR then the command arranges for the placer
-to manage the geometry of a slave whose path name is \fIwindow\fR.
-The remaining arguments consist of one or more \fIoption\-value\fR
-pairs that specify the way in which \fIwindow\fR's
-geometry is managed.
-If the placer is already managing \fIwindow\fR, then the
-\fIoption\-value\fR pairs modify the configuration for \fIwindow\fR.
-In this form the \fBplace\fR command returns an empty string as result.
+.TP
+\fBplace \fIwindow option value \fR?\fIoption value ...\fR?
+Arrange for the placer to manage the geometry of a slave whose
+pathName is \fIwindow\fR.  The remaining arguments consist of one or
+more \fIoption\-value\fR pairs that specify the way in which
+\fIwindow\fR's geometry is managed.  \fIOption\fR may have any of the
+values accepted by the \fBplace configure\fR command.
+.TP
+\fBplace configure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR?
+Query or modify the geometry options of the slave given by
+\fIwindow\fR.  If no \fIoption\fR is specified, this command returns a
+list describing the available options (see \fBTk_ConfigureInfo\fR for
+information on the format of this list).  If \fIoption\fR is specified
+with no \fIvalue\fR, 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 \fIoption\fR is specified).  If
+one or more \fIoption\-value\fR pairs are specified, then the command
+modifies the given option(s) to have the given value(s); in this case
+the command returns an empty string.
+
 The following \fIoption\-value\fR pairs are supported:
+.RS
+.TP
+\fB\-anchor \fIwhere\fR
+\fIWhere\fR specifies which point of \fIwindow\fR is to be positioned
+at the (x,y) location selected by the \fB\-x\fR, \fB\-y\fR,
+\fB\-relx\fR, and \fB\-rely\fR options.
+The anchor point is in terms of the outer area of \fIwindow\fR
+including its border, if any.
+Thus if \fIwhere\fR is \fBse\fR then the lower-right corner of
+\fIwindow\fR's border will appear at the given (x,y) location
+in the master.
+The anchor position defaults to \fBnw\fR.
+.TP
+\fB\-bordermode \fImode\fR
+\fIMode\fR 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 \fBinside\fR.
+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 \fB\-x 0\fR corresponds to an x-coordinate just
+inside the border and an option of \fB\-relwidth 1.0\fR
+means \fIwindow\fR will fill the area inside the master's
+border.
+
+If \fImode\fR is \fBoutside\fR then the placer considers
+the area of the master to include its border;
+this mode is typically used when placing \fIwindow\fR
+outside its master, as with the options \fB\-x 0 \-y 0 \-anchor ne\fR.
+Lastly, \fImode\fR may be specified as \fBignore\fR, 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 \fBignore\fR is probably
+not very useful.
+.TP
+\fB\-height \fIsize\fR
+\fISize\fR specifies the height for \fIwindow\fR in screen units
+(i.e. any of the forms accepted by \fBTk_GetPixels\fR).
+The height will be the outer dimension of \fIwindow\fR including its
+border, if any.
+If \fIsize\fR is an empty string, or if no \fB\-height\fR or
+\fB\-relheight\fR option is specified, then the height requested
+internally by the window will be used.
 .TP
 \fB\-in \fImaster\fR
 \fIMaster\fR specifes the path name of the window relative
@@ -62,12 +115,25 @@ that \fIwindow\fR is visible whenever \fImaster\fR is visible.
 If this option isn't specified then the master defaults to
 \fIwindow\fR's parent.
 .TP
-\fB\-x \fIlocation\fR
-\fILocation\fR specifies the x-coordinate within the master window
-of the anchor point for \fIwindow\fR.
-The location is specified in screen units (i.e. any of the forms
-accepted by \fBTk_GetPixels\fR) and need not lie within the bounds
-of the master window.
+\fB\-relheight \fIsize\fR
+\fISize\fR specifies the height for \fIwindow\fR.
+In this case the height is specified as a floating-point number
+relative to the height of the master: 0.5 means \fIwindow\fR will
+be half as high as the master, 1.0 means \fIwindow\fR will have
+the same height as the master, and so on.
+If both \fB\-height\fR and \fB\-relheight\fR are specified for a slave,
+their values are summed.  For example, \fB\-relheight 1.0 \-height \-2\fR
+makes the slave 2 pixels shorter than the master.
+.TP
+\fB\-relwidth \fIsize\fR
+\fISize\fR specifies the width for \fIwindow\fR.
+In this case the width is specified as a floating-point number
+relative to the width of the master: 0.5 means \fIwindow\fR will
+be half as wide as the master, 1.0 means \fIwindow\fR will have
+the same width as the master, and so on.
+If both \fB\-width\fR and \fB\-relwidth\fR are specified for a slave,
+their values are summed.  For example, \fB\-relwidth 1.0 \-width 5\fR
+makes the slave 5 pixels wider than the master.
 .TP
 \fB\-relx \fIlocation\fR
 \fILocation\fR specifies the x-coordinate within the master window
@@ -81,13 +147,6 @@ then their values are summed.  For example, \fB\-relx 0.5 \-x \-2\fR
 positions the left edge of the slave 2 pixels to the left of the
 center of its master.
 .TP
-\fB\-y \fIlocation\fR
-\fILocation\fR specifies the y-coordinate within the master window
-of the anchor point for \fIwindow\fR.
-The location is specified in screen units (i.e. any of the forms
-accepted by \fBTk_GetPixels\fR) and need not lie within the bounds
-of the master window.
-.TP
 \fB\-rely \fIlocation\fR
 \fILocation\fR specifies the y-coordinate within the master window
 of the anchor point for \fIwindow\fR.
@@ -100,17 +159,6 @@ then their values are summed.  For example, \fB\-rely 0.5 \-x 3\fR
 positions the top edge of the slave 3 pixels below the
 center of its master.
 .TP
-\fB\-anchor \fIwhere\fR
-\fIWhere\fR specifies which point of \fIwindow\fR is to be positioned
-at the (x,y) location selected by the \fB\-x\fR, \fB\-y\fR,
-\fB\-relx\fR, and \fB\-rely\fR options.
-The anchor point is in terms of the outer area of \fIwindow\fR
-including its border, if any.
-Thus if \fIwhere\fR is \fBse\fR then the lower-right corner of
-\fIwindow\fR's border will appear at the given (x,y) location
-in the master.
-The anchor position defaults to \fBnw\fR.
-.TP
 \fB\-width \fIsize\fR
 \fISize\fR specifies the width for \fIwindow\fR in screen units
 (i.e. any of the forms accepted by \fBTk_GetPixels\fR).
@@ -120,77 +168,42 @@ If \fIsize\fR is an empty string, or if no \fB\-width\fR
 or \fB\-relwidth\fR option is specified, then the width requested
 internally by the window will be used.
 .TP
-\fB\-relwidth \fIsize\fR
-\fISize\fR specifies the width for \fIwindow\fR.
-In this case the width is specified as a floating-point number
-relative to the width of the master: 0.5 means \fIwindow\fR will
-be half as wide as the master, 1.0 means \fIwindow\fR will have
-the same width as the master, and so on.
-If both \fB\-width\fR and \fB\-relwidth\fR are specified for a slave,
-their values are summed.  For example, \fB\-relwidth 1.0 \-width 5\fR
-makes the slave 5 pixels wider than the master.
-.TP
-\fB\-height \fIsize\fR
-\fISize\fR specifies the height for \fIwindow\fR in screen units
-(i.e. any of the forms accepted by \fBTk_GetPixels\fR).
-The height will be the outer dimension of \fIwindow\fR including its
-border, if any.
-If \fIsize\fR is an empty string, or if no \fB\-height\fR or
-\fB\-relheight\fR option is specified, then the height requested
-internally by the window will be used.
-.TP
-\fB\-relheight \fIsize\fR
-\fISize\fR specifies the height for \fIwindow\fR.
-In this case the height is specified as a floating-point number
-relative to the height of the master: 0.5 means \fIwindow\fR will
-be half as high as the master, 1.0 means \fIwindow\fR will have
-the same height as the master, and so on.
-If both \fB\-height\fR and \fB\-relheight\fR are specified for a slave,
-their values are summed.  For example, \fB\-relheight 1.0 \-height \-2\fR
-makes the slave 2 pixels shorter than the master.
+\fB\-x \fIlocation\fR
+\fILocation\fR specifies the x-coordinate within the master window
+of the anchor point for \fIwindow\fR.
+The location is specified in screen units (i.e. any of the forms
+accepted by \fBTk_GetPixels\fR) and need not lie within the bounds
+of the master window.
 .TP
-\fB\-bordermode \fImode\fR
-\fIMode\fR 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 \fBinside\fR.
-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 \fB\-x 0\fR corresponds to an x-coordinate just
-inside the border and an option of \fB\-relwidth 1.0\fR
-means \fIwindow\fR will fill the area inside the master's
-border.
-If \fImode\fR is \fBoutside\fR then the placer considers
-the area of the master to include its border;
-this mode is typically used when placing \fIwindow\fR
-outside its master, as with the options \fB\-x 0 \-y 0 \-anchor ne\fR.
-Lastly, \fImode\fR may be specified as \fBignore\fR, 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 \fBignore\fR is probably
-not very useful.
+\fB\-y \fIlocation\fR
+\fILocation\fR specifies the y-coordinate within the master window
+of the anchor point for \fIwindow\fR.
+The location is specified in screen units (i.e. any of the forms
+accepted by \fBTk_GetPixels\fR) and need not lie within the bounds
+of the master window.
 .PP
 If the same value is specified separately with
 two different options, such as \fB\-x\fR and \fB\-relx\fR, then
 the most recent option is used and the older one is ignored.
-.PP
-The \fBplace slaves\fR command returns a list of all the slave
-windows for which \fIwindow\fR is the master.
-If there are no slaves for \fIwindow\fR then an empty string is
-returned.
-.PP
-The \fBplace forget\fR command causes the placer to stop managing
-the geometry of \fIwindow\fR.  As a side effect of this command
-\fIwindow\fR will be unmapped so that it doesn't appear on the
-screen.
-If \fIwindow\fR isn't currently managed by the placer then the
-command has no effect.
-\fBPlace forget\fR returns an empty string as result.
-.PP
-The \fBplace info\fR command returns a list giving the current
-configuration of \fIwindow\fR.
+.RE
+.TP
+\fBplace forget \fIwindow\fR
+Causes the placer to stop managing the geometry of \fIwindow\fR.  As a
+side effect of this command \fIwindow\fR will be unmapped so that it
+doesn't appear on the screen.  If \fIwindow\fR isn't currently managed
+by the placer then the command has no effect.  This command returns an
+empty string.
+.TP
+\fBplace info \fIwindow\fR
+Returns a list giving the current configuration of \fIwindow\fR.
 The list consists of \fIoption\-value\fR pairs in exactly the
 same form as might be specified to the \fBplace configure\fR
 command.
+.TP
+\fBplace slaves \fIwindow\fR
+Returns a list of all the slave windows for which \fIwindow\fR is the master.
+If there are no slaves for \fIwindow\fR then an empty string is returned.
+
 If the configuration of a window has been retrieved with
 \fBplace info\fR, that configuration can be restored later by
 first using \fBplace forget\fR to erase any existing information