summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/option.n22
-rw-r--r--doc/pack.n28
-rw-r--r--doc/panedwindow.n10
-rw-r--r--doc/photo.n27
-rw-r--r--doc/place.n27
-rw-r--r--doc/popup.n19
-rw-r--r--doc/raise.n17
-rw-r--r--doc/scale.n8
-rw-r--r--doc/scrollbar.n22
-rw-r--r--doc/selection.n38
-rw-r--r--doc/send.n19
-rw-r--r--doc/spinbox.n6
-rw-r--r--doc/text.n131
-rw-r--r--doc/toplevel.n9
-rw-r--r--doc/winfo.n18
-rw-r--r--doc/wm.n56
16 files changed, 310 insertions, 147 deletions
diff --git a/doc/option.n b/doc/option.n
index 4545eb2..9f6d48e 100644
--- a/doc/option.n
+++ b/doc/option.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: option.n,v 1.2 1998/09/14 18:22:58 stanton Exp $
+'\" RCS: @(#) $Id: option.n,v 1.2.26.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH option n "" Tk "Tk Built-In Commands"
@@ -14,13 +14,12 @@
.SH NAME
option \- Add/retrieve window options to/from the option database
.SH SYNOPSIS
+.nf
\fBoption add \fIpattern value \fR?\fIpriority\fR?
-.sp
\fBoption clear\fR
-.sp
\fBoption get \fIwindow name class\fR
-.sp
\fBoption readfile \fIfileName \fR?\fIpriority\fR?
+.fi
.BE
.SH DESCRIPTION
@@ -86,6 +85,21 @@ Any of the above keywords may be abbreviated. In addition, priorities
may be specified numerically using integers between 0 and 100,
inclusive. The numeric form is probably a bad idea except for new priority
levels other than the ones given above.
+.SH EXAMPLES
+Instruct every button in the application to have red text on it unless
+explicitly overridden:
+.CS
+\fBoption add\fR *button.foreground red startupFile
+.CE
+.PP
+Allow users to control what happens in an entry widget when the Return
+key is pressed by specifying a script in the option database and add a
+default option for that which rings the bell:
+.CS
+entry .e
+bind .e <Return> [\fBoption get\fR .e returnCommand Command]
+\fBoption add\fR *.e.returnCommand bell widgetDefault
+.CE
.SH KEYWORDS
database, option, priority, retrieve
diff --git a/doc/pack.n b/doc/pack.n
index ddda916..c6c3588 100644
--- a/doc/pack.n
+++ b/doc/pack.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: pack.n,v 1.3 2001/02/12 18:06:47 drh Exp $
+'\" RCS: @(#) $Id: pack.n,v 1.3.6.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH pack n 4.0 Tk "Tk Built-In Commands"
@@ -108,7 +108,7 @@ of two values to specify padding for left and right separately.
\fB\-pady \fIamount\fR
\fIAmount\fR specifies how much vertical external padding to
leave on each side of the slave(s). \fIAmount\fR may be a list
-of two values to specify padding for top and bottom separtely.
+of two values to specify padding for top and bottom separately.
\fIAmount\fR defaults to 0.
.TP
\fB\-side \fIside\fR
@@ -156,7 +156,6 @@ Returns a list of all of the slaves in the packing order for \fImaster\fR.
The order of the slaves in the list is the same as their order in
the packing order.
If \fImaster\fR has no slaves then an empty string is returned.
-
.SH "THE PACKER ALGORITHM"
.PP
For each master the packer maintains an ordered list of slaves
@@ -217,7 +216,6 @@ left in the cavity.
If the cavity shrinks to zero size, then all remaining slaves
on the packing list will be unmapped from the screen until
the master window becomes large enough to hold them again.
-
.SH "EXPANSION"
.PP
If a master window is so large that there will be extra space
@@ -228,7 +226,6 @@ Extra horizontal space is distributed among the expandable
slaves whose \fB\-side\fR is \fBleft\fR or \fBright\fR,
and extra vertical space is distributed among the expandable
slaves whose \fB\-side\fR is \fBtop\fR or \fBbottom\fR.
-
.SH "GEOMETRY PROPAGATION"
.PP
The packer normally computes how large a master must be to
@@ -243,7 +240,6 @@ If propagation is disabled then the packer will not set
the requested width and height of the packer.
This may be useful if, for example, you wish for a master
window to have a fixed size that you specify.
-
.SH "RESTRICTIONS ON MASTER WINDOWS"
.PP
The master for each slave must either be the slave's parent
@@ -251,7 +247,6 @@ The master for each slave must either be the slave's parent
This restriction is necessary to guarantee that the
slave can be placed over any part of its master that is
visible without danger of the slave being clipped by its parent.
-
.SH "PACKING ORDER"
.PP
If the master for a slave is not its parent then you must make sure
@@ -263,6 +258,25 @@ to create the master window first: the most recently created window
will be highest in the stacking order.
Or, you can use the \fBraise\fR and \fBlower\fR commands to change
the stacking order of either the master or the slave.
+.SH EXAMPLE
+.CS
+# Make the widgets
+label .t \-text "This widget is at the top" \-bg red
+label .b \-text "This widget is at the bottom" \-bg green
+label .l \-text "Left\\nHand\\nSide"
+label .r \-text "Right\\nHand\\nSide"
+text .mid
+\.mid insert end "This layout is like Java's BorderLayout"
+# Lay them out
+\fBpack\fR .t \-side top \-fill x
+\fBpack\fR .b \-side bottom \-fill x
+\fBpack\fR .l \-side left \-fill y
+\fBpack\fR .r \-side right \-fill y
+\fBpack\fR .mid \-expand 1 \-fill both
+.CE
+
+.SH "SEE ALSO"
+grid(n), place(n)
.SH KEYWORDS
geometry manager, location, packer, parcel, propagation, size
diff --git a/doc/panedwindow.n b/doc/panedwindow.n
index 20e43cf..c22718a 100644
--- a/doc/panedwindow.n
+++ b/doc/panedwindow.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: panedwindow.n,v 1.2.2.1 2003/07/17 20:49:00 dkf Exp $
+'\" RCS: @(#) $Id: panedwindow.n,v 1.2.2.2 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH panedwindow n 8.4 Tk "Tk Built-In Commands"
@@ -63,7 +63,6 @@ horizontally or vertically, according to the value of the
\fB\-orient\fR option. Each pane contains one widget, and each pair of
panes is separated by a moveable (via mouse movements) sash. Moving a
sash causes the widgets on either side of the sash to be resized.
-
.SH "WIDGET COMMAND"
.PP
The \fBpanedwindow\fR command creates a new Tcl command whose name is
@@ -125,7 +124,7 @@ the following forms:
Return a list containing the x and y coordinates of the most recent
proxy location.
.TP
-\fIpathname \fBproxy forget\fR
+\fIpathName \fBproxy forget\fR
Remove the proxy from the display.
.TP
\fIpathName \fBproxy place \fIx y\fR
@@ -142,6 +141,7 @@ Return the current x and y coordinate pair for the sash given by
\fIindex\fR. \fIIndex\fR must be an integer between 0 and 1 less than
the number of panes in the panedwindow. The coordinates given are
those of the top left corner of the region containing the sash.
+.TP
\fIpathName \fBsash dragto \fIindex x y\fR
This command computes the difference between the given coordinates and the
coordinates given to the last \fBsash coord\fR command for the given
@@ -229,16 +229,14 @@ panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR.
.TP
\fIpathName \fBpanes\fR
Returns an ordered list of the widgets managed by \fIpathName\fR.
-
.SH "RESIZING PANES"
-
A pane is resized by grabbing the sash (or sash handle if present) and
dragging with the mouse. This is accomplished via mouse motion
bindings on the widget. When a sash is moved, the sizes of the panes
on each side of the sash, and thus the widgets in those panes, are
adjusted.
.PP
-When a pane is resized from outside (eg, it is packed to expand and
+When a pane is resized from outside (e.g. it is packed to expand and
fill, and the containing toplevel is resized), space is added to the final
(rightmost or bottommost) pane in the window.
diff --git a/doc/photo.n b/doc/photo.n
index bd49def..48c99ae 100644
--- a/doc/photo.n
+++ b/doc/photo.n
@@ -9,7 +9,7 @@
'\" Department of Computer Science,
'\" Australian National University.
'\"
-'\" RCS: @(#) $Id: photo.n,v 1.14.2.3 2003/07/17 22:55:27 dkf Exp $
+'\" RCS: @(#) $Id: photo.n,v 1.14.2.4 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH photo n 4.0 Tk "Tk Built-In Commands"
@@ -36,7 +36,6 @@ in regions where no image data has been supplied
or where it has been set transparent by the \fBtransparency set\fR
subcommand.
.VE 8.4
-
.SH "CREATING PHOTOS"
.PP
Like all images, photos are created using the \fBimage create\fR
@@ -93,7 +92,6 @@ Specifies the width of the image, in pixels. This option is useful
primarily in situations where the user wishes to build up the contents
of the image piece by piece. A value of zero (the default) allows the
image to expand or shrink horizontally to fit the data stored in it.
-
.SH "IMAGE COMMAND"
.PP
When a photo image is created, Tk also creates a new command
@@ -216,7 +214,7 @@ the specified color.
\fB\-format\fI format-name\fR
Specifies the name of the image file format handler to be used.
Specifically, this subcommand searches
-for the first handler whose name matches a initial substring of
+for the first handler whose name matches an initial substring of
\fIformat-name\fR and which has the capability to read this image data.
If this option is not given, this subcommand uses the first
handler that has the capability to read the image data.
@@ -347,7 +345,7 @@ the specified color.
\fB\-format\fI format-name\fR
Specifies the name of the image file format handler to be used to
write the data to the file. Specifically, this subcommand searches
-for the first handler whose name matches a initial substring of
+for the first handler whose name matches an initial substring of
\fIformat-name\fR and which has the capability to write an image
file. If this option is not given, this subcommand uses the first
handler that has the capability to write an image file.
@@ -397,7 +395,6 @@ to use of the formats supported by the handler.
Note that not all image handlers may support writing transparency data
to a file, even where the target image format does.
.VE 8.4
-
.SH "COLOR ALLOCATION"
.PP
When a photo image is displayed in a window, the photo image code
@@ -427,12 +424,28 @@ each primary color to try to allocate. It can also be used to force
the image to be displayed in shades of gray, even on a color display,
by giving a single number rather than three numbers separated by
slashes.
-
.SH CREDITS
.PP
The photo image type was designed and implemented by Paul Mackerras,
based on his earlier photo widget and some suggestions from
John Ousterhout.
+.SH EXAMPLE
+Load an image from a file and tile it to the size of a window, which
+is useful for producing a tiled background:
+.CS
+# These lines should be called once
+\fBimage create photo\fR untiled -file "theFile.ppm"
+\fBimage create photo\fR tiled
+
+# These lines should be called whenever .someWidget changes
+# size; a <Configure> binding is useful here
+set width [winfo width .someWidget]
+set height [winfo height .someWidget]
+tiled \fBcopy\fR untiled \-to 0 0 $width $height \-shrink
+.CE
+
+.SH "SEE ALSO"
+image(n)
.SH KEYWORDS
photo, image, color
diff --git a/doc/place.n b/doc/place.n
index 3a256e1..028654d 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.3 2000/08/10 00:21:06 ericm Exp $
+'\" RCS: @(#) $Id: place.n,v 1.3.8.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH place n "" Tk "Tk Built-In Commands"
@@ -14,15 +14,7 @@
.SH NAME
place \- Geometry manager for fixed or rubber-sheet placement
.SH SYNOPSIS
-\fBplace \fIwindow option value \fR?\fIoption value ...\fR?
-.sp
-\fBplace configure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR?
-.sp
-\fBplace forget \fIwindow\fR
-.sp
-\fBplace info \fIwindow\fR
-.sp
-\fBplace slaves \fIwindow\fR
+\fBplace \fIoption arg \fR?\fIarg ...\fR?
.BE
.SH DESCRIPTION
@@ -104,7 +96,7 @@ If \fIsize\fR is an empty string, or if no \fB\-height\fR or
internally by the window will be used.
.TP
\fB\-in \fImaster\fR
-\fIMaster\fR specifes the path name of the window relative
+\fIMaster\fR specifies the path name of the window relative
to which \fIwindow\fR is to be placed.
\fIMaster\fR must either be \fIwindow\fR's parent or a descendant
of \fIwindow\fR's parent.
@@ -203,13 +195,12 @@ command.
\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.
-
+.PP
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
for the window and then invoking \fBplace configure\fR with
the saved information.
-
.SH "FINE POINTS"
.PP
It is not necessary for the master window to be the parent
@@ -245,6 +236,16 @@ 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.
+.SH EXAMPLE
+Make the label occupy the middle bit of the toplevel, no matter how it
+is resized:
+.CS
+label .l \-text "In the\\nMiddle!" \-bg black \-fg white
+\fBplace\fR .l \-relwidth .3 \-relx .35 \-relheight .3 \-rely .35
+.CE
+
+.SH "SEE ALSO"
+grid(n), pack(n)
.SH KEYWORDS
geometry manager, height, location, master, place, rubber sheet, slave, width
diff --git a/doc/popup.n b/doc/popup.n
index a1b49bd..2fb37d9 100644
--- a/doc/popup.n
+++ b/doc/popup.n
@@ -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: popup.n,v 1.2 1998/09/14 18:22:59 stanton Exp $
+'\" RCS: @(#) $Id: popup.n,v 1.2.26.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH tk_popup n 4.0 Tk "Tk Built-In Commands"
@@ -28,6 +28,23 @@ menu's upper left corner is positioned at the given point.
Otherwise \fIentry\fR gives the index of an entry in \fImenu\fR and
the menu will be positioned so that the entry is positioned over
the given point.
+.SH EXAMPLE
+How to attach a simple popup menu to a widget.
+.CS
+# Create a menu
+set m [menu .popupMenu]
+$m add command \-label "Example 1" \-command bell
+$m add command \-label "Example 2" \-command bell
+
+# Create something to attach it to
+pack [label .l \-text "Click me!"]
+
+# Arrange for the menu to pop up when the label is clicked
+bind .l <1> {\fBtk_popup\fR .popupMenu %X %Y}
+.CE
+
+.SH "SEE ALSO"
+bind(n), menu(n), tk_optionMenu(n)
.SH KEYWORDS
menu, popup
diff --git a/doc/raise.n b/doc/raise.n
index 534aa12..1a14049 100644
--- a/doc/raise.n
+++ b/doc/raise.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: raise.n,v 1.2 1998/09/14 18:22:59 stanton Exp $
+'\" RCS: @(#) $Id: raise.n,v 1.2.26.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH raise n 3.3 Tk "Tk Built-In Commands"
@@ -30,9 +30,22 @@ In this case the \fBraise\fR command will insert
\fIwindow\fR into the stacking order just above \fIaboveThis\fR
(or the ancestor of \fIaboveThis\fR that is a sibling of \fIwindow\fR);
this could end up either raising or lowering \fIwindow\fR.
+.SH EXAMPLE
+Make a button appear to be in a sibling frame that was created after
+it. This is is often necessary when building GUIs in the style where
+you create your activity widgets first before laying them out on the
+display:
+.CS
+button .b -text "Hi there!"
+pack [frame .f -background blue]
+pack [label .f.l1 -text "This is above"]
+pack .b -in .f
+pack [label .f.l2 -text "This is below"]
+\fBraise\fR .b
+.CE
.SH "SEE ALSO"
-lower
+lower(n)
.SH KEYWORDS
obscure, raise, stacking order
diff --git a/doc/scale.n b/doc/scale.n
index ba6a124..e0077e5 100644
--- a/doc/scale.n
+++ b/doc/scale.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: scale.n,v 1.3 2000/08/25 06:58:32 ericm Exp $
+'\" RCS: @(#) $Id: scale.n,v 1.3.8.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH scale n 4.1 Tk "Tk Built-In Commands"
@@ -63,7 +63,7 @@ rounding occurs. Defaults to 1 (i.e., the value will be integral).
Specifies a boolean value indicating whether or not the current
value of the scale is to be displayed.
.OP \-sliderlength sliderLength SliderLength
-Specfies the size of the slider, measured in screen units along the slider's
+Specifies the size of the slider, measured in screen units along the slider's
long dimension. The value may be specified in any of the forms acceptable
to \fBTk_GetPixels\fR.
.OP \-sliderrelief sliderRelief SliderRelief
@@ -117,7 +117,7 @@ of real values (determined by the \fBfrom\fR, \fBto\fR, and
\fBresolution\fR options),
and the position of the slider selects a particular real value.
The slider's position (and hence the scale's value) may be adjusted
-with the mouse or keyboard as described in the BINDINGS
+with the mouse or keyboard as described in the \fBBINDINGS\fR
section below. Whenever the scale's value is changed, a Tcl
command is invoked (using the \fBcommand\fR option) to notify
other interested widgets of the change.
@@ -133,7 +133,6 @@ of numerical tick marks just to the left of the current value
(just below the trough for horizontal scales). Each of these three
annotations may be enabled or disabled using the
configuration options.
-
.SH "WIDGET COMMAND"
.PP
The \fBscale\fR command creates a new Tcl command whose
@@ -197,7 +196,6 @@ This command is invoked to change the current value of the scale,
and hence the position at which the slider is displayed. \fIValue\fR
gives the new value for the scale.
The command has no effect if the scale is disabled.
-
.SH BINDINGS
.PP
Tk automatically creates class bindings for scales that give them
diff --git a/doc/scrollbar.n b/doc/scrollbar.n
index 2c2d73b..6acc7e4 100644
--- a/doc/scrollbar.n
+++ b/doc/scrollbar.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: scrollbar.n,v 1.3 2000/08/25 06:58:32 ericm Exp $
+'\" RCS: @(#) $Id: scrollbar.n,v 1.3.8.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH scrollbar n 4.1 Tk "Tk Built-In Commands"
@@ -69,7 +69,7 @@ A scrollbar is a widget that displays two arrows, one at each end of
the scrollbar, and a \fIslider\fR in the middle portion of the
scrollbar.
It provides information about what is visible in an \fIassociated window\fR
-that displays an document of some sort (such as a file being edited or
+that displays a document of some sort (such as a file being edited or
a drawing).
The position and size of the slider indicate which portion of the
document is visible in the associated window. For example, if the
@@ -78,9 +78,8 @@ between the two arrows, it means that the associated window displays
the top third of its document.
.PP
Scrollbars can be used to adjust the view in the associated window
-by clicking or dragging with the mouse. See the BINDINGS section
+by clicking or dragging with the mouse. See the \fBBINDINGS\fR section
below for details.
-
.SH "ELEMENTS"
.PP
A scrollbar displays five elements, which are referred to in the
@@ -100,7 +99,6 @@ The region between the slider and \fBarrow2\fR.
.TP 10
\fBarrow2\fR
The bottom or right arrow in the scrollbar.
-
.SH "WIDGET COMMAND"
.PP
The \fBscrollbar\fR command creates a new Tcl command whose
@@ -190,7 +188,6 @@ For example, if \fIfirst\fR is 0.2 and \fIlast\fR is 0.4, it means
that the first part of the document visible in the window is 20%
of the way through the document, and the last visible part is 40%
of the way through.
-
.SH "SCROLLING COMMANDS"
.PP
When the user interacts with the scrollbar, for example by dragging
@@ -227,7 +224,6 @@ is a slight overlap between the old and new views.
\fINumber\fR is either 1, which means the next page should
become visible, or \-1, which means that the previous page should
become visible.
-
.SH "OLD COMMAND SYNTAX"
.PP
In versions of Tk before 4.0, the \fBset\fR and \fBget\fR widget
@@ -268,13 +264,11 @@ to use the old syntax.
If it is given two real arguments then the new syntax will be
used in the future, and if it is given four integer arguments then
the old syntax will be used.
-
.SH BINDINGS
Tk automatically creates class bindings for scrollbars that give them
the following default behavior.
If the behavior is different for vertical and horizontal scrollbars,
the horizontal behavior is described in parentheses.
-
.IP [1]
Pressing button 1 over \fBarrow1\fR causes the view in the
associated widget to shift up (left) by one unit so that the
@@ -336,6 +330,16 @@ as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively.
The Home key adjusts the view to the top (left edge) of the document.
.IP [14]
The End key adjusts the view to the bottom (right edge) of the document.
+.SH EXAMPLE
+Create a window with a scrollable \fBtext\fR widget:
+.CS
+toplevel .tl
+text .tl.t -yscrollcommand {.tl.s set}
+\fBscrollbar\fR .tl.s -command {.tl.t yview}
+grid .tl.t .tl.s -sticky nsew
+grid columnconfigure .tl 0 -weight 1
+grid rowconfigure .tl 0 -weight 1
+.CE
.SH KEYWORDS
scrollbar, widget
diff --git a/doc/selection.n b/doc/selection.n
index 44fda07..c4847e7 100644
--- a/doc/selection.n
+++ b/doc/selection.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: selection.n,v 1.4 2001/06/04 03:15:20 hobbs Exp $
+'\" RCS: @(#) $Id: selection.n,v 1.4.4.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH selection n 8.1 Tk "Tk Built-In Commands"
@@ -128,9 +128,43 @@ that it has lost the selection.
If \fIcommand\fR is specified, it is a Tcl script to execute when
some other window claims ownership of the selection away from
\fIwindow\fR. \fISelection\fR defaults to PRIMARY.
+.SH EXAMPLES
+On X11 platforms, one of the standard selections available is the
+SECONDARY selection. Hardly anything uses it, but here is how to read
+it using Tk:
+.CS
+set selContents [\fBselection get\fR \-selection SECONDARY]
+.CE
+.PP
+Many different types of data may be available for a selection; the
+special type TARGETS allows you to get a list of available types:
+.CS
+foreach type [\fBselection get\fR \-type TARGETS] {
+ puts "Selection PRIMARY supports type $type"
+}
+.CE
+.PP
+To claim the selection, you must first set up a handler to supply the
+data for the selection. Then you have to claim the selection...
+.CS
+# Set up the data handler ready for incoming requests
+set foo "This is a string with some data in it... blah blah"
+\fBselection handle\fR \-selection SECONDARY . getData
+proc getData {offset maxChars} {
+ puts "Retrieving selection starting at $offset"
+ return [string range $::foo $offset [expr {$offset+$maxChars}]]
+}
+
+# Now we grab the selection itself
+puts "Claiming selection"
+\fBselection own\fR \-command lost \-selection SECONDARY .
+proc lost {} {
+ puts "Lost selection"
+}
+.CE
.SH "SEE ALSO"
-clipboard
+clipboard(n)
.SH KEYWORDS
clear, format, handler, ICCCM, own, selection, target, type
diff --git a/doc/send.n b/doc/send.n
index 7a74003..979d9de 100644
--- a/doc/send.n
+++ b/doc/send.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: send.n,v 1.3 1999/04/16 01:51:09 stanton Exp $
+'\" RCS: @(#) $Id: send.n,v 1.3.20.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH send n 4.0 Tk "Tk Built-In Commands"
@@ -91,6 +91,23 @@ such as that provide by \fBxauth\fR.
Under Windows, \fBsend\fR is currently disabled. Most of the
functionality is provided by the \fBdde\fR command instead.
.VE
+.SH EXAMPLE
+This script fragment can be used to make an application that only runs
+once on a particular display.
+.CS
+if {[tk appname FoobarApp] ne "FoobarApp"} {
+ \fBsend\fR -async FoobarApp RemoteStart $argv
+ exit
+}
+# The command that will be called remotely, which raises
+# the application main window and opens the requested files
+proc RemoteStart args {
+ raise .
+ foreach filename $args {
+ OpenFile $filename
+ }
+}
+.CE
.SH KEYWORDS
.VS
application, dde, name, remote execution, security, send
diff --git a/doc/spinbox.n b/doc/spinbox.n
index 9da7b41..5876879 100644
--- a/doc/spinbox.n
+++ b/doc/spinbox.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: spinbox.n,v 1.3 2001/12/18 23:02:35 hobbs Exp $
+'\" RCS: @(#) $Id: spinbox.n,v 1.3.2.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH spinbox n 8.4 Tk "Tk Built-In Commands"
@@ -168,7 +168,7 @@ loses focus.
.IP \fBall\fR 10
\fBvalidateCommand\fR will be called for all above conditions.
.PP
-It is posible to perform percent substitutions on the \fBvalidateCommand\fR
+It is possible to perform percent substitutions on the \fBvalidateCommand\fR
and \fBinvalidCommand\fR, just as you would in a \fBbind\fR script. The
following substitutions are recognized:
.PP
@@ -365,7 +365,7 @@ has several forms, depending on \fIoption\fR:
\fIpathName \fBselection adjust \fIindex\fR
Locate the end of the selection nearest to the character given by
\fIindex\fR, and adjust that end of the selection to be at \fIindex\fR
-(i.e including but not going beyond \fIindex\fR). The other
+(i.e. including but not going beyond \fIindex\fR). The other
end of the selection is made the anchor point for future
\fBselect to\fR commands. If the selection
isn't currently in the spinbox, then a new selection is created to
diff --git a/doc/text.n b/doc/text.n
index 69fb036..a663c09 100644
--- a/doc/text.n
+++ b/doc/text.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: text.n,v 1.15 2003/02/19 18:52:14 mdejong Exp $
+'\" RCS: @(#) $Id: text.n,v 1.15.2.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH text n 8.4 Tk "Tk Built-In Commands"
@@ -52,21 +52,21 @@ Requests additional space above each text line in the widget,
using any of the standard forms for screen distances.
If a line wraps, this option only applies to the first line
on the display.
-This option may be overriden with \fB\-spacing1\fR options in
+This option may be overridden with \fB\-spacing1\fR options in
tags.
.OP \-spacing2 spacing2 Spacing2
For lines that wrap (so that they cover more than one line on the
display) this option specifies additional space to provide between
the display lines that represent a single line of text.
The value may have any of the standard forms for screen distances.
-This option may be overriden with \fB\-spacing2\fR options in
+This option may be overridden with \fB\-spacing2\fR options in
tags.
.OP \-spacing3 spacing3 Spacing3
Requests additional space below each text line in the widget,
using any of the standard forms for screen distances.
If a line wraps, this option only applies to the last line
on the display.
-This option may be overriden with \fB\-spacing3\fR options in
+This option may be overridden with \fB\-spacing3\fR options in
tags.
.OP \-state state State
Specifies one of two states for the text: \fBnormal\fR or \fBdisabled\fR.
@@ -75,7 +75,9 @@ and no insertion cursor will be displayed, even if the input focus is
in the widget.
.OP \-tabs tabs Tabs
Specifies a set of tab stops for the window. The option's value consists
-of a list of screen distances giving the positions of the tab stops. Each
+of a list of screen distances giving the positions of the tab stops,
+each of which is a distance relative to the left edge of the widget
+(excluding borders, padding, etc). Each
position may optionally be followed in the next list element
by one of the keywords \fBleft\fR, \fBright\fR, \fBcenter\fR,
or \fBnumeric\fR, which specifies how to justify
@@ -94,7 +96,9 @@ tab stops at two-centimeter intervals; the first two use left
justification and the third uses center justification.
If the list of tab stops does not have enough elements to cover all
of the tabs in a text line, then Tk extrapolates new tab stops using
-the spacing and alignment from the last tab stop in the list.
+the spacing and alignment from the last tab stop in the list. Tab
+distances must be strictly positive, and must always increase from one
+tab stop to the next (if not, an error is thrown).
The value of the \fBtabs\fR option may be overridden by \fB\-tabs\fR
options in tags.
If no \fB\-tabs\fR option is specified, or if it is specified as
@@ -144,27 +148,26 @@ to be displayed with different fonts and colors.
In addition, Tcl commands can be associated with tags so
that scripts are invoked when particular actions such as keystrokes
and mouse button presses occur in particular ranges of the text.
-See TAGS below for more details.
+See \fBTAGS\fR below for more details.
.PP
-The second form of annotation consists of marks, which are floating
-markers in the text.
+The second form of annotation consists of floating markers in the text
+called "marks".
Marks are used to keep track of various interesting positions in the
text as it is edited.
-See MARKS below for more details.
+See \fBMARKS\fR below for more details.
.PP
The third form of annotation allows arbitrary windows to be
embedded in a text widget.
-See EMBEDDED WINDOWS below for more details.
+See \fBEMBEDDED WINDOWS\fR below for more details.
.PP
The fourth form of annotation allows Tk images to be embedded in a text
widget.
-See EMBEDDED IMAGES below for more details.
+See \fBEMBEDDED IMAGES\fR below for more details.
.PP
.VS 8.4
The text widget also has a built-in undo/redo mechanism.
-See UNDO MECHANISM below for more details.
+See \fBTHE UNDO MECHANISM\fR below for more details.
.VE 8.4
-
.SH INDICES
.PP
Many of the widget commands for texts take one or more indices
@@ -289,14 +292,13 @@ left-to-right order. For example, the index ``\fBend \- 1 chars\fR''
refers to the next-to-last character in the text and
``\fBinsert wordstart \- 1 c\fR'' refers to the character just before
the first one in the word containing the insertion cursor.
-
.SH TAGS
.PP
The first form of annotation in text widgets is a tag.
A tag is a textual string that is associated with some of the characters
in a text.
Tags may contain arbitrary characters, but it is probably best to
-avoid using the the characters `` '' (space), \fB+\fR, or \fB\-\fR:
+avoid using the characters `` '' (space), \fB+\fR, or \fB\-\fR:
these characters have special meaning in indices, so tags containing
them can't be used as indices.
There may be any number of tags associated with characters in a
@@ -500,8 +502,7 @@ For details, see the description of the \fBtag bind\fR widget
command below.
.PP
The third use for tags is in managing the selection.
-See THE SELECTION below.
-
+See \fBTHE SELECTION\fR below.
.SH MARKS
.PP
The second form of annotation in text widgets is a mark.
@@ -521,7 +522,7 @@ Marks may be manipulated with the ``\fIpathName \fBmark\fR'' widget
command, and their current locations may be determined by using the
mark name as an index in widget commands.
.PP
-Each mark also has a \fIgravity\fR, which is either \fBleft\fR or
+Each mark also has a "gravity", which is either \fBleft\fR or
\fBright\fR.
The gravity for a mark specifies what happens to the mark when
text is inserted at the point of the mark.
@@ -538,7 +539,7 @@ to different things.
.PP
Two marks have special significance.
First, the mark \fBinsert\fR is associated with the insertion cursor,
-as described under THE INSERTION CURSOR below.
+as described under \fBTHE INSERTION CURSOR\fR below.
Second, the mark \fBcurrent\fR is associated with the character
closest to the mouse and is adjusted automatically to track the
mouse position and any changes to the text in the widget (one
@@ -546,7 +547,6 @@ exception: \fBcurrent\fR is not updated in response to mouse
motions if a mouse button is down; the update will be deferred
until all mouse buttons have been released).
Neither of these special marks may be deleted.
-
.SH "EMBEDDED WINDOWS"
.PP
The third form of annotation in text widgets is an embedded window.
@@ -616,7 +616,6 @@ stretched.
.TP
\fB\-window \fIpathName\fR
Specifies the name of a window to display in the annotation.
-
.SH "EMBEDDED IMAGES"
.PP
The final form of annotation in text widgets is an embedded image.
@@ -630,21 +629,21 @@ text is modified or scrolled.
Each embedded image occupies one character's worth of index space
in the text widget, and it may be referred to either by
its position in the widget's index space, or the name it is assigned
-when the image is inserted into the text widget widh \fBimage create\fP.
+when the image is inserted into the text widget with \fBimage create\fP.
If the range of text containing the embedded image is deleted then
that copy of the image is removed from the screen.
.PP
When an embedded image is added to a text widget with the \fBimage
create\fR widget command, a name unique to this instance of the image
is returned. This name may then be used to refer to this image
-instance. The name is taken to be the value of the \fB-name\fP option
-(described below). If the \fB-name\fP option is not provided, the
-\fB-image\fP name is used instead. If the \fIimageName\fP is already
+instance. The name is taken to be the value of the \fB\-name\fP option
+(described below). If the \fB\-name\fP option is not provided, the
+\fB\-image\fP name is used instead. If the \fIimageName\fP is already
in use in the text widget, then \fB#\fInn\fR is added to the end of the
\fIimageName\fP, where \fInn\fP is an arbitrary integer. This insures
the \fIimageName\fP is unique.
Once this name is assigned to this instance of the image, it does not
-change, even though the \fB-image\fP or \fB-name\fP values can be changed
+change, even though the \fB\-image\fP or \fB\-name\fP values can be changed
with \fBimage configure\fP.
.PP
When an embedded image is added to a text widget with the
@@ -684,7 +683,6 @@ It may have any of the usual forms defined for a screen distance.
\fIPixels\fR specifies the amount of extra space to leave on
the top and on the bottom of the embedded image.
It may have any of the usual forms defined for a screen distance.
-
.SH "THE SELECTION"
.PP
Selection support is implemented via tags.
@@ -713,7 +711,6 @@ the text widget are tied to the \fB\-background\fR,
\fB\-borderwidth\fR, and \fB\-foreground\fR options for the \fBsel\fR
tag: changes in either will automatically be reflected in the
other.
-
.SH "THE INSERTION CURSOR"
.PP
The mark named \fBinsert\fR has special significance in text widgets.
@@ -723,33 +720,30 @@ command.
The \fBinsert\fR mark represents the position of the insertion
cursor, and the insertion cursor will automatically be drawn at
this point whenever the text widget has the input focus.
-
.SH "THE MODIFIED FLAG"
The text widget can keep track of changes to the content of the widget
by means of the modified flag. Inserting or deleting text will set
-this flag. The flag can be queried, set and cleared programatically
+this flag. The flag can be queried, set and cleared programmatically
as well. Whenever the flag changes state a \fB<<Modified>>\fR virtual
event is generated. See the \fBedit modified\fR widget command for
more details.
-
.SH "THE UNDO MECHANISM"
.PP
.VS 8.4
The text widget has an unlimited undo and redo mechanism (when the
-\fB-undo\fR widget option is true) which records every insert and
+\fB\-undo\fR widget option is true) which records every insert and
delete action on a stack.
.PP
-Boundaries (called "separators") are inserted between edit actions.
-The purpose of these separators is to group inserts and deletes into
-one compound edit action. When undoing a change everything between
-two separators will be undone. The undone changes are then moved to
-the redo stack, so that an undone edit can be redone again. The redo
-stack is cleared whenever new edit actions are recorded on the undo
-stack. The undo and redo stacks can be cleared to keep their depth
-under control.
+Boundaries (called "separators") are inserted between edit actions. The
+purpose of these separators is to group inserts, deletes and replaces
+into one compound edit action. When undoing a change everything between
+two separators will be undone. The undone changes are then moved to the
+redo stack, so that an undone edit can be redone again. The redo stack
+is cleared whenever new edit actions are recorded on the undo stack. The
+undo and redo stacks can be cleared to keep their depth under control.
.PP
-Separators are inserted automatically when the \fB-autoseparators\fR
-widget option is true. You can insert separators programatically as
+Separators are inserted automatically when the \fB\-autoseparators\fR
+widget option is true. You can insert separators programmatically as
well. If a separator is already present at the top of the undo stack
no other will be inserted. That means that two separators on the undo
stack are always separated by at least one insert or delete action.
@@ -764,7 +758,6 @@ the flag has been reset again.
See below for the \fBedit\fR widget command that controls the undo
mechanism.
.VE 8.4
-
.SH "WIDGET COMMAND"
.PP
The \fBtext\fR command creates a new Tcl command whose
@@ -860,7 +853,7 @@ The command returns an empty string.
If more indices are given, multiple ranges of text will be deleted.
All indices are first checked for validity before any deletions are made.
They are sorted and the text is removed from the last range to the
-first range to deleted text does not cause a undesired index shifting
+first range to deleted text does not cause an undesired index shifting
side-effects. If multiple ranges with the same start index are given,
then the longest range is used. If overlapping ranges are given, then
they will be merged into spans that do not cause deletion of text
@@ -932,7 +925,7 @@ Include information about text in the dump results. The value is the
text up to the next element or the end of range indicated by \fIindex2\fR.
A text element does not span newlines. A multi-line block of text that
contains no marks or tag transitions will still be dumped as a set
-of text seqments that each end with a newline. The newline is part
+of text segments that each end with a newline. The newline is part
of the value.
.TP
\fB\-window\fR
@@ -958,9 +951,9 @@ user can set or clear the modified flag. If \fIboolean\fR is
specified, sets the modified flag of the widget to \fIboolean\fR.
.TP
\fIpathName \fBedit redo\fR
-When the \fB-undo\fR option is true, reapplies the last undone edits
+When the \fB\-undo\fR option is true, reapplies the last undone edits
provided no other edits were done since then. Generates an error when
-the redo stack is empty. Does nothing when the \fB-undo\fR option is
+the redo stack is empty. Does nothing when the \fB\-undo\fR option is
false.
.TP
\fIpathName \fBedit reset\fR
@@ -968,13 +961,13 @@ Clears the undo and redo stacks.
.TP
\fIpathName \fBedit separator\fR
Inserts a separator (boundary) on the undo stack. Does nothing when
-the \fB-undo\fR option is false.
+the \fB\-undo\fR option is false.
.TP
\fIpathName \fBedit undo\fR
-Undoes the last edit action when the \fB-undo\fR option is true. An
+Undoes the last edit action when the \fB\-undo\fR option is true. An
edit action is defined as all the insert and delete commands that are
recorded on the undo stack in between two separators. Generates an
-error when the undo stack is empty. Does nothing when the \fB-undo\fR
+error when the undo stack is empty. Does nothing when the \fB\-undo\fR
option is false.
.RE
.VE 8.4
@@ -1009,7 +1002,7 @@ The following forms of the command are currently supported:
Returns the value of a configuration option for an embedded image.
\fIIndex\fR identifies the embedded image, and \fIoption\fR
specifies a particular configuration option, which must be one of
-the ones listed in the section EMBEDDED IMAGES.
+the ones listed in the section \fBEMBEDDED IMAGES\fR.
.TP
\fIpathName \fBimage configure \fIindex\fR ?\fIoption value ...\fR?
Query or modify the configuration options for an embedded image.
@@ -1023,7 +1016,7 @@ identical to the corresponding sublist of the value returned if no
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.
-See EMBEDDED IMAGES for information on the options that
+See \fBEMBEDDED IMAGES\fR for information on the options that
are supported.
.TP
\fIpathName \fBimage create \fIindex\fR ?\fIoption value ...\fR?
@@ -1033,7 +1026,7 @@ Any number of \fIoption\-value\fR pairs may be specified to
configure the annotation.
Returns a unique identifier that may be used as an index to refer to
this image.
-See EMBEDDED IMAGES for information on the options that
+See \fBEMBEDDED IMAGES\fR for information on the options that
are supported, and a description of the identifier returned.
.TP
\fIpathName \fBimage names\fR
@@ -1045,7 +1038,7 @@ embedded in \fIwindow\fR.
Returns the position corresponding to \fIindex\fR in the form
\fIline.char\fR where \fIline\fR is the line number and \fIchar\fR
is the character number.
-\fIIndex\fR may have any of the forms described under INDICES above.
+\fIIndex\fR may have any of the forms described under \fBINDICES\fR above.
.TP
\fIpathName \fBinsert \fIindex chars \fR?\fItagList chars tagList ...\fR?
Inserts all of the \fIchars\fR arguments just before the character at
@@ -1185,12 +1178,13 @@ Ignore case differences between the pattern and the text.
The argument following \fB\-count\fR gives the name of a variable;
if a match is found, the number of index positions between beginning and
end of the matching range will be stored in the variable. If there are no
-embedded images or windows in the matching range, this is equivalent to the
+embedded images or windows in the matching range (and there are no
+elided characters if \fB\-elide\fR is not given), this is equivalent to the
number of characters matched. In either case, the range \fImatchIdx\fR to
\fImatchIdx + $count chars\fR will return the entire matched text.
.TP
\fB\-elide\fR
-Find elidden (hidden) text as well. By default only displayed text is
+Find elided (hidden) text as well. By default only displayed text is
searched.
.TP
\fB\-\|\-\fR
@@ -1271,7 +1265,7 @@ The only events for which bindings may be specified are those related
to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR,
\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events.
Event bindings for a text widget use the \fBcurrent\fR mark described
-under MARKS above. An \fBEnter\fR event triggers for a tag when the tag
+under \fBMARKS\fR above. An \fBEnter\fR event triggers for a tag when the tag
first becomes present on the current character, and a \fBLeave\fR event
triggers for a tag when it ceases to be present on the current character.
\fBEnter\fR and \fBLeave\fR events can happen either because the
@@ -1322,7 +1316,7 @@ 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 \fItagName\fR;
in this case the command returns an empty string.
-See TAGS above for details on the options available for tags.
+See \fBTAGS\fR above for details on the options available for tags.
.TP
\fIpathName \fBtag delete \fItagName \fR?\fItagName ...\fR?
Deletes all tag information for each of the \fItagName\fR
@@ -1424,7 +1418,7 @@ The following forms of the command are currently supported:
Returns the value of a configuration option for an embedded window.
\fIIndex\fR identifies the embedded window, and \fIoption\fR
specifies a particular configuration option, which must be one of
-the ones listed in the section EMBEDDED WINDOWS.
+the ones listed in the section \fBEMBEDDED WINDOWS\fR.
.TP
\fIpathName \fBwindow configure \fIindex\fR ?\fIoption value ...\fR?
Query or modify the configuration options for an embedded window.
@@ -1438,7 +1432,7 @@ identical to the corresponding sublist of the value returned if no
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.
-See EMBEDDED WINDOWS for information on the options that
+See \fBEMBEDDED WINDOWS\fR for information on the options that
are supported.
.TP
\fIpathName \fBwindow create \fIindex\fR ?\fIoption value ...\fR?
@@ -1446,7 +1440,7 @@ This command creates a new window annotation, which will appear
in the text at the position given by \fIindex\fR.
Any number of \fIoption\-value\fR pairs may be specified to
configure the annotation.
-See EMBEDDED WINDOWS for information on the options that
+See \fBEMBEDDED WINDOWS\fR for information on the options that
are supported.
Returns an empty string.
.TP
@@ -1563,7 +1557,6 @@ the one given by \fInumber\fR visible at the top of the window.
\fINumber\fR must be an integer.
This command used to be used for scrolling, but now it is obsolete.
.RE
-
.SH BINDINGS
.PP
Tk automatically creates class bindings for texts that give them
@@ -1717,18 +1710,19 @@ front of the insertion cursor without moving the insertion cursor.
Meta-backspace and Meta-Delete delete the word to the left of the
insertion cursor.
.IP [30]
-Control-x deletes whatever is selected in the text widget.
+Control-x deletes whatever is selected in the text widget
+after copying it to the clipboard.
.IP [31]
Control-t reverses the order of the two characters to the right of
the insertion cursor.
.IP [32]
.VS 8.4
Control-z (and Control-underscore on UNIX when \fBtk_strictMotif\fR is
-true) undoes the last edit action if the \fB-undo\fR option is true.
+true) undoes the last edit action if the \fB\-undo\fR option is true.
Does nothing otherwise.
.IP [33]
Control-Z (or Control-y on Windows) reapplies the last undone edit
-action if the \fB-undo\fR option is true. Does nothing otherwise.
+action if the \fB\-undo\fR option is true. Does nothing otherwise.
.VE 8.4
.PP
If the widget is disabled using the \fB\-state\fR option, then its
@@ -1738,7 +1732,6 @@ take place.
.PP
The behavior of texts can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
-
.SH "PERFORMANCE ISSUES"
.PP
Text widgets should run efficiently under a variety
@@ -1772,5 +1765,9 @@ especially if they have many marks and tags within them.
The display line with the insert cursor is redrawn each time the
cursor blinks, which causes a steady stream of graphics traffic.
Set the \fBinsertOffTime\fP attribute to 0 avoid this.
+
+.SH "SEE ALSO"
+entry(n), scrollbar(n)
+
.SH KEYWORDS
text, widget, tkvars
diff --git a/doc/toplevel.n b/doc/toplevel.n
index 78d4e56..f40ad58 100644
--- a/doc/toplevel.n
+++ b/doc/toplevel.n
@@ -1,3 +1,4 @@
+'\" -*- nroff -*-
'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
@@ -5,7 +6,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: toplevel.n,v 1.4 2001/09/26 21:36:19 pspjuth Exp $
+'\" RCS: @(#) $Id: toplevel.n,v 1.4.4.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH toplevel n 8.4 Tk "Tk Built-In Commands"
@@ -61,8 +62,8 @@ If this option is less than or equal to zero then the window will
not request any size at all.
.OP \-menu menu Menu
Specifies a menu widget to be used as a menubar. On the Macintosh, the
-menubar will be displayed accross the top of the main monitor. On
-Microsoft Windows and all UNIX platforms, the menu will appear accross
+menubar will be displayed across the top of the main monitor. On
+Microsoft Windows and all UNIX platforms, the menu will appear across
the toplevel window as part of the window dressing maintained by the
window manager.
.OP \-screen "" ""
@@ -75,7 +76,7 @@ database, and it may not be modified with the \fBconfigure\fR
widget command.
.OP \-use use Use
This option is used for embedding. If the value isn't an empty string,
-it must be the the window identifier of a container window, specified as
+it must be the window identifier of a container window, specified as
a hexadecimal string like the ones returned by the \fBwinfo id\fR
command. The toplevel widget will be created as a child of the given
container instead of the root window for the screen. If the container
diff --git a/doc/winfo.n b/doc/winfo.n
index aacdabf..0a1b06d 100644
--- a/doc/winfo.n
+++ b/doc/winfo.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: winfo.n,v 1.3 2001/12/04 03:07:43 mdejong Exp $
+'\" RCS: @(#) $Id: winfo.n,v 1.3.2.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH winfo n 4.3 Tk "Tk Built-In Commands"
@@ -197,7 +197,8 @@ in pixels. This is the value used by \fIwindow\fR's geometry
manager to compute its geometry.
.TP
\fBwinfo rgb \fIwindow color\fR
-Returns a list containing three decimal values, which are the
+Returns a list containing three decimal values in the range 0 to
+65535, which are the
red, green, and blue intensities that correspond to \fIcolor\fR in
the window given by \fIwindow\fR. \fIColor\fR
may be specified in any of the forms acceptable for a color
@@ -326,6 +327,19 @@ Returns a decimal string giving the y-coordinate, in \fIwindow\fR's
parent, of the
upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it
has no border).
+.SH EXAMPLE
+Print where the mouse pointer is and what window it is currently over:
+.CS
+set x [\fBwinfo pointerx\fR .]
+set y [\fBwinfo pointery\fR .]
+puts -nonewline "Mouse pointer at ($x,$y) which is "
+set win [\fBwinfo containing\fR $x $y]
+if {$win eq ""} {
+ puts "over no window"
+} else {
+ puts "over $win"
+}
+.CE
.SH KEYWORDS
atom, children, class, geometry, height, identifier, information, interpreters,
diff --git a/doc/wm.n b/doc/wm.n
index 90125a2..7edf339 100644
--- a/doc/wm.n
+++ b/doc/wm.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: wm.n,v 1.11 2002/07/16 18:06:41 vincentdarley Exp $
+'\" RCS: @(#) $Id: wm.n,v 1.11.2.1 2004/10/28 12:25:22 dkf Exp $
'\"
.so man.macros
.TH wm n 8.4 Tk "Tk Built-In Commands"
@@ -58,12 +58,13 @@ flags and their values. The second form returns the value for the
specific option. The third form sets one or more of the values. The
values are as follows:
.PP
-On Windows, \fB-disabled\fR gets or sets whether the window is in a
-disabled state. \fB-toolwindow\fR gets or sets the style of the window
-to toolwindow (as defined in the MSDN). \fB-topmost\fR gets or sets
+On Windows, \fB\-disabled\fR gets or sets whether the window is in a
+disabled state. \fB\-toolwindow\fR gets or sets the style of the window
+to toolwindow (as defined in the MSDN). \fB\-topmost\fR gets or sets
whether this is a topmost window (displays above all other windows).
.PP
-On Macintosh,
+On Macintosh, there are currently two attribute values:
+\fB\-modified\fR and \fB\-titlepath\fR.
.PP
On Unix, there are currently no special attribute values.
.RE
@@ -234,8 +235,8 @@ Otherwise it returns the name of
the current icon bitmap associated with \fIwindow\fR, or an empty
string if \fIwindow\fR has no icon bitmap. On the Windows operating
system, an additional flag is supported:
-\fBwm iconbitmap \fIwindow\fR ?\fI-default\fR? ?\fIimage\fR?.
-If the \fI-default\fR
+\fBwm iconbitmap \fIwindow\fR ?\fB\-default\fR? ?\fIimage\fR?.
+If the \fB\-default\fR
flag is given, the icon is applied to all toplevel windows (existing
and future) to which no other specific icon has yet been applied.
In addition to bitmap image types, a full path specification to
@@ -312,8 +313,6 @@ specified, then the command returns an empty string. Otherwise
it returns a Tcl list with two elements, which are the
maximum width and height currently in effect.
The maximum size defaults to the size of the screen.
-If resizing has been disabled with the \fBwm resizable\fR command,
-then this command has no effect.
See the sections on geometry management below for more information.
.TP
\fBwm minsize \fIwindow\fR ?\fIwidth height\fR?
@@ -328,8 +327,6 @@ specified, then the command returns an empty string. Otherwise
it returns a Tcl list with two elements, which are the
minimum width and height currently in effect.
The minimum size defaults to one pixel in each dimension.
-If resizing has been disabled with the \fBwm resizable\fR command,
-then this command has no effect.
See the sections on geometry management below for more information.
.TP
\fBwm overrideredirect \fIwindow\fR ?\fIboolean\fR?
@@ -483,7 +480,6 @@ Note: it sometimes seems to be necessary to withdraw a
window and then re-map it (e.g. with \fBwm deiconify\fR) to get some
window managers to pay attention to changes in window attributes
such as group.
-
.SH "GEOMETRY MANAGEMENT"
.PP
By default a top-level window appears on the screen in its
@@ -510,7 +506,6 @@ all forms of resizing, including the window's natural size as
well as manual resizes and the \fBwm geometry\fR command.
You can also use the command \fBwm resizable\fR to completely
disable interactive resizing in one or both dimensions.
-
.SH "GRIDDED GEOMETRY MANAGEMENT"
.PP
Gridded geometry management occurs when one of the widgets of an
@@ -544,13 +539,46 @@ in \fBwm minsize\fR, \fBwm maxsize\fR, and \fBwm geometry\fR commands
are treated as grid units rather than pixel units.
Interactive resizing is also carried out in even numbers of grid units
rather than pixels.
-
.SH BUGS
.PP
Most existing window managers appear to have bugs that affect the
operation of the \fBwm\fR command. For example, some changes won't
take effect if the window is already active: the window will have
to be withdrawn and de-iconified in order to make the change happen.
+.SH EXAMPLES
+A fixed-size window that says that it is fixed-size too:
+.CS
+toplevel .fixed
+\fBwm title\fR .fixed "Fixed-size Window"
+\fBwm resizable\fR .fixed 0 0
+.CE
+.PP
+A simple dialog-like window, centred on the screen:
+.CS
+# Create and arrange the dialog contents.
+toplevel .msg
+label .msg.l \-text "This is a very simple dialog demo."
+button .msg.ok \-text OK \-default active \-command {destroy .msg}
+pack .msg.ok \-side bottom \-fill x
+pack .msg.l \-expand 1 \-fill both
+
+# Now set the widget up as a centred dialog.
+
+# But first, we need the geometry managers to finish setting
+# up the interior of the dialog, for which we need to run the
+# event loop with the widget hidden completely...
+\fBwm withdraw\fR .msg
+update
+set x [expr {([winfo screenwidth .]\-[winfo width .msg])/2}]
+set y [expr {([winfo screenheight .]\-[winfo height .msg])/2}]
+\fBwm geometry\fR .msg +$x+$y
+\fBwm transient\fR .msg .
+\fBwm title\fR .msg "Dialog demo"
+\fBwm deiconify\fR .msg
+.CE
+
+.SH "SEE ALSO"
+toplevel(n), winfo(n)
.SH KEYWORDS
aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager
generated by cgit v0.12 at 2024-11-03 08:52:09 (GMT)