summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorericm <ericm>2000-08-10 00:21:05 (GMT)
committerericm <ericm>2000-08-10 00:21:05 (GMT)
commitd1c711f1d22a1524af5994cfa3f8888e5bc4dc9e (patch)
tree3acd79b0de2739be7bffae01ae70436c029d98a9 /doc
parent33dfdb962c35a1f9a9c1b61e10ab8bd93b1704b6 (diff)
downloadtk-d1c711f1d22a1524af5994cfa3f8888e5bc4dc9e.zip
tk-d1c711f1d22a1524af5994cfa3f8888e5bc4dc9e.tar.gz
tk-d1c711f1d22a1524af5994cfa3f8888e5bc4dc9e.tar.bz2
* 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.
Diffstat (limited to 'doc')
-rw-r--r--doc/SetOptions.313
-rw-r--r--doc/place.n209
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